Release Notes

This release includes support for subscriptions over Server-Sent Events, as well as a few bug fixes and improvements.

Server

• Added support for subscriptions over Server-Sent Events #2126 by @SvenW and #2141 by @kyri-petrou
• Fixed an issue with error handling with application/graphql-response+json #2144 by @ghostdogpr
• Optimized performance #2121 #2142 by @kyri-petrou
• Added Mixed query execution mode, where top-level fields are guaranteed to be executed in parallel and nested fields are executed in batched mode #2129 by @kyri-petrou
• Improved UX for constructing a Caliban interpreter via interop #2130 by @kyri-petrou

Tools

• Fixed an issue with schema codegen when using the @lazy directive and the ZIO environment is not Any #2125 by @develeon

Release Notes

This release includes a new set of performance improvements as well as some usability improvements, in particular for schema code generation. It is fully backward compatible with 2.5.0.

Server

• Improved performance #2092 #2102 #2103 #2111 #2113 by @kyri-petrou and #2112 by @ghostdogpr
• Improved QuickAdapter UX & performance #2090 by @kyri-petrou
• Defined a specific innerThrowable type for errors raised in ArgBuilders #2118 by @kyri-petrou

Client

• Allowed Jsoniter parsing large JSON payloads #2085 by @ghostdogpr and #2109 by @harrylaou
• Added a render method in CalibanClientError that can render extensions #2110 by @harrylaou

Tools

• Added a new directive called @newtype for the schema codegen to map ID to your own types #2091 by @develeon
• Made the schema codegen generate the @GQLDeprecated annotation for deprecated fields #2107 by @johnspade
• Fixed schema codegen when using derives with a ZIO Environment that is not Any #2104 by @develeon
• Fixed schema comparison of implements #2116 by @ghostdogpr

Release Notes

This release brings a bug fix for an issue that was introduced in 2.5.0 and possibly caused duplicated fields in responses when using fragments. It is fully backward compatible with 2.5.0.

Server

• Fixed a field merging issue that might cause duplicated fields in responses when using fragments #2077 #2081 by @kyri-petrou
• Added annotations for forcing object fields as nullable / non-nullable #2075 by @kyri-petrou
• Made Document serialization friendly-ier #2061 by @kyri-petrou
• Added code to catch exceptions happening in FunctionStep #2059 by @kyri-petrou

Interop

• Added InjectEnv implicit for cats.effect.IO #2062 by @kyri-petrou
• Fixed content type performance issue with zio-http #2060 by @kyri-petrou

Tools

• Fix server code generation to support @lazy fields with abstract effect #2064 by @johnspade

Release Notes

This release brings an incredible amount of performance improvements, some major library upgrades (zio-http, Play) as well as some powerful new derivation abilities such as deriving fields from case class methods.

Server

• Improved compile and runtime performance #2013 #2014 #2015 #2017 #2019 #2020 #2021 #2024 #2029 #2031 #2033 #2039 #2044 #2046 #2051 #2052 #2053 #2056 by @kyri-petrou
• Added the ability to exclude fields from interfaces #1975 by @kyri-petrou
• Added the ability to derive fields from case class methods with Scala 3 #2041 by @kyri-petrou
• Added apply method to Schema and ArgBuilder for convenience #2023 by @kyri-petrou
• Updated zio-query to 0.6.0 which contains some performance optimizations #2037 @kyri-petrou
• Allowed parallel execution of mutation non-top level fields #2040 by @kyri-petrou
• Implemented path via a PathValue type instead of Either[String, Int] #2048 by @kyri-petrou

Adapters

• Updated zio-http to RC4 & Play to 3.0.0 #1968 by @kyri-petrou
• Added api.unsafe.runServer to run a server immediately in the QuickAdapter #2050 by @kyri-petrou
• Removed unnecessary dependency on pekko-serialization-jackson #2028 by @kyri-petrou

Federation

• Added federation 2.6 support, updated gateway dependencies #2043 by @paulpdaniels

Release Notes

