diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index ceffe21b34..bb07beea8c 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -17,6 +17,7 @@ jump_to: - Presence#rest-presence - Encryption#rest-encryption - Forwards compatibility#rest-compatibility + - Batch Operations#batch-operations Realtime client library: - RealtimeClient - Connection#realtime-connection @@ -339,6 +340,14 @@ h3(#rest-encryption). Encryption h3(#rest-compatibility). Forwards compatibility * @(RSF1)@ The library must apply the "robustness principle":https://en.wikipedia.org/wiki/Robustness_principle in its processing of requests and responses with the Ably system. In particular, deserialization of Messages and related types, and associated enums, must be tolerant to unrecognised attributes or enum values. Such unrecognised values must be ignored. +h3(#batch-operations). Batch Operations +* @(BO1)@ The batch operations functions must use the REST endpoints in Batch Mode, sending a single request containing all specified data +* @(BO2)@ Batch operations must be able to be performed for the following: +** @(BO2a)@ @BatchOperations::publish@ publishes messages against one or more channels with one or more messages +*** @(B02a1)@ Functions should be provided to pass either an array or a single @BatchSpec@ object. In languages where function overloading is not possible, an array is preferred. +** @(BO2b)@ @BatchOperations::getPresence@ retrieves the presence data for one or more channels +* @(BO3)@ When a batch operation only contains one batch, the underlying request is functionally identical to its non-batch equivalent, but the returned result should be a @BatchResponse@ object. + h2(#realtime). Realtime client library features The Ably Realtime client libraries establish and maintain a persistent connection to Ably and provide methods to publish and subscribe to messages over a low latency realtime connection. @@ -1348,7 +1357,7 @@ h4. ChannelDetails h4. ChannelStatus -* @(CHS1)@ @ChannelStatus@ is a type that contains status and occupancy for a channel +* @(CHS1)@ @ChannelStatus@ is a type that contains status and occupancy for a channel * @(CHS2)@ The attributes of @ChannelStatus@ consist of: ** @(CHS2a)@ @isActive@ boolean - represents if the channel is active ** @(CHS2b)@ @occupancy@ @ChannelOccupancy@ - occupancy is an object containing the metrics for the channel @@ -1361,15 +1370,43 @@ h4. ChannelOccupancy h4. ChannelMetrics -* @(CHM1)@ @ChannelMetrics@ is a type that contains the count of publishers and subscribers, connections and presenceConnections, presenceMembers and presenceSubscribers +* @(CHM1)@ @ChannelMetrics@ is a type that contains the count of publishers and subscribers, connections and presenceConnections, presenceMembers and presenceSubscribers * @(CHM2)@ The attributes of @ChannelMetrics@ consist of: ** @(CHM2a)@ @connections@ integer - the total number of connections to the channel ** @(CHM2b)@ @presenceConnections@ integer - the total number of presence connections to the channel ** @(CHM2c)@ @presenceMembers@ integer - the total number of presence members for the channel ** @(CHM2d)@ @presenceSubscribers@ integer - the total number of presence subscribers for the channel -** @(CHM2e)@ @publishers@ integer - the total number of publishers to the channel +** @(CHM2e)@ @publishers@ integer - the total number of publishers to the channel ** @(CHM2f)@ @subscribers@ integer - the total number of subscribers to the channel +h4. BatchResult +* @(BPA1)@ Contains the results from the batch operation +* @(BPA2)@ @BatchResult@ has the following attributes: +** @(BPA2a)@ @responses@ is an array of batch response objects. +** @(BPA2b)@ @error@ is an @ErrorInfo@ object which is populated if one or more batch publish requests failed. +*** @(BPA2b1)@ This error should only be set if it relates to a partial success. All fatal errors should be handled via language appropriate error handling. + +h4. BatchPublishResponse +* @(BPB1)@ Contains information for each batch publish request within a @BatchResult@ +* @(BPB2)@ @BatchPublishResponse@ has the following attributes: +** (@BPB2a)@ @channel@ is the channel name which this publish request was directed to +** (@BPB2b)@ @messageId@ contains the resultant message ID, if the request succeeds and is null if @error@ is present +** (@BPB2c)@ @error@ contains an @ErrorInfo@ object if this publish request failed, and is null if it succeeded + +h4. BatchPresenceResponse +* @(BPD1)@ Contains information for each batch presence request within a @BatchResult@ +* @(BPD2)@ @BatchPresenceResponse@ contains the following attributes: +** @(BPD2a)@ @channel@ is the channel name which this presence request +** @(BPD2b)@ @presence@ is an array of presence data for the @channel@ + +h4. BatchPresence +* @(BPE1)@ Is a partial @PresenceMessage@ object containing @clientId@ and @action@, or @error@ if the presence failed +* @(PBE2)@ @BatchPresence@ contains the following attributes: +** @(PBE2a)@ @clientId@ - identical to #TP3c +** @(PBE2b)@ @action@ - identical to #TP3b - null if @error@ is present +** @(PBE2c)@ @error@ - an @ErrorInfo@ object representing the failure reason for this channel - null if @action@ is present + + h3(#options). Option types h4. ClientOptions @@ -1525,6 +1562,7 @@ class Rest: constructor(ClientOptions) // RSC1 auth: Auth // RSC5 push: Push + batch: BatchOperations // BO1 device() => io LocalDevice channels: Channels // RSN1 request( @@ -1697,6 +1735,29 @@ class RealtimeChannel: unsubscribe(String, (Message) ->) // RTL8a setOptions(options: ChannelOptions) => io // RTL16 +class BatchOperations: + publish([BatchSpec]) => BatchResult // BO2a + publish(BatchSpec) => BatchResult // BO2a + getPresence([String]) => BatchResult // BO2b + +class BatchResult: + error: ErrorInfo? // BPA2b + responses: []T? // BPA2a + +class BatchPublishResponse: + channel: String // BPB2a + messageId: String? // BPB2b + error: ErrorInfo? // BPB2c + +class BatchPresenceResponse: + channel: String // BPD2a + presence: []BatchPresence // PBD2b + +class BatchPresence: + clientId: string + action: string? + error: ErrorInfo? + class PushChannel: subscribeDevice() => io // RSH7a subscribeClient() => io // RSH7b @@ -1704,6 +1765,10 @@ class PushChannel: unsubscribeClient() => io // RSH7d listSubscriptions() => io PaginatedResult // RSH7e +class BatchSpec: + channels: [String] + messages: [Message] + enum ChannelState: INITIALIZED ATTACHING