334 facilitate receivers localizing that string data. The emitter |
334 facilitate receivers localizing that string data. The emitter |
335 MUST normalize all string data to valid UTF-8 and receivers SHOULD |
335 MUST normalize all string data to valid UTF-8 and receivers SHOULD |
336 validate that received data conforms to UTF-8. The topic name |
336 validate that received data conforms to UTF-8. The topic name |
337 SHOULD be ASCII. |
337 SHOULD be ASCII. |
338 |
338 |
339 Stream Encoding Settings (``0x08``) |
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 This frame type holds information defining the content encoding |
388 This frame type holds information defining the content encoding |
343 settings for a *stream*. |
389 settings for a *stream*. |
344 |
390 |
349 ``Stream Flag`` set. |
395 ``Stream Flag`` set. |
350 |
396 |
351 The payload of this frame defines what content encoding has (possibly) |
397 The payload of this frame defines what content encoding has (possibly) |
352 been applied to the payloads of subsequent frames in this stream. |
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 |
400 The payload consists of a series of CBOR values. The first value is a |
355 encoding *profile*, followed by the string name of that profile, which |
401 bytestring denoting the content encoding profile of the data in this |
356 must be an ASCII string. All bytes that follow can be used by that |
402 stream. Subsequent CBOR values supplement this simple value in a |
357 profile for supplemental settings definitions. See the section below |
403 profile-specific manner. See the ``Content Encoding Profiles`` section |
358 on defined encoding profiles. |
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 Stream States and Flags |
420 Stream States and Flags |
361 ======================= |
421 ======================= |
362 |
422 |
363 Streams can be in two states: *open* and *closed*. An *open* stream |
423 Streams can be in two states: *open* and *closed*. An *open* stream |
384 |
444 |
385 0x04 |
445 0x04 |
386 Apply content encoding. When set, any content encoding settings |
446 Apply content encoding. When set, any content encoding settings |
387 defined by the stream should be applied when attempting to read |
447 defined by the stream should be applied when attempting to read |
388 the frame. When not set, the frame payload isn't encoded. |
448 the frame. When not set, the frame payload isn't encoded. |
|
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. |
389 |
454 |
390 Streams |
455 Streams |
391 ======= |
456 ======= |
392 |
457 |
393 Streams - along with ``Request IDs`` - facilitate grouping of frames. |
458 Streams - along with ``Request IDs`` - facilitate grouping of frames. |
450 |
515 |
451 Streams can have named content encoding *profiles* associated with |
516 Streams can have named content encoding *profiles* associated with |
452 them. A profile defines a shared understanding of content encoding |
517 them. A profile defines a shared understanding of content encoding |
453 settings and behavior. |
518 settings and behavior. |
454 |
519 |
455 The following profiles are defined: |
520 Profiles are described in the following sections. |
456 |
521 |
457 TBD |
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. |
|
532 |
|
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 Command Protocol |
550 Command Protocol |
460 ================ |
551 ================ |
461 |
552 |
462 A client can request that a remote run a command by sending it |
553 A client can request that a remote run a command by sending it |