ghostdogpr/caliban

Caliban is a high-performance GraphQL library for Scala that provides a complete stack for building and consuming GraphQL APIs. It features automatic schema derivation from Scala types, support for modern execution patterns like incremental delivery and subscriptions, and adapters for major HTTP frameworks including Akka, http4s, Pekko, and Play. The system also includes a type-safe code generation engine for creating client libraries and integrates with Apollo Federation for distributed graph architectures.

37 changes.

The project underwent a major architectural shift by migrating the core library to ZIO 2, introducing a new execution configuration, error model, and support for incremental delivery via @defer and @stream directives. This period also saw the introduction of a comprehensive code generation tool, a dedicated GraphQL client, and extensive interop modules for Cats Effect, Monix, and Tapir-based HTTP adapters.

32 changes.

The project migrated its core and examples to ZIO, introducing semi-auto schema derivation via Magnolia 1 and comprehensive Scala 3 macro support for performance and compile-time validation. This period also established robust observability through Apollo Federation Tracing, expanded framework interoperability with Tapir adapters, and added file upload capabilities alongside extensive client code generation features.

29 changes.

This period focused on expanding Caliban's ecosystem with comprehensive Apollo Federation v2 support, including new directives and a compatibility testing tool. It introduced high-performance JSON encoding, OpenTelemetry tracing, and a schema transformation system, while adding new server adapters for Pekko HTTP and zio-http with WebSocket capabilities.

7 changes.

The project restructured the sbt codegen plugin into modular components with CLI support and expanded test coverage for code generation options and client output. Concurrently, new infrastructure for federated GraphQL stitching was introduced, including cache invalidation and remote schema resolution capabilities, alongside core library updates for Scala 2.13 compatibility.

Introduces a new \ApolloFederatedTracing\ wrapper in the federation module that implements the Apollo Federation metrics specification. This feature allows federated services to expose tracing data via the \ftv1\ extension in GraphQL responses, enabling better observability and performance monitoring for federated graph architectures. The implementation includes an overall wrapper to capture request timing and a field wrapper to track individual field execution, with an optional configuration to exclude pure fields from tracing to improve performance.

federation/src/main/scala/caliban/federation/tracing · high confidence

A new apollo-compatibility module has been added to provide a federated subgraph implementation for verifying compatibility against the Apollo Federation Subgraph Specification. This tool includes a Scala-based server (using Caliban and ZIO) that exposes a GraphQL schema with Federation v2.3 directives, custom directives, and various entity resolution patterns. It is designed to be run via Docker (exposing port 4001) and can be used with the @apollo/federation-subgraph-compatibility CLI to test other subgraphs against the spec.

apollo-compatibility · high confidence

Introduces a new reporting subsystem that allows Caliban servers to automatically report their GraphQL schema to Apollo Studio. This includes the ReportingDaemon for managing the reporting lifecycle, SchemaReporter for handling the HTTP communication and error handling (including retries for transient errors), and client-side GraphQL mutation definitions for the Apollo reporting API.

reporting/src/main · high confidence

The calibantotapir example now demonstrates how to unify GraphQL and REST endpoints using Tapir, including a new GraphiQL UI accessible at /graphiql, Swagger documentation at /docs, and a sample REST endpoint at /example alongside the standard GraphQL routes.

examples/src/main/scala/example/calibantotapir · high confidence

The core module now includes a new interop layer for Circe, introducing a \CirceJson\ trait that provides \Schema\ and \ArgBuilder\ instances for Circe's \Json\ type. This allows users to directly use Circe's \Json\ as a GraphQL scalar, enabling seamless encoding of GraphQL input values into Circe JSON structures and decoding of response values back into them.

core/src/main/scala/caliban/interop/circe · high confidence

Users can now use fs2.Stream types directly in Caliban GraphQL schemas. This change introduces new implicit schemas in the caliban.interop.fs2.implicits package that allow fs2 streams to be resolved as GraphQL subscriptions or data streams, bridging the gap between ZIO's ZStream and fs2's Stream abstraction for reactive data handling.

interop/cats/src/main/scala/caliban/interop/fs2 · high confidence

The examples directory now includes a complete Federation v2 implementation featuring Character and Episode services. This example demonstrates how to define federated schemas using \GQLKey\ annotations for entity resolution, configure standard wrappers like tracing and timeouts, and run separate GraphQL servers for each subgraph on distinct ports.

examples/src/main/scala/example/federation/v2 · high confidence

A new example file (ExampleMonixInterop.scala) has been added to the examples directory, illustrating how to integrate Caliban with Monix. The example demonstrates constructing a GraphQL API using Monix's Task for queries and Observable for subscriptions, and shows how to execute these operations and handle the resulting reactive streams within a Monix TaskApp environment.

examples/src/main/scala/example/interop/monix · high confidence

Introduces the \MonixInterop\ module, enabling Caliban users to work with Monix effects. This includes utilities to convert ZIO-based GraphQL interpreters into Monix \Task\ for async execution and schema validation, as well as schema definitions that allow GraphQL fields to return Monix \Task\ (for queries) and \Observable\ (for subscriptions), seamlessly bridging ZIO streams with Monix reactive types.

