vacp2p/rfc
1
0
Fork 0
mirror of https://github.com/vacp2p/rfc.git synced 2025-01-27 07:05:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Feature/add json rpc api spec (#265)

Browse Source 
* Minor improvements; added polling for latest messages
This commit is contained in:
Hanno Cornelius 2020-12-02 10:55:34 +02:00 committed by GitHub
parent 430178c55b
commit 419875cc4a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 28 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
specs/waku/v2/waku-v2-rpc-api.md
View File

@ -117,6 +117,8 @@ The following structured types are defined for use on the Relay API:
| `payload` | `String` | mandatory | The payload being relayed |
| `contentTopic` | `Number` | optional | Message content topic for optional content-based filtering |
> **_NOTE:_** `WakuRelayMessage` maps directly to a [`WakuMessage`](#WakuMessage), except that the latter contains an explicit message `version`. For `WakuRelay` purposes, the versioning is handled by the API.
### `post_waku_v2_relay_v1_message`
The `post_waku_v2_relay_v1_message` method publishes a message to be relayed on a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor)
@ -160,19 +162,19 @@ The `delete_waku_v2_relay_v1_subscriptions` method unsubscribes a node from an a
- **`Bool`** - `true` on success or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
### `get_waku_v2_relay_v1_messages_head`
### `get_waku_v2_relay_v1_messages`
The `get_waku_v2_relay_v1_messages_head` method returns the latest message on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor). The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server MUST block until a message is received or a timeout is reached. This method can be used to long poll a `topic` for new messages.
The `get_waku_v2_relay_v1_messages` method returns a list of messages that were received on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server SHOULD return an empty list. This method can be used to poll a `topic` for new messages.
#### Parameters
| Field | Type | Inclusion | Description |
| ----: | :--: | :--: |----------- |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) to poll for the latest message |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) to poll for the latest messages |
#### Response
- [**`WakuMessage`**](#WakuMessage) - the latest `message` on the polled `topic` or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
- **`Array`[[`WakuMessage`](#WakuMessage)]** - the latest `messages` on the polled `topic` or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
## Store API
@ -268,6 +270,20 @@ The `delete_waku_v2_filter_v1_subscription` method removes subscriptions in a [l
- **`Bool`** - `true` on success or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
### `get_waku_v2_filter_v1_messages`
The `get_waku_v2_filter_v1_messages` method returns a list of messages that were received on a subscribed content `topic` after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled content `topic`. If no message has yet been received on the polled content `topic`, the server SHOULD respond with an empty list. This method can be used to poll a content `topic` for new messages.
#### Parameters
| Field | Type | Inclusion | Description |
| ----: | :--: | :--: |----------- |
| `contentTopic` | `Number` | mandatory | The content topic to poll for the latest messages |
#### Response
- **`Array`[[`WakuMessage`](#WakuMessage)]** - the latest `messages` on the polled content `topic` or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
# Example usage
## Store API
@ -450,6 +466,12 @@ This method is part of the `store` API and the specific resources to retrieve ar
}
```
# References
1. [JSON-RPC specification](https://www.jsonrpc.org/specification)
1. [LibP2P PubSub specification - topic descriptor](https://github.com/libp2p/specs/tree/master/pubsub#the-topic-descriptor)
1. [Waku v2 specification](https://github.com/vacp2p/specs/blob/master/specs/waku/v2/waku-v2.md)
# Changelog
TBD

2
wordlist.txt
View File

@ -89,7 +89,9 @@ keypair
kimdemey
Lange
libp
LibP
libp2p
LibP2P
lifecycle
LLC
localHash