Skip to content

Spec for edit/delete #380

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+83 −0
Open

Spec for edit/delete #380

Show file tree
Hide file tree
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
42 changes: 42 additions & 0 deletions textile/api-docstrings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,22 @@ Enables messages to be published and historic messages to be retrieved for a cha
|| `data` ||| The payload of the message. |
| setOptions(options: ChannelOptions) => io ||| RSL7 | Sets the [`ChannelOptions`]{@link ChannelOptions} for the channel. |
|| `options` ||| A [`ChannelOptions`]{@link ChannelOptions} object. |
| getMessage(serialOrMsg: String \| Message) => io Message ||| RSL11 | Retrieves the latest version of a specific message by its serial identifier or by providing a [`Message`]{@link Message} object containing the serial (which will not be mutated). |
|| `serialOrMsg` ||| Either the serial identifier string of the message to retrieve, or a [`Message`]{@link Message} object containing a populated `serial` field. |
||| `Message` || A [`Message`]{@link Message}, the latest version of the message |
| updateMessage(Message, operation?: MessageOperation, params?: `Dict<String, Stringifiable>`) => io Message ||| RSL12 | Publishes an update to existing message with patch semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Note that this publishes an update, it does not mutate the original message if passed in. |
|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field and the fields to update. |
|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the update operation. |
|| `params` ||| Optional parameters sent as part of the query string. |
||| `Message` || A [`Message`]{@link Message} object containing the updated message. |
| deleteMessage(Message, operation?: MessageOperation, params?: `Dict<String, Stringifiable>`) => io ||| RSL13 | Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged (meaning that if you for example want the `MESSAGE_DELETE` to have an empty data, you should explicitly set the `data` to an empty object). |
|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field. |
|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the delete operation. |
|| `params` ||| Optional parameters sent as part of the query string. |
| getMessageVersions(serialOrMsg: String \| Message, params?: `Dict<String, Stringifiable>`) => io `PaginatedResult<Message>` ||| RSL14 | Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. |
|| `serialOrMsg` ||| Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`]{@link Message} object containing a populated `serial` field. |
|| `params` ||| Optional parameters sent as part of the query string. |
||| `PaginatedResult<Message>` || A [`PaginatedResult`]{@link PaginatedResult} object containing an array of [`Message`]{@link Message} objects representing all versions of the message. |
| push: PushChannel ||| RSH4 | A [`PushChannel`]{@link PushChannel} object. |

## class RealtimeChannel
Expand Down Expand Up @@ -351,6 +367,22 @@ Enables messages to be published and subscribed to. Also enables historic messag
|| `(Message)` ||| An event listener function. |
| setOptions(options: ChannelOptions) => io ||| RTL16 | Sets the [`ChannelOptions`]{@link ChannelOptions} for the channel. An optional callback may be provided to notify of the success or failure of the operation. |
|| `options` ||| A [`ChannelOptions`]{@link ChannelOptions} object. |
| getMessage(serialOrMsg: String \| Message) => io Message ||| RTL28 | Retrieves the latest version of a specific message by its serial identifier or by providing a [`Message`]{@link Message} object containing the serial. |
|| `serialOrMsg` ||| Either the serial identifier string of the message to retrieve, or a [`Message`]{@link Message} object containing a populated `serial` field. |
||| `Message` || A [`Message`]{@link Message}, the latest version of the message |
| updateMessage(Message, operation?: MessageOperation, params?: `Dict<String, Stringifiable>`) => io Message ||| RTL29 | Updates an existing message with patch semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Note that this publishes an update, it does not mutate the original message if passed in. |
|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field and the fields to update. |
|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the update operation. |
|| `params` ||| Optional parameters sent as part of the query string. |
||| `Message` || A [`Message`]{@link Message} object containing the updated message. |
| deleteMessage(Message, operation?: MessageOperation, params?: `Dict<String, Stringifiable>`) => io ||| RTL30 | Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged (meaning that if you for example want the `MESSAGE_DELETE` to have an empty data, you should explicitly set the `data` to an empty object). |
|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field. |
|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the delete operation. |
|| `params` ||| Optional parameters sent as part of the query string. |
| getMessageVersions(serialOrMsg: String \| Message, params?: `Dict<String, Stringifiable>`) => io `PaginatedResult<Message>` ||| RTL31 | Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. |
|| `serialOrMsg` ||| Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`]{@link Message} object containing a populated `serial` field. |
|| `params` ||| Optional parameters sent as part of the query string. |
||| `PaginatedResult<Message>` || A [`PaginatedResult`]{@link PaginatedResult} object containing an array of [`Message`]{@link Message} objects representing all versions of the message. |

## class MessageFilterObject