This version brings a few bug fixes and improvements related to schema derivation on Scala 3.
In addition to that, it contains a new adapter named QuickAdapter and based on zio-http, that serves 2 purposes:

• Offer the best performance among all adapters. This adapter is not using Tapir under the hood to prevent any overhead. We picked zio-http and jsoniter-scala because they gave the best benchmarks results among all our supported adapters and json libraries. The only drawback is that it doesn't include WebSocket support at the moment. If you care about performance above all, use this adapter!

• Be super quick and easy to get started. With this adapter you can simply do that to go from your api to a running server:

import caliban._
import caliban.quick._ // adds syntax to `GraphQL`

val api: GraphQL[Any] = ???

api.runServer(
  port = 8080,
  apiPath = "/api/graphql",
  graphiqlPath = Some("/graphiql")
)

Server

• Added QuickAdapter (see above) #1998 by @kyri-petrou
• Fixed derivation of nested sum types with Scala 3 #2005 by @kyri-petrou
• Fixed incorrect enum value renaming with Scala 3 #2006 by @kyri-petrou
• Optimized schema derivation with Scala 3 #1995 by @kyri-petrou

Tools

• Fixed incorrect interface description in server code gen #2000 by @ghostdogpr

Release Notes

This version brings a few bug fixes as well as some performance improvements.
Big thanks to @kyri-petrou for his many contributions!

Server

• Fixed schema renaming on recursive types #1974 by @kyri-petrou
• Fixed schema renaming on interfaces #1978 by @kyri-petrou
• Fixed schema derivation for nested sum types on Scala 3 #1991 #1994 by @kyri-petrou
• Fixed an issue with @defer fields not working as expected when backed by DataSources #1981 by @kyri-petrou
• Improved performance of resolving large objects #1967 by @kyri-petrou
• Improved performance of jsoniter codecs #1979 by @kyri-petrou
• Improved interface field description #1976 by @kyri-petrou
• Used magnolia macros and reduced Scala 3 compilation time + codegen size #1952 by @kyri-petrou
• Added a helper method for creating custom enum schemas #1953 by @kyri-petrou

Tools

• Fixed a warning about impure expression that could popup when using the compile time codegen #1965 by @satorg

Release Notes

