[Discussion] Websocket support

[joshmossas]

Currently the only support for realtime messages is via Server Sent Events. This works well but only supports server -> client messages. One day it would be good to have first class websocket support enabling two-way realtime communication.

Some Things To Consider

• Do we keep the request -> response model of current HTTP procedures? Or do we need to establish a new abstraction for these sorts of messages?
  • For example JSON-RPC has request -> response style RPCs and notifications which are send and forget
  • Maybe if we come up with a new notifications / events abstraction this could be reused for webhooks and other similar send and forget style events.
• How will we handle authentication?
  • HTTP headers are only available during the initial "upgrade" request
• How will we determine what procedure is being called?
  • URLs are being used for HTTP procedures, which obv doesn't work for websockets

Some Initial Ideas

Not a ton of thought has been put into these just kinda spitballing here.

Mimicking the Server Sent Event (SSE) payload

We could use a format similar to Server Sent Events (SSE). SSE messages use \n\n to separate different properties.

# example SSE
event: message
data: {"id":"1","content":"hello world"}

Similarly websocket messages could look something like this:

# request payload
id: 1442
procedure: users.getUser
headers: { "Authorization": "Bearer 12345", "client-version": "4" }
data: { "userId": "1" }

# response payload
id: 1442
statusCode: 200
procedure: users.getUser
data: { "id":"1", "name": "John Doe", "email": null, "isAdmin": false }

\n already have to be escaped by JSON so there's no conflicts there.

The id field could be used by the client to implement a request -> response style pattern. Maybe omitting the id field would make it "send and forget".

The procedure field is used to indicate which procedure is being called.