Expand All @@ -364,6 +396,16 @@ Contains properties to filter messages with when calling [`subscribe()`]{@link R
| name: string ||| RTL22a | Filters messages by a specific message `name`. |
| clientId: string ||| RTL22a | Filters messages by a specific message `clientId`. |

## class MessageOperation

Contains metadata about a message update or delete operation.

| Method / Property | Parameter | Returns | Spec | Description |
|---|---|---|---|---|
| clientId?: String ||| MOP2a | Optional identifier of the client performing the operation. |
| description?: String ||| MOP2b | Optional human-readable description of the operation. |
| metadata?: `Dict<String, String>` ||| MOP2c | Optional dictionary of key-value pairs containing additional metadata about the operation. |

## class ChannelProperties

Describes the properties of the channel state.
Expand Down
41 changes: 41 additions & 0 deletions textile/features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -381,6 +381,38 @@ h3(#rest-channel). RestChannel
* @(RSL8)@ @RestChannel#status@ function: makes a http get request to @<restHost>/channels/<channelId>@ where @<restHost>@ represents the current rest host as described by "@RSC11@":#RSC11
** @(RSL8a)@ Returns a @ChannelDetails@ object
* @(RSL10)@ @RestChannel#annotations@ attribute contains the @RestAnnotations@ object for this channel
* @(RSL11)@ @RestChannel#getMessage@ function:
** @(RSL11a)@ Takes a first argument of a @serial@ string of the message to be retrieved.
*** @(RSL11a1)@ In languages where method overloading is supported, the first argument should also accept a @Message@ object (which must contain a populated @serial@ field)
** @(RSL11b)@ The SDK must send a GET request to the endpoint @/channels/{channelName}/messages/{serial}@
** @(RSL11c)@ Returns the decoded @Message@ object for the specified message serial
* @(RSL12)@ @RestChannel#updateMessage@ function:
** @(RSL12a)@ Takes a first argument of a @Message@ object (which must contain a populated @serial@ field), an optional second argument of a @MessageOperation@ object, and an optional third argument of @Dict<string, stringifiable>@ publish params
** @(RSL12b)@ The SDK must send a PATCH to @/channels/{channelName}/messages/{serial}@, with any @params@ sent in the querystring. The request body consists of an object with the following fields:
*** @(RSL12b1)@ @serial@ - the serial identifier of the message being updated
*** @(RSL12b2)@ @operation@ - the @MessageOperation@ object if provided
*** @(RSL12b3)@ @name@ - the message name from the @Message@ object if provided
*** @(RSL12b4)@ @data@ - the message data from the @Message@ object if provided, encoded per @RSL4@
*** @(RSL12b5)@ @encoding@ - the encoding field set according to @RSL4@ if @data@ was encoded
*** @(RSL12b6)@ @extras@ - the extras field from the @Message@ object if provided
** @(RSL12c)@ The body must be encoded to the appropriate format per @RSC8@
** @(RSL12d)@ Returns the updated @Message@ object, which the server will have responded with
* @(RSL13)@ @RestChannel#deleteMessage@ function:
** @(RSL13a)@ Takes a first argument of a @Message@ object (which must contain a populated @serial@ field), an optional second argument of a @MessageOperation@ object, and an optional third argument of @Dict<string, stringifiable>@ publish params
** @(RSL13b)@ The SDK must send a POST to @/channels/{channelName}/messages/{serial}/delete@, with any @params@ sent in the querystring. The request body consists of an object with the following fields:
*** @(RSL13b1)@ @serial@ - the serial identifier of the message being deleted
*** @(RSL13b2)@ @operation@ - the @MessageOperation@ object if provided
*** @(RSL13b3)@ @name@ - the message name from the @Message@ object if provided
*** @(RSL13b4)@ @data@ - the message data from the @Message@ object if provided, encoded per @RSL4@
*** @(RSL13b5)@ @encoding@ - the encoding field set according to @RSL4@ if @data@ was encoded
*** @(RSL13b6)@ @extras@ - the extras field from the @Message@ object if provided
** @(RSL13c)@ The body must be encoded to the appropriate format per @RSC8@
** @(RSL13d)@ Returns the updated (well, 'deleted') @Message@ object, which the server will have responded with
* @(RSL14)@ @RestChannel#getMessageVersions@ function:
** @(RSL14a)@ Takes a first argument a @serial@ string of the message whose versions are to be retrieved, and an optional second argument of @Dict<string, stringifiable>@ params
*** @(RSL14a1)@ In languages where method overloading is supported, the first argument should also accept a @Message@ object (which must contain a populated @serial@ field)
** @(RSL14b)@ The SDK must send a GET request to the endpoint @/channels/{channelName}/messages/{serial}/versions@
** @(RSL14c)@ Returns a @PaginatedResult<Message>@

h3(#plugins). Plugins
* @(PC1)@ Specific client library features that are not commonly used may be supplied as independent libraries, as plugins, in order to avoid excessively bloating the client library. Although such plugins are packaged as independent libraries, they are still considered logically to be part of the client library code and, as such, may be tightly coupled with the client library implementation. The client library can be assumed to be aware of the plugin specific type and capabilities, and such plugins may by design be coupled to a specific version of the client library.
Expand Down Expand Up @@ -820,6 +852,10 @@ h3(#realtime-channel). RealtimeChannel
** @(RTL25a)@ If the channel is already in the given state, calls the listener with a `null` argument.
** @(RTL25b)@ Else, calls @#once@ with the given state and listener.
* @(RTL26)@ @RealtimeChannel#annotations@ attribute contains the @RealtimeAnnotations@ object for this channel
* @(RTL28)@ @RealtimeChannel#getMessage@ function: same as @RestChannel#getMessage@
* @(RTL29)@ @RealtimeChannel#updateMessage@ function: same as @RestChannel#updateMessage@
* @(RTL30)@ @RealtimeChannel#deleteMessage@ function: same as @RestChannel#deleteMessage@
* @(RTL31)@ @RealtimeChannel#getMessageVersions@ function: same as @RestChannel#getMessageVersions@

h3(#realtime-presence). RealtimePresence

Expand Down Expand Up @@ -2449,6 +2485,11 @@ class ChannelOptions: // TB*
params?: Dict<String, String> // TB2c
modes?: [ChannelMode] // TB2d

class MessageOperation: // MOP*
clientId?: String // MOP2a
description?: String // MOP2b
metadata?: Dict<String, String> // MOP2c

class DeriveOptions: // DO*
filter: String // DO2a (The filter string is a valid JMESPath String Expression)

Expand Down
Loading