interop/monix/src/main/scala/caliban/interop/monix · high confidence

Users can now integrate Caliban with the Monix library via the new \caliban.interop.monix.implicits\ package. This adds implicit classes to \GraphQLInterpreter\ and \GraphQL\ that enable asynchronous execution returning Monix \Task\ and \Observable\ types, and provides implicit schema conversions for \Task\[A\]\ and \Observable\[A\]\ fields, allowing Monix-based effects to be used directly in GraphQL schemas.

interop/monix/src/main/scala/caliban/interop/monix/implicits · high confidence

New tracing components (SchemaTracer, FieldTracer, TracingWrapper) have been added to integrate OpenTelemetry into Caliban's execution pipeline. SchemaTracer creates spans for GraphQL operations, adhering to semantic conventions for span naming (e.g., 'query \<name\>') and masking sensitive argument values (lists, enums, booleans, strings) to prevent data leakage in traces. FieldTracer wraps individual field resolution, ensuring proper span status handling (including error states) via ZIO's acquire-release pattern. These wrappers are composed in TracingWrapper to provide a unified tracing experience for GraphQL requests.

tracing/src/main · high confidence

Caliban now provides a Play JSON integration module, allowing users to seamlessly use Play's \JsValue\ type within GraphQL schemas. This change introduces a new \PlayJson\ trait that supplies implicit \Schema\ and \ArgBuilder\ instances for \JsValue\, enabling automatic conversion between Caliban's internal value representations and Play JSON structures for both input arguments and response values.

core/src/main/scala/caliban/interop/play, core/src/main/scala/caliban/interop/zio · high confidence

This change introduces a new \caliban.relay\ package that provides first-class support for the Relay Connection spec. It adds a \Base64Cursor\ implementation for encoding pagination offsets, along with \Connection\, \PageInfo\, and \Edge\ types to model paginated results. The \PaginationArgs\ module handles validation for forward (\first\/\after\) and backward (\last\/\before\) pagination, returning structured errors via \Exit\. Additionally, it implements the global identification spec through \NodeResolver\ and \RelaySupport\, allowing users to define a \Node\ interface and resolve objects by ID using a \TypeResolver\. This enables clients to fetch individual nodes via a standard \node(id: ID!)\ query.

core/src/main/scala/caliban/relay · high confidence

This change introduces a new interop module that bridges Caliban with the cats-effect ecosystem. It provides implicit classes to convert existing Caliban components into cats-effect types: \GraphQLInterpreter\ gains \executeAsync\ and \checkAsync\ methods to return results wrapped in a generic effect \F\[\_\]\, \GraphQL\ gains an \interpreterF\ method to create interpreters effectfully, and a new \Schema\ instance is provided to handle fields returning \F\[A\]\ types.

interop/cats/src/main/scala/caliban/interop/cats/implicits · high confidence

Introduces a new jsoniter-based codec for serializing and deserializing GraphQL input and response values. This implementation provides a high-performance alternative to existing JSON libraries by leveraging the jsoniter-scala library, including specific optimizations for handling nested structures and preventing stack overflows via recursion depth limits.

core/src/main/scala/caliban/interop/jsoniter · high confidence

The examples directory now includes a new optimization showcase that contrasts a naive GraphQL implementation with an optimized one using ZIO Query. The naive example demonstrates a waterfall pattern resulting in 47 requests, while the optimized example utilizes batched data sources to reduce this to just 8 requests, illustrating how to structure resolvers for better performance.

examples/src/main/scala/example/optimizations · high confidence

The examples directory now includes configuration files for running Apollo Federation gateways. A new Play example configuration file (application.conf) has been added, alongside JavaScript implementations for both the original Apollo Federation gateway (gateway/gateway.js) and the Federation V2 gateway (gateway\_v2/gateway.js). These files demonstrate how to set up gateway servers to aggregate the 'episodes' and 'characters' subgraphs, with the V2 example utilizing the newer @apollo/server package and IntrospectAndCompose for schema composition.

examples/src/main/resources · high confidence

A new \reports.proto\ file has been added to the federation module, defining the schema for federation tracing data. This includes message structures for \Trace\, \Node\, \QueryPlanNode\, and related metadata (such as cache policies, HTTP details, and error locations), enabling the collection and reporting of detailed execution traces across federated GraphQL services.

federation/src/main/protobuf · high confidence

The project now includes a CircleCI configuration that establishes a continuous integration pipeline for building and testing the codebase. The pipeline runs linting, unit tests, and scripted tests across multiple Scala versions (2.12, 2.13, and 3.3) and JDK versions (17 and 21). It also includes specific jobs for testing Scala.js and Scala Native targets, with a dedicated script to install a supported version of Clang (version 19) to ensure stable compilation for Scala Native.

.circleci · high confidence

This change introduces the complete Caliban GraphQL client library for Scala, providing the core infrastructure for executing GraphQL queries and mutations. It includes type-safe argument encoding (ArgEncoder) and scalar decoding (ScalarDecoder) for standard types, UUIDs, and Java 8 temporal types (Instant, LocalDate, etc.), as well as support for dropping null values in input objects. The client features a composable SelectionBuilder API for constructing queries, automatic rendering of GraphQL operations (including fragments, aliases, and directives), and HTTP execution via sttp with jsoniter for JSON serialization. It also exposes GraphQL response extensions and provides a dedicated IntrospectionClient for schema introspection.

