Skip to content

Add spec for ObjectMessage encoding and decoding #335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VeskeR merged 1 commit into from
Sep 5, 2025
Merged

Add spec for ObjectMessage encoding and decoding #335

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 41 additions & 9 deletions textile/features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1523,6 +1523,8 @@ h4. ObjectMessage
** @(OM3d)@ The size of the @extras@ property is the string length of its JSON representation
** @(OM3f)@ The size of the @clientId@ property is its string length
** @(OM3e)@ The size of a @null@ or omitted property is zero
* @(OM4)@ For @ObjectMessage@ encoding see @ObjectData@ "OD4":#OD4 and @ObjectOperation@ "OOP5":#OOP5 encoding
* @(OM5)@ For @ObjectMessage@ decoding see @ObjectData@ "OD5":#OD5 decoding

h4. ObjectOperation

Expand All @@ -1535,16 +1537,23 @@ h4. ObjectOperation
** @(OOP3d)@ @counterOp@ @ObjectsCounterOp@ object - the payload for the operation if it is an operation on an @ObjectsCounter@ object type
** @(OOP3e)@ @map@ @ObjectsMap@ object - the payload for the operation if the operation is @MAP_CREATE@. Defines the initial value for the @ObjectsMap@ object
** @(OOP3f)@ @counter@ @ObjectsCounter@ object - the payload for the operation if the operation is @COUNTER_CREATE@. Defines the initial value for the @ObjectsCounter@ object
** @(OOP3g)@ @nonce@ string - the nonce, must be present on @COUNTER_CREATE@ and @MAP_CREATE@ operations sent to the server
** @(OOP3h)@ @initialValue@ binary - the initial value bytes for the object
** @(OOP3i)@ @initialValueEncoding@ string - defines how the @initialValue@ should be interpreted. Should be @msgpack@ or @json@
** @(OOP3g)@ @nonce@ string - the nonce. Must be present on @COUNTER_CREATE@ and @MAP_CREATE@ operations sent to the server. Should not be accessed by the client library if received from the server
** @(OOP3h)@ @initialValue@ binary - the initial value bytes for the object. Must be present on @COUNTER_CREATE@ and @MAP_CREATE@ operations sent to the server. Should not be accessed by the client library if received from the server
** @(OOP3i)@ @initialValueEncoding@ string - defines how the @initialValue@ should be interpreted by the server. Must be @msgpack@ or @json@. Must be present on @COUNTER_CREATE@ and @MAP_CREATE@ operations sent to the server. Should not be accessed by the client library if received from the server
* @(OOP4)@ The size of the @ObjectOperation@ is calculated as follows:
** @(OOP4a)@ The size is the sum of the sizes of the @mapOp@, @counterOp@, @map@, and @counter@ properties
** @(OOP4b)@ The size of the @mapOp@ property is calculated per "OMO3":#OMO3
** @(OOP4c)@ The size of the @counterOp@ property is calculated per "OCO3":#OCO3
** @(OOP4d)@ The size of the @map@ property is calculated per "OMP4":#OMP4
** @(OOP4e)@ The size of the @counter@ property is calculated per "OCN3":#OCN3
** @(OOP4f)@ The size of a @null@ or omitted property is zero
* @(OOP5)@ @ObjectOperation@ encoding:
** @(OOP5a)@ When the MessagePack protocol is used:
*** @(OOP5a1)@ A binary @ObjectOperation.initialValue@ is encoded as a MessagePack binary type
*** @(OOP5a2)@ Set @ObjectOperation.initialValueEncoding@ to @msgpack@
** @(OOP5b)@ When the JSON protocol is used:
*** @(OOP5b1)@ A binary @ObjectOperation.initialValue@ is Base64-encoded and represented as a JSON string
*** @(OOP5b2)@ Set @ObjectOperation.initialValueEncoding@ to @json@

h4. ObjectState

