grafbase

Breaking

• The deploy, build, environment, init, logs, start, link, unlink and dev commands have been removed as a part of sunsetting standalone graphs
  • branch
    • The list subcommand for the branch command has been removed
  • create
    • create no longer accepts a --mode flag
  • introspect
    • The url positional argument on introspect is now required
    • The dev flag on introspect has been removed
  • publish
    • The graph reference posiitional argument on publish is now required
    • The dev flag on publish has been removed
    • The dev_api_port flag on publish has been removed
  • check
    • The subgraph_name argument on check is now required

Features

• publish now supports a message flag to provide a message when publishing a graph

Features

Breaking: the Grafbase Gateway does not allow batching by default. To enable batching, set the gateway.batching.enabled option to true in the gateway configuration. You can also limit the number of requests that can be batched by setting the gateway.batching.limit option to a number greater than 0. If the limit is not set, the default is to have no limit which might allow denial of service attacks, so be careful when setting this option.

[gateway.batching]
enabled = true
limit = 5

documentation

Fixes

• Improved tracing to track subgraph HTTP requests as spans, removing unnecessary instrumentation that spammed traces.
• Removed unnecessary fuel consumption tracking in hooks, making CPU heavy hooks more efficient.

Chores

• Updated dependencies across the project, including a major update to crucial libraries and tools.

Features

• Support specifying access log rotate size as a string with a unit such as:

[gateway.access_logs]
enabled = true
path = "./logs"
rotate.size = "200MiB"

Fixes

