[RFC] Management API and fine-tuned controls

Background

This project aims to mitigate concerns about utilizing GraphOS Uplink in a high-uptime environment. For some customers, updating on a set poll interval is not sufficient- the time may differ between days or even specific business hours, so it needs to be highly cached during some windows, but not others.

To help alleviate these concerns, we’re proposing a few new additions to the project.

Proposal

We are proposing the following improvements to uplink-relay:

Allowing for the polling behavior to be configured to a fixed interval in seconds (e.g. every 30 seconds)
Allowing for the polling behavior to be set via Cron expressions
Support to pin uplink-relay to specific versions of both a supergraph and persisted query manifest
Creating a new management API to supplement/replace the existing update mechanisms

Cron Expressions Support

Cron expressions are used for many different applications but are commonly associated with routine, consistent work that needs to be performed. For example, many utilize this to automate HTTPS certificate rotations or generally run an operation on some fixed cadence.

Due to the ubiquity of cron and associated documentation, it feels a natural fit for a more fine-tuned way to handle updates with uplink-relay.

Furthermore, we’ll be looking to add support for multiple expressions via a YAML array to enable more complex polling configurations.

Example YAML (not reflective of full feature or development)

poll_interval: '45 23 * * 6' # Runs at 23:45 (11:45 PM) every Saturday.

Pinning Schema and Persisted Query Manifest Versions

In larger enterprise organizations, it is common to utilize a blue/green deployment system. This method of deployment requires that a given application configuration can be fixed to a point in time.

Blue/green deployments, however, have run into roadblocks when using Uplink, as it serves the latest version of a given schema at all times. To mitigate this, it is common for said larger organizations to manage multiple graphs, making them effectively represent these environments. While this works, it is imperfect.

To better support this, uplink-relay is looking to add support for two new configuration options:

launchID, which represents the ID for a given Launch
persistedQueryManifestID, which represents the manifest ID

Management API

Cron expressions may not address all needs, nor do they resolve non-interval update requirements. We’re proposing the creation of a new management API that’ll enable users to perform critical functions on uplink-relay.

This API will be GraphQL-based, but will initially be planned to support:

Purging cache entries for a given type (or types) of operations
- This will enable organizations to remove cached supergraphs or persisted query manifests, for example
Forcing an update of an operation, such as updating the supergraph or persisted query manifest
Updating pinned versions of a supergraph/persisted queries manifest (see above)

For the schema, we will be exposing a new endpoint (/graphql) to support this. The proposed schema is located here.

apollosolutions / uplink-relay