Expand Down Expand Up @@ -1623,18 +1632,41 @@ h4. ObjectData
* @(OD1)@ An @ObjectData@ represents a value in an object on a channel
* @(OD2)@ The attributes available in an @ObjectData@ are:
** @(OD2a)@ @objectId@ string - a reference to another object
** @(OD2b)@ @encoding@ string - can be set by the client to indicate that value in @string@ or @bytes@ field have an encoding
** @(OD2c)@ @boolean@ boolean - a primitive boolean leaf value in the object graph. Only one of the value fields - @boolean@, @bytes@, @number@ or @string@ - can be set at a time
** @(OD2d)@ @bytes@ binary - a primitive binary leaf value in the object graph. Only one of the value fields - @boolean@, @bytes@, @number@ or @string@ - can be set at a time
** @(OD2e)@ @number@ number - a primitive number leaf value in the object graph. Only one of the value fields - @boolean@, @bytes@, @number@ or @string@ - can be set at a time
** @(OD2f)@ @string@ string - a primitive string leaf value in the object graph. Only one of the value fields - @boolean@, @bytes@, @number@ or @string@ - can be set at a time
** @(OD2b)@ @encoding@ string - may be set by the client library to indicate that value in @string@ field have an encoding
** @(OD2c)@ @boolean@ boolean - a primitive boolean leaf value in the object graph. Only one of the value fields - @boolean@, @bytes@, @number@ or @string@ - must be set at a time
** @(OD2d)@ @bytes@ binary | string - a primitive binary leaf value in the object graph. It is sent to and received from the server as a Base64-encoded string when using the JSON protocol. Only one of the value fields - @boolean@, @bytes@, @number@ or @string@ - must be set at a time
** @(OD2e)@ @number@ number - a primitive number leaf value in the object graph. Only one of the value fields - @boolean@, @bytes@, @number@ or @string@ - must be set at a time
** @(OD2f)@ @string@ string - a primitive string leaf value in the object graph. Only one of the value fields - @boolean@, @bytes@, @number@ or @string@ - must be set at a time
* @(OD3)@ The size of the @ObjectData@ is calculated as follows:
** @(OD3a)@ The size is the sum of the sizes of the @boolean@, @bytes@, @number@, and @string@ properties
** @(OD3b)@ If set, the size of a @boolean@ property is 1
** @(OD3c)@ If set, the size of a @bytes@ property is its size in bytes (of the actual binary, not the base64 representation, regardless of whether the binary protocol is in use)
** @(OD3d)@ If set, the size of a @number@ property is 8
** @(OD3e)@ If set, the size of a @string@ property is its length
** @(OD3f)@ The size of a @null@ or omitted property is zero
* @(OD4)@ @ObjectData@ encoding:
** @(OD4a)@ Payloads must be booleans, binary, numbers, strings, or JSON-encodable objects or arrays. Any other data type must not be permitted and result in an error with code 40013
** @(OD4b)@ @ObjectData.encoding@ must be left unset unless specified otherwise by the payload encoding procedure in "OD4c":#OD4c and "OD4d":#OD4d
** @(OD4c)@ When the MessagePack protocol is used:
*** @(OD4c1)@ A boolean payload is encoded as a MessagePack boolean type, and the result is set on the @ObjectData.boolean@ attribute
*** @(OD4c2)@ A binary payload is encoded as a MessagePack binary type, and the result is set on the @ObjectData.bytes@ attribute
*** @(OD4c3)@ A number payload is encoded as a MessagePack float64 type, and the result is set on the @ObjectData.number@ attribute
*** @(OD4c4)@ A string payload is encoded as a MessagePack string type, and the result is set on the @ObjectData.string@ attribute
*** @(OD4c5)@ A payload consisting of a JSON-encodable object or array is stringified as a JSON object or array, encoded as a MessagePack string type, and the result is set on the @ObjectData.string@ attribute. The @ObjectData.encoding@ attribute is then set to "json"
** @(OD4d)@ When the JSON protocol is used:
*** @(OD4d1)@ A boolean payload is represented as a JSON boolean and set on the @ObjectData.boolean@ attribute
*** @(OD4d2)@ A binary payload is Base64-encoded and represented as a JSON string; the result is set on the @ObjectData.bytes@ attribute
*** @(OD4d3)@ A number payload is represented as a JSON number and set on the @ObjectData.number@ attribute
*** @(OD4d4)@ A string payload is represented as a JSON string and set on the @ObjectData.string@ attribute
*** @(OD4d5)@ A payload consisting of a JSON-encodable object or array is stringified as a JSON object or array, represented as a JSON string and the result is set on the @ObjectData.string@ attribute. The @ObjectData.encoding@ attribute is then set to "json"
* @(OD5)@ @ObjectData@ decoding:
** @(OD5a)@ When the MessagePack protocol is used:
*** @(OD5a1)@ The payloads in @ObjectData.boolean@, @ObjectData.bytes@, @ObjectData.number@, and @ObjectData.string@ are decoded as their corresponding MessagePack types
*** @(OD5a2)@ If @ObjectData.encoding@ is set to "json", the @ObjectData.string@ content is decoded by parsing the string as JSON
** @(OD5b)@ When the JSON protocol is used:
*** @(OD5b1)@ The payloads in @ObjectData.boolean@, @ObjectData.number@, and @ObjectData.string@ are decoded as their corresponding JSON types
*** @(OD5b2)@ The @ObjectData.bytes@ payload is Base64-decoded into a binary value
*** @(OD5b3)@ If @ObjectData.encoding@ is set to "json", the @ObjectData.string@ content is decoded by parsing the string as JSON

h4. Annotation

Expand Down Expand Up @@ -2631,7 +2663,7 @@ class ObjectData // OD*, internal
objectId: String? // OD2a
encoding: String? // OD2b
boolean: Boolean? // OD2c
bytes: Binary? // OD2d
bytes: Binary? | String? // OD2d
number: Number? // OD2e
string: String? // OD2f

Expand Down
Loading