d-exclaimation / over-layer

A GraphQL over Websocket Stream-based Transport Layer on Akka.

OverLayer

A GraphQL over Websocket Stream-based Transport Layer on Akka.

Setup

Latest Version: 1.0.3

"io.github.d-exclaimation" %% "over-layer" % latestVersion

GraphQL Over Websockets

In the GraphQL world, we have the concept of a "subscription" which is a request from the client to subscribe a stream of data that is sent from the server. This is usually done using websocket with a additional subprotocol.

This package is a websocket transport layer for managing, encoding, and decoding Sangria stream based operations into the proper sub-protocol format using Akka Actors.

Usage/Examples

• Documentation
• Getting Started

Protocols

• subscriptions-transport-ws
• graphql-ws

Feedback

If you have any feedback, feel free to reach out through the issues tab or through my Twitter @d_exclaimation.

over-layer's Issues

Feature Request: GraphQL over SSE

Description

Implement GraphQL Subscription over SSE (Subscription operation only). Shouldn't be too difficult as to GraphQL over WebSocket. However, I need to support the graphql-sse protocol to be fully client compatible. Not sure whether to support other protocols and client implementation.

Prerequisites

• #2
• #5
• #4

Implementation and Plans

• Start with focusing solely on Distinct connections mode on HTTP/2 (require enabling HTTP/2 for akka-http).
• Continue with implementing Single connection mode which require a lot more configuration with the HTTP side of the applications but allow for HTTP/1.1.

Bug: GraphQL Subscription Source abruptly terminated after idle for longer than 30 seconds

Description

I found an issue where the GraphQL subscription Akka Source died after 20-30 seconds of being idle (no data). Not sure the cause outside a timeout. Error thrown said Actor system or materializer was terminated when it's clearly not.

Callback to send a message to Ended message was not delivered, for unknown reason.

Need to fix. Either add a logic to reinitialize stream on failure or find out why the timeout happens in the first place.

Bug: Kill Switch kills entire stream

Description

When trying to stop an operation, the Envoy shuts down the appropriate stream to prevent sending more data, but this ended up killing the appropriate subscription entirely, not sure on whether that's just the envoy's fault or not.

A temporarily solution

Use a Sink instead of runForEach, which will handle broadcasting data also might allow me to kill the sink but not the Source.

Bug: Websocket Flow and Sink completed even when message is passing through.

Description

I was strictly aware that akka streams are all given with timeouts mostly to prevent memory leaks. However, even though data is going out of the flow, The flow completes by itself (Sink was affected and also trigger onComplete). Despite that, The Source were fine, the graphql subscriptions were also fine. They didn't stop due to the fact data is flowing through. The termination ended alongside closing the websocket which is an issue if data is the process of being push out.

Not sure, what is causing it. Maybe it's just my poor implementation for the Flow that didn't work or some configuration was setup.

For now, I am labelling it as unresolved issue / bug.

Update packages

Enhancement: API Documentation & Advanced Guide

Description

Adding the missing API documentation, and additional guide for specific use cases.

Prerequisites

• #4

Enhancement: Integrate Unit Test

Description

Adding Unit Tests to the package would be great. Automating that with Github Actions can be also a nice thing to have. At the moment, I have an end-to-end test working but I don't know how to set that one up with Github Actions, but still probably be needing a proper unit test as well.

Feature Request: Subscription Operation

Description

Allowing no subscription operation. At the moment, I restrict the transport layer to only accept subscription as non subscription are usually sent via regular HTTP. However, I do think it's very possible to add this capability, not to mention, there are no limitations like what were on Whiskey.

Do note that mutation on subscription probably have less security and more potential exploits and vulnerability. Adding back the security convenience of HTTP over a single web-socket connection would be more work than necessary.

Solution suggestion

Let ProxyServer handle non subscription operations immediately instead of passing down to Envoy as this will be a short lived operation and will not collide with the executor streaming setup on Envoy.

Enhancement: Consider publishing with Scala Compiler version

Description

At the moment, package is published without the suffix of _<scala-version>. I don't know exactly what issues it can be when trying to use this package on older scala version, so I might consider adding that into the published package to make sure it can only be fetch for version that can work with it

Changes

Changes to build.sbt

// Remove this line
crossPaths := false

Changes to fetching as dependencies

"io.github.d-exclaimation" %% "over-layer" % "0.1.1"

Sunsetting OverLayer

With the recent news that Akka is changing their license, I am a bit uncertain for the future of this library as a whole. This library relies heavily on Akka, Akka Streams, and Akka HTTP. I don't see myself maintaining this library given that 3 of its primary dependencies are not going to be open source any more. Not to mention to use this, you would also need to use those 3 libraries which I feel like defeats the purpose of having this library to begin with.