Release Notes

This release introduces Caliban Gateway, a new module that serves several GraphQL services behind one endpoint. It is an alternative to Apollo Router, Hive Router and Cosmo Router.

This is a large feature that has been in the works for a long time, with a first PoC written more than 3 years ago! The module is still very fresh, even though it shows excellent performance 🚀. Try it and let us know if you find any bugs or anything that should be improved.

The release also includes a few bug fixes and a big speedup for validating fragment-heavy queries.

Caliban Gateway

caliban-gateway combines Apollo Federation subgraphs, plain GraphQL services and local Caliban APIs into a single graph. It can also load an existing supergraph.

:::scala
val gateway = Gateway.compose(
  Subgraph.federation("products", url"http://products:8080/graphql"),
  Subgraph.graphql("reviews", url"http://reviews:8080/graphql")
)

for {
  interpreter <- gateway.interpreter
  _           <- QuickAdapter(interpreter).runServer(4000, "/graphql")
} yield ()

At startup, the gateway fetches both schemas and composes them. Clients then query localhost:4000/graphql as if it were a single service. The gateway can also:

• plan each operation across subgraphs, with batched, multi-hop entity joins, and show the plan with explain
• run queries, mutations and subscriptions
• rename or hide types, fields and arguments in the public schema
• reload subgraph schemas while the server keeps running
• run hooks for persisted documents, authorization and subgraph headers
• report ZIO metrics, with tracing available in the caliban-gateway-tracing module
• apply timeouts, retries, authentication and request limits

It passes all 199 cases of the Federation Gateway Audit, which now runs in CI. Check the documentation to get started, and the gateway-examples project for local, remote, mixed and Federation setups.

New Features

• Added Caliban Gateway by @ghostdogpr in https://github.com/ghostdogpr/caliban/pull/3103 with help from @paulpdaniels
• Added HttpConfig to the Quick adapter (QuickAdapter#configureHttp) to limit request, upload and response body sizes by @ghostdogpr in https://github.com/ghostdogpr/caliban/pull/3103

Note: the Quick adapter now rejects request bodies larger than 1 MB by default (16 MB for uploads and responses). Use configureHttp to raise these limits.

Bug Fixes

• Fixed fragment field-merging validation missing conflicts between nested fields by @ghostdogpr in https://github.com/ghostdogpr/caliban/pull/3085
• Validated values nested inside @oneOf inputs by @kroeberk in https://github.com/ghostdogpr/caliban/pull/3101
• Fixed @defer over WebSocket by @ghostdogpr in https://github.com/ghostdogpr/caliban/pull/3103
• Fixed several HTTP compatibility issues in the Quick adapter (content negotiation, request media types, error status codes) by @ghostdogpr in https://github.com/ghostdogpr/caliban/pull/3103

Performance Improvements

• Reduced allocations in fragment field-merging validation, making it up to 2.6x faster on fragment-heavy queries by @ghostdogpr in https://github.com/ghostdogpr/caliban/pull/3085

Other Small Improvements

• Moved RemoteSchema from caliban-tools to core, in the same package, so the gateway doesn't depend on tools by @ghostdogpr in https://github.com/ghostdogpr/caliban/pull/3103