Home

Awesome

Maven Central

Stargate

An open source data API gateway.

Stargate is a data gateway deployed between client applications and a Cassandra database. For developers, it makes it easy to use Cassandra for any application workload by adding plugin support for new APIs, data types, and access methods - even secondary database models. It's built with extensibility as a first-class citizen to enable rapid innovation. For operators, Stargate introduces microservice architecture, allowing independent deployment and scale of storage nodes, API Service nodes, and coordinator nodes in Cassandra clusters.

Contents

Introduction

We created Stargate because we got tired of using different databases and different APIs depending on the work that we were trying to get done. With "read the manual" fatigue and lengthy selection processes wearing on us every time we started a new project, we thought - why not create a framework that can serve many APIs for a range of workloads?

This project enables customization of all aspects of data access and has modules for authentication, APIs, request handling / routing, and persistence backends.
The current form is specific to Apache Cassandra (C*) compatible backends.

As shown in the figure below, Stargate is often deployed behind a load balancer or proxy and exposes multiple endpoints to client applications, including HTTP APIs, gRPC, and the Cassandra Query Language (CQL). Stargate sits in front of a Cassandra cluster which is used as the storage backend.

image

Stargate consists of the following components, which we introduce briefly here with links to the corresponding modules in this monorepo.

API Services

These are independently scalable microservices which various APIs, typically HTTP based. These modules can be found under the apis directory:

Each API Service contains its own integration test suite that tests it against the coordinator node and supported Cassandra backends. There is also a sgv2-quarkus-common module containing utilities that may be used by all Java/Quarkus based API services.

Coordinator Node

Coordinator nodes participate as non-data storing nodes in the backing Cassandra cluster, which enables them to read and write data more efficiently. Stargate Coordinator nodes can also be scaled independently. Coordinator nodes expose gRPC and CQL interfaces for fast access by client applications. The following are the key modules comprising the coordinator and its exposed interfaces:

Persistence Services

Stargate coordinator nodes support a pluggable approach for implementing the coordination layer to execute requests passed by API services and other interfaces to underlying data storage instances. Persistence service implementations are responsible handling and converting requests to database queries, dispatching to a specific version of Cassandra, and returning and serving responses.

Authentication and Authorization Services

Stargate coordinator nodes also support a pluggable authentication and authorization approach.

Coordinator Node Testing

The following modules provide support for testing:

Instructions for running and extending the test suite can be found in the developer guide.

Repositories

Here is an overview of the key repositories in the Stargate GitHub organization:

The organization also contains several gRPC client libraries for various languages.

Issue Management

You can reference the CONTRIBUTING.md for a full description of how to get involved, but the short of it is below.

Supported Versions and Branching Strategy

The Stargate project maintains support for the current major version number and one major version number previous. We mark the previous major version number as deprecated in order to encourage usage of the latest version. We anticipate supporting a major version number release N for one year after the subsequent major version number release (N+1), or until the major version number release (N+2), whichever comes first. For example, v1 will be supported until when Stargate v3 is released, but no later than October 2023 (1 year after release date of Stargate v2). We anticipate producing a new major version number release every 6-12 months.

Supporting a release entails making bug fixes, keeping dependencies up to date, and making sure Docker images are free from vulnerabilities.

The current major version is maintained on the default main branch. The prior major version number is maintained on a version branch, for example, v1.

We make bug fixes in all supported releases. The recommended approach is to commit a fix first to the previous major version branch (if applicable) and merge it forward into the current major version branch.

We use minor version numbers to indicate any changes to the coordinator that would cause compatibility changes for Stargate APIs. For example, a breaking change to the bridge API in v2.0.x would cause creation of a v2.1.0 release, and any API implementations would need to explicitly update in order to be compatible. You can use any version of the coordinator and API that have same the major and minor version number without issues.

We iterate forward rather than producing patch releases. For example, for a vulnerability found in v2.0.3, we'd make any required fixes and dependency updates and release v2.0.4. We maintain a regular release cadence of approximately twice a month but can iterate more quickly as the situation dictates.

Thanks

YourKit Logo

This project uses tools provided by YourKit, LLC. YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of <a href="https://www.yourkit.com/java/profiler/">YourKit Java Profiler</a> and <a href="https://www.yourkit.com/.net/profiler/">YourKit .NET Profiler</a>, innovative and intelligent tools for profiling Java and .NET applications.