diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 7d987c3..82b429f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -128,6 +128,27 @@ types: type: RequestId description: "The request id this chunk belongs to. This is generated by the send function and its type is defined in messaging-api." + SyncStatusDetail: + type: object + description: "Provides a snapshot of the channel's synchronisation state." + fields: + received: + type: uint + description: "Number of messages successfully received." + missing: + type: uint + description: "Number of messages detected as missing but not yet retrieved." + lost: + type: uint + description: "Number of messages that could not be retrieved after all attempts." + + SyncStatus: + type: enum + description: "Indicates whether the channel has detected any outstanding missing messages." + values: + - synced: "No known missing messages (some may be permanently lost)." + - syncing: "Actively attempting to retrieve one or more missing messages." + IEncryption: type: object description: "Interface for a pluggable encryption mechanism. @@ -172,7 +193,9 @@ types: type: string default: "" description: "Reliable channel identifier. - If empty, the message is considered ephemeral and is not sent reliably. + If empty, the message is considered ephemeral: it is not tracked by SDS, never retransmitted, and NEVER segmented. + Ephemeral payloads exceeding the network size limit MUST be rejected with an error. + When the rate limit is approached, ephemeral messages are dropped immediately rather than queued. If != empty, the messageEnvelope will be segmented, SDS'ed and encrypted under the given reliable channel." ReliableChannel: @@ -185,6 +208,9 @@ types: messageEvents: type: ReliableMessageEvents description: "Event emitter for message-related events on this channel" + syncStatus: + type: SyncStatus + description: "Current synchronisation status of the channel. Transitions between 'syncing' and 'synced' as missing messages are detected and resolved." ReliableChannelConfig: type: object @@ -358,6 +384,33 @@ types: type: string description: "Error message describing what went wrong" + ReliableMessageAcknowledgedEvent: + type: object + description: "Event emitted when the message has been definitively acknowledged via causal history." + fields: + requestId: + type: RequestId + description: "The request ID associated with the acknowledged message" + + ReliableIrretrievableMessageEvent: + type: object + description: "Event emitted when a missing message could not be retrieved after all store-query attempts." + fields: + requestId: + type: RequestId + description: "The request ID of the unrecoverable message" + + ReliableSyncStatusEvent: + type: object + description: "Event emitted when the channel's sync status transitions between 'synced' and 'syncing'." + fields: + status: + type: SyncStatus + description: "The new sync status" + detail: + type: SyncStatusDetail + description: "Counters describing the current sync state" + ReliableMessageEvents: type: event_emitter description: "Event source for reliable message events on a channel" @@ -366,8 +419,17 @@ types: type: ReliableMessageReceivedEvent "reliable:message:sent": type: ReliableMessageSentEvent + "reliable:message:acknowledged": + type: ReliableMessageAcknowledgedEvent + description: "Message definitively acknowledged via causal history." "reliable:message:send-error": type: ReliableMessageSendErrorEvent + "reliable:message:irretrievable": + type: ReliableIrretrievableMessageEvent + description: "Missing message could not be retrieved after all store-query attempts." + "reliable:sync:status": + type: ReliableSyncStatusEvent + description: "Channel sync status changed between 'synced' and 'syncing'." ``` #### Messaging function definitions