ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2024-12-19 04:57:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

adjust markup to clarify the encoding exceptions

Browse Source
This commit is contained in:
Jean-Paul Calderone 2023-03-13 10:42:30 -04:00
parent 7859ba7337
commit 5facd06725
1 changed files with 10 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/proposed/http-storage-node-protocol.rst
View File

@ -347,6 +347,8 @@ A request MAY be submitted using an alternate encoding by declaring this in the
A request MAY indicate its preference for an alternate encoding in the response using the ``Accept`` header field. A request MAY indicate its preference for an alternate encoding in the response using the ``Accept`` header field.
A request which includes no ``Accept`` header field MUST be interpreted in the same way as a request including a ``Accept: application/cbor`` header field. A request which includes no ``Accept`` header field MUST be interpreted in the same way as a request including a ``Accept: application/cbor`` header field.
Clients and servers MAY support additional request and response message body encodings.
Clients and servers SHOULD support ``application/json`` request and response message body encoding. Clients and servers SHOULD support ``application/json`` request and response message body encoding.
For HTTP messages carrying binary share data, For HTTP messages carrying binary share data,
this is expected to be a particularly poor encoding. this is expected to be a particularly poor encoding.
@ -360,7 +362,11 @@ Because of the simple types used throughout
and the equivalence described in `RFC 7049`_ and the equivalence described in `RFC 7049`_
these examples should be representative regardless of which of these two encodings is chosen. these examples should be representative regardless of which of these two encodings is chosen.
One exception to this rule is for sets. There are two exceptions to this rule.
1. Sets
!!!!!!!
For CBOR messages, For CBOR messages,
any sequence that is semantically a set (i.e. no repeated values allowed, order doesn't matter, and elements are hashable in Python) should be sent as a set. any sequence that is semantically a set (i.e. no repeated values allowed, order doesn't matter, and elements are hashable in Python) should be sent as a set.
Tag 6.258 is used to indicate sets in CBOR; Tag 6.258 is used to indicate sets in CBOR;
@ -368,12 +374,12 @@ see `the CBOR registry <https://www.iana.org/assignments/cbor-tags/cbor-tags.xht
The JSON encoding does not support sets. The JSON encoding does not support sets.
Sets MUST be represented as arrays in JSON-encoded messages. Sets MUST be represented as arrays in JSON-encoded messages.
Another exception to this rule is for bytes. 2. Bytes
!!!!!!!!
The CBOR encoding natively supports a bytes type while the JSON encoding does not. The CBOR encoding natively supports a bytes type while the JSON encoding does not.
Bytes MUST be represented as strings giving the `Base64`_ representation of the original bytes value. Bytes MUST be represented as strings giving the `Base64`_ representation of the original bytes value.
Clients and servers MAY support additional request and response message body encodings.
HTTP Design HTTP Design
~~~~~~~~~~~ ~~~~~~~~~~~