Awesome
HTTP Server For JSON Event Sourcing
This is a standalone HTTP server for interacting with JSON aggregates. On the write-side you can send commands, which are handled asynchronously. They are put on a Kafka command topic, which corresponds to the aggregate type in the command. This is acknowledged with a 202 HTTP status code (Accepted). Changes to aggregates come back through Server-Sent Events. This flow fits well with reactive clients.
The read-side is handled with MongoDB. You can fetch and search aggregates.
The supported paths and methods are explained in the repository pincette-jes-api.
One special path is <contextPath>/health, which just returns status code 200 (OK). This can be used for health checks.
Authentication
All requests should have a JSON Web Token, which may appear as a bearer token in the Authotrization header or the cookie named access_token. The configuration should have the public key with which the tokens can be validated.
Configuration
The configuration is managed by the Lightbend Config package. By default it will try to load conf/application.conf. An alternative configuration may be loaded by adding -Dconfig.resource=myconfig.conf, where the file is also supposed to be in the conf directory. If no configuration file is available it will load a default one from the resources. All configuration entries can be overridden with equivalent environment variables. The following entries are available:
| Entry | Envvar | Mandatory | Default | Description |
|---|---|---|---|---|
| accessLog | ACCESS_LOG | No | false | A boolean indicating if access log entries should be sent to the log topic, which should be set. |
| contextPath | CONTEXT_PATH | No | /api | The URL path prefix. |
| environment | ENVIRONMENT | No | None | The name of the environment, which will be used as a suffix for the aggregates, e.g. tst, acc, etc. |
| fanout.uri | FANOUT_URI | No | None | The URL of the fanout.io service. |
| fanout.privateKey | FANOUT_PRIVATE_KEY | Only when FANOUT_URI is present | None | The private key in PEM format with which the usernames are signed during the Server-Sent Events set-up. |
| fanout.publicKey | FANOUT_PUBLIC_KEY | Only when FANOUT_URI is present | None | The public key in PEM format with which the usernames are verified during the Server-Sent Events set-up. |
| jwtPublicKey | JWT_PUBLIC_KEY | Yes | None | The public key string, which is used to validate all JSON Web Tokens. |
| kafka | KAFKA_* | No | localhost:9092 | All Kafka settings come below this entry. So for example, the setting bootstrap.servers would go to the entry kafka.bootstrap.servers. The equivalent environment variable would then be KAFKA_BOOTSTRAP_SERVERS. |
| logLevel | LOG_LEVEL | No | INFO | The log level as defined in java.util.logging.Level. |
| logTopic | LOG_TOPIC | No | None | The Kafka topic where the log entries are sent to in the Elastic Common Schema. |
| metricsTopic | METRICS_TOPIC | No | None | The Kafka topic where the metrics entries are sent to in JSON. They are per minute and per aggregate/HTTP method. |
| mongodb.database | MONGODB_DATABASE | No | es | The name of the MongoDB database. |
| mongodb.uri | MONGODB_URI | No | mongodb://localhost:27017 | The URI of the MongoDB service. |
| whoami | WHOAMI | No | None | An array of fields that are extracted from the JWT and put in a JSON object that becomes the value of the whoami cookie. The cookie can be used by clients to obtain basic information about the current user. |
Metrics
If the metricsTopic configration entry is set, metrics messages are sent to it for every aggregate/HTTP method combination. This happens every minute. The messages look like this (the time is in milliseconds):
{
"aggregate": "my_aggregate",
"method": "GET",
"minute": "2023-11-01T17:23:00Z",
"requestCount": 245,
"requestBytes": 2786,
"responseBytes": 32152,
"timeSpent": 12250,
"averageRequestBytes": 11,
"averageResponseBytes": 131,
"averageTimeSpent": 50
}
Building and Running
You can build the tool with mvn clean package. This will produce a self-contained JAR-file in the target directory with the form pincette-jes-http-<version>-jar-with-dependencies.jar. You can launch this JAR with java -jar, followed by a port number.
You can run the JVM with the option -mx128m.
Docker
Docker images can be found at https://hub.docker.com/repository/docker/jsoneventsourcing/pincette-jes-http. They expose port 9000. You can either use environment variables to configure them or add a configuration layer with a Docker file that looks like this:
FROM registry.hub.docker.com/jsoneventsourcing/pincette-jes-http:<version>
COPY conf/tst.conf /conf/application.conf
So wherever your configuration file comes from, it should always end up at /conf/application.conf.
Kubernetes
You can mount the configuration in a ConfigMap and Secret combination. The ConfigMap should be mounted at /conf/application.conf. You then include the secret in the configuration from where you have mounted it. See also https://github.com/lightbend/config/blob/main/HOCON.md#include-syntax.