Skip to content

Commit d9cc855

Browse files
committed
more simplification. Eliminated header chains.
1 parent d8e43cc commit d9cc855

File tree

1 file changed

+44
-133
lines changed

1 file changed

+44
-133
lines changed

Protocol.md

Lines changed: 44 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -68,59 +68,10 @@ A stream ID must be locally unique for a Requester in a connection.
6868
| __REQUEST_N__ | 0x0015 | __Request N__: Request N more items |
6969
| __CANCEL__ | 0x0016 | __Cancel Request__: |
7070
| __RESPONSE__ | 0x0020 | __Response__: Response to a request. |
71+
| __ERROR__ | 0x0021 | __Error__: Response that is an error. |
7172
| __EXT__ | 0xFFFF | __Extension Header__: Used To Extend More Options As Well As Extensions. |
7273

73-
### Header Chains
74-
75-
ReactiveSocket uses IPv6-style header chains to provide flexibility. The general layout of a ReactiveSocket
76-
frame is a Frame Header followed by 0 or more Headers.
77-
78-
__Note__: Currently, only RESPONSEs use header chains.
79-
80-
```
81-
+----------------------------------------+
82-
| Frame Length (for TCP only) |
83-
+----------------------------------------+
84-
| Frame Header (version, Stream ID, etc.)|
85-
+----------------------------------------+
86-
| Header |
87-
+----------------------------------------+
88-
| Header |
89-
+----------------------------------------+
90-
| ...... |
91-
+----------------------------------------+
92-
| Header |
93-
+----------------------------------------+
94-
```
95-
96-
The general format for a header is given below.
97-
98-
```
99-
0 1 2 3
100-
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
101-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
102-
| Type |I| Header Length |
103-
+---------------+-+---------------------------------------------+
104-
Header Data (Depends on Type)
105-
```
106-
107-
* __Type__: (8) Type of header.
108-
* __Flags__:
109-
* (__I__)gnore: ignore current header if not understood.
110-
* __Header Length__: (23) Length of current header in bytes (23 = max 8,388,608 bytes). Includes
111-
the Type and Header Length fields.
112-
113-
#### Header Types
114-
115-
| Type | Value | Description |
116-
|:-----------------------------------|:-------|:------------|
117-
| __HDR_RESERVED__ | 0x00 | __Reserved__ |
118-
| __HDR_NEXT__ | 0x22 | __Next__: |
119-
| __HDR_COMPLETE__ | 0x23 | __Complete__: |
120-
| __HDR_ERROR__ | 0x24 | __Error__: |
121-
| __HDR_EXT__ | 0xFF | __Extension Header__: Used To Extend More Options As Well As Extensions. |
122-
123-
__Note__: Headers Sent By Requesters Fall Into The 0x10 - 0x1F Range. Headers Sent By Responders Fall Into The 0x20 - 0x2F Range.
74+
__NOTE__: In general Requesters send types 0x0010 to 0x001F and Responders send types 0x0020 to 0x002F.
12475

12576
### Setup Frame
12677

