Define API shape to interact with back-end over WebSockets

[dzintars]

Currently I am using just simple type and payload structure which will work for a small amount of services, but as amount of services will grow we will encounter bunch of naming collisions. And overall to name the methods will be harder.

Right now i have an idea to mimic the RPC style where wss message should define the service and the method it is calling.
Also i am thinking how to version the methods. Most likely, i don't need to version services as those will be pretty stable, but methods and messages(payload)definitely will be modified over the time.

So, let's define pseudo message shape for now:

/**
 * Messages
 */
const ListModulesRequestPayload {
  parent: action.payload.id,
  page_size: action.payload.pageSize,
  page_token: action.payload.pageToken,
}

/** 
 * Websocket.Send will be an action creator function taking those 3 arguments.
 * Object used to describe the signature.
 */
WebsocketActions.Send: {
  service: 'ModulesService',
  rpc: 'ListModulesRequest',
  message: ListModulesRequestPayload,
}

[dzintars]

What if we want to use multiple wss API endpoints instead of single one?
We will execute something like Websocket.Connect('wss://someService.api.oswee.com'). At this point user could have multiple wss connections open. How do we will distinguish to what connection we should throw that message in?

[dzintars]

What if we want to manage services at proxy level? I mean, we should jump into every wss envelope, read the headers of it and forward to the right service which sound impossible to me with websocket connection.

[dzintars]

Hmmm... seems this could work...
f933e73 and dzintars/wss@be9c394

[dzintars]

Now i need to think, how to incorporate Protobufs for payload definitions.
Ideally i want to define message shape in protobufs and generate TypeScript typings and Go stubs.
This way in TypeScript IDE side at least i will see the shape of the every RPC/method payload.
Perfectly would be to generate some kind of Swagger as well.

[dzintars]

Something feels wrong with current naming.
I am using ListModulesRequest and ListModulesResponse to distinguish between outbound and inbound actions. And then adding a suffix *Payload to name the actual message.
To be closer to the idiomatic Protobufs i would need to use ListModules method name and ListModulesRequest message name. For outbound it could work, but ... what the API should return then? It can't return the same ListModules method name because it could make a loop because Redux will throw that action back into websocket. Or it will simply do nothing, because message signature (data) will be non-serializable in backend.

What if Response will look different?
What if in onmessage() we are looking at "message name" instead of method name?
For example:

const ListModulesResponse {
  name: "ListModulesResponse",
  body: {
    parent: action.payload.id,
    page_size: action.payload.pageSize,
    page_token: action.payload.pageToken,
  }
}

So from API we could receive such simple object:

{
  service: "ModulesService",
  rpc: "ListModules",
  message: {
    name: "ListModulesResponse",
    body: {
      parent: action.payload.id,
      page_size: action.payload.pageSize,
      page_token: action.payload.pageToken,
    },
  },
}

Then message.name would signal an Redux action.
Moreover... we potentially could augment message with version number, some context IDs or.. any other extra data.

[dzintars]

This for now seems good, but carries kinda lot of metadata. All that JSON structure wastes prety much bytes. But it is still much less that plain POST/GET etc request.
https://golb.hplar.ch/2020/04/exchange-protobuf-messages.html
I should look into websocket sub-protocols like WAMP, MQTT etc.. ideally i would like to send messages in binary over the wire.

Also i need to think about some message buffering. If client is trying to send more messages as server can handle. For example large images or other binary data. Connection will be blocked.
https://www.ably.io/concepts/websockets
https://www.npmjs.com/package/protobufjs

protoc -I=$SRC_DIR --js_out=$DST_DIR $SRC_DIR/addressbook.proto

Motivation:
It's not that JSON is bad. These days browsers did a lot optimizations to parse JSON really fast and so on. Main motivation is to have message format which can be understood by client and by the server and to give developers good DX. Because Protobufs uses protobuf IDL which then can be compiled into many languages (in my case Go and potentially TypeScript) it is good candidate for implementation there. And if we use protobufs then we should send messages as arraybuffer. So all that JSON representation above becomes irrelevant.
Besides JSON is quite optimized in browsers, there is still some overhead. It is more important if we want to build event-intensive communication with lots of small and larger messages.
https://medium.com/samsung-internet-dev/being-fast-and-light-using-binary-data-to-optimise-libraries-on-the-client-and-the-server-5709f06ef105
So, at the end we have 2 goals there:

• Make communication effective
• Make good DX

[dzintars]

You could either wrap your messages in an envelope message, for example ...

message Envelope {
  oneof kind {
    SomeMessage a = 1:
    SomeOtherMessage b = 2;
  }
}

or implement a custom header for your purpose.

protobufjs/protobuf.js#689

[dzintars]

Some updates from Go Protobufs
gogo/protobuf#691
https://blog.golang.org/protobuf-apiv2

[dzintars]

The binary protobuf encoding format is not most CPU efficient for browser clients. Furthermore, the generated code size increases as the total protobuf definition increases.
https://github.com/grpc/grpc-web/blob/master/doc/roadmap.md#non-binary-message-encoding

But I still should think about the bandwidth. If this service will be hosted in some of the clouds, then every extra byte can be costly for event-intensive communication. Same applies for mobile users on 2G and 3G.

[dzintars]

How to import type declarations from external API repository?
https://dev.to/room_js/typescript-how-do-you-share-type-definitions-across-multiple-projects-1203

npm link ?
lerna ?

[dzintars]

At this point i created simple Module package in API and imported type declarations in app-navigation redux.
This link helped a little bit understand how to use protobuf generated declarations - https://github.com/easyCZ/grpc-web-hacker-news/blob/32fd37b82d5dafcd4c51089b82f4c52b8514504f/README.md

My questions ATM:

• How to namespace all message types per service so that i could import them in TS like @oswee/modules-service/list-modules-response or similar way.
• Should i focus for now just on simple JSON exchange format?

[dzintars]

Today i got an thought that... probably my current approach of sending entire object of

export interface Modules {
  readonly entities: { [id: string]: Module }
  readonly ids: string[]
}

is wasteful.

If we are using websocket we should not send large messages.
Instead, i could send every Module entity as separate message.
Websocket is tailored for a small "packets". If we send large blobs, the socket gets blocked.
Also... current approach could introduce some over-consumption of data.
It would allow for more flexible data manipulations.
From UX perspective, user should not wait for an entire data set. If user is interested in last record created and we stream latest data first, then user immediately sees the his record and can make manipulations on it. And we have an opportunity to cancel delivery of the remaining entities if user navigated away from the current view (little bandwidth optimization).
Also, it seems to me that Protobufs does not support entities: { [id: string]: Module } field type.

Downsides is that every time new entity arrives, store get updated and thus components get repainted.

This could change the communication message shape as we are leaning away from Request/Response thinking more towards Events.

New navigation/Component Connected callback
1st entity arrived
2nd entity arrived
3rd entity arrived
Nth entity arrived

Basically UI should not ask for the data. UI just broadcasts an events. Depending on the events, relative data gets streamed back.

This is some mental shift in the thinking.