This version fixes a regression introduced in 2.4.0 that prevents the usage of java.time types in schemas when using Scala 3 and JDK 17+ (https://github.com/ghostdogpr/caliban/pull/1950).

Release Notes

This version contains:

• an important number of performance improvements
• support for new specs and protocols: deprecated input fields, GraphQL over HTTP, new Apollo Caching, Federation 2.5
• usability improvements, small fixes and library upgrades

[!WARNING]
Due to an issue in zio-http 3.0.0-RC2, servers exposing websocket endpoints via the caliban-zio-http module are required to include additional config for subscriptions to work as shown in this example.

This is a temporary workaround until a new version of zio-http is released which contains a fix to this issue.

Server

• Optimized core performance #1876 #1922 #1929 by @kyri-petrou
• Added support for deprecated input fields (draft spec) #1932 by @ghostdogpr
• Added a wrapper for the new Apollo Caching Protocol. The old is now deprecated #1878 by @paulpdaniels
• Added a simple wrapper to check directives #1905 by @ghostdogpr
• Updated zio-query to the latest version so that it catches die errors happening inside the DataSource #1916 by @ghostdogpr
• Fixed mocking up superclass for module class macros warning on Scala 3 #1880 by @kyri-petrou
• Fixed duplicate types being output when calling render on a schema #1888 by @nox213
• Used the latest version of Magnolia #1858 by @kyri-petrou
• Made Introspection introspectable #1900 by @ghostdogpr
• Removed old deprecated code #1902 by @ghostdogpr
• Added the option to disable tracing of pure fields in ApolloTracing wrapper #1907 by @kyri-petrou
• Added the option to dynamically enable / disable ApolloTracing #1933 by @kyri-petrou
• Stopped generating a stack trace in CalibanError (not that getCause will return null in ValidationError) #1924 by @kyri-petrou
• Changed tracing span name to adhere to semantic guidelines #1875 by @Fluxx
• Fixed inline character escaping when rendering GraphQL #1936 by @paulpdaniels

Adapters

• Added 100% compliance with GraphQL over HTTP spec #1909 by @kyri-petrou
• Updated zio-http to RC2 #1910 by @kyri-petrou
• Enabled support for play-json in Scala 3 #1893 by @kyri-petrou

Tools

• Properly escaped union types in client code generation #1908 by @ghostdogpr
• Fixed various things in server code generation #1925 by @oyvindberg
• Added support for a @lazy directive to generate side-effecting fields in server code generation #1927 by @oyvindberg

Federation

• Added federation 2.5 support #1906 by @paulpdaniels

Release Notes

This version contains important performance improvements as well as support for Pekko.

Server

• Performance improvements
  • Drastically improved performance of the metrics wrapper #1850 by @kyri-petrou
  • Optimized query execution by resolving fields lazily and prevent unnecessary work #1849 by @kyri-petrou
  • Improved performance and correctness of schema and type rendering #1835 by @paulpdaniels
  • Reduced size of the code generated by Schema derivation with Scala 3 #1830 by @kyri-petrou
  • Optimized VariableCoercer #1856 by @kyri-petrou
• Added support for auto enum derivation with Scala 3 #1834 by @kyri-petrou
• Added a wrapper that allows skipping selected validation wrappers during introspection #1837 by @kyri-petrou
• Fixed WS protocol by always returning an id upon errors #1845 by @SvenW
• Added a helper renderSchema to render a schema without a resolver #1877 by @ghostdogpr

Adapters

• Added support for Pekko #1862 by @MichelEdkrantz

Release Notes

This version contains a lot of small fixes as well as performance and usability improvements.

Server

• Added fs2 stream interop #1737 by @satorg
• Added a helper to easily render the schema for a type #1759 by @ghostdogpr
• Optimized validation performance #1820 by @kyri-petrou
• Added status label to the graphql_fields_total metric #1724 by @SvenW
• Added validation of names in validateSchema #1731 by @ghostdogpr
• Added validation that root types are objects #1735 by @ghostdogpr
• Supported rendering of schema directives even if no queries/mutations/subscriptions #1742 by @yarian
• Improved efficiency of code when deriving SemiAuto #1785 by @kyri-petrou
• Added support for interfaces implementing interfaces #1803 by @doohochang
• Added support for schema descriptions #1808 by @nox213
• Fixed fieldWithArgs schema generation #1812 by @paulpdaniels
• Excluded fields with different arguments from interfaces #1815 by @kyri-petrou

Adapters

• Allowed access to ServerRequest in configure #1816 by @ghostdogpr
• Cached creation of interpreter #1725 by @kyri-petrou

Tools

• Added a parameter for codegen when to enable or disable isRepeatable during introspection (disable it if the remote server does not support it) #1732 by @ghostdogpr
• Added support for derives Schema.SemiAuto in schema code generation #1758 by @nox213

Release Notes

This is a tiny release with a single change on ZHttpAdapter (#1723). We noticed that the type signatures of makeHttpService and makeWebSocketService were inconsistent (the former returned HttpApp[R, Throwable] while the latter returned HttpApp[R, Response] aka App[R]). We've made them both return App[R], which should be easier to use!

Release Notes

This release brings a few important changes, including a refactor of request interceptors, support for the @defer directive and support for Scala Native in caliban-client 🚀

Love this project? I am now on Github Sponsors. A good way to give back and encourage future developments! ❤️

New Adapter API

Request interceptors and configuration options such as skipValidation or enableIntrospection have been modified to be more powerful: you can now eliminate part of ZIO environment with request interceptors, and you can modify execution configuration dynamically.

These improvements require a small change in existing code. When calling makeHttpService, makeHttpUploadService or makeWebSocketService, you now need to wrap your interpreter into (respectively) an HttpInterpreter, HttpUploadInterpreter or WebSocketInterpreter.

// before
ZHttpAdapter.makeHttpService(interpreter)
// after
ZHttpAdapter.makeHttpService(HttpInterpreter(interpreter))

With these wrapper classes come 2 powerful methods:

• configure takes a Configurator[R] which is an alias for URIO[R & Scope, Unit].
  It allows configuring the interpreter by running an effect that will run for each request and that can modify the configuration of the running fiber. Built-in configurators such as setSkipValidation, setEnableIntrospection and setQueryExecution are available in the Configurator object and let you dynamically change the configuration of the interpreter.
• intercept takes an Interceptor[-R1, +R] which is an alias for ZLayer[R1 & ServerRequest, TapirResponse, R].
  It is basically a more powerful version of configure that gives you access to the incoming request (ServerRequest) and lets you modify the environment of the interpreter (from R to R1). A typical use case would be to extract an authentication token from the request and eliminate the authentication requirement from the environment if the token is valid. See an example here. You can also use this to change the configuration based on the incoming request (e.g. allow introspection only when a valid token is present).

val interpreter: GraphQLInterpreter[AuthToken, CalibanError] = ???
// turn our GraphQL interpreter into an HttpInterpreter
val noAuthInterpreter: HttpInterpreter[AuthToken, CalibanError] = HttpInterpreter(interpreter)
// define authentication logic (from a ServerRequest, fail or build an AuthToken)
val auth: ZLayer[ServerRequest, TapirResponse, AuthToken] = ???
// pass our interceptor to eliminate the AuthToken requirement from the environment
val authInterpreter: HttpUploadInterpreter[Any, CalibanError] = httpInterpreter.intercept(auth)
// get our route for Akka Http
val route = AkkaHttpAdapter.makeHttpService(authInterpreter)

This change was done in #1707 by @ghostdogpr

Other changes

Server

• Added experimental support for the @defer directive #1480 by @paulpdaniels
• Added directives parameter to scalarSchema #1694 by @yarian
• Added support for derives ArgBuilder.GenAuto derivation #1699 by @kyri-petrou
• Added support for adding directives to individual enums #1663 by @paulpdaniels
• Fixed derives Schema.Auto derivation #1666 by @kyri-petrou
• Fixed rendering of directives in arguments #1690 by @tusharmath
• Fixed repeatable directive introspection #1695 by @ghostdogpr
• Fixed propogation of directives in objectSchema #1698 by @yarian

Client

• Added support for Scala Native #1682 by @kyri-petrou

Adapters

• Upgraded zio-http to 3.0.0-RC1 #1705 by @jgulotta

Release Notes

This release is packed with features, improvements and fixes. In fact, it is probably the single most important release since Caliban Client was added. It contains several breaking changes, so make to read what follows before upgrading!

Schema derivation

One of the most requested features of Caliban was the ability to opt out from the automatic schema derivation and use a semi-automatic approach where you have to create a schema for each individual type. Automatic schema derivation is convenient when you get started, but can quickly becoming a pain when you have large schemas: slow compilation, large amount of generated code, difficulty finding which types require a custom instance or even knowing which instance is actually used.

We decided to make automatic generation optional using an import. Without this import, you will need to provide an implicit/given schema for each type that is not already supported. We also added support for the derives keyword in Scala 3, so that it's super easy to create schemas with the least amount of boilerplate.

Here is how derivation work with Scala 3:

// semi-auto derivation, needs a Schema for inner types
final case class Foo(value: String) derives Schema.SemiAuto

// semi-auto derivation when R in Schema[R, A] is not Any
object CustomSchema extends SchemaDerivation[MyEnv]
final case class Foo(value: String) derives CustomSchema.SemiAuto

// semi-auto derivation without the derives keyword
given Schema[MyEnv, Foo] = Schema.gen

// auto derivation
import Schema.auto._
given Schema[MyEnv, Foo] = genAll

Here's how it looks with Scala 2 (also cross-compile with Scala 3):

// semi-auto derivation, needs Schema for inner types
implicit val fooSchema: Schema[Any, Foo] = Schema.gen

// auto derivation, generates a Schema for inner types
import Schema.auto._
implicit val fooSchema: Schema[Any, Foo] = genAll

// semi-auto derivation when R in Schema[R, A] is not Any
object schema extends GenericSchema[MyEnv]
implicit val fooSchema: Schema[MyEnv, Foo] = schema.gen

// auto derivation when R in Schema[R, A] is not Any
object schema extends GenericSchema[MyEnv]
import schema.auto._
implicit val fooSchema: Schema[MyEnv, Foo] = genAll

Note that ArgBuilder derivation follows the same pattern (without the R part) and requires an import if you want auto generation.

This change was done in #1591 by @ghostdogpr

Adapters and Json libraries

Historically each adapter was tied to a specific Json library: for example Circe was used for http4s and zio-http, while play-json was the default for play. As we recently introduced support for jsoniter-scala, we found it was quite inconvenient to use it with the existing adapters. So we decided to make the adapters completely free of any Json dependency, so you can use the Json library you want!

All you have to do is adding one of these Tapir dependencies:

"com.softwaremill.sttp.tapir" %% "tapir-json-circe"     % "1.2.11" // Circe
"com.softwaremill.sttp.tapir" %% "tapir-jsoniter-scala" % "1.2.11" // Jsoniter
"com.softwaremill.sttp.tapir" %% "tapir-json-play"      % "1.2.11" // Play JSON
"com.softwaremill.sttp.tapir" %% "tapir-json-zio"       % "1.2.11" // ZIO JSON

And then later in your code (you only need one!):

import sttp.tapir.json.circe._
import sttp.tapir.json.jsoniter._
import sttp.tapir.json.play._
import sttp.tapir.json.zio._

This change was done in #1552 by @kyri-petrou

Performance improvements

Performance was improved in almost every parts of Caliban: from parsing to validation to execution. Even Caliban Client received some love! Here are the details:

• Used the Fastparse parser on Scala 3, which makes parsing much faster and removes code duplication (previously Fastparse was used for Scala 2 and cats-parse for Scala 3) #1646 by @kyri-petrou
• Used ZPure instead of ZIO for validation logic, which improves validation performance greatly #1633 by @paulpdaniels
• Added multiple execution performance improvements in particular with fragments #1635 #1643 #1650 by @kyri-petrou
• Switched the internal JSON library used in Caliban Client from Circe to Jsoniter-scala for a better runtime performance #1639 by @paulpdaniels

Other changes

Server

• Moved the graphQL function directly to the caliban package (the old one is still there but deprecated) by @ghostdogpr
• Added new wrappers for observability #1616 by @frekw
  • Wrappers.logSlowQueries for logging slow queries with ZIO.logWarning
  • Wrappers.metrics for gathering metrics about query execution
  • TracingWrapper.traced for creating traces with OpenTelemetry (in a separate dependency caliban-tracing)
• Reduced the size of the code generated by derivation (Scala 3 only) #1607 by @kyri-petrou
• Stopped adding the suffix Input to input objects that already have that suffix #1471 by @brodin
• Prevented validation error when an input field is null but a default value exists #1629 by @ghostdogpr
• Stopped requiring a Schema for fields annotated with @GQLExcluded (Scala 3 only) #1630 by @kyri-petrou
• Added support for repeatable directives #1617 by @jgulotta
• Added the ability to skip query validation in wrappers (used in ApolloPersistedQueries wrapper) #1557 by @kyri-petrou
• Fixed rendering of directive arguments that contain special characters #1656 by @camarena
• Added isIntrospection field on Document #1662 by @kyri-petrou
• Fixed the Monix interop that had been broken by an older release #1628 by @ghostdogpr

Adapters

• Upgraded zio-http dependency to 0.0.5 (this is using the new organization) #1521 by @frekw

Federation

• Added support for federation v2.3 #1631 by @paulpdaniels

Tools

• Fixed client code generation for interfaces #1559 by @ghostdogpr
• Made the introspection SelectionBuilder public #1596 by @lassebn

Release Notes

This release contains several bug fixes and dependency upgrades (see versions here), as well as support for the Jsoniter Json library. This library is optimized for performance so the encoding/decoding of GraphQL requests/responses consumes less memory and is significantly faster than other solutions. Note that for performance reasons, this implementation is not tail-recursive so you might want to limit query depth with the maxDepth wrapper. Give it a try if you're looking for the best possible throughput!

Server

• Added support for Jsoniter #1527 by @kyri-petrou
• Made RequestInterceptor.empty a val, so that we don't instantiate many of them #1435 by @guizmaii
• Ensured String is returned by introspection even when it's not used #1444 by @ghostdogpr
• Added support for VARIABLE_DEFINITION as a possible directive location #1446 by @aadunn
• Improved performance by move primitives to RootType #1508 by @frekw
• Fixed rendering of descriptions for multi-line descriptions ending in quote #1544 by @camarena

Adapters

• Fixed ping/pong handler in tapir websocket protocol #1458 by @rolang
• Fixed WebSocket.afterInit #1515 by @ghostdogpr

Federation

• Made entity resolvers support partial responses and errors combined #1437 by @SvenW

Tools

• Fixed scalafmt newline issue #1518 by @jfwilson
• Allowed specifying a scalar mapping for ID in client codegen #1529 by @ghostdogpr
• Made codegen valid on scala 3 when a field is named _ #1540 by @guymers

Release Notes

Server

• Fixed the annotations macro on Scala 3 which caused runtime errors when using Schema for java.time on JDK 17 #1414 by @ghostdogpr
• Prevented validation errors during variable coercion when skipValidation is true #1421 by @ghostdogpr
• Upgraded zio-query to 0.3.1, which brings a performance improvement in some cases (thanks to @adamgfraser)

Adapters

• Fixed http4s websocket support that was broken in the last release #1417 by @ghostdogpr

Tools

• Added Scala 3 support for caliban-tools, making the compile-time plugin usable #1415 by @pmeheut

Release Notes

Server

• Fixed the annotations macro on Scala 3 which caused runtime errors when using Schema for java.time on JDK 17 #1414 by @ghostdogpr
• Prevented validation errors during variable coercion when skipValidation is true #1421 by @ghostdogpr

Adapters

• Fixed http4s websocket support that was broken in the last release #1417 by @ghostdogpr

Release Notes

This release contains the same features as 1.4.2, but is based on ZIO 2.0.0. You can consult this guide about the upgrade and the differences between ZIO 1.x and 2.x.

Going forward, all new features will be made on this branch. We might backport important bug fixes to the 1.x branch if necessary.

Release Notes

Server

• Fixed floating point numbers input validation #1370 by @moonkev
• Properly escaped special characters in description strings when rendering the schema #1372 #1373 by @joheriks
• Improved persisted query performance by caching the document #1371 by @paulpdaniels
• Fixed field types in field metadata for interface fields on union #1375 by @guymers
• Fixed coercion of non-null values into lists of size one #1376 by @guymers

Adapters

• Added support the more recent graphql-transport-ws WebSocket protocol #1354 by @paulpdaniels
• Updated zio-http to 1.0.0.0-RC29 #1412 by @guizmaii

Client

• Handled the case of a type named Option in the generated code #1377 by @alterationx10

Release Notes

Server

• Fixed parsing of empty comment lines in Scala 3 #1337 by @sergeykolbasov
• Fixed rendering of object arguments to directives #1353 by @joheriks
• Fixed some edge cases of input type validation #1347 by @frekw
• Fixed a potential security vulnerability in the ApolloPersistedQuery wrapper #1362 by @paulpdaniels
• Added targets to field metadata to expose the type conditions of a field #1315 by @frekw

Adapters

• Ensured the subscription Websockets are interrupted properly #1342 by @moonkev
• Added support for lower-case content-type headers #1321 by @frekw
• Upgraded zio-http to 1.0.0.0-RC27 #1361 by @strokyl

Client

• Fixed generated code for views with more than 22 fields #1363 by @ollyw

Plugins

• Added support for Apollo Federation v2 #1344 by @paulpdaniels

Release Notes

This release contains the same changes as 1.4.0, but for ZIO 2.0. It is based on ZIO 2.0.0-RC2.