mirror of https://github.com/vacp2p/rfc.git
docs(36/WAKU2-BINDINGS-API): add filter, store, and lightpush functions (#525)
Co-authored-by: fryorcraken.eth <110212804+fryorcraken@users.noreply.github.com> Co-authored-by: Hanno Cornelius <68783915+jm-clius@users.noreply.github.com>
This commit is contained in:
Richard Ramos
GitHub
parent
b48250d212
commit
bb5357ae3b
|
|
@ -106,6 +106,105 @@ Fields:
|
|||
- `data`: Decrypted message payload base64 encoded,
|
||||
- `padding`: Padding base64 encoded.
|
||||
|
||||
### `FilterSubscription` type
|
||||
|
||||
The criteria to create subscription to a light node in JSON Format:
|
||||
|
||||
```ts
|
||||
{
|
||||
contentFilters: ContentFilter[];
|
||||
pubsubTopic: string?;
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
- `contentFilters`: Array of [`ContentFilter`](#contentfilter-type) being subscribed to / unsubscribed from.
|
||||
- `topic`: Optional pubsub topic.
|
||||
|
||||
|
||||
### `ContentFilter` type
|
||||
|
||||
```ts
|
||||
{
|
||||
contentTopic: string;
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
- `contentTopic`: The content topic of a Waku message.
|
||||
|
||||
### `StoreQuery` type
|
||||
|
||||
Criteria used to retrieve historical messages
|
||||
|
||||
```ts
|
||||
interface StoreQuery {
|
||||
pubsubTopic?: string;
|
||||
contentFilters?: ContentFilter[];
|
||||
startTime?: number;
|
||||
endTime?: number;
|
||||
pagingOptions?: PagingOptions
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
- `pubsubTopic`: The pubsub topic on which messages are published.
|
||||
- `contentFilters`: Array of [`ContentFilter`](#contentfilter-type) to query for historical messages,
|
||||
- `startTime`: The inclusive lower bound on the timestamp of queried messages. This field holds the Unix epoch time in nanoseconds.
|
||||
- `endTime`: The inclusive upper bound on the timestamp of queried messages. This field holds the Unix epoch time in nanoseconds.
|
||||
- `pagingOptions`: Paging information in [`PagingOptions`](#pagingoptions-type) format.
|
||||
|
||||
### `StoreResponse` type
|
||||
|
||||
The response received after doing a query to a store node:
|
||||
|
||||
```ts
|
||||
interface StoreResponse {
|
||||
messages: JsonMessage[];
|
||||
pagingOptions?: PagingOptions;
|
||||
}
|
||||
```
|
||||
Fields:
|
||||
|
||||
- `messages`: Array of retrieved historical messages in [`JsonMessage`](#jsonmessage-type) format.
|
||||
- `pagingOption`: Paging information in [`PagingOptions`](#pagingoptions-type) format from which to resume further historical queries
|
||||
|
||||
### `PagingOptions` type
|
||||
|
||||
```ts
|
||||
interface PagingOptions {
|
||||
pageSize: number;
|
||||
cursor?: Index;
|
||||
forward: bool;
|
||||
}
|
||||
```
|
||||
Fields:
|
||||
|
||||
- `pageSize`: Number of messages to retrieve per page.
|
||||
- `cursor`: Message Index from which to perform pagination. If not included and forward is set to true, paging will be performed from the beginning of the list. If not included and forward is set to false, paging will be performed from the end of the list.
|
||||
- `forward`: `true` if paging forward, `false` if paging backward
|
||||
|
||||
### `Index` type
|
||||
|
||||
```ts
|
||||
interface Index {
|
||||
digest: string;
|
||||
receiverTime: number;
|
||||
senderTime: number;
|
||||
pubsubTopic: string;
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
- `digest`: Hash of the message at this [`Index`](#index-type).
|
||||
- `receiverTime`: UNIX timestamp in nanoseconds at which the message at this [`Index`](#index-type) was received.
|
||||
- `senderTime`: UNIX timestamp in nanoseconds at which the message is generated by its sender.
|
||||
- `pubsubTopic`: The pubsub topic of the message at this [`Index`](#index-type).
|
||||
|
||||
## Events
|
||||
|
||||
Asynchronous events require a callback to be registered.
|
||||
|
|
@ -190,6 +289,7 @@ interface JsonSignal {
|
|||
keepAliveInterval?: number;
|
||||
relay?: boolean;
|
||||
minPeersToPublish?: number
|
||||
filter?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -215,6 +315,8 @@ If a key is `undefined`, or `null`, a default value will be set.
|
|||
Default `true`.
|
||||
- `minPeersToPublish`: The minimum number of peers required on a topic to allow broadcasting a message.
|
||||
Default `0`.
|
||||
- `filter`: Enable filter protocol.
|
||||
Default `false`.
|
||||
|
||||
For example:
|
||||
```json
|
||||
|
|
@ -683,6 +785,202 @@ For example:
|
|||
```
|
||||
|
||||
|
||||
## Waku Filter
|
||||
|
||||
### `extern char* waku_filter_subscribe(char* filterJSON, char* peerID, int timeoutMs)`
|
||||
|
||||
Creates a subscription in a lightnode for messages that matches a content filter and optionally a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
|
||||
|
||||
**Parameters**
|
||||
|
||||
1. `char* filterJSON`: JSON string containing the [`FilterSubscription`](#filtersubscription-type) to subscribe to.
|
||||
2. `char* peerID`: Peer ID to subscribe to.
|
||||
The peer must be already known.
|
||||
It must have been added before with [`waku_add_peer`](#extern-char-waku_add_peerchar-address-char-protocolid)
|
||||
or previously dialed with [`waku_connect_peer`](#extern-char-waku_connect_peerchar-address-int-timeoutms).
|
||||
Use `NULL` to automatically select a node.
|
||||
3. `int timeoutMs`: Timeout value in milliseconds to execute the call.
|
||||
If the function execution takes longer than this value,
|
||||
the execution will be canceled and an error returned.
|
||||
Use `0` for no timeout.
|
||||
|
||||
**Returns**
|
||||
|
||||
A [`JsonResponse`](#jsonresponse-type).
|
||||
If the execution is successful, the `result` field is set to `true`.
|
||||
|
||||
For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": true
|
||||
}
|
||||
```
|
||||
|
||||
**Events**
|
||||
|
||||
When a message is received, a ``"message"` event` is emitted containing the message, pubsub topic, and node ID in which
|
||||
the message was received.
|
||||
|
||||
The `event` type is [`JsonMessageEvent`](#jsonmessageevent-type).
|
||||
|
||||
For Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "message",
|
||||
"event": {
|
||||
"subscriptionID": 1,
|
||||
"pubsubTopic": "/waku/2/default-waku/proto",
|
||||
"messageID": "0x6496491e40dbe0b6c3a2198c2426b16301688a2daebc4f57ad7706115eac3ad1",
|
||||
"wakuMessage": {
|
||||
"payload": "TODO",
|
||||
"contentTopic": "/my-app/1/notification/proto",
|
||||
"version": 1,
|
||||
"timestamp": 1647826358000000000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `extern char* waku_filter_unsubscribe(char* filterJSON, int timeoutMs)`
|
||||
|
||||
Removes subscriptions in a light node matching a content filter and, optionally, a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
|
||||
|
||||
**Parameters**
|
||||
|
||||
1. `char* filterJSON`: JSON string containing the [`FilterSubscription`](#filtersubscription-type).
|
||||
2. `int timeoutMs`: Timeout value in milliseconds to execute the call.
|
||||
If the function execution takes longer than this value,
|
||||
the execution will be canceled and an error returned.
|
||||
Use `0` for no timeout.
|
||||
|
||||
**Returns**
|
||||
|
||||
A [`JsonResponse`](#jsonresponse-type).
|
||||
If the execution is successful, the `result` field is set to `true`.
|
||||
|
||||
For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": true
|
||||
}
|
||||
```
|
||||
|
||||
## Waku Lightpush
|
||||
|
||||
### `extern char* waku_lightpush_publish(char* messageJSON, char* topic, char* peerID, int timeoutMs)`
|
||||
|
||||
Publish a message using Waku Lightpush.
|
||||
|
||||
**Parameters**
|
||||
|
||||
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
|
||||
2. `char* pubsubTopic`: pubsub topic on which to publish the message.
|
||||
If `NULL`, it uses the default pubsub topic.
|
||||
3. `char* peerID`: Peer ID supporting the lightpush protocol.
|
||||
The peer must be already known.
|
||||
It must have been added before with [`waku_add_peer`](#extern-char-waku_add_peerchar-address-char-protocolid)
|
||||
or previously dialed with [`waku_connect_peer`](#extern-char-waku_connect_peerchar-address-int-timeoutms).
|
||||
Use `NULL` to automatically select a node.
|
||||
3. `int timeoutMs`: Timeout value in milliseconds to execute the call.
|
||||
If the function execution takes longer than this value,
|
||||
the execution will be canceled and an error returned.
|
||||
Use `0` for no timeout.
|
||||
|
||||
Note: `messageJson.version` is overwritten to `0`.
|
||||
|
||||
**Returns**
|
||||
|
||||
A [`JsonResponse`](#jsonresponse-type).
|
||||
If the execution is successful, the `result` field contains the message ID.
|
||||
|
||||
### `extern char* waku_lightpush_publish_enc_asymmetric(char* messageJson, char* pubsubTopic, char* peerID, char* publicKey, char* optionalSigningKey, int timeoutMs)`
|
||||
|
||||
Optionally sign,
|
||||
encrypt using asymmetric encryption
|
||||
and publish a message using Waku Lightpush.
|
||||
|
||||
**Parameters**
|
||||
|
||||
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
|
||||
2. `char* pubsubTopic`: pubsub topic on which to publish the message.
|
||||
If `NULL`, it uses the default pubsub topic.
|
||||
3. `char* peerID`: Peer ID supporting the lightpush protocol.
|
||||
The peer must be already known.
|
||||
It must have been added before with [`waku_add_peer`](#extern-char-waku_add_peerchar-address-char-protocolid)
|
||||
or previously dialed with [`waku_connect_peer`](#extern-char-waku_connect_peerchar-address-int-timeoutms).
|
||||
4. `char* publicKey`: hex encoded public key to be used for encryption.
|
||||
5. `char* optionalSigningKey`: hex encoded private key to be used to sign the message.
|
||||
6. `int timeoutMs`: Timeout value in milliseconds to execute the call.
|
||||
If the function execution takes longer than this value,
|
||||
the execution will be canceled and an error returned.
|
||||
Use `0` for no timeout.
|
||||
|
||||
Note: `messageJson.version` is overwritten to `1`.
|
||||
|
||||
**Returns**
|
||||
|
||||
A [`JsonResponse`](#jsonresponse-type).
|
||||
If the execution is successful, the `result` field contains the message ID.
|
||||
|
||||
### `extern char* waku_lightpush_publish_enc_symmetric(char* messageJson, char* pubsubTopic, char* peerID, char* symmetricKey, char* optionalSigningKey, int timeoutMs)`
|
||||
|
||||
Optionally sign,
|
||||
encrypt using symmetric encryption
|
||||
and publish a message using Waku Lightpush.
|
||||
|
||||
**Parameters**
|
||||
|
||||
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
|
||||
2. `char* pubsubTopic`: pubsub topic on which to publish the message.
|
||||
If `NULL`, it uses the default pubsub topic.
|
||||
3. `char* peerID`: Peer ID supporting the lightpush protocol.
|
||||
The peer must be already known.
|
||||
It must have been added before with [`waku_add_peer`](#extern-char-waku_add_peerchar-address-char-protocolid)
|
||||
or previously dialed with [`waku_connect_peer`](#extern-char-waku_connect_peerchar-address-int-timeoutms).
|
||||
4. `char* symmetricKey`: hex encoded secret key to be used for encryption.
|
||||
5. `char* optionalSigningKey`: hex encoded private key to be used to sign the message.
|
||||
6. `int timeoutMs`: Timeout value in milliseconds to execute the call.
|
||||
If the function execution takes longer than this value,
|
||||
the execution will be canceled and an error returned.
|
||||
Use `0` for no timeout.
|
||||
|
||||
Note: `messageJson.version` is overwritten to `1`.
|
||||
|
||||
**Returns**
|
||||
|
||||
A [`JsonResponse`](#jsonresponse-type).
|
||||
If the execution is successful, the `result` field contains the message ID.
|
||||
|
||||
## Waku Store
|
||||
|
||||
### `extern char* waku_store_query(char* queryJSON, char* peerID, int timeoutMs)`
|
||||
|
||||
Retrieves historical messages on specific content topics. This method may be called with [`PagingOptions`](#pagingoptions-type),
|
||||
to retrieve historical messages on a per-page basis. If the request included [`PagingOptions`](#pagingoptions-type), the node
|
||||
must return messages on a per-page basis and include [`PagingOptions`](#pagingoptions-type) in the response. These [`PagingOptions`](#pagingoptions-type)
|
||||
must contain a cursor pointing to the Index from which a new page can be requested.
|
||||
|
||||
**Parameters**
|
||||
|
||||
1. `char* queryJSON`: JSON string containing the [`StoreQuery`](#storequery-type).
|
||||
2. `char* peerID`: Peer ID supporting the store protocol.
|
||||
The peer must be already known.
|
||||
It must have been added before with [`waku_add_peer`](#extern-char-waku_add_peerchar-address-char-protocolid)
|
||||
or previously dialed with [`waku_connect_peer`](#extern-char-waku_connect_peerchar-address-int-timeoutms).
|
||||
3. `int timeoutMs`: Timeout value in milliseconds to execute the call.
|
||||
If the function execution takes longer than this value,
|
||||
the execution will be canceled and an error returned.
|
||||
Use `0` for no timeout.
|
||||
|
||||
**Returns**
|
||||
|
||||
A [`JsonResponse`](#jsonresponse-type).
|
||||
If the execution is successful, the `result` field contains a [`StoreResponse`](#storeresponse-type)..
|
||||
|
||||
|
||||
## Decrypting messages
|
||||
|
||||
### `extern char* waku_decode_symmetric(char* messageJson, char* symmetricKey)`
|
||||
|
|
|
|||
Loading…
Reference in New Issue