borer-compat-akka

ByteString support

The borer-core module by itself only knows how to encode to and decode from plain byte arrays (Array[Byte]) and a few other types (like java.nio.ByteBuffer, see the chapter on Input, Output, ByteAccess for full details).

When you include the borer-compat-akka module as a dependency (see the Getting Started chapter for details) and

import io.bullet.borer.compat.akka.*

you also get:

  • full “zero-copy” support for encoding to and decoding from akka.util.ByteString
  • implicit codecs for akka.util.ByteString, akka.actor.ActorRef and akka.actor.typed.ActorRef[T]

Akka Http (Un)Marshalling

In addition to ByteString support the borer-compat-akka also provides convenient marshallers and unmarshallers for HTTP entities.

When you include the borer-compat-akka module as a dependency (see the Getting Started chapter for details) and

import io.bullet.borer.compat.akkaHttp.*

akka-http will transparently marshal to and from your custom domain model types:

sourceimport akka.http.scaladsl.server.Route
import akka.http.scaladsl.server.Directives.*

// borer encoders/decoders for the custom model above
import io.bullet.borer.{Encoder, Decoder}
import io.bullet.borer.derivation.MapBasedCodecs.*

// custom model for request and response content
case class MyRequest(foo: String) derives Decoder
case class MyResponse(importantValue: Int) derives Encoder

// bring automatic (un) marshaller construction in scope
import io.bullet.borer.compat.akkaHttp._

// route that unmarshalls to `MyRequest` and marshals to `MyResponse`
val route: Route =
  pathSingleSlash {
    post {
      entity(as[MyRequest]) { myRequest =>
        complete {
          MyResponse(myRequest.foo.length)
        }
      }
    }
  }

By default the Unmarshaller constructed by borer-compat-akka understand both CBOR and JSON with Content-Type application/cbor and application/json, respectively.
The Marshaller also supports both formats and lets the client determine via HTTP content negotiation (i.e. the Accept header) , which one it prefers. If the client has no clear preference, i.e. it accepts both CBOR and JSON with equal “q-value” (preference weight) the Marshaller choses JSON by default. This default, however, can be configured to CBOR if needed.

(Un)marshaller construction can be customized in various ways, e.g. with custom media types, and is also available for streams, i.e. to and from akka.stream.scaladsl.Source[T, _] rather than simply T.
Check out the sources for full details.

1.14.0