Base branch for protocol v2 #127

masad-frost · 2024-05-15T16:44:05Z

All the changes are documented in Protocol.md but here's a summary:

Handle invalid client requests by sending a close with an error back
- This was the main motivation for the change. While we could sort-of implement this error response without the other changes, things are setup in such a way where it is very hard to implement correctly without deeper changes in how we handle closing.
Add more robust closing mechanics
- Half-close states
- Close signals from read end of the pipes
- Abort full-closure (for errors and cancellation)
Switch from Pushable and AsyncIterator APIs to a ReadStream and WriteStream
All procedures have init and some have input

While the changes are not strictly backwards compatible, hence the major protocol bump, the system can still operate across versions to some extent.

See PRs linked below for more information on the above

TODOs

.replit

jackyzha0 · 2024-06-03T16:43:53Z

PROTOCOL.md

@@ -64,27 +64,43 @@ Note that this protocol specification does NOT detail the language-level specifi
 1. `subscription`: the client sends 1 message, the server responds with m messages.

 A server (also called a router) is made up of multiple 'services'. Each 'service' has multiple 'procedures'.
-A procedure declares its type (`rpc | stream | upload | subscription`), an input message type (`Input`), an output message type (`Output`), an error type (`Error`), and the associated handler.
+A procedure declares its type (`rpc | stream | upload | subscription`), an initial message (`Init`), an output message type (`Output`), an error type (`Error`), and the associated handler. `upload` and `stream` may define an input message type (`Input`), which means they accept further messages from the client.


it's still weird to me that 'additional' messages are called Input

feels like

Init should be Input

Input should be Stream or Body

(i just cooked up Stream off the top of my dome but that actually seems like the reasonable thing here)

I like the direction that input gives. Body can mean output too. Maybe we should use request/response terminology.

Init could also mean output too, I agree though maybe request/terminology would help here

jackyzha0 · 2024-06-03T16:46:02Z

PROTOCOL.md


-Note that any procedure that has a client-to-server procedure stream (i.e. `stream` and `upload`) can optionally define a single initialization message to be sent to the server before the client starts sending the actual `Input` messages.
+- `rpc`: `Init -> Result<Output, Error>`
+- `upload`: `Init, AsyncIter<Input> -> Result<Output, Error>`


maybe replace AsyncIter + Pushable with readable/writable streams and provide TS definitions for those here

yeah could use an update here re: AsyncIter + Pushable

jackyzha0 · 2024-06-03T17:01:40Z

PROTOCOL.md

+
+Writers send messages that are recieved by the other side's reader. ONLY writers can end streams. Readers can send a signal to the writer that they are no longer interested in the stream, but the writer can choose to ignore this signal and continue sending messages.
+
+Streams can be in a half-closed state. This happens when one party sends a close signal indicating that it will no longer send


maybe to clarify, we should say that any given stream is made up of a write side and read side

A | B 1 <--|--- 3 2 --|---> 4 1. A-side read 2. A-side write 3. B-side write 4. B-side read

half-closes can only be sent on 2 and 3

* Update PROTOCOL.md * Update PROTOCOL.md Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * Update PROTOCOL.md * half-close semantics * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * fmt * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Update PROTOCOL.md * Include reader-writer semantics --------- Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com>

* ReadStream implementation * remove tee for now * Make the stream itself an iterable * Implement return for iterator * comment

jackyzha0

talked more IRL, going to think a bit more about the stream interface and ergonomics broadly

i think directionally very correct but could use a lot of simplification

jackyzha0 · 2024-07-26T19:52:22Z

README.md

