caliban

Release Notes

Server

• Upgraded zio-query to 0.2.5, bringing a x2 speed improvement in the "simple" benchmark scenario #579 thanks to @adamgfraser
• Applied the GQLName annotation properly to fields #551 by @ghostdogpr
• Improved schemas inference #561 by @darl
• Improved validation performance #563 by @ghostdogpr
• Allowed passing errors to wrappers #569 by @paulpdaniels
• Avoided name clash between regular and interop effect schemas #572 by @ghostdogpr
• Properly handled websocket disconnections in the Akka Http Adapter #571 by @moonkev
• Fixed the error message returned for empty queries by @ghostdogpr

Federation

• Added support for orphan types #584 by @paulpdaniels

Tools

• Fixed argument names in server code generation #554 and #578 by @galales

Release Notes

Server (Core)

• Upgraded ZIO and its dependencies to 1.0.0 🎉 #540 by @paulpdaniels
• Fixed a bug causing nested fragments not working properly #532 by @ghostdogpr
• Added a new wrapper @@ printErrors that prints errors to the console #513 by @ghostdogpr
• Added location and path info to the error when we catch an ExecutionError inside a resolver #506 by @paulpdaniels
• Improved compatibility of CalibanError with Java conventions #505 by @Krever

Server (Adapters)

• Added a contextWrapper parameter to the Play Adapter that can be used to inject something into ZIO environment using the request context (e.g. auth info, open tracing metadata) #498 by @paulpdaniels
• Added support for contextWrapper in subscriptions and improved its usability (Play and Akka Http) #519 by @moonkev
• Added support for application/graphql and query parameter in POST request to Akka HTTP Adapter #514 by @moonkev
• Added support for application/graphql and query parameter in POST request to Http4s Adapter #521 by @moonkev
• Added support for application/graphql and query parameter in POST request to Finch Adapter #525 #528 by @keyno63
• Improved the adapters to handle failures and stream termination in a way that is consistent with Apollo #529 by @moonkev
• Removed uzhttp support to reduce maintenance efforts and because its usage is not recommended according to its maintainer. If you want it back, come tell us on Discord.

Client

• Added the ability to specify a query name #527 by @paulpdaniels
• Added extensions to GraphQLResponseError #503 by @cilicio

Release Notes

Performance Improvements

This release comes with various performance improvements done in #490 by @ghostdogpr and @yoohaemin.
Query parsing, validation, execution: every phase has seen some optimizations! 🎉
Benchmarks show that the introspection query is executed 4x faster than before.

Before:

[info] Benchmark                             Mode  Cnt      Score     Error  Units
[info] GraphQLBenchmarks.introspectCaliban  thrpt    5    565.365 ±  27.284  ops/s
[info] GraphQLBenchmarks.introspectSangria  thrpt    5    485.646 ±   7.157  ops/s
[info] GraphQLBenchmarks.simpleCaliban      thrpt    5  15850.452 ± 554.077  ops/s
[info] GraphQLBenchmarks.simpleSangria      thrpt    5   7710.546 ± 140.220  ops/s

After:

[info] Benchmark                             Mode  Cnt      Score     Error  Units
[info] GraphQLBenchmarks.introspectCaliban  thrpt    5   2249.019 ±  30.014  ops/s
[info] GraphQLBenchmarks.introspectSangria  thrpt    5    495.380 ±  14.566  ops/s
[info] GraphQLBenchmarks.simpleCaliban      thrpt    5  20622.959 ± 774.391  ops/s
[info] GraphQLBenchmarks.simpleSangria      thrpt    5   7939.774 ±  43.622  ops/s

Breaking changes

These improvements cause very minor breaking changes:

• If you had a custom schema calling toType, you will need to change it to toType_ which is an optimized version that caches the generated type instead of recalculating it.
• If you used the class Field in a wrapper, fields and conditionalFields have been merged into simply fields, with a new parameter condition: Option[String] to indicate the field is conditional. In addition to improving performance, this allows maintaining the order of fields between the query and the response.

Server changes

• Added builtin support for java time #473 by @paulpdaniels
• Fixed a determinism issue with schema derivation of interfaces #493 by @ghostdogpr
• Used fromSinkAndSourceCoupled rather than fromSinkAndSource in the Akka Http Adapter so that streams are properly terminated on WebSocket disconnection by the browser #483 by @moonkev
• Added a contextWrapper parameter to the Akka Http Adapter that can be used to inject something into ZIO environment using the request context (e.g. auth info, open tracing metadata) #494 by @darl