client/src/main/scala/caliban/client · high confidence

This change adds the \caliban.federation\ module, enabling Caliban schemas to be consumed by GraphQL Federation gateways. It introduces \EntityResolver\ for materializing types from their 'any' representation, \FederationSupport\ for augmenting schemas with \\_service\ and \\_entities\ queries, and specific implementations for Federation V1 (\FederationV1\) and V2 (\FederationV2\). The module exposes versioned instances (v1, v2\_0 through v2\_13) in the \federation\ package object, allowing users to opt into specific federation specs and their associated directives (such as \@key\, \@provides\, \@requires\, and \@external\).

federation/src/main/scala/caliban/federation · high confidence

The codegen module now provides a unified code generation engine for Caliban GraphQL clients and schema definitions, featuring a new default scalafmt configuration for Scala 3 (version 3.8.2) and a comprehensive set of generation options. Users can now configure the generated code via \CalibanCommonSettings\ and \Options\, including specifying a custom effect type, enabling abstract effect types, mapping scalars, adding imports, splitting generated files, and controlling enum extensibility. The client writer supports advanced features like union and interface handling, deprecated field exclusion, and view generation, while the schema writer supports derives and environment-specific schema derivation. The system also handles reserved keywords safely and allows introspection from URLs or local files.

codegen/src/main · high confidence

Adds a new \client-laminext\ module providing a JavaScript/Scala client for GraphQL queries, mutations, and subscriptions using the Laminext library. This integration enables reactive UI updates via \EventStream\ for HTTP requests and WebSocket-based subscriptions, supports JSON serialization via \jsoniter\, and includes a demo application to illustrate usage.

client-laminext · high confidence

This change establishes the foundational Abstract Syntax Tree (AST) for the Caliban GraphQL library by adding new case classes in the \caliban.parsing.adt\ package. It defines the structural types for GraphQL documents, including \Definition\ (with \ExecutableDefinition\ for operations and fragments, and \TypeSystemDefinition\ for schemas, directives, and type definitions like Object, Interface, Enum, etc.), \Directive\ (with support for introspection flags and helper methods for deprecation and one-of checks), \Document\ (with lazy, cached accessors for filtering definitions by type), \Selection\ (for fields, fragment spreads, and inline fragments), \Type\ (for named and list types with nullability handling), \VariableDefinition\, \LocationInfo\, and \OperationType\. These types provide the internal representation used by the parser and other components to model GraphQL schemas and queries.

core/src/main/scala/caliban/parsing/adt · high confidence

Caliban now supports file uploads via the new \caliban.uploads\ module, introducing \Upload\, \FileMeta\, and \GraphQLUploadRequest\ types to handle multipart file data. The implementation remaps GraphQL variables to reference uploaded files by name and validates nested variable values, ensuring that file references are correctly injected into complex input structures (objects and lists) at the specified path.

core/src/main/scala/caliban/uploads · high confidence

Caliban now provides a new \Transformer\ framework in the core module, allowing users to programmatically modify the GraphQL schema and its resolution logic. This feature includes built-in transformers for renaming types (\RenameType\), fields (\RenameField\), and arguments (\RenameArgument\), as well as excluding specific fields from the schema (\ExcludeField\). These transformers can be composed and applied to customize the schema output without modifying the underlying data models.

core/src/main/scala/caliban/transformers · high confidence

Introduces a new \AkkaHttpAdapter\ that implements HTTP, upload, WebSocket, and GraphiQL services for the Akka HTTP framework. This adapter leverages the Tapir integration to provide a unified interface for serving GraphQL APIs, including support for subscriptions via WebSocket and interactive documentation via GraphiQL.

adapters/akka-http/src/main · high confidence

Added a new example demonstrating a GraphQL client implementation using Caliban and sttp client 4. The example defines type-safe selection builders for querying characters (including union types for roles like Captain, Pilot, Engineer, and Mechanic) and performing mutations, executed via a ZIO-based HTTP client against a local GraphQL endpoint.

examples/src/main/scala/example/client · high confidence

Added a new example demonstrating GraphQL schema stitching by resolving fields from a remote GitHub GraphQL API. The example uses Caliban's RemoteResolver to fetch the remote schema via introspection, configure HTTP headers for authentication, and map remote types to local types, serving the stitched API on port 8080 with GraphiQL and WebSocket support.

examples/src/main/scala/example/stitching · high confidence

This change introduces a new \PekkoHttpAdapter\ in the \adapters/pekko-http\ module, enabling users to run Caliban GraphQL services on Apache Pekko HTTP. The adapter provides methods to create HTTP routes for standard queries (\makeHttpService\), file uploads (\makeHttpUploadService\), and WebSocket subscriptions (\makeWebSocketService\). It also includes support for serving the GraphiQL UI (\makeGraphiqlService\), with an overloaded method that accepts a \wsPath\ parameter to configure WebSocket subscription endpoints. The implementation bridges Caliban's ZIO-based interpreters with Pekko's streaming and HTTP capabilities via the Tapir adapter layer.