@@ -281,87 +232,48 @@ Frame Contents
281232
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
282233
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
283234
|R| Frame Length (for TCP only) |
284-
+---------------+-+-------------+-------------------------------+
285-
| Version |I| Flags | Frame Type = RESPONSE |
286-
+---------------+-+-------------+-------------------------------+
235+
+---------------+-+-+-+-+-------+-------------------------------+
236+
| Version |I|B|E|C| Resvd | Frame Type = RESPONSE |
237+
+---------------+-+-+-+-+-------+-------------------------------+
287238
| Stream ID |
288239
| |
289240
+---------------------------------------------------------------+
290-
| Header |
291-
+---------------------------------------------------------------+
292-
| Header |
293-
+---------------------------------------------------------------+
294-
| ... |
295-
+---------------------------------------------------------------+
296-
| Header |
297-
+---------------------------------------------------------------+
241+
Response Data
298242
```
299243

300-
RESPONSE frames have a chain of headers that contains payload.
301-
302-
#### Next Header
244+
1. Flag Fragment Information:
245+
1. __Begin Bit__: bit to indicate beginning of a fragmented response.
246+
1. __End Bit__: bit to indicate end of a fragmented response.
247+
1. __Complete Bit__: bit to indicate COMPLETE.
248+
1. __Response Data__: payload for onNext.
303249

304-
Contents
305-
306-
1. 1 Byte Fragment Information:
307-
1. __Begin Bit__: bit to indicate beginning of a fragmented element.
308-
1. __End Bit__: bit to indicate end of a fragmented element.
309-
1. __Header Data__: payload for onNext.
310-
311-
```
312-
0 1 2 3
313-
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
314-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
315-
| Type |I| Header Length |
316-
+-+-+-----------+-+---------------------------------------------+
317-
|B|E| Reserved | Header Data (Depends on Type) ...
318-
+-+-+-----------+
319-
```
250+
A Response is general referred to as a NEXT.
320251

321-
#### Error Header
252+
A Response with the Complete Bit set is referred to as a COMPLETE.
322253

323-
Contents
254+
#### Error Frame
324255

325-
1. __Header Data__: error information.
326-
327-
```
328-
0 1 2 3
329-
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
330-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
331-
| Type |I| Header Length |
332-
+-+-+-----------+-+---------------------------------------------+
333-
Header Data
334-
```
335-
336-
#### Complete Header
337-
338-
Contents
339-
340-
```
341-
0 1 2 3
342-
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
343-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
344-
| Type |I| Header Length |
345-
+-+-+-----------+-+---------------------------------------------+
346-
```
347-
348-
#### Extension Header
256+
Frame Contents
349257

350258
```
351259
0 1 2 3
352260
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
353261
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
354-
| 0xFF |I| Extended Type |
355-
+---------------+-+---------------------------------------------+
356-
| Header Length |
262+
|R| Frame Length (for TCP only) |
263+
+---------------+-+-------------+-------------------------------+
264+
| Version |I| Reserved | Frame Type = ERROR |
265+
+---------------+-+-------------+-------------------------------+
266+
| Stream ID |
267+
| |
357268
+---------------------------------------------------------------+
358-
Depends on Extended Type...
269+
Error Data
359270
```
360271

361-
* __Frame Type__: (8) 0xFF for Extension Header.
362-
* __Flags__:
363-
* (__I__)gnore: Can be ignored.
364-
* __Extended Type__: Extended type information
272+
1. __Error Data__: error information.
273+
274+
An ERROR frame is used for dual purposes:
275+
* As a means for a server to reject a SETUP frame.
276+
* As a means of communicating a stream ERROR from a Responder to a Requester.
365277

366278
### Extension Frame
367279

@@ -439,17 +351,17 @@ In the section below, "*" refers to 0 or more and "+" refers to 1 or more.
439351
### Request Response
440352

441353
1. RQ -> RS: REQUEST_RESPONSE
442-
1. RS -> RQ: RESPONSE with NEXT and COMPLETE
354+
1. RS -> RQ: RESPONSE with COMPLETE
443355

444356
or
445357

446358
1. RQ -> RS: REQUEST_RESPONSE
447-
1. RS -> RQ: RESPONSE with ERROR
359+
1. RS -> RQ: ERROR
448360

449361
or
450362

451363
1. RQ -> RS: REQUEST_RESPONSE
452-
1. RQ -> RS: RESPONSE with CANCEL
364+
1. RQ -> RS: CANCEL
453365

454366
Upon sending a response, the stream is terminated on the Responder.
455367

@@ -472,19 +384,19 @@ REQUEST_FNF are assumed to be best effort and MAY not be processed due to: (1) S
472384
### Request Stream
473385

474386
1. RQ -> RS: REQUEST_STREAM
475-
1. RS -> RQ: RESPONSE with 0 or more NEXTs
476-
1. RS -> RQ: RESPONSE with ERROR
387+
1. RS -> RQ: RESPONSE*
388+
1. RS -> RQ: ERROR
477389

478390
or
479391

480392
1. RQ -> RS: REQUEST_STREAM
481-
1. RS -> RQ: RESPONSE with 1 or more NEXTs
393+
1. RS -> RQ: RESPONSE*
482394
1. RS -> RQ: RESPONSE with COMPLETE
483395

484396
or
485397

486398
1. RQ -> RS: REQUEST_STREAM
487-
1. RS -> RQ: RESPONSE with 0 or more NEXTs
399+
1. RS -> RQ: RESPONSE*
488400
1. RQ -> RS: CANCEL
489401

490402
At any time, a client may send REQUEST_N frames.
@@ -500,18 +412,18 @@ Upon sending a COMPLETE or ERROR, the stream is terminated on the Responder.
500412
### Request Subscription
501413

502414
1. RQ -> RS: REQUEST_SUBSCRIPTION
503-
1. RS -> RQ: RESPONSE with 0 or more NEXTs
415+
1. RS -> RQ: RESPONSE*
504416

505417
or
506418

507419
1. RQ -> RS: REQUEST_SUBSCRIPTION
508-
1. RS -> RQ: RESPONSE with 0 or more NEXTs
509-
1. RS -> RQ: RESPONSE with ERROR
420+
1. RS -> RQ: RESPONSE*
421+
1. RS -> RQ: ERROR
510422

511423
or
512424

513425
1. RQ -> RS: REQUEST_SUBSCRIPTION
514-
1. RS -> RQ: RESPONSE with 0 or more NEXTs
426+
1. RS -> RQ: RESPONSE*
515427
1. RQ -> RS: CANCEL
516428

517429
At any time, a client may send REQUEST_N frames.
@@ -536,7 +448,7 @@ Upon sending a ERROR, the stream is terminated on the Responder.
536448
#### Responder
537449

538450
1. CLOSED: implicit starting/ending state of all stream IDs
539-
1. Responding: sending NEXTs and processing REQUEST_N
451+
1. Responding: sending RESPONSEs and processing REQUEST_N
540452
1. CLOSED (received CANCEL)
541453
1. CLOSED (sent COMPLETE or received REQUEST_FNF)
542454
1. CLOSED (sent ERROR)
@@ -547,6 +459,10 @@ Upon sending a ERROR, the stream is terminated on the Responder.
547459
* Should StreamIDs be timedout after inactivity?
548460
* if so, need keepalive semantics
549461

462+
### ChangeLog
463+
464+
1. Removed usage of header chains to discourage frames from being too large.
465+
550466
### TODO
551467

552468
1. REQUEST_N needs to return point in stream in some way. Or even a new header type REQUEST_N_POSITIONED, or POSITION header, e.g.
@@ -556,9 +472,4 @@ Upon sending a ERROR, the stream is terminated on the Responder.
556472
* Responder instance
557473
1. Exlicit METADATA header needed?
558474
* need metadata semantics
559-
1. Explore
560-
* RESPONSE Frame
561-
* remove header type and bring BE flags byte into header type location. Keep length.
562-
* remove COMPLETE and add C bit to NEXT (COMPLETE is a NEXT header with C bit set and no data)
563-
* remove ERROR and add R bit to NEXT (ERROR is a NEXT header with R bit set and optionally data)
564-
* keep extension header and add 0xF after BECR flags to extend to new types.
475+
1. Handling the unexpected questions

0 commit comments

Comments
 (0)