Client changes

• Improved error messages in Caliban Client when a typeclass instance is missing #489 by @ghostdogpr
• Properly handled case class reserved fields in codegen #497 by @ghostdogpr
• Properly escaped double quotes in codegen #485 by @MasseGuillaume
• Exposed "extensions" in Caliban Client #486 by @MasseGuillaume

Release Notes

• Upgraded ZIO and its dependencies to 1.0.0-RC21-1 #472 by @ghostdogpr
• Improved the handling of uncaught errors (zio's Die) so that they are properly caught with path and location #463 by @ghostdogpr
• Fixed the Schema for ZStream when it is used outside of a Subscription #457 by @ghostdogpr
• Fixed the Schema for () => A #459 by @ghostdogpr
• Used triple-quotes for multiline comments in code generation #465 by @AlixBa

Release Notes

• Renamed caliban-codegen to caliban-tools and added a new feature to compare GraphQL schemas from various origins (Caliban, remote server introspection, file, string). See documentation #436 by @ghostdogpr
• Fixed false positives in object type validation #440 by @ghostdogpr
• Added Schema and ArgBuilder for ZIO Chunk #439 by @renancaju
• Added --effect option to schema codegen #443 by @AlixBa
• Updated zio-query to 0.2.2 (contains an important bug fix if you use multiple DataSource)

Release Notes

• Upgraded ZIO and related dependencies to 1.0.0-RC20 #429 by @ghostdogpr
• Added schema validation for GraphQL objects. All schema validation rules have now been implemented. #259 by @zach-albia
• Changed the auto-derivation for value classes to generate a Schema for the underlying type #430 by @palanga
• Fixed nested type name computation #427 by @kiranbayram
• Added SelectionBuilder.combineAll in caliban-client #411 @ghostdogpr

Release Notes

Major library upgrades

• Upgraded ZIO to 1.0.0-RC19-2 + all ZIO-related dependencies #395 by @ghostdogpr
• Upgraded Scala.js to 1.x #395 by @ghostdogpr
• Upgraded ZQuery to 0.2.0. If you use ZQuery, make sure to check the release notes, they come with a migration guide! #380 #395 by @adamgfraser
• Upgraded tapir to 0.15.0 #389 by @ghostdogpr

Support for the Play Framework

• Added a brand new adapter for the Play Framework #382 by @javimartinez. Check the example app!

Other changes

• Allowed overriding the name of query/operation name in Tapir interop #375 by @fkowal
• Moved the codegen console output into the sbt module #385 by @joprice
• Made query optional in GET methods of Finch and Akka HTTP adapters #400 by @javimartinez
• Handled missing variables properly #403 by @joprice
• Exposed more information in FieldInfo by @ghostdogpr

Release Notes

• Made ZQuery stack-safe and fixed potential stack overflow exceptions when returning large lists #378 by @adamgfraser
• Allowed configuring the package name in codegen #370 by @joprice
• Improved documentation

Release Notes

Tapir Integration

Caliban is now able to generate a GraphQL API from Tapir endpoints! That means that if you use Tapir for exposing a REST API, you should be able to expose a GraphQL API with minimal efforts.

Creating a GraphQL object is similar to creating routes for http4s or Akka HTTP:

val addBook: Endpoint[Book, Nothing, Unit, Nothing] = ???
def bookAddLogic(book: Book): UIO[Unit] = ???

val api = addBook.toGraphQL(bookAddLogic)

Simple conversions rules will create Query fields for GET endpoints and Mutations fields for POST/PUT/DELETE endpoints. You might need to provide custom Schema or ArgBuilder instances if you use types that Caliban can't handle (see schema documentation).

Check the documentation for more information. There's also a full example in the examples project.

Other Changes

• Changed Http4sAdapter.makeWebSocketService's implementation so that incoming messages are processed in a child fiber, allowing usage of FiberRef #364 by @mitsutaka-takeda
• Added options to the codegen tool to pass a custom scalafmt file or use custom headers when getting the schema by introspection #357 by @kiranbayram
• Fixed newline handling in graphql response when toString is used instead of Json #358 by @gjuhasz86
• Handled Scala reserved keywords properly in schema code generation

Build

• Upgraded Magnolia to 0.16.0
• Upgraded Monix to 3.2.1
• Upgrade http4s to 0.21.4

Release Notes

Caliban

• Added support for arguments not wrapped in cases classes. That means a field can be of type String => ??? or Int => ???. In that case though, the arbitrary name value will be used to name the argument. #342 by @ghostdogpr
• Added support for variables in WebSockets #348 by @mitsutaka-takeda
• Added the option to disable introspection #329 by @joprice
• Added schema directives validation #333 by @javimartinez
• Made ZQuery run arbitrary effects in parallel when using the parallelism combinators #339 by @adamgfraser
• Fixed validation rules to avoid an error saying that a type was defined multiple times when creating a custom schema #346 by @ghostdogpr

Caliban Client

• Added support for Json scalar in Caliban Client #345 by @ghostdogpr
• Added code generation for the Subscription object #340 by @rleibman
• Prevented the client generation from creating code that doesn't compile when _ is used as a field by @ghostdogpr

Build

• Made the codegen usable as a library (caliban-codegen) separated from the sbt plugin (now named caliban-codegen-sbt) #327 by @joprice
• Stopped publishing the backend components for Scala.js (Scala.js stays of course available for caliban-client) #324 by @ghostdogpr
• Upgraded Magnolia to 0.15.0 and started using ReadOnlyCaseClass for improved compile times #324 by @ghostdogpr

Release Notes

• Added support for Apollo Federation via a new module called caliban-federation #314 by @paulpdaniels
• Allowed the codegen tool to work directly from a GraphQL API URL, using introspection #318 by @ghostdogpr
• Added the ability to send keep-alive messages in the adapters that support WebSockets #317 #323 by @rleibman @ghostdogpr
• Added ZQuery#orDie #320 by @adamgfraser

Release Notes

• Added a new adapter for uzhttp, a new minimal, low-level HTTP server library powered by ZIO. A good choice if you only need to expose your GraphQL API and don't need extra capabilities. WebSockets are supported as well. The example is the simplest of all the adapters! #313 by @ghostdogpr
• Added support for Apollo Persisted Queries using a new Wrapper #302 by @ghostdogpr
• Fixed an issue causing compilation issues when using different ZIO environments in different places. With this fix, it is no longer required to use the same env everywhere in your API #311 by @ghostdogpr
• Added a helper and an example to make http4s middleware creation easier (e.g. for authentication) #310 by @ghostdogpr
• Added instances of ArgBuilder for Seq, Set and Vector #304 by @javimartinez
• Added GET variant to the Finch adapter #312 by @javimartinez
• Added various aliases for ZQuery #306 by @adamgfraser
• Added ArgBuilder example to the docs #315 by @gjuhasz86

Release Notes

Akka Http Adapter

There are some minor breaking changes to akka-http adapter API.
With this release AkkaHttpAdapter doesn't lock you up with circe, but lets you choose a json backend between circe and play-json.
The simplest way to keep previous behavior is to:

• mixin AkkaHttpCirceAdapter trait to your endpoint definition wrapper
• add "de.heikoseeberger" %% "akka-http-circe" % "1.31.0" dependency to your build.sbt, because now it's optional for caliban-akka-http. Luckily, compiler will detect if it's missing.
• Use adapter instead of AkkaHttpAdapter to create routes.

You can see an example of this simple migration here.

A more composable and recommended way to create caliban adapter would be this (this time it's play-json):

val adapter = AkkaHttpAdapter(new PlayJsonBackend)

#292 #296 by @vpavkin

Other Changes

• Fixed an issue in ZQuery causing some effects to be evaluated twice #291 by @adamgfraser
• Added ZQuery#optional #293 by @adamgfraser
• Added Schema instances for Seq and Vector #297 by @ghostdogpr
• Added Schema instance for Play Json #294 by @vpavkin

Release Notes

Fixed a bug causing a failure to parse enums used in variables.

Release Notes

Fixed a regression in the WebSocket protocol implementation in Http4sAdapter and AkkaHttpAdapter that caused subscriptions not to be received.

Release Notes

ZIO upgrade

Caliban is now using ZIO 1.0.0-RC18-2 which should be one of the last versions before it reaches 1.0.0. All the examples have been updated to make use of the new ZLayer data type for building and providing environments (#279 by @ghostdogpr ).

In addition to this, ZQuery and GraphQLInterpreter now have provideLayer variants (#270 #271 by @adamgfraser @ghostdogpr).

Type name validation

When turning your API into an interpreter, Caliban will now verify that each type is defined only once and return an error if for example it finds a clash between 2 case classes with the same name from different packages. In the process, the check method was moved from GraphQL to GraphQLInterpreter (#274 by @ghostdogpr ).

Caliban Client bug fixes and improvements

• Fixed an error when receiving a response with no data field #252 by @ghostdogpr
• Fixed input values encoding #253 by @ghostdogpr
• Added a default value for arguments of type Option and List #254 by @kitlangton

Other Changes

• Fixed handling of variables nested inside lists and objects #257 by @Krever
• Improved schema validation #243 #244 by @TobiasPfeifer @mriceron
• Added skipValidation parameter to all adapters #260 by @javimartinez
• Added support for error extensions #246 by @DJLemkes
• Upgraded Finch to 0.32.1 and added support for Scala 2.13 #278 by @ghostdogpr
• Allowed defining an empty root query (useful when you break your API in multiple parts and combine them) #274 by @ghostdogpr
• Added parser support for Type System Extensions #266 by @jorge-vasquez-2301

Release Notes

GraphQL Client

This release comes with the first version of a new module called caliban-client that allows writing and executing type-safe GraphQL queries in plain Scala. Check the docs for more information!

Breaking change

The method GraphQL#interpreter now returns an effect that can fail with a ValidationError. This change allows performing additional checks when turning an API into an interpreter, such as verifying that types are not using forbidden names, etc. You'll need to modify your code to run this effect before you can use the interpreter. (#227 #233 by @ghostdogpr @palanga )

Other Changes

• Added new adapter for Finch (#179) by @hderms
• Added support for interfaces using an annotation (#223)
• Added custom directive support (#225) by @paulpdaniels
• Added wrapper for Apollo Caching (#225) by @paulpdaniels
• Fixed an issue causing a validation error for input scalars that are object-shaped (#241)
• Updated magnolia to 0.12.7

Release Notes

• New caliban-monix module for Monix interop with support for Task and Observable (#214)
• Added support for WebSockets in Akka HTTP Adapter (#219) together with @phderome
• Made GraphQL#combine logic smarter (#217)
• Updated http4s to 0.21.1

Release Notes

• Added an sbt plugin called caliban-codegen to generate Scala code from a GraphQL Schema by @igorfialko @yoohaemin @ghostdogpr
• Solved a potential stack overflow issue with Map, Either and Tuple schemas (#197)
• Improvements to ZQuery ergonomics by @adamgfraser (#194 #200)
• Made maxDepth and maxFields wrappers stack-safe
• Updated fastparse to 2.2.4
• Updated http4s to 0.21.0
• Updated cats-effect to 2.1.1
• Updated circe to 0.13.0

Release Notes

Major changes

Caliban allows you to perform additional actions at various levels of a query processing, via the concept of Wrapper. Using wrappers, you can:

• verify that a query doesn't reach some limit (e.g. depth, complexity)
• modify a query before it's executed
• add timeouts to queries or fields
• log each field execution time
• support Apollo Tracing or anything similar
• etc.

Use GraphQL#withWrapper or @@ to attach a wrapper to an API:

val api = graphQL(...) @@ timeout(3 seconds)

Built-in wrappers include:

• maxDepth returns a wrapper that fails queries whose depth is higher than a given value
• maxFields returns a wrapper that fails queries whose number of fields is higher than a given value
• timeout returns a wrapper that fails queries taking more than a specified time
• printSlowQueries returns a wrapper that prints slow queries
• onSlowQueries returns a wrapper that can run a given function on slow queries

The previous feature called query analyzers have been replaced by wrappers which are strictly more powerful.

Other Changes

• Added support for Apollo Tracing (#165)
• Added path information in errors (#165)
• Added source location information in errors (#168) by @paulpdaniels
• Support for custom Json scalar for Circe Json (#176). Requires import caliban.interop.circe.json._.
• Support for GET requests in http4s and akka adapters (#177) by @phderome
• ZStream used in Queries and Mutations will be transformed into List since it only makes sense to return a stream for Subscriptions (#174)
• Fixed a potential class cast exception when using mapError
• Added variant makeHttpServiceM in Akka HTTP Adapter to hide usage of unsafeRun from calling code (#181) by @loicdescotte
• Updated akka to 2.6.3
• Updated fastparse to 2.2.3