logos-messaging/specs
1
0
Fork 0
mirror of https://github.com/logos-messaging/specs.git synced 2026-01-07 16:43:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

add links

Browse Source
This commit is contained in:
Sasha 2025-03-17 00:36:41 +01:00
parent fe20d795b6
commit 9180cf1fb7
No known key found for this signature in database
1 changed files with 30 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
standards/application/messaging-api.md
View File

@ -108,9 +108,9 @@ If not provided, nodes discovered through the network SHOULD be used.
A list of `Multiaddr` addresses to remote peers that SHOULD be used for obtaining various network resources. A list of `Multiaddr` addresses to remote peers that SHOULD be used for obtaining various network resources.
These resources MAY include: These resources MAY include:
- infrequent [STORE]() queries; - infrequent [STORE](../standards/core/store.md) queries;
- a [LIGHTPUSH]() endpoint for broadcasting data; - a [LIGHTPUSH](../standards/core/lightpush.md) endpoint for broadcasting data;
- a [FILTER]() endpoint for receiving circulating data. - a [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md) endpoint for receiving circulating data.
If not provided, nodes discovered through the network SHOULD be used. If not provided, nodes discovered through the network SHOULD be used.
@ -124,13 +124,13 @@ A list of `Multiaddr` addresses to remote peers that SHOULD be used for any appl
##### `confirmStored` ##### `confirmStored`
An optional property that defaults to `false`. An optional property that defaults to `false`.
If set to `true` and `confirmContentTopics` are provided, a recurring background [STORE]() query (as described in the `Message Storage API` section) MUST be initiated. If set to `true` and `confirmContentTopics` are provided, a recurring background [STORE](../standards/core/store.md) query (as described in the `Message Storage API` section) MUST be initiated.
If set to `true` without `confirmContentTopics`, the background [STORE]() query (as described in the `Messaging Storage API` section) MUST only be initiated after the `Subscribe API` is called. If set to `true` without `confirmContentTopics`, the background [STORE](../standards/core/store.md) query (as described in the `Messaging Storage API` section) MUST only be initiated after the `Subscribe API` is called.
If set to `false`, the `stored` property on the `MessageRecord` (defined in the `Message Storage API`) MUST NOT be populated, unless `History API` is triggered. If set to `false`, the `stored` property on the `MessageRecord` (defined in the `Message Storage API`) MUST NOT be populated, unless `History API` is triggered.
##### `confirmReceived` ##### `confirmReceived`
An optional property that defaults to `true`. An optional property that defaults to `true`.
If set to `true`, the node MUST initiate a network listener for messages circulated under `confirmContentTopics` via either [FILTER]() or [RELAY]() using the `Subscribe API`. If set to `true`, the node MUST initiate a network listener for messages circulated under `confirmContentTopics` via either [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) using the `Subscribe API`.
If set to `true` but `confirmContentTopics` are not provided, the received property on the `MessageRecord` (as defined in the `Message Storage API`) MUST be populated only after the `Subscribe API` is called. If set to `true` but `confirmContentTopics` are not provided, the received property on the `MessageRecord` (as defined in the `Message Storage API`) MUST be populated only after the `Subscribe API` is called.
If set to `false`, the received property MUST NOT be populated, unless `Subscribe API` is called. If set to `false`, the received property MUST NOT be populated, unless `Subscribe API` is called.
@ -148,15 +148,15 @@ Instead, the initial configuration MUST be supplied at node creation time accord
The `Send API` is responsible for broadcasting messages across the network using the configured protocol. The `Send API` is responsible for broadcasting messages across the network using the configured protocol.
The node SHOULD select the appropriate protocol based on its configuration and the protocols that are mounted: The node SHOULD select the appropriate protocol based on its configuration and the protocols that are mounted:
- If the initial configuration specifies mode: "edge", then [LIGHTPUSH]() MUST be used to send messages. - If the initial configuration specifies mode: "edge", then [LIGHTPUSH](../standards/core/lightpush.md) MUST be used to send messages.
- If the initial configuration specifies mode: "service", then [RELAY]() MUST be used to send messages. - If the initial configuration specifies mode: "service", then [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) MUST be used to send messages.
The `Send API` is also responsible for ensuring message delivery and MUST attempt retries as described in the `Retry` section. The `Send API` is also responsible for ensuring message delivery and MUST attempt retries as described in the `Retry` section.
#### Retry #### Retry
If a message fails to satisfy any of the following conditions, it MUST be automatically resent: If a message fails to satisfy any of the following conditions, it MUST be automatically resent:
- The message is not successfully sent using [LIGHTPUSH]() or [RELAY](). - The message is not successfully sent using [LIGHTPUSH](../standards/core/lightpush.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md).
- The message is not acknowledged by `Message Storage API` described below. - The message is not acknowledged by `Message Storage API` described below.
- Retry attempts MUST NOT continue if the node’s health state changes to unhealthy (as defined in the `Health API` described below). - Retry attempts MUST NOT continue if the node’s health state changes to unhealthy (as defined in the `Health API` described below).
- Retry attempts MUST resume when the node’s health state transitions to either `minimally healthy` or `healthy` defined in the `Health API` below. - Retry attempts MUST resume when the node’s health state transitions to either `minimally healthy` or `healthy` defined in the `Health API` below.
@ -199,7 +199,7 @@ Additionally, it MUST provide information regarding the `pubsubTopic` and `conte
The specific types of encoders, their extended functionalities, and the mechanisms for their instantiation are considered out of scope for this document. The specific types of encoders, their extended functionalities, and the mechanisms for their instantiation are considered out of scope for this document.
##### `Message` ##### `Message`
A `Message` object MUST conform to the [MESSAGE]() specification. A `Message` object MUST conform to the [MESSAGE](https://github.com/vacp2p/rfc-index/blob/8ee2a6d6b232838d83374c35e2413f84436ecf64/waku/standards/core/14/message.md) specification.
- The payload property MUST be provided. - The payload property MUST be provided.
- All other properties are optional; if omitted, they SHOULD be supplied by the `Encoder`. - All other properties are optional; if omitted, they SHOULD be supplied by the `Encoder`.
@ -209,7 +209,7 @@ This `GUID` MAY be used to cancel a scheduled request or to retrieve information
##### `send` ##### `send`
An `Encoder` and a `Message` MUST be provided as parameters. An `Encoder` and a `Message` MUST be provided as parameters.
When invoked, the method schedules the message to be sent via [LIGHTPUSH]() or [RELAY]() based on the node’s configuration. When invoked, the method schedules the message to be sent via [LIGHTPUSH](../standards/core/lightpush.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) based on the node’s configuration.
The method MUST throw an error if the `pubsubTopic` provided by the `Encoder` is not supported by the underlying node. The method MUST throw an error if the `pubsubTopic` provided by the `Encoder` is not supported by the underlying node.
The method MUST return the associated `RequestID` for the scheduled send attempt. The method MUST return the associated `RequestID` for the scheduled send attempt.
If the send operation fails, it MAY be retried from the `Message Storage API` using the `RequestID`. If the send operation fails, it MAY be retried from the `Message Storage API` using the `RequestID`.
@ -305,14 +305,14 @@ Content-Type: application/json
### Subscribe ### Subscribe
The `Subscribe API` SHOULD be used to initiate a subscription over [FILTER]() or [RELAY]() for continuous message retrieval. The `Subscribe API` SHOULD be used to initiate a subscription over [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) for continuous message retrieval.
When the `Subscribe API` is invoked, the following behaviors MUST occur. When the `Subscribe API` is invoked, the following behaviors MUST occur.
A subscription is established via [FILTER]() or [RELAY]() based on the node’s configuration for ongoing message reception. A subscription is established via [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) based on the node’s configuration for ongoing message reception.
If `confirmStored` is set to `true`, If `confirmStored` is set to `true`,
a recurring [STORE]() query MUST be initiated for the specified `contentTopics` to continuously update the stored property in the `MessageRecord` (as defined in the `Message Storage API`) for messages circulating in the network after the `Subscribe API` call. a recurring [STORE](../standards/core/store.md) query MUST be initiated for the specified `contentTopics` to continuously update the stored property in the `MessageRecord` (as defined in the `Message Storage API`) for messages circulating in the network after the `Subscribe API` call.
For details on the recurring query, refer to the `Message Storage API` section. For details on the recurring query, refer to the `Message Storage API` section.
Once the `Subscribe API` is called, the received property in the `MessageRecord` (as described in the `Message Storage API`) MUST be populated. Once the `Subscribe API` is called, the received property in the `MessageRecord` (as described in the `Message Storage API`) MUST be populated.
@ -352,14 +352,14 @@ which MUST be used for managing the subscription (e.g., for later unsubscribing)
The method MUST throw an error if the `pubsubTopic` provided by the `Decoder` is not supported by the underlying node. The method MUST throw an error if the `pubsubTopic` provided by the `Decoder` is not supported by the underlying node.
No specific order is guaranteed for callback invocation; No specific order is guaranteed for callback invocation;
subscription callbacks MUST be executed as messages are received from the protocol in use. subscription callbacks MUST be executed as messages are received from the protocol in use.
If `confirmStored` is set to `true`, a recurring [STORE]() query MUST be started. If `confirmStored` is set to `true`, a recurring [STORE](../standards/core/store.md) query MUST be started.
##### `unsubscribe` ##### `unsubscribe`
Removes a previously created subscription identified by its unique `SubscriptionID`. Removes a previously created subscription identified by its unique `SubscriptionID`.
Once unsubscribed, the associated `SubscriptionListener` MUST NOT receive any further messages. Once unsubscribed, the associated `SubscriptionListener` MUST NOT receive any further messages.
If the provided `SubscriptionID` does not correspond to an active subscription, If the provided `SubscriptionID` does not correspond to an active subscription,
the call MUST be ignored. the call MUST be ignored.
If recurring [STORE]() query was initiated by this `SubscriptionID`, it MUST be stopped. If recurring [STORE](../standards/core/store.md) query was initiated by this `SubscriptionID`, it MUST be stopped.
##### `getActiveSubscriptions` ##### `getActiveSubscriptions`
Returns an array of unique `SubscriptionID` values representing all currently active subscriptions. Returns an array of unique `SubscriptionID` values representing all currently active subscriptions.
@ -469,7 +469,7 @@ Messages can be identified by:
These identifiers SHOULD be passed to the appropriate methods described below to retrieve or manage messages. These identifiers SHOULD be passed to the appropriate methods described below to retrieve or manage messages.
Depending on the presence of the `confirmStored` or `confirmReceived` options in the `Initial configuration`, the `Message Storage API` will trigger either the `Subscribe API` or the periodic [STORE]() query as described in the `Acknowledgements` section below. Depending on the presence of the `confirmStored` or `confirmReceived` options in the `Initial configuration`, the `Message Storage API` will trigger either the `Subscribe API` or the periodic [STORE](../standards/core/store.md) query as described in the `Acknowledgements` section below.
Once a message is added to the `Message Storage API`, or if any details about it change, Once a message is added to the `Message Storage API`, or if any details about it change,
the appropriate events from the `message:*` event family (as described in the `Event Source API` section) MUST be invoked after the message is added or updated in the underlying storage. the appropriate events from the `message:*` event family (as described in the `Event Source API` section) MUST be invoked after the message is added or updated in the underlying storage.
@ -477,21 +477,21 @@ the appropriate events from the `message:*` event family (as described in the `E
#### Acknowledgements #### Acknowledgements
Message acknowledgement is a background operation that performs the following functions: Message acknowledgement is a background operation that performs the following functions:
- It subscribes to [FILTER]() or [RELAY]() and marks messages as `received` when detected. - It subscribes to [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) and marks messages as `received` when detected.
- It periodically queries [STORE]() and marks messages as `stored` when available. - It periodically queries [STORE](../standards/core/store.md) and marks messages as `stored` when available.
This operation MUST be initiated if either of the following conditions is met: This operation MUST be initiated if either of the following conditions is met:
- Either `confirmStored` or `confirmReceived` is set to `true` and `confirmContentTopics` is provided. - Either `confirmStored` or `confirmReceived` is set to `true` and `confirmContentTopics` is provided.
- The `Subscribe API` has been initiated for one or more `contentTopics`. - The `Subscribe API` has been initiated for one or more `contentTopics`.
The recurring [STORE]() query MUST prioritize the `storeNodes` specified in the initial configuration before using other available nodes. The recurring [STORE](../standards/core/store.md) query MUST prioritize the `storeNodes` specified in the initial configuration before using other available nodes.
These queries SHOULD occur once every 60 seconds for all `confirmContentTopics` provided as part of the initial configuration. These queries SHOULD occur once every 60 seconds for all `confirmContentTopics` provided as part of the initial configuration.
Furthermore, if the node’s health status transitions to `unhealthy` (as defined by the `Health API`), Furthermore, if the node’s health status transitions to `unhealthy` (as defined by the `Health API`),
the periodic [STORE]() query MUST be halted, the periodic [STORE](../standards/core/store.md) query MUST be halted,
and it MUST resume once the health status transitions to either `minimally healthy` or `healthy`. and it MUST resume once the health status transitions to either `minimally healthy` or `healthy`.
Recurring [STORE]() query and background subscription to `confirmContentTopics` is a subscription defined in the `Subscribe API` and can be handled the same way. Recurring [STORE](../standards/core/store.md) query and background subscription to `confirmContentTopics` is a subscription defined in the `Subscribe API` and can be handled the same way.
This background subscription has a reserved `SubscriptionID` of `1692854c-cbde-4afe-901f-1c86ecbd9ea1`. This background subscription has a reserved `SubscriptionID` of `1692854c-cbde-4afe-901f-1c86ecbd9ea1`.
Additionally, the `stored` property MUST be updated for any other messages received via the `History API`. Additionally, the `stored` property MUST be updated for any other messages received via the `History API`.
@ -539,8 +539,8 @@ This update occurs only after the `sending` property has transitioned back to `f
##### `stored` ##### `stored`
Defaults to `false`. Defaults to `false`.
Indicates whether a message has been confirmed to be present in the underlying [STORE]() protocol. Indicates whether a message has been confirmed to be present in the underlying [STORE](../standards/core/store.md) protocol.
This property is populated based on a recurring [STORE]() query described in `Acknowledgements` section or via the `History API`. This property is populated based on a recurring [STORE](../standards/core/store.md) query described in `Acknowledgements` section or via the `History API`.
Once a message is confirmed as stored, the `stored` property MUST be updated to `true` as a final state. Once a message is confirmed as stored, the `stored` property MUST be updated to `true` as a final state.
If an error occurs during reception, the `error` field MUST be populated with implementation-specific details. If an error occurs during reception, the `error` field MUST be populated with implementation-specific details.
@ -781,20 +781,20 @@ Refer to `Event Source API` for more details.
Indicates that the node’s connectivity is insufficient for reliable operation. Indicates that the node’s connectivity is insufficient for reliable operation.
In this state: In this state:
- No connections to service nodes are available, regardless of protocol. - No connections to service nodes are available, regardless of protocol.
- No peers are present in the [RELAY]() mesh. - No peers are present in the [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) mesh.
##### `minimally healthy` ##### `minimally healthy`
Indicates that the node meets the minimum connectivity requirements necessary to function, Indicates that the node meets the minimum connectivity requirements necessary to function,
although performance or reliability may be compromised. although performance or reliability may be compromised.
In this state: In this state:
- The node has at least one connection to a service node implementing [FILTER]() and one connection to a service node implementing [LIGHTPUSH](). - The node has at least one connection to a service node implementing [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md) and one connection to a service node implementing [LIGHTPUSH](../standards/core/lightpush.md).
- The [RELAY]() mesh includes connections to at least four other peers. - The [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) mesh includes connections to at least four other peers.
##### `healthy` ##### `healthy`
Indicates that the node’s connectivity meets or exceeds optimal operational thresholds. Indicates that the node’s connectivity meets or exceeds optimal operational thresholds.
In this state: In this state:
- The node has at least two connections to service nodes implementing [FILTER]() and at least two connections to service nodes implementing [LIGHTPUSH](). - The node has at least two connections to service nodes implementing [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md) and at least two connections to service nodes implementing [LIGHTPUSH](../standards/core/lightpush.md).
- The [RELAY]() mesh includes connections to at least six other peers. - The [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) mesh includes connections to at least six other peers.
##### Programmatic API ##### Programmatic API
@ -943,7 +943,7 @@ node.events.addEventListener("message:received", (event: CustomEvent<MessageReco
For the `REST API`, long polling over the `Message Store API` SHOULD be used. For the `REST API`, long polling over the `Message Store API` SHOULD be used.
##### `message:stored` ##### `message:stored`
This event MUST be dispatched when a message is confirmed to be `stored` in the underlying [STORE]() protocol or via the `History API`. This event MUST be dispatched when a message is confirmed to be `stored` in the underlying [STORE](../standards/core/store.md) protocol or via the `History API`.
When the message is stored, the `stored` property in the corresponding `MessageRecord` is updated to `true`. When the message is stored, the `stored` property in the corresponding `MessageRecord` is updated to `true`.
The payload is the updated `MessageRecord`. The payload is the updated `MessageRecord`.