- input: Type.Object({ n: Type.Number() }),
- output: Type.Object({ result: Type.Number() }),
+ requestData: Type.Object({ n: Type.Number() }),
+ responseData: Type.Object({ result: Type.Number() }),
 errors: Type.Never(),
 // note that a handler is unique per user RPC
 async handler(ctx, { n }) {


probably needs an update too

same with await client.example.add.rpc below

jackyzha0 · 2024-07-26T19:54:21Z

PROTOCOL.md


-Note that any procedure that has a client-to-server procedure stream (i.e. `stream` and `upload`) can optionally define a single initialization message to be sent to the server before the client starts sending the actual `Input` messages.
+- `rpc`: `Init -> Result<Output, Error>`
+- `upload`: `Init, AsyncIter<Input> -> Result<Output, Error>`


yeah could use an update here re: AsyncIter + Pushable

jackyzha0 · 2024-07-26T20:03:21Z

PROTOCOL.md

 - It is an explicit heartbeat, so the `AckBit` MUST be the only bit set.
 - The payload MUST be `{ type: 'ACK' }`.
 - Because this is a control message that is not associated with a specific stream, you MUST NOT set `serviceName` or `procedureName` and `streamId` can be something arbitrary (e.g. `heartbeat`).

+There are 2 error payloads that are defined in the protocol sent from server to client, these codes are reserved:


Suggested change

There are 2 error payloads that are defined in the protocol sent from server to client, these codes are reserved:

There are 3 error payloads that are defined in the protocol sent from server to client, these codes are reserved:

jackyzha0 · 2024-07-26T20:04:54Z

PROTOCOL.md

+
+`ProtocolError`s, just like service-level errors, are wrapped with a `Result`, which is further wrapped with `TransportMessage` and MUST have a `StreamAbortBit` flag. Please note that these are separate from user-defined errors, which should be treated just like any output message.
+
+There are 4 `Control` payloads:


control payloads technically aren't normative i think, i just send these in the TS implementation so its easier to debug without needing to decode the controlFlags but controlFlags are enough

is the suggestion here that we change it to be normative?

jackyzha0 · 2024-07-26T20:05:14Z

PROTOCOL.md

+
+interface ControlHandshakeRequest {
+ type: 'HANDSHAKE_REQ';
+ protocolVersion: 'v2.0';


lfg

maybe we should have docs on how to handle v1 receiving a v2 request and vice versa

router/server.ts

router/streams.ts

util/testHelpers.ts

__tests__/typescript-stress.test.ts

masad-frost · 2024-07-30T19:13:30Z

good review, i'll be sending some PRs and we can sync up afterwards

Got some comments on streams being complicated, so this is a take on simplified API. - Less methods and states that people need to understand - Merge interfaces into a single object (i.e. a `stream` call would have both read and write capabilities on the same object)

## Why Follow up on #249 to actually use the new interfaces. Removed extra refactor done in #249 that merges the interfaces as that proved to be a challenging API (un-yak-shave 🙅 🐃) ## What changed - Removed close requests (mostly cherry-picked from #248) - Otherwise a simple swapping out of the interfaces ## Versioning - [ ] Breaking protocol change - [ ] Breaking ts/js API change

Just a simple follow up to #250

masad-frost requested a review from a team as a code owner May 15, 2024 16:44

masad-frost requested review from jackyzha0 and removed request for a team May 15, 2024 16:44

masad-frost force-pushed the protocolv2 branch 2 times, most recently from cc48498 to 23a05c8 Compare May 21, 2024 18:10

masad-frost mentioned this pull request May 21, 2024

Client uses ReadStream and WriteStream #136

Merged

2 tasks

masad-frost force-pushed the protocolv2 branch from 9be4fa0 to ad39e56 Compare May 21, 2024 23:39

masad-frost mentioned this pull request May 23, 2024

improve tracing #140

Merged

2 tasks

masad-frost force-pushed the protocolv2 branch from e0d311b to b7bd349 Compare May 29, 2024 18:57

masad-frost closed this May 31, 2024

masad-frost reopened this May 31, 2024

masad-frost force-pushed the protocolv2 branch from 053a846 to 751ccaf Compare May 31, 2024 21:05

masad-frost mentioned this pull request May 31, 2024

[protocolv2] Half-close client #162

Merged

masad-frost force-pushed the protocolv2 branch from 751ccaf to 6a8a15a Compare May 31, 2024 23:06

masad-frost mentioned this pull request Jun 1, 2024

[protocolv2] Implement close requests #165

Merged

jackyzha0 reviewed Jun 3, 2024

View reviewed changes

.replit Outdated Show resolved Hide resolved

jackyzha0 reviewed Jun 3, 2024

View reviewed changes

masad-frost force-pushed the protocolv2 branch 2 times, most recently from d310cd0 to 4311f54 Compare June 6, 2024 18:50

masad-frost mentioned this pull request Jun 11, 2024

Emit status events when transport status changes #184

Merged

2 tasks

masad-frost force-pushed the protocolv2 branch 2 times, most recently from 973954f to fd4afee Compare June 13, 2024 15:36

masad-frost force-pushed the protocolv2 branch from eab068d to 334056e Compare June 20, 2024 18:39

masad-frost and others added 5 commits June 24, 2024 23:49

Add INVALID_REQUEST to RiverUncaughtSchema (#107)

34dc578

Streams interface (#118)

bbac0b2

ReadStream implementation (#130)

3675b23

* ReadStream implementation * remove tee for now * Make the stream itself an iterable * Implement return for iterator * comment

WriteStream implementation (#132)

a802329

masad-frost added 18 commits July 15, 2024 18:04

0.200.0-rc.7

b2cb04f

Merge remote-tracking branch 'origin/main' into protocolv2

c70e8b0

0.200.0-rc.8

4357884

Add unwrap to iterator

944ea30

0.200.0-rc.9

9b55481

Fix asClientUpload returning an array

7b50c64

0.200.0-rc.10

7e42e02

Expose serializeSchemaBackwardsCompatible

5cb0ede

0.200.0-rc.11

93b4aa9

Expose old serialized schemas

632e212

0.200.0-rc.12

e64d96f

Merge remote-tracking branch 'origin/main' into protocolv2

60a18b6

0.200.0-rc.13

8782852

Allow nested unions as errors

93479b4

0.200.0-rc.14

493babe

0.200.0-rc.15

adbcc1b

Merge remote-tracking branch 'origin/main' into protocolv2

0df2852

0.200.0-rc.16

8227782

jackyzha0 reviewed Jul 30, 2024

View reviewed changes

masad-frost commented Jul 30, 2024

View reviewed changes

__tests__/typescript-stress.test.ts Outdated Show resolved Hide resolved

masad-frost mentioned this pull request Jul 30, 2024

[protocolv2] Remove the concept of close requests #248

Closed

masad-frost added 2 commits July 31, 2024 19:00

fmt

251758b

masad-frost mentioned this pull request Aug 1, 2024

[protocolv2] Use new simpler readable and writable interfaces #250

Merged

2 tasks

masad-frost added 5 commits July 31, 2024 22:16

[protocolv2] Rename reader to readable and writer to writable (#251)

87dd2de

Just a simple follow up to #250

Address a bunch of feedback

d44ef6b

restucture onmessage a bit

97f1479

Update tests

50aaf24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Base branch for protocol v2 #127

Base branch for protocol v2 #127

masad-frost commented May 15, 2024 •

edited

Loading

jackyzha0 Jun 3, 2024

masad-frost Jun 3, 2024

jackyzha0 Jun 3, 2024

masad-frost Aug 2, 2024

jackyzha0 Jun 3, 2024

jackyzha0 Jul 26, 2024

masad-frost Aug 2, 2024

jackyzha0 Jun 3, 2024

masad-frost Aug 2, 2024

jackyzha0 left a comment

jackyzha0 Jul 26, 2024

jackyzha0 Jul 26, 2024

masad-frost Aug 2, 2024

jackyzha0 Jul 26, 2024

jackyzha0 Jul 26, 2024

masad-frost Aug 2, 2024

jackyzha0 Jul 26, 2024

masad-frost Aug 2, 2024

jackyzha0 Jul 26, 2024

masad-frost Aug 2, 2024

masad-frost commented Jul 30, 2024


		Writers send messages that are recieved by the other side's reader. ONLY writers can end streams. Readers can send a signal to the writer that they are no longer interested in the stream, but the writer can choose to ignore this signal and continue sending messages.

		Streams can be in a half-closed state. This happens when one party sends a close signal indicating that it will no longer send

	There are 2 error payloads that are defined in the protocol sent from server to client, these codes are reserved:
	There are 3 error payloads that are defined in the protocol sent from server to client, these codes are reserved:


		`ProtocolError`s, just like service-level errors, are wrapped with a `Result`, which is further wrapped with `TransportMessage` and MUST have a `StreamAbortBit` flag. Please note that these are separate from user-defined errors, which should be treated just like any output message.

		There are 4 `Control` payloads:

Base branch for protocol v2 #127

Are you sure you want to change the base?

Base branch for protocol v2 #127

Conversation

masad-frost commented May 15, 2024 • edited Loading

TODOs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jackyzha0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

masad-frost commented Jul 30, 2024

masad-frost commented May 15, 2024 •

edited

Loading