diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 6cfceb59..b1494be1 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -29,6 +29,13 @@ contributors: * [Function definitions](#function-definitions) * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) + * [General events emission](#general-events-emission) + * [Type definitions](#type-definitions-1) + * [Subscribe to messages](#subscribe-to-messages) + * [Type definitions](#type-definitions-2) + * [Function definitions](#function-definitions-1) + * [Predefined values](#predefined-values-1) + * [Extended definitions](#extended-definitions-1) * [The Validation API](#the-validation-api) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -75,6 +82,7 @@ An alternative would be to choose a programming language. However, such choice m - `array`: iterable object containing values of all the same type. - `result`: an enum type that either contains a value or void (success), or an error (failure); The error is left to the implementor. - `error`: Left to the implementor on whether `error` types are `string` or `object` in the given language. + - `event_emitter`: An object that emit events. - Usage of `result` is RECOMMENDED, usage of exceptions is NOT RECOMMENDED, no matter the language. TODO: Review whether to specify categories of errors. @@ -302,6 +310,88 @@ If the `mode` set is `core`, the initialised `WakuNode` SHOULD use: `edge` mode SHOULD be used if node functions in resource restricted environment, whereas `core` SHOULD be used if node has no strong hardware or bandwidth restrictions. +### General events emission + +#### Type definitions + +```yaml +types: + EventEmitter: + type: event_emitter + description: "An event emitter for general node events." + events: + "error:subscribe": + type: string + description: "Event emitted when subscription to a content topic irremediably fails. The event contains an error message." + # Extending `WakuNode` definition + WakuNode: + fields: + events: + type: EventEmitter + description: "Event emitter for Waku node." +``` + +### Subscribe to messages + +#### Type definitions + +```yaml +types: + MessageEmitter: + type: event_emitter + description: "An event emitter for message-related events. Emits events keyed by content topic, with the message payload as bytes." + events: + string: + type: bytes + description: "Event emitted when a message is received on the specified content topic. The event name is the content topic string, and the event payload is the raw message bytes." + # Extending `WakuNode` definition + WakuNode: + fields: + messageEmitter: + type: MessageEmitter + description: "Event emitter for received messages, keyed by content topic." +``` + +#### Function definitions + +```yaml +functions: + subscribe: + description: "Subscribe to specific content topics" + parameters: + - name: contentTopics + type: Array + description: "The content topics for the node to subscribe to." + returns: + type: void +``` + +#### Predefined values + +#### Extended definitions + +**`mode`**: + +If the `mode` set is `edge`, `subscribe` SHOULD trigger set up a subscription using [FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) as client and [P2P-RELIABILITY](/standards/application/p2p-reliability.md). + +If the `mode` set is `core`, `subscribe` SHOULD trigger set up a subscription using [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) and [P2P-RELIABILITY](/standards/application/p2p-reliability.md). +This MAY trigger joining a new shard if not already set. + +Only messages on subscribed content topics SHOULD be emitted by `messageEmitter`, meaning messages received via `RELAY` SHOULD be filtered by content topics before emission. + +**`error`**: + +Only irremediable failures should lead to emitting a `"error:subscribe"`. +Failure to reach nodes can be omitted, and should be handled via the health (TODO) events; +[P2P-RELIABILITY](/standards/application/p2p-reliability.md) SHOULD handle automated re-subscriptions and redundancy. + +Examples of irremediable failures are: + +- Invalid content topic format +- Exceeding number of content topics +- Node not started +- Other node-level configuration issue + ## The Validation API [WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md) is currently the primary message validation mechanism in place.