The statusCode field is used to indicated whether the response failed or not. I used an HTTP status code here but that might be weird - unsure. (Currently RPC errors are pretty heavily tied to HTTP status codes. I might need to make a cleaner error declaration abstract to enable other protocols. Either that or we just use HTTP status codes for everything even if it's technically not HTTP)

The headers field would be the client headers sent with every request. (Some alternative approaches could be explored to maybe avoid sending client headers with every request?)

The data field is the actual payload of the message

Mimicking the HTTP Payload

We could also explore sending a payload that's similar to HTTP itself. Then any needed metadata could be set as headers before the actual body

# example HTTP request
POST /users/get-user HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.example.com
Content-Type: application/json
Authorization: Bearer 12345
Client-Version: 4

{ "userId": "1" }

# example Arri websocket request payload
users.getUser
Request-Id: 1442
Authorization: Bearer 12345
Client-Version: 4

{ "userId": "1" }

# example Arri websocket response payload
users.getUser
Status-Code: 200
Request-Id: 1442

{ "id":"1", "name": "John Doe", "email": null, "isAdmin": false }

Just like the other example maybe the Request-Id header could be omitted for "send and forget" style requests.

One advantage to this is that it would be pretty trivial to send alternative content types like cbor or messagepack should we add support down the line (I would like to eventually support a binary encoding method). A simple Content-Type header would do the trick just like with HTTP.

[jeftadlvw]

I'd abstract the communication from the transport layer.

What if you use arri itself to cast the metadata into a schema? You'd define the metadata schema, include a payload key, populate the object and serialize it according to the transport layer. This might even allow for optimized metadata serialization per transport layer. So in case of HTTP, you could use HTTP-Headers. Or when using binary representations, you could reduce your metadata keys to magic numbers instead of strings.

Additional idea for HTTP:
You could choose binary content type (like cbor) to use as the HTTP body to improve throughput? That said, I did not look too deep into the project yet. Maybe you're already doing that.

This project has a lot of potential. Looking forward to your decisions!
For HTTP media types see: https://www.iana.org/assignments/media-types/media-types.xhtml

[joshmossas]

Hey @jeftadlvw

I actually love the idea of creating a schema for the request metadata. That'll allow us to create a type-safe experience for global metadata like auth tokens. We'll have to make some breaking changes to the TS server and Go server to account for this but it'll prolly be worth it long term. I would also like to preserve the ability to interact directly with the with the HTTP (and later Websocket) primitives on the server side, but that should be doable.

Magic Numbers

Concerning magic numbers. I've actually been thinking it'd be cool to build in a option to enable this across arri. Basically some toggle in which all the keys get changed to numbers to reduce in payload size. This could be an optional toggle in the generated clients and the server would respond accordingly. So full property names by default with the option to optimize if desired.

Maybe the schemas could look something like this:

// TS

// some possible syntax options for defining these magic numbers
const User = a.object("User", {
  id: a.keyId(1, a.string()),
  name: a.keyId(2, a.string()),
  email: a.keyId(3, a.nullable(a.string())),
});
const User = a.object("User", {
  id:  a.string({ keyId: 1 }),
  name: a.string({ keyId: 2 }),
  email: a.nullable(a.string(), { keyId: 3 }),
});
const User = a.object("User", {
  "id|1": a.string(),
  "name|2": a.string(),
  "email|3": a.nullable(a.string()),
});
type User = a.infer<typeof User>


const myUser = {
  id: "foo",
  name: "john doe",
  email: null,
};

// default serialization
a.serialize(User, myUser);
// { "id": "foo", "name": "john doe", "email": null }

// serialization with minified keys
a.serialize(User, { id: "foo", name: "john doe", email: null }, { minifyKeys: true })
// { "1": "foo", "2": "john doe", "3": null }

// go
type User struct {
  Id string `id:1`
  Name string `id:2`
  Email arri.Nullable[string] `id:3`
}

myUser := User{
  Id: "foo",
  Name: "john doe",
  Email: arri.Null[string](),
}

// default serialization
arri.EncodeJSON(myUser, arri.EncodingOptions{})
// { "id": "foo", "name": "john doe", "email": null }

// serialization with minified keys
arri.EncodeJSON(myUser, arri.EncodingOptions{ MinifyKeys: true })
// { "1": "foo", "2": "john doe", "3": null }

The Go syntax seems pretty straightforward. I will have to think more about the typescript syntax. It could get really noisy if we aren't careful, but the idea has a lot of promise.

Binary Payloads

Concerning using a binary content type, I 100% want to support a binary format in the future. The two I've been leaning towards are either cbor or msgpack but I'm open to feedback regarding this. I think my only requirement is that it probably should be a self-describing format similar to JSON (i.e. not protobuf or flatbuffers). Would be willing to expound upon my reasoning for this if pressed on it though. I could also have my mind changed. The feature should also be toggleable.

That said I think I probably want to nail down the Arri specifications first and get us to a v1.0.0 before I start exploring these various optimizations.

[joshmossas]

That said there are several bits of metadata that are constant regardless of the transport. Namely the procedureName, clientVersion and in the case of websockets probably a requestId. So these would need to be separate from any user defined metadata, but that's easy enough.

Also I think we can prolly still call this metadata "headers" (maybe RPC headers?) since they will appear before the body of any message regardless of transport.

[jeftadlvw]

Hi @joshmossas

Your thoughts sound good! I'll fire some more input and opinions to think and consider, if that's okay ^^

I would also like to preserve the ability to interact directly with the with the HTTP (and later Websocket) primitives on the server side, but that should be doable.

Yes, agree. I did not mean to not use HTTP, but to abstract the networking so that the user is free to choose which network layer to use (HTTP, Websocket, TCP socket, ...) and that each abstraction layer translates outgoing and incoming data so that the user interacts with a uniform interface. This way you can still use HTTP headers for e.g. metadata, but the user would get a regular Map<string, any>.

That's why I proposed to expose the interface with an arri-schema. Translation layers would return an object, which is validated by arri and passed to the handler.

Using this architecture would easily allow binary data.

The two I've been leaning towards are either cbor or msgpack but I'm open to feedback regarding this.

Yes, agreed. cbor and msgpack both fit really good with your project (data on the wire is schemaless and validated on both sides). I also suggest to export an API to interoperate with these types for uniform use (which you'll already have when sending binary data over the wire (using HTTP or raw TCP) is implemented).

Concerning magic numbers. I've actually been thinking it'd be cool to build in a option to enable this across arri.

Yes, this would be very cool indeed. But manually defining keys does not fit with the vision and goal of this project (as far as I understand) and makes the code less readable (which is definitely not what you want). However, it would be very cool if you'd map object keys to a magic number under the hood for transporting data. This would lead to less bytes in the blob send over the wire. This should not be a problem if both sides have the same schema, which is what you're aiming for (right?).

But I'd postpone this idea and focus on stable naming and terms, a "metadata" schema and dx.

That's my addition to the sauce. Happy programming!

[joshmossas]

Relevant PR. Still very much a work in progress.

#181