adapters/pekko-http/src/main · high confidence

Added new example applications for the Pekko HTTP adapter that demonstrate modern usage patterns, including built-in GraphiQL endpoints and WebSocket support for subscriptions. The ExampleApp showcases how to configure HTTP, WebSocket, and GraphiQL routes together, while AuthExampleApp illustrates how to implement custom authentication logic using Tapir interceptors.

examples/src/main/scala/example/pekkohttp · high confidence

Adds a new Play adapter that integrates Caliban with the Play Framework by leveraging Tapir for HTTP routing and Apache Pekko Streams for handling requests, uploads, and WebSocket subscriptions. This allows users to serve GraphQL APIs, including GraphiQL UI and subscription endpoints, within a Play application using the modern Pekko ecosystem.

adapters/play/src/main · high confidence

The \caliban-quick\ module introduces a new adapter built on zio-http, providing a lightweight alternative to the existing Tapir-based adapters. This new adapter allows users to serve GraphQL APIs with built-in support for WebSocket subscriptions, file uploads, and the GraphiQL UI. It exposes a \QuickAdapter\ class that generates \Routes\ for API, upload, and WebSocket endpoints, along with a convenience \runServer\ method for quick setup. The implementation includes a dedicated \GraphiQLHandler\ to serve the UI from CDN and handles WebSocket protocol negotiation, enabling real-time subscriptions directly through the zio-http server.

adapters/quick/src/main/scala/caliban · high confidence

A new \Macros.scala\ file introduces Scala 3-specific compile-time macros to enhance schema derivation. Users can now derive GraphQL fields directly from case class methods using the \@GQLField\ annotation or automatically for all methods via \@GQLFieldsFromMethods\. The macros also provide specialized logic to correctly identify excluded fields (\@GQLExcluded\) and detect enum fields, ensuring accurate schema generation for these specific patterns in Scala 3.

core/src/main/scala-3/caliban/schema/macros · high confidence

The \interop/tapir\ module now provides a complete set of new interpreters (\HttpInterpreter\, \HttpUploadInterpreter\, \WebSocketInterpreter\) that expose Caliban GraphQL capabilities as Tapir server endpoints. This enables users to run GraphQL servers using the Tapir framework, supporting standard HTTP POST/GET requests, GraphQL file uploads via multipart forms, and WebSocket subscriptions with automatic subprotocol negotiation (preferring \graphql-ws\ over legacy protocols). The implementation includes specific handling for content-type headers, query parameter encoding, and configurable request interceptors and path prepending.

interop/tapir/src/main · high confidence

Added a new example demonstrating how to convert Tapir REST endpoints into Caliban GraphQL schemas, featuring book management operations (add, delete, list) with JSON serialization via jsoniter. The example application now includes a GraphiQL interface accessible at /graphiql alongside the GraphQL API endpoint, allowing users to interact with the generated schema directly in the browser.

examples/src/main/scala/example/tapirtocaliban · high confidence

The \caliban.ws\ package now includes a new \Protocol.scala\ file implementing the \graphql-transport-ws\ protocol (alongside legacy support), defining the message types, connection lifecycle, and subscription handling logic. A new \WebSocketHooks.scala\ trait and companion object provide extensibility points for customizing WebSocket behavior, such as \beforeInit\, \afterInit\, \onMessage\, \onPing\, \onPong\, and \onAck\ callbacks. A new \package.scala\ defines the \CalibanPipe\ type alias used by the protocol implementation. This change introduces the core infrastructure for WebSocket subscriptions within the Caliban core module.

core/src/main/scala/caliban/ws · high confidence

The federation example has been rewritten to use ZIO and Caliban's federation v1 support, replacing the previous implementation. This new example demonstrates a federated GraphQL architecture with separate Character and Episode services, featuring entity resolution, subscriptions for character deletion events, and standard API wrappers like tracing and query limits.

examples/src/main/scala/example/federation · high confidence

This release introduces new infrastructure for federated GraphQL stitching in the \stitching\ module. A \CacheInvalidator\ component has been added to allow subgraphs to invalidate cached data via HTTP POST requests, supporting invalidation by subgraph name, type, or cache tag with secret-based authentication. Additionally, core stitching abstractions have been refactored: \RemoteResolver\ now handles the full pipeline for querying remote GraphQL endpoints (including improved error handling for HTTP and upstream GraphQL errors), \RemoteSchemaResolver\ provides a way to proxy remote schemas as local GraphQL operations, and new types like \PartialRemoteSchema\ and \ResolveRequest\ support more flexible schema composition.

stitching · high confidence

A new \interop/cats\ module has been added to provide bidirectional conversion between ZIO effects (\RIO\) and Cats Effect types (\F\). This includes \CatsInterop\, \ToEffect\, and \FromEffect\ traits that allow executing GraphQL queries within a Cats Effect context using a \Dispatcher\. It also introduces \InjectEnv\ to support contextual interop, enabling the injection of ZIO environments into effects like \Kleisli\ or \IO\ with \IOLocal\, facilitating seamless integration between ZIO and Cats Effect-based applications.

interop/cats/src/main/scala/caliban/interop/cats · high confidence