• Subgraph requests now use the Accept: application/graphql-response+json; charset=utf-8, application/json; charset=utf-8 header instead of Accept: application/json, following the Graphql-over-HTTP spec recommendation.
• Fix an stack overflow in certain debug logs (#2136)
• Return null for inaccessible enum values (#2116)
• Enforce inaccessibility of inaccessible arguments (#2117)
• Support inline fragments in the fields argument of @requires (#2166)
• Support inline fragments in the selections in @provides (#2149)
• Fix certain subgraph queries when using unions or interfaces (#2160)
• Fix planning of interfaces if keys are not provided (#2151)

Fixes

• Infinite recursion with certain schemas.

Access Log Rotation by Size

In version 0.12.0, we introduced a streamlined method for logging and storing access information using the Gateway Hooks. In this version we rewrote the logger into a faster and more minimal version. Now, you can rotate the log based on file size, configurable as follows:

[gateway.access_logs]
enabled = true
path = "./logs"
rotate.size = 10_000_000 # bytes

The rotation mechanism is now standardized. The active log file is named access.log. When a rotation occurs, we rename this file to access.log.X, where X is the timestamp of the original log file's creation.

Fixes

• Enforced inaccessibility of inaccessible arguments.
• Engine returns null for inaccessible enum values.
• Parser correctly handles null values.
• Replaced the parser crate with a faster alternative, improving performance for parsing large schemas.

Features

Access logs through hooks

We are announcing access logs, which are a bit different from the common logs the gateway outputs to the standard output.

Access logs are always stored into a file, and generated through custom WebAssembly hook functions. This allows you to define what gets logged and when, and in which format the logs are written.

The feature consists the following configuration options:

[gateway.access_logs]
enabled = true
path = "/path/to/logs"
rotate = "daily"
mode = "blocking"

Read more on the configuration.

In addition to the configuration, to generate access logs you must implement one or more response hook functions and provide them as WASI hooks (read more about WASI hooks).

The following hooks are now available to implement:

• on-subgraph-response gets called after requesting a subgraph.
• on-operation-response gets called after an operation is completed.
• on-http-response gets called just before an HTTP response is sent back to the client.

The hooks provide necessary information and metrics on the operation, and the user must define what to log based on this information. The log format can be anything that can be serialized as bytes, ranging from just text, JSON, CSV or XML.

Read more on access logs with response hooks.

Better logs with pretty formatting by default in the terminal

It can be forced with --log-style pretty, the previous format is available with --log-style text. Now when using --log debug, the executed subgraph query with variables and the response are shown.

Fixes

• federated dev:
  • Less strict handling of Accept header (#2051)
  • Remove subgraph urls from subgraph request errors (#2052)
  • Fix introspection of defaults of enum type (#2057)
• fix grafbase create --mode=self-hosted outside of project context (#2054)

Fixes

• Fix crash on gateway startup when passing federated SDL with @join__type on an interface. See the pull request description for more details: https://github.com/grafbase/grafbase/pull/2064

Features

• The gateway now implements tracing propagation: it can receive tracing context (trace id, parent span id, additional context) from headers in the requests it receives, and pass that context on to subgraphs when it makes requests to them. That enables correlation of requests across network boundaries.

  There are different standards for propagation. In this release, we implement Trace Context and Baggage — the standard OpenTelemetry mechanisms for trace parent and trace context propagation respectively —, and AWS X-Ray. Multiple mechanisms can be combined.

  This is configurable through the telemetry.tracing.propagation key in the configuration. For example:

  [telemetry.tracing.propagation]
  trace_context = true
  baggage = true
  

  In addition, a new option named parent_based_sampler appears in telemetry.tracing:

  [telemetry.tracing]
  sampling = 0.2
  parent_based_sampler = true
  

  When enabled, the gateway will honor sampling configuration passed in through the sampled header (W3C spec), then fall back to its own configuration. This option is disabled by default and should not be enabled if the gateway is exposed directly to the internet, since malicious clients could increase load on the gateway by forcing traces to be recorded.

  See also the documentation

Fixes

• Correct handling of operationName.
• nbf claim was required in JWT auth. Now it is only validated if present.
• Gateway does not require the Accept header anymore and will default to application/json if absent.
• Fix deadlock case with OpenTelemetry

Fixes

• cli: make grafbase.config.ts optional for gb create --mode=self-hosted. The configuration is not relevant in fully self-hosted deployments. (#2045)

Features

• We added a bunch of new metrics to the gateway. (docs)

Fixes

• Using --log=trace would panic.
• Gateway configuration defaults were not consistently applied. When not providing any TOML configuration path, it led request_body_limit to have a default value of 0 refusing all requests.
• @join__field is now optional for non-federated types: no @join__type directive with a key argument.

Fixes

• The 0.9.2 release of the gateway accidentally included changes that will be released with 0.10.0. This version only includes the fixes present in the changelogs of versions 0.9.1 and 0.9.2.

Fixes

• Limit the grace period to 3 seconds for graceful shutdowns (https://github.com/grafbase/grafbase/pull/2026)

Features

• The grafbase create command now supports creating self-hosted graphs, either through the interactive flow or through the --mode=self-hosted flag. (#2018)

Fixes

• Terminology improvements for consistency in multiple parts of the CLI ("project" -> "graph")

Fixes

• Fix rendering of multiline strings in federated graph SDL (https://github.com/grafbase/grafbase/pull/2021)
• Fix excessive strictness in the Content-Type headers we accepted following the strict implementation of Graphql-over-HTTP. Content-Type headers with parameters (for example "application/json;charset=utf-8") are now accepted again. (https://github.com/grafbase/grafbase/pull/2023)

Breaking Changes

• Gateway now requires the Accept header as recommended in the GraphQL-over-HTTP specification (spec. Use application/json to have the same behavior as previous versions.

Features

• Added entity caching (docs)
• Follow GraphQL-over-HTTP specification (spec, errors doc)
• Add support for using a SSE connection to a subgraph for subscriptions. If the websocket URL is absent, we will start a SSE connection with following header Accept: text/even-stream,application/json;q=0.9.
• Add request_body_limit in the configuration, which defaults to 2MiB. The gateway returns a 413 error if the request exceeds the limit.

Fixes

• Improved subgraph request performance.
• Better error message when graph ref contains the account name.
• Gateway timeout wasn't applied when executing a query or mutation with a streaming response. The operation preparation (parsing, validation, planning) is always subject to the timeout.

Features

• The CLI gained a new grafbase branch create to create branches on self-hosted graphs (#1997)

Fixes

• Fix auto-detection of JWKS urls for issuers with subpaths (#1927)
• Fix the implementation of KvStoreInner (#1938)

Features

• Add support for dynamic rate limit configurations with hot reload (#1963)
  • Introduce dynamic rate limiting with the capability to hot reload configurations without a server restart.
  • Allow configuration of hot reload in gateway server setup.
  • Documentation
• Add support for retries in subgraph requests (#1917)
  • Define retry settings per subgraph or for all subgraphs.
  • Documentation
• Allow specifying a global timeout for all subgraphs (#1975)
  • This is in addition to defining a timeout per specific subgraph.
  • Documentation

Features

• Rate limit with Redis (docs)
• Post execution authorization hooks (docs example)

Bug fixes

• Don't forward hop-by-hop headers to subgraphs
• Forward doesn't duplicate headers anymore.
• Apply global header rules only once
• Optional global rate limits

Fixes

• Remove rogue dbg