mirror of https://github.com/waku-org/nwaku.git
94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# Waku APIs
|
|
|
|
## Nim API
|
|
|
|
The Nim Waku API consist of a set of methods opearting on the Waku Node object.
|
|
Some of them have different arity depending on what privacy/bandwidth trade-off
|
|
the consumer wants to make. These methods are:
|
|
|
|
1. **Init** - create a node.
|
|
2. **Start** - start a created node.
|
|
3. **Subscribe** - to a topic or a specific content filter.
|
|
4. **Unsubscribe** - to a topic or a specific content filter.
|
|
5. **Publish** - to a topic, or a topic and a specific content filter.
|
|
6. **Query** - for historical messages.
|
|
7. **Info** - to get information about the node.
|
|
8. **Resume** - to retrieve and persist the message history since the node's last online time.
|
|
|
|
```Nim
|
|
proc init*(T: type WakuNode, nodeKey: crypto.PrivateKey,
|
|
bindIp: ValidIpAddress, bindPort: Port,
|
|
extIp = none[ValidIpAddress](), extPort = none[Port]()): T =
|
|
## Creates a Waku Node.
|
|
##
|
|
## Status: Implemented.
|
|
|
|
proc start*(node: WakuNode) {.async.} =
|
|
## Starts a created Waku Node.
|
|
##
|
|
## Status: Implemented.
|
|
|
|
proc subscribe*(node: WakuNode, topic: Topic, handler: TopicHandler) =
|
|
## Subscribes to a PubSub topic. Triggers handler when receiving messages on
|
|
## this topic. TopicHandler is a method that takes a topic and some data.
|
|
##
|
|
## NOTE The data field SHOULD be decoded as a WakuMessage.
|
|
## Status: Implemented.
|
|
|
|
proc subscribe*(node: WakuNode, request: FilterRequest, handler: ContentFilterHandler) {.async, gcsafe.} =
|
|
## Registers for messages that match a specific filter. Triggers the handler whenever a message is received.
|
|
## FilterHandler is a method that takes a MessagePush.
|
|
##
|
|
## Status: Implemented.
|
|
|
|
proc unsubscribe*(node: WakuNode, topic: Topic, handler: TopicHandler) =
|
|
## Unsubscribes a handler from a PubSub topic.
|
|
##
|
|
## Status: Implemented.
|
|
|
|
proc unsubscribeAll*(node: WakuNode, topic: Topic) =
|
|
## Unsubscribes all handlers registered on a specific PubSub topic.
|
|
##
|
|
## Status: Implemented.
|
|
|
|
proc unsubscribe*(w: WakuNode, contentFilter: ContentFilter) =
|
|
## Unsubscribe from a content filter.
|
|
##
|
|
## Status: Not yet implemented.
|
|
## TODO Implement.
|
|
|
|
proc publish*(node: WakuNode, topic: Topic, message: WakuMessage) =
|
|
## Publish a `WakuMessage` to a PubSub topic. `WakuMessage` should contain a
|
|
## `contentTopic` field for light node functionality. This field may be also
|
|
## be omitted.
|
|
##
|
|
## Status: Implemented.
|
|
|
|
proc query*(w: WakuNode, query: HistoryQuery, handler: QueryHandlerFunc) {.async, gcsafe.} =
|
|
## Queries known nodes for historical messages. Triggers the handler whenever a response is received.
|
|
## QueryHandlerFunc is a method that takes a HistoryResponse.
|
|
##
|
|
## Status: Implemented.
|
|
|
|
proc info*(node: WakuNode): WakuInfo =
|
|
## Returns information about the Node, such as what multiaddress it can be reached at.
|
|
##
|
|
## Status: Implemented.
|
|
##
|
|
|
|
proc resume*(node: WakuNode, peerList: Option[seq[PeerInfo]]) =
|
|
## Retrieves and persists the history of waku messages published on the default waku pubsub topic since the last time the waku node has been online.
|
|
## It requires the waku node to have the store protocol mounted in the full mode (i.e., persisting messages).
|
|
## `peerList` indicates the list of peers to query from.
|
|
## The history is fetched from all available peers in this list and then consolidated into one deduplicated list.
|
|
## If no peerList is passed, the history is fetched from one of the known peers.
|
|
## It retrieves the history successfully given that the dialed peer has been online during the queried time window.
|
|
##
|
|
## Status: Implemented.
|
|
##
|
|
```
|
|
|
|
## JSON RPC
|
|
|
|
TODO To specify
|