Added three new example files in the Cats interop directory: ContextualCatsInterop and ContextualCatsInteropIO demonstrate propagating a custom LogContext between cats-effect and ZIO using Cats MTL's Local and CatsInterop.contextual, while ExampleCatsInterop shows integrating FS2 streams with ZIO streams for GraphQL subscriptions and queries.

examples/src/main/scala/example/interop/cats · high confidence

The http4s adapter has been rewritten to leverage the Tapir library for defining and interpreting HTTP and WebSocket routes. This change introduces new factory methods (such as \makeHttpService\, \makeHttpUploadService\, and \makeWebSocketService\) that bridge Caliban's interpreters with http4s server endpoints via Tapir's \Http4sServerInterpreter\ and \ZHttp4sServerInterpreter\. It also adds support for serving the GraphiQL UI from a CDN and provides utility functions to extract request context into ZIO layers, enabling more flexible middleware and environment management for http4s-based GraphQL servers.

adapters/http4s/src/main · high confidence

Added four new example applications in the http4s module that showcase the updated Tapir-based adapters. AuthExampleApp and AuthExampleAppF demonstrate how to integrate authentication middleware with ZIO and Cats Effect respectively, while ExampleApp and ExampleAppF provide standard server setups with CORS support and GraphiQL endpoints using the new HttpInterpreter and WebSocketInterpreter components.

examples/src/main/scala/example/http4s · high confidence

This change introduces a suite of new wrapper components in the core library to enhance observability, performance, and query management. The \ApolloPersistedQueries\ wrapper implements the Apollo Persisted Queries spec with an in-memory cache to reduce parsing overhead for repeated queries. \ApolloTracing\ adds detailed timing information to response extensions, following the Apollo Tracing format, and allows disabling tracing for pure fields to improve performance. The \Caching\ wrapper introduces a \@cacheControl\ directive and response extensions to support HTTP caching strategies based on field and type hints. \CostEstimation\ provides a \@cost\ directive and validation wrappers to estimate and limit query complexity, preventing overly expensive operations. \FieldMetrics\ records per-field execution counts and durations as Prometheus-compatible histograms. Finally, \IncrementalDelivery\ adds support for the \@defer\ and \@stream\ directives with specific validation rules, enabling partial response delivery.

core/src/main/scala/caliban/wrappers · high confidence

The \caliban.parsing\ package now includes \Parser.scala\, \SourceMapper.scala\, and \VariablesCoercer.scala\. The \Parser\ provides methods to parse GraphQL query strings and input values into AST documents, utilizing \fastparse\ and mapping errors to source locations via \SourceMapper\. The \VariablesCoercer\ handles the validation and coercion of GraphQL variables against the schema, ensuring type compatibility and handling non-null constraints.

core/src/main/scala/caliban/parsing · high confidence

Added two new example applications in the \quick\ package: \AuthExampleApp\ and \ExampleApp\. \AuthExampleApp\ demonstrates how to implement custom authentication middleware for GraphQL queries and subscriptions using ZIO layers, exposing endpoints for API access, WebSocket subscriptions, and the GraphiQL interface. \ExampleApp\ provides a simpler baseline setup using the \QuickAdapter\ with configurable SSE heartbeat intervals and WebSocket paths, serving as a reference for basic server configuration.

examples/src/main/scala/example/quick · high confidence

The schema module now includes a comprehensive set of annotations for controlling GraphQL schema generation, such as GQLDeprecated, GQLDescription, GQLExcluded, GQLName, GQLInterface, GQLUnion, GQLValueType, GQLDefault, GQLNullable, GQLNonNullable, and GQLOneOfInput. Additionally, the core typeclasses Schema and ArgBuilder are defined with their respective derivation mechanisms, alongside supporting structures like Step, ReducedStep, RootSchema, and RootSchemaBuilder to facilitate type mapping and execution planning.

core/src/main/scala/caliban/schema · high confidence

The \tools\ module now includes \IntrospectionClient\ and \RemoteSchema\ to fetch and parse GraphQL schemas from remote servers via introspection, supporting custom headers and preserving subscription types. Additionally, \SchemaComparison\ and \SchemaComparisonChange\ provide detailed diffing capabilities between two schemas, detecting breaking changes such as deleted types or fields, added arguments, and changes to directive repeatability or interface implementations.

tools/src/main · high confidence

Caliban now supports the GraphQL @defer and @stream directives, allowing clients to receive partial query results incrementally rather than waiting for the entire response. This is implemented via new execution models in the Executor, including a new QueryExecution configuration with Parallel, Sequential, Batched, and Mixed modes to optimize how effectful fields are resolved. The update introduces a new Feature flag system to enable these capabilities and handles the necessary infrastructure for deferred fragment and stream processing.

core/src/main/scala/caliban/execution · high confidence

Caliban now supports Apollo Federation versions up to v2.13, including new directives and capabilities introduced in v2.12 and v2.13. This update adds the \@cacheTag\ directive (v2.12) for entity caching, the \@context\ and \@fromContext\ directives (v2.8), the \@cost\ and \@listSize\ directives (v2.9), and the \@policy\ directive (v2.6). It also introduces the \@connect\ and \@source\ directives (Connect spec v0.4) for external service integration, along with \@authenticated\ and \@requiresScopes\ (v2.5) for authorization. Users can now leverage these features by importing the corresponding version-specific traits (e.g., \FederationDirectivesV2\_12\).

