Show More
@@ -336,7 +336,53 b' MUST normalize all string data to valid ' | |||
|
336 | 336 | validate that received data conforms to UTF-8. The topic name |
|
337 | 337 | SHOULD be ASCII. |
|
338 | 338 | |
|
339 |
S |
|
|
339 | Sender Protocol Settings (``0x08``) | |
|
340 | ----------------------------------- | |
|
341 | ||
|
342 | This frame type advertises the sender's support for various protocol and | |
|
343 | stream level features. The data advertised in this frame is used to influence | |
|
344 | subsequent behavior of the current frame exchange channel. | |
|
345 | ||
|
346 | The frame payload consists of a CBOR map. It may contain the following | |
|
347 | bytestring keys: | |
|
348 | ||
|
349 | contentencodings | |
|
350 | (array of bytestring) A list of content encodings supported by the | |
|
351 | sender, in order of most to least preferred. | |
|
352 | ||
|
353 | Peers are allowed to encode stream data using any of the listed | |
|
354 | encodings. | |
|
355 | ||
|
356 | See the ``Content Encoding Profiles`` section for an enumeration | |
|
357 | of supported content encodings. | |
|
358 | ||
|
359 | If not defined, the value is assumed to be a list with the single value | |
|
360 | ``identity``, meaning only the no-op encoding is supported. | |
|
361 | ||
|
362 | Senders MAY filter the set of advertised encodings against what it | |
|
363 | knows the receiver supports (e.g. if the receiver advertised encodings | |
|
364 | via the capabilities descriptor). However, doing so will prevent | |
|
365 | servers from gaining an understanding of the aggregate capabilities | |
|
366 | of clients. So clients are discouraged from doing so. | |
|
367 | ||
|
368 | When this frame is not sent/received, the receiver assumes default values | |
|
369 | for all keys. | |
|
370 | ||
|
371 | If encountered, this frame type MUST be sent before any other frame type | |
|
372 | in a channel. | |
|
373 | ||
|
374 | The following flag values are defined for this frame type: | |
|
375 | ||
|
376 | 0x01 | |
|
377 | Data continuation. When set, an additional frame containing more protocol | |
|
378 | settings immediately follows. | |
|
379 | 0x02 | |
|
380 | End of data. When set, the protocol settings data has been completely | |
|
381 | sent. | |
|
382 | ||
|
383 | The ``0x01`` flag is mutually exclusive with the ``0x02`` flag. | |
|
384 | ||
|
385 | Stream Encoding Settings (``0x09``) | |
|
340 | 386 | ----------------------------------- |
|
341 | 387 | |
|
342 | 388 | This frame type holds information defining the content encoding |
@@ -351,11 +397,25 b' This frame type MUST ONLY occur on frame' | |||
|
351 | 397 | The payload of this frame defines what content encoding has (possibly) |
|
352 | 398 | been applied to the payloads of subsequent frames in this stream. |
|
353 | 399 | |
|
354 | The payload begins with an 8-bit integer defining the length of the | |
|
355 | encoding *profile*, followed by the string name of that profile, which | |
|
356 | must be an ASCII string. All bytes that follow can be used by that | |
|
357 | profile for supplemental settings definitions. See the section below | |
|
358 | on defined encoding profiles. | |
|
400 | The payload consists of a series of CBOR values. The first value is a | |
|
401 | bytestring denoting the content encoding profile of the data in this | |
|
402 | stream. Subsequent CBOR values supplement this simple value in a | |
|
403 | profile-specific manner. See the ``Content Encoding Profiles`` section | |
|
404 | for more. | |
|
405 | ||
|
406 | In the absence of this frame on a stream, it is assumed the stream is | |
|
407 | using the ``identity`` content encoding. | |
|
408 | ||
|
409 | The following flag values are defined for this frame type: | |
|
410 | ||
|
411 | 0x01 | |
|
412 | Data continuation. When set, an additional frame containing more encoding | |
|
413 | settings immediately follows. | |
|
414 | 0x02 | |
|
415 | End of data. When set, the encoding settings data has been completely | |
|
416 | sent. | |
|
417 | ||
|
418 | The ``0x01`` flag is mutually exclusive with the ``0x02`` flag. | |
|
359 | 419 | |
|
360 | 420 | Stream States and Flags |
|
361 | 421 | ======================= |
@@ -387,6 +447,11 b' 0x04' | |||
|
387 | 447 | defined by the stream should be applied when attempting to read |
|
388 | 448 | the frame. When not set, the frame payload isn't encoded. |
|
389 | 449 | |
|
450 | TODO consider making stream opening and closing communicated via | |
|
451 | explicit frame types (e.g. a "stream state change" frame) rather than | |
|
452 | flags on all frames. This would make stream state changes more explicit, | |
|
453 | as they could only occur on specific frame types. | |
|
454 | ||
|
390 | 455 | Streams |
|
391 | 456 | ======= |
|
392 | 457 | |
@@ -452,9 +517,35 b' Streams can have named content encoding ' | |||
|
452 | 517 | them. A profile defines a shared understanding of content encoding |
|
453 | 518 | settings and behavior. |
|
454 | 519 | |
|
455 | The following profiles are defined: | |
|
520 | Profiles are described in the following sections. | |
|
521 | ||
|
522 | identity | |
|
523 | -------- | |
|
524 | ||
|
525 | The ``identity`` profile is a no-op encoding: the encoded bytes are | |
|
526 | exactly the input bytes. | |
|
527 | ||
|
528 | This profile MUST be supported by all peers. | |
|
529 | ||
|
530 | In the absence of an identified profile, the ``identity`` profile is | |
|
531 | assumed. | |
|
456 | 532 | |
|
457 | TBD | |
|
533 | zstd-8mb | |
|
534 | -------- | |
|
535 | ||
|
536 | Zstandard encoding (RFC 8478). Zstandard is a fast and effective lossless | |
|
537 | compression format. | |
|
538 | ||
|
539 | This profile allows decompressor window sizes of up to 8 MB. | |
|
540 | ||
|
541 | zlib | |
|
542 | ---- | |
|
543 | ||
|
544 | zlib compressed data (RFC 1950). zlib is a widely-used and supported | |
|
545 | lossless compression format. | |
|
546 | ||
|
547 | It isn't as fast as zstandard and it is recommended to use zstandard instead, | |
|
548 | if possible. | |
|
458 | 549 | |
|
459 | 550 | Command Protocol |
|
460 | 551 | ================ |
@@ -49,7 +49,8 b' FRAME_TYPE_COMMAND_RESPONSE = 0x03' | |||
|
49 | 49 | FRAME_TYPE_ERROR_RESPONSE = 0x05 |
|
50 | 50 | FRAME_TYPE_TEXT_OUTPUT = 0x06 |
|
51 | 51 | FRAME_TYPE_PROGRESS = 0x07 |
|
52 |
FRAME_TYPE_S |
|
|
52 | FRAME_TYPE_SENDER_PROTOCOL_SETTINGS = 0x08 | |
|
53 | FRAME_TYPE_STREAM_SETTINGS = 0x09 | |
|
53 | 54 | |
|
54 | 55 | FRAME_TYPES = { |
|
55 | 56 | b'command-request': FRAME_TYPE_COMMAND_REQUEST, |
@@ -58,6 +59,7 b' FRAME_TYPES = {' | |||
|
58 | 59 | b'error-response': FRAME_TYPE_ERROR_RESPONSE, |
|
59 | 60 | b'text-output': FRAME_TYPE_TEXT_OUTPUT, |
|
60 | 61 | b'progress': FRAME_TYPE_PROGRESS, |
|
62 | b'sender-protocol-settings': FRAME_TYPE_SENDER_PROTOCOL_SETTINGS, | |
|
61 | 63 | b'stream-settings': FRAME_TYPE_STREAM_SETTINGS, |
|
62 | 64 | } |
|
63 | 65 | |
@@ -89,6 +91,22 b' FLAGS_COMMAND_RESPONSE = {' | |||
|
89 | 91 | b'eos': FLAG_COMMAND_RESPONSE_EOS, |
|
90 | 92 | } |
|
91 | 93 | |
|
94 | FLAG_SENDER_PROTOCOL_SETTINGS_CONTINUATION = 0x01 | |
|
95 | FLAG_SENDER_PROTOCOL_SETTINGS_EOS = 0x02 | |
|
96 | ||
|
97 | FLAGS_SENDER_PROTOCOL_SETTINGS = { | |
|
98 | b'continuation': FLAG_SENDER_PROTOCOL_SETTINGS_CONTINUATION, | |
|
99 | b'eos': FLAG_SENDER_PROTOCOL_SETTINGS_EOS, | |
|
100 | } | |
|
101 | ||
|
102 | FLAG_STREAM_ENCODING_SETTINGS_CONTINUATION = 0x01 | |
|
103 | FLAG_STREAM_ENCODING_SETTINGS_EOS = 0x02 | |
|
104 | ||
|
105 | FLAGS_STREAM_ENCODING_SETTINGS = { | |
|
106 | b'continuation': FLAG_STREAM_ENCODING_SETTINGS_CONTINUATION, | |
|
107 | b'eos': FLAG_STREAM_ENCODING_SETTINGS_EOS, | |
|
108 | } | |
|
109 | ||
|
92 | 110 | # Maps frame types to their available flags. |
|
93 | 111 | FRAME_TYPE_FLAGS = { |
|
94 | 112 | FRAME_TYPE_COMMAND_REQUEST: FLAGS_COMMAND_REQUEST, |
@@ -97,7 +115,8 b' FRAME_TYPE_FLAGS = {' | |||
|
97 | 115 | FRAME_TYPE_ERROR_RESPONSE: {}, |
|
98 | 116 | FRAME_TYPE_TEXT_OUTPUT: {}, |
|
99 | 117 | FRAME_TYPE_PROGRESS: {}, |
|
100 | FRAME_TYPE_STREAM_SETTINGS: {}, | |
|
118 | FRAME_TYPE_SENDER_PROTOCOL_SETTINGS: FLAGS_SENDER_PROTOCOL_SETTINGS, | |
|
119 | FRAME_TYPE_STREAM_SETTINGS: FLAGS_STREAM_ENCODING_SETTINGS, | |
|
101 | 120 | } |
|
102 | 121 | |
|
103 | 122 | ARGUMENT_RECORD_HEADER = struct.Struct(r'<HH') |
General Comments 0
You need to be logged in to leave comments.
Login now