This project holds shared functionality, configuration and concepts for all Stargate V2 APIs.
By default, the APIs use the header-based authentication mechanism.
All requests must include the X-Cassandra-Token.
The actual authentication and authorization checks are delegated to the Stargate V2 Bridge, by passing the value of that header as the Cassandra token.
The header-based authentication can be switched off and any Quarkus Build-in Authentication Mechanism can be used. In that case, you need to provide a correct CassandraTokenResolver implementation, in order to resolve the Cassandra token when calling the Stargate V2 Bridge.
The Authentication & security configuration provides a detailed description of the available configuration options.
The common project enables configuration of the Cassandra consistency levels used in Stargate APIs. The consistency levels can be defined separately for queries doing:
- schema changes
- writes
- reads
The Queries configuration provides a detailed view of the available configuration options.
All Stargate V2 APIs export Prometheus-based metrics.
The metrics collection is performed using the quarkus-micrometer-registry-prometheus extension. The common module enables additional metric configuration.
The Metrics configuration provides a detailed view of the available configuration options.
The Stargate V2 provides support for multi-tenancy. Multi-tenancy is optional and is controlled by the configured TenantResolver implementation. If a tenant is resolved for an HTTP request, the information about the tenant will be propagated to the Stargate V2 Bridge. In addition, the tenant identifier can be used to tag metrics, or included in logs or traces.
The Multi-tenancy configuration provides a detailed view of the available configuration options.
This project defines several common stargate. properties using dedicated config classes annotated with the @ConfigMapping.
The list of currently available properties is documented in the Configuration Guide.
This project uses Quarkus, the Supersonic Subatomic Java Framework. If you want to learn more about Quarkus, please visit its website.
We recommended that you install the Quarkus CLI for the best development experience. See CLI Tooling for more information.
Note that this project uses Java 17, please ensure that you have the target JDK installed on your system.
WARNING: The common module is not made as a running application, but rather as a dependency used in the other modules.
The tests in this project can be run using the command:
../mvnw testTo build without executing the tests, run:
../mvnw install -DskipUnitTestsNOTE: The common module does not contain integration tests.
This project depends on various Quarkus extensions, modules that run on top of a Quarkus application. These extensions are shared between all API projects.
The application configuration is specified using the YAML format.
Default configuration properties are specified in the application.yaml file.
The YAML configuration also support profile aware files.
In this case, properties for a specific profile may reside in an application-{profile}.yaml named file.
The gRPC extension provides an easy way for consuming gRPC services, in this case the Stargate Bridge gRPC service. The pom.xml file defines what proto files should be used for generating the stubs:
<quarkus.generate-code.grpc.scan-for-proto>io.stargate.grpc:grpc-proto</quarkus.generate-code.grpc.scan-for-proto>The clients are configured using the quarkus.grpc.clients.[client-name] properties.
In order to pass the request context information to the Bridge, the client should be obtained using the GrpcClients utility class.
Enables validation of configuration, beans, REST endpoints, etc.
Enables out-of-the-box metrics collection and the Prometheus exporter.
Metrics are exported at the Prometheus default /metrics endpoint.
All non-application endpoints are ignored from the collection.
Enables the OpenTelemetry tracing support.
In order to activate the tracing, you need to supply the OTLP gRPC endpoint using the JVM parameters -Dquarkus.otel.exporter.otlp.enabled=true -Dquarkus.otel.exporter.otlp.endpoint=http://localhost:55680.
The easiest way to locally collect and visualize traces is to use the jaegertracing/opentelemetry-all-in-one Docker image with in-memory storage:
docker run \
--rm \
-e SPAN_STORAGE_TYPE=memory \
-p 55680:55680 \
-p 16686:16686 \
jaegertracing/opentelemetry-all-in-oneYou can then visualize traces using Jaeger UI started on http://localhost:16686.
The project uses the reactive implementation of the resteasy to create HTTP resources.
The JSON serialization is done using the Jackson library (provided by quarkus-resteasy-reactive-jackson extension).
The exception handling is done using the dedicated handlers annotated with org.jboss.resteasy.reactive.server.ServerExceptionMapper.
By default, the application is served based on the quarkus.http.port configuration value and varies between API projects.
The root path for the non-application endpoints (health, Open API, etc.) is /stargate.
All configuration options for the HTTP server can be found in Quarkus Configuration Options.
The OpenAPI definitions are generated and available under /api/docs/openapi endpoint.
The info portions of the Open API definitions are set using the quarkus.smallrye-openapi.info- configuration properties.
The Swagger UI is available at the /swagger-ui endpoint.
Note that Swagger UI is enabled by default in the production profile and can be disabled by setting the quarkus.swagger-ui.always-include property to false.