federation/src/main/scala/caliban/federation/v2x · high confidence

The \caliban-quick\ adapter now exposes configuration options for real-time subscriptions via new \SseConfig\ and \WebSocketConfig\ case classes. Users can control Server-Sent Events (SSE) heartbeat intervals to prevent connection timeouts and configure WebSocket keep-alive times, hooks, and underlying zio-http settings. These configurations are integrated into the \runServer\ and \routes\ convenience methods on \GraphQL\, allowing users to enable and customize WebSocket-based subscriptions by specifying a \webSocketPath\.

adapters/quick/src/main/scala/caliban/quick · high confidence

This change introduces new Scala 2-specific source files to support cross-compilation and performance. It adds a \Macros\ object providing a compile-time \gqldoc\ macro to validate GraphQL documents at compile time, stubs for Scala 3-specific annotations (\@static\, \@threadUnsafe\) to ensure API compatibility, and syntax extensions (\EnrichedImmutableMapOps\, \EnrichedListOps\, \EnrichedListBufferOps\) that provide optimized or polyfilled methods like \foreachOne\ and \addOne\ to address Scala 2.12/2.13 differences and hot-path performance.

core/src/main/scala-2/caliban · high confidence

The core library has been migrated to ZIO 2, introducing a new \Configurator\ that allows runtime configuration of query execution (e.g., skipping validation, enabling/disabling introspection, setting execution strategies like parallel or batched, and providing custom caches). The error model has been restructured into a sealed \CalibanError\ trait with specific subtypes (\ParsingError\, \ValidationError\, \ExecutionError\) that support error extensions. The public API now centers on the \GraphQL\ trait and \GraphQLInterpreter\, which handle schema rendering, validation, and request execution, while supporting incremental delivery via \Defer\ and \Stream\ types and WebSocket subscriptions through dedicated input/output models.

core/src/main/scala/caliban · high confidence

The introspection schema now uses semi-auto derivation via the new IntrospectionDerivation trait, allowing the system to automatically generate schemas for introspection types like \_\Type, \\Field, and \\Schema while providing explicit control over union types such as \\_TypeKind.

core/src/main/scala-3/caliban/introspection · high confidence

The introspection system has been refactored to allow introspection queries themselves to be introspected, enabling tools to query the structure of the introspection API. This change introduces support for the standard @skip and @include directives on fields, fragment spreads, and inline fragments, as well as the @specifiedBy directive for custom scalars. Additionally, the @oneOf directive is now included in the introspection schema when applicable, and the Boolean and String types are explicitly registered to support these directive arguments.

core/src/main/scala/caliban/introspection · high confidence

The introspection module now provides a new \IntrospectionDerivation\ trait that enables semi-automatic derivation of the introspection schema. By mixing in this trait, users can access the \introspectionSchema\ and rely on implicit \Schema\ instances for \\_\_Type\, simplifying the setup required for introspection capabilities.

core/src/main/scala-2/caliban/introspection · high confidence

The example application has been rewritten to use ZIO effects (UIO, URIO, ZStream) for all GraphQL resolvers, replacing previous execution models. This migration enables advanced features such as the @defer directive via the IncrementalDelivery wrapper, subscription support for character deletion events, and query analysis wrappers (max fields, max depth, timeout, slow query logging). The API now leverages semi-auto schema derivation and integrates with Apollo Tracing, providing a more robust and performant example implementation.

examples/src/main/scala/example · high confidence

The rendering subsystem has been replaced with a new, specification-compliant engine that supports GraphQL schema extensions (the \extend\ keyword) and properly escapes control characters in string values. This new implementation introduces a \Renderer\ abstraction that enables both pretty-printed and compact output modes, significantly improving performance for document serialization while ensuring correct handling of block strings and directive locations.

core/src/main/scala/caliban/rendering · high confidence

The Play framework examples have been updated to use the new Tapir-based adapters (HttpInterpreter and WebSocketInterpreter) instead of the previous implementation. This change introduces support for request interceptors, allowing for features like authentication (as shown in the new AuthExampleApp) and enabling the GraphiQL UI in the main example app.

examples/src/main/scala/example/play · high confidence

The introspection abstract data types in \core/src/main/scala/caliban/introspection/adt\ have been restructured to align with the GraphQL specification's support for repeatable directives and deprecation on input values. New or updated case classes (\\_\Directive\, \\\EnumValue\, \\\Field\, \\\InputValue\, \\\Type\, \\\Schema\) now include \isRepeatable\ flags, \directives\ lists, and \isDeprecated\/\deprecationReason\ fields on input values. The \\\DeprecatedArgs\ class was introduced to control the inclusion of deprecated items in introspection queries, and \\\_DirectiveLocation\ was added to cover all standard directive locations. These changes enable the schema to correctly expose repeatable directives and deprecation status for input fields in introspection responses.

core/src/main/scala/caliban/introspection/adt · high confidence

