Skip to content

Latest commit

 

History

History
118 lines (75 loc) · 8.55 KB

README.md

File metadata and controls

118 lines (75 loc) · 8.55 KB
Raw

CircleCI

Apollo Router

The Apollo Router is a configurable, high-performance graph router written in Rust to run a federated supergraph that uses Apollo Federation 2.

Apollo Router is well-tested, regularly benchmarked, includes most major features of Apollo Gateway and is able to serve production-scale workloads. Please note that the (pre-1.0) version is not yet "semver stable" and we may still make breaking changes. Generally speaking, we expect most breaking changes to be on the plugin API and the configuration file format. We will clearly convey such changes in the release notes.

New releases and their release notes (along with notes about any breaking changes) can be found on the Releases page, and the latest release can always be found on the latest page. The CHANGELOG.md at the root of this repository also contains unreleased changes in addition to the full history of changes.

Currently, we're publishing new releases every 1-2 weeks.

Getting started

Follow the quickstart tutorial to get up and running with the Apollo Router.

See the documentation for more details.

Usage

Apollo Router requires a supergraph file to be passed as the --supergraph argument and an optional configuration file. to be supplied. These are either located in the current directory or explicitly specified via flag, either by an absolute path, or a path relative to the current directory.

USAGE:
    router [OPTIONS] [SUBCOMMAND]

OPTIONS:
        --apollo-uplink-endpoints <APOLLO_UPLINK_ENDPOINTS>
            The endpoints (comma separated) polled to fetch the latest supergraph schema [env:
            APOLLO_UPLINK_ENDPOINTS=]

        --apollo-uplink-poll-interval <APOLLO_UPLINK_POLL_INTERVAL>
            The time between polls to Apollo uplink. Minimum 10s [env: APOLLO_UPLINK_POLL_INTERVAL=]
            [default: 10s]

        --apollo-uplink-timeout <APOLLO_UPLINK_TIMEOUT>
            The timeout for each of the polls to Apollo Uplink. [env: APOLLO_UPLINK_TIMEOUT=]
            [default: 30s]

    -c, --config <CONFIG_PATH>
            Configuration location relative to the project directory [env:
            APOLLO_ROUTER_CONFIG_PATH=]

    -h, --help
            Print help information

        --hot-reload
            Reload configuration and schema files automatically [env: APOLLO_ROUTER_HOT_RELOAD=]

        --log <LOG_LEVEL>
            Log level (off|error|warn|info|debug|trace) [env: APOLLO_ROUTER_LOG=] [default: info]

    -s, --supergraph <SUPERGRAPH_PATH>
            Schema location relative to the project directory [env: APOLLO_ROUTER_SUPERGRAPH_PATH=]

    -V, --version
            Display version and exit

SUBCOMMANDS:
    config    Configuration subcommands
    help      Print this message or the help of the given subcommand(s)

Who is Apollo?

Apollo is building software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with:

  • Apollo Studio – A free, end-to-end platform for managing your GraphQL lifecycle. Track your GraphQL schemas in a hosted registry to create a source of truth for everything in your graph. Studio provides an IDE (Apollo Explorer) so you can explore data, collaborate on queries, observe usage, and safely make schema changes.
  • Apollo Federation – The industry-standard open architecture for building a distributed graph. Compose and manage your graphs using Rover and then use Apollo Router to query plan and route requests across multiple subgraphs.
  • Apollo Client – The most popular GraphQL client for the web. Apollo also builds and maintains Apollo iOS and Apollo Android.
  • Apollo Server – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.

Learn how to build with Apollo

Check out the Odyssey learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the Apollo Community to interact with and get technical help from the GraphQL community.

Design principles

The development of the Apollo Router is driven by the following design principles that inform architecture decisions and implementation.

Correctness: the router strives to be the most correct implementation of GraphQL and Federation, we care about testing and documenting everything implied by the specification, up to failure cases. The router’s behavior should follow the principle of least surprise for developers.

Reliability: the router is a critical part of GraphQL APIs, so it must be one of the strongest parts of the infrastructure. This implies stability in its behavior (no crashes, infinite loops, leaks, etc), availability (predictable latency, RAM and CPU usage, scalability) and observability (metrics, alerts). It should give strong confidence to infrastructure people that they can learn its limits and operate it safely.

Safe experimentation: the router will support all the future work around Federation, so it must allow new ideas and explorations without disturbing existing features. The project is still in movement, we cannot allow it to crystallize too early, while still following the principles of correctness and reliability.

Usability: the router must be simple to operate. Prefer extensibility over configuration options, and ensure that the user has enough information to help themselves when things go wrong. For example:

  • Common environmental misconfiguration should be detected and surfaced to the user in the form of mitigation steps.
  • User supplied extensions should be observable and flagged when they cause performance issues. Tell the users how much time an extension is consuming per request and why.

Architecture

The following principles guide :

Unit testability: all new code should be unit testable, or have a good reason why it is not. This may mean spending a little extra time to ensure code is testable in isolation. Do not rely solely on integration testing.

Integration test suite: we will integrate with the gateway’s test suite and help improve it to test all aspects of the specifications. In particular, this test suite will verify failure cases like invalid queries or network problems. Integration tests must be bullet proof, and must not fail in the case of slow test execution or race conditions.

Measurement and learning: reliability has to be tested and measured, through benchmarks, profiling, and through exploration of the router’s limits. We want to learn how to operate the router and what is its nominal point. To that end, the router shall be instrumented in detail, allowing us to measure how code changes affect it. We especially take care of measuring the overhead of new features, to minimize latency and resource usage.

Extensibility: by allowing extensions and directives to modify the router’s behavior, we can run experiments and test new features without impacting specific queries or endpoints. Additionally, these experiments are easy to deactivate at runtime (feature flags, canaries, etc).

Project maintainers

Apollo Graph, Inc.

Licensing

Source code in this repository is covered by the Elastic License 2.0. The default throughout the repository is a license under the Elastic License 2.0, unless a file header or a license file in a subdirectory specifies another license. See the LICENSE for the full license text.