Akka Streams Json Support

⚠️ This project is no longer being maintained due to Akka's move away from Open Source. There is version of this library pekko-streams-circe that uses Pekko, the open source fork of Akka.

This library provides Json support for stream based applications using jawn as a parser. It supports all backends that jawn supports with support for circe provided as a example.

Differences with akka-stream-json

This is a fork of akka-stream-json since it no longer appears to be maintained. Hence the main differences between akka-stream-json and this project is.

• The project is called akka-streams-json rather than akka-stream-json. This is just to differentiate the git repos and project names.
• This project aims to be updated to the latest versions of akka/akka-http/circe as frequent as possible. PR's are also welcome to maintain the project
• We use ScalaTest rather then Specs2 for testing. This is because ScalaTest has better Future support compared to Specs2 (in order to do tests against Future in Specs2 you have to block on the Future which degrades performance a lot).

Apart from this, the actual initial code/implementation is exactly the same as the fork, the only difference being the package names (i.e. using org.mdedetrich rather than de.knutwalker). The following contents of README.md was also mainly copied from the original repo.

Installation

There are two main modules, akka-stream-json and akka-http-json. akka-stream-json is the basis and provides the stream-based parser while akka-http-json enabled support to use the desired json library as an Unmarshaller.

libraryDependencies ++= List(
  "org.mdedetrich" %% "akka-stream-json" % "0.8.2",
  "org.mdedetrich" %% "akka-http-json" % "0.8.2"
)

akka-streams-json depends on jawn-parser at version 1.0.0 for the 0.7.x series The circe submodule depends on version 0.13.x of circe-jawn for 0.7.x series

akka-stream-json is published for Scala 2.13 and 2.12.

Usage

The parser lives at org.mdedetrich.akka.json.stream.JsonStreamParser

Use one of the constructor methods in the companion object to create the parser at various levels of abstraction, either a Stage, a Flow, or a Sink. You just add the jawn support facade of your choice and you will can parsed into their respective Json AST.

For Http support, either import org.mdedetrich.akka.http.JsonSupport._ or mixin ... with org.mdedetrich.akka.http.JsonSupport.

Given an implicit jawn facade, this enable you to decode into the respective Json AST using the Akka HTTP marshalling framework. As jawn is only about parsing and does not abstract over rendering, you'll only get an Unmarshaller.

Circe

libraryDependencies ++= List(
  "org.mdedetrich" %% "akka-stream-circe" % "0.8.2",
  "org.mdedetrich" %% "akka-http-circe" % "0.8.2"
)

(Using circe 0.14.x)

Adding support for a specific framework is quite easy.

These support modules allow you to directly marshall from/unmarshall into your data types using circes Decoder and Encoder type classes.

Just mixin or import org.mdedetrich.akka.http.support.CirceHttpSupport for Http or pipe your Source[ByteString, _].via(org.mdedetrich.akka.stream.CirceStreamSupport.decode[A]) to get a Source[A, _].

This flow even supports parsing multiple json documents in whatever fragmentation they may arrive, which is great for consuming stream/sse based APIs.

If there is an error in parsing the Json you can catch org.mdedetrich.akka.http.support.CirceStreamSupport.JsonParsingException. The exception provides Circe cursor history, current cursor and the type hint of the error.

Why jawn?

Jawn provides a nice interface for asynchronous parsing. Most other Json marshalling provider will consume the complete entity at first, convert it to a string and then start to parse. With jawn, the json is incrementally parsed with each arriving data chunk, using directly the underlying ByteBuffers without conversion.

License

This code is open source software licensed under the Apache 2.0 License.