The GraphQL parser implementation has been restructured into distinct, modular traits (NumberParsers, StringParsers, ValueParsers, SelectionParsers, and the main Parsers object) to improve maintainability and performance. This change introduces more robust parsing for string literals, including support for variable-width Unicode escape sequences and corrected handling of block-string line terminators and control-character rendering. It also fixes a bug where float literals containing both a fraction and an exponent were being truncated, and ensures that enum values starting with true, false, or null are correctly parsed without being misinterpreted as keywords.

core/src/main/scala/caliban/parsing/parsers · high confidence

The Caliban sbt plugin has been restructured into distinct modules to improve maintainability and add new capabilities. A new CLI interface is now available via \calibanGenSchema\ and \calibanGenClient\ commands, allowing users to generate GraphQL sources and client code directly from the sbt console. The plugin's internal logic has been split into separate files for keys, settings, source generation, and compatibility layers (including Scala 2/3 specific implementations), providing a cleaner architecture for the code generation tasks.

codegen-sbt/src/main · high confidence

The Scala 2-specific schema derivation logic has been rewritten to use Magnolia 1, introducing new version-specific files for annotations, schema derivation, and ArgBuilder derivation. This change enables support for new GraphQL features including \@GQLDirective\ for adding custom directives to schema types, \@GQLOneOfInput\ for one-of input types, and \@GQLValueType\ for treating case classes as scalars. It also improves ArgBuilder behavior by correctly handling value types and providing better fallbacks for parent type annotations.

core/src/main/scala-2/caliban/schema · high confidence

The core library now supports Scala 2.13 by introducing separate source directories for Scala 2.12 and 2.13. The \caliban.Hash\ object is implemented differently in each: Scala 2.12 uses \MurmurHash3.productHash\, while Scala 2.13 uses the newer \MurmurHash3.caseClassHash\. This ensures correct hashing behavior for case classes on both supported Scala versions.

core/src/main/scala-2.12, core/src/main/scala-2.13 · high confidence

This change introduces the Scala 3-specific implementation for Caliban's schema and argument builder derivation in the \core/src/main/scala-3/caliban/schema\ package. It replaces previous approaches with new files leveraging Scala 3 macros and Magnolia, including \SchemaDerivation.scala\ and \ArgBuilderDerivation.scala\ for automatic type class derivation. The update adds support for deriving GraphQL fields from case class methods via \@GQLField\ and \@GQLFieldsFromMethods\ annotations, handles \oneOf\ input types with \OneOfArgBuilder\, and provides specialized schemas for enums, interfaces, unions, and value types. It also includes utilities for customizing input type naming, handling directives, and supporting semantic non-null features.

core/src/main/scala-3/caliban/schema · high confidence

This change introduces Scala 3-specific implementation files to optimize runtime performance and add compile-time safety. It adds a \Hash\ object to leverage MurmurHash3 for case class hashing, and \syntax\ extensions that use \@static\ and inline methods to optimize map lookups and list iteration (replacing \foreach\ with a while loop) in hot paths. Additionally, a new \Macros\ object provides a \gqldoc\ inline macro that validates GraphQL document strings at compile-time, aborting compilation if the document is invalid.

core/src/main/scala-3/caliban · high confidence

The GraphQL WebSocket client now uses jsoniter for encoding and decoding messages instead of the previous JSON library. This change introduces new request and response case classes (GraphQLWSRequest and GraphQLWSResponse) that rely on jsoniter codecs, ensuring consistent serialization behavior across the WebSocket transport layer.

client/src/main/scala/caliban/client/ws · high confidence

The Akka HTTP example applications have been migrated to use the new Tapir-based adapters. This change updates the example code to utilize \HttpInterpreter\ and \WebSocketInterpreter\ from the \caliban.interop.tapir\ package, replacing previous implementation details. Users can now see how to configure routes for HTTP and WebSocket GraphQL endpoints, as well as GraphiQL services, using the modern Tapir integration within the Akka HTTP framework.

examples/src/main/scala/example/akkahttp · high confidence

The macros module now uses Magnolia v1 for automatic schema derivation in Scala 2. This change introduces new files (Derived.scala and DerivedMagnolia.scala) that wrap Magnolia's generation output to manage implicit priority, ensuring that derived schemas work correctly alongside other implicit definitions.

macros · high confidence

The client implementation examples in the compile-time codegen test suite have been updated to use sttp 4 for HTTP requests, replacing the previous client library. This change affects the generated client code structure, specifically how requests are sent and responses are handled within the test modules.

codegen-sbt/src/sbt-test/compiletime-codegen/test-compile/modules/clients · high confidence

The validation logic in \core/src/main/scala/caliban/validation\ has been restructured into distinct, specialized files (\FieldMap\, \FragmentValidator\, \SchemaValidator\, \ValueValidator\, \ValidationOps\, and \Validator\) to improve performance and maintainability. This change introduces a new \FieldMap\ for efficient collection of fields and fragments, a dedicated \FragmentValidator\ with caching and memoization to optimize conflict detection, and a \SchemaValidator\ that enforces stricter rules for input objects (including \@oneOf\ support) and directives. The refactoring also adds \ValidationOps\ for streamlined error handling and \Utils\ for type checking, resulting in faster validation execution and more precise error reporting for users.

core/src/main/scala/caliban/validation · high confidence

Add compile-time codegen test modules for posts and potatoes APIs; Add comprehensive JMH benchmarks for Caliban and competing GraphQL libraries; Add gen-client-task scripted test with GitLab schema and scalafmt integration; Add scripted test infrastructure for caliban-codegen-sbt; Added comprehensive test coverage for schema derivation, rendering, and validation; Added comprehensive test suite for the Scala code generator; Added integration tests for the HTTP4s adapter; Added integration tests for the ZIO HTTP Quick adapter; Added integration tests for the gen-client task; Added placeholder directories for test modules; Added scripted test for caliban-codegen-sbt; Added scripted test for split-files code generation; Added scripted tests for compile-time Caliban client code generation; Added test coverage for Caliban client core components; Added test for GraphQL API validation; Added test for newtype and lazy directive code generation; Added test suite for Federation v2.x schema directives and fixtures; Added test suite for the Tapir adapter integration; Added tests for Cats interop contextual and plain modes; Added tests for FS2 stream interop schema derivation; Added tests for Federation Tracing behavior; Added tests for Federation V1 entity resolution and SDL generation; Added tests for ReportingDaemon schema reporting behavior; Added tests for SBT codegen options parsing; Added tests for introspection client, remote schema parsing, and schema comparison; Added tests for the Pekko HTTP adapter; Added tests for tracing and masking functionality; Expanded GraphQL schema test coverage for codegen edge cases; Expanded test coverage for GraphQL client code generation; Test configuration for Play adapter buffer limits; Test suite defines ZIO environment type for newtype compilation.

This release updates the project's build configuration and dependencies, including upgrading Scala versions (2.12.21, 2.13.18, 3.3.8), ZIO (2.1.26), Tapir (1.13.32), and various other libraries like http4s, Play, and ZIO-HTTP. It also introduces a new \client-laminext\ module with its own \package.json\ for frontend dependencies and adds several SBT scripted tests for the codegen plugin to verify compilation and generation settings across different Scala versions.

(dependencies) · high confidence

The project's build system has been upgraded to sbt 1.13.0, accompanied by significant updates to key plugins: sbt-scalafmt to 2.6.2, sbt-scalajs to 1.22.0, sbt-scala-native to 0.5.12, sbt-ci-release to 1.12.1, and sbt-mdoc to 2.9.2. To support this modernized build environment, new helper utilities have been introduced, including a console welcome message that displays useful sbt tasks and version information, a scripted dependency definition for testing (sttp 3.10.1, zio-test 2.1.9), and a dedicated Scala 3 test helper command to verify codegen-sbt compilation across Scala 2.12 and Scala 3.

project · high confidence

The repository has been initialized with essential configuration files, including \.gitignore\, \.scalafmt.conf\ (version 3.8.2), \.pre-commit-config.yaml\, and \.sbtopts\ (configuring 3G metaspace and heap). Documentation files such as \README.md\, \CONTRIBUTING.md\, and \CODE\_OF\_CONDUCT.md\ have been added, along with a list of adopters.

(repo-wide) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 51 → 50 (-0.2)
• Rubric changed (rubric-2026.09.8 → rubric-2026.09.16) — scores are not directly comparable.

• Code Health 87 → 87 (+0.0)
• Architecture 90 → 81 (-9.1)
• Maturity 39 → 38 (-0.1)
• Readiness 49 → 54 (+4.9)
• Security 61 → 65 (+3.9)
• Accessibility 60 (new)

• Change coupling: AkkaHttpAdapter.scala ↔ Http4sAdapter.scala (adapters/akka-http/src/main/scala/caliban/AkkaHttpAdapter.scala)
• Documentation: contradicts the code (docs/index.html)
• Documentation: no architecture or design documentation (docs/docs/middleware.html)
• Documentation: no installation or build instructions (docs/docs/relay-connections.html)
• Off-boarding risk: anonymized user #1

• Documentation: no installation or build instructions (docs/docs/index.html)
• Documentation: no project overview (docs/docs/index.html)
• Documentation: no project overview (docs/docs/middleware.html)
• Documentation: no project overview (docs/docs/optimization.html)
• Documentation: no project overview (docs/docs/relay-connections.html)
• No ADRs found
• Off-boarding risk: anonymized user #1
• Projects may be oversized for their cohesion
• Scanner failed to run — not a clean result

• 10 commits — 10 feature/other, 0 fixes

• (root) — 8 commits
• project/plugins.sbt — 2 commits

• change: Update client4:core, client4:jsoniter, ... to 4.0.27 (#3127)
• change: Update interface to 1.0.29 (#3123)
• change: Update jsoniter-scala-circe, ... to 2.41.0 (#3120)
• change: Update jsoniter-scala-circe, ... to 2.41.2 (#3126)
• change: Update opentelemetry-sdk-testing to 1.66.0 (#3118)
• change: Update sbt-buildinfo to 0.13.2 (#3119)
• change: Update sbt-mima-plugin to 1.2.1 (#3121)
• change: Update tapir-akka-http-server, tapir-core, ... to 1.13.32 (#3128)
• change: Update zio-http to 3.11.5 (#3117)
• change: Update zio-http to 3.11.6 (#3122)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

ghostdogpr/caliban was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.