mirror of https://github.com/vacp2p/rfc.git
Waku v2: Specify push-based filter spec (#175)
* Waku v2: Specify push-based filter spec * Make spell checker happy * Update specs/waku/waku-v2.md Co-authored-by: Dean Eigenmann <7621705+decanus@users.noreply.github.com> * Update specs/waku/waku-v2.md Co-authored-by: Kim De Mey <kim.demey@gmail.com> * Remove confusing technical detail para * Addressed review comments * spellchecker Co-authored-by: Dean Eigenmann <7621705+decanus@users.noreply.github.com> Co-authored-by: Kim De Mey <kim.demey@gmail.com>
This commit is contained in:
Oskar Thorén
GitHub
parent
9e87d3d993
commit
a391edf448
|
|
@ -190,12 +190,12 @@ message RPC {
|
|||
}
|
||||
|
||||
message HistoryQuery {
|
||||
string uuid = 1;
|
||||
string uuid = 1;
|
||||
repeated string topic = 2;
|
||||
}
|
||||
|
||||
message HistoryResponse {
|
||||
string uuid = 1;
|
||||
string uuid = 1;
|
||||
repeated Message messages = 2;
|
||||
}
|
||||
```
|
||||
|
|
@ -216,37 +216,106 @@ The `uuid` field MUST indicate which query is being responded to.
|
|||
|
||||
The `messages` field MUST contain the messages found.
|
||||
|
||||
|
||||
### Content filtering
|
||||
|
||||
**Protocol identifier***: `/vac/waku/filter/2.0.0-alpha2`
|
||||
**Protocol identifier***: `/vac/waku/filter/2.0.0-alpha3`
|
||||
|
||||
Content filter is a way to do [message-based
|
||||
Content filtering is a way to do [message-based
|
||||
filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering).
|
||||
Currently the only content filter being applied is on `contentTopic`. This
|
||||
corresponds to topics in Waku v1.
|
||||
|
||||
A node that only sets this field but doesn't subscribe to any topic SHOULD only
|
||||
get notified when the content subtopic matches. A content subtopic matches when
|
||||
a `Wakumessage` `contentTopic` field is the same.
|
||||
#### Rationale
|
||||
|
||||
A node that receives this RPC SHOULD apply this content filter before relaying.
|
||||
Since such a node is doing extra work for a light node, it MAY also account for
|
||||
usage and be selective in how much service it provides. This mechanism is
|
||||
currently planned but underspecified.
|
||||
Unlike the `store` protocol for historical messages, this protocol allows for
|
||||
native lower latency scenarios such as instant messaging. It is thus
|
||||
complementary to it.
|
||||
|
||||
Strictly speaking, it is not just doing basic request response, but performs
|
||||
sender push based on receiver intent. While this can be seen as a form of light
|
||||
pub/sub, it is only used between two nodes in a direct fashion. Unlike the
|
||||
Gossip domain, this is meant for light nodes which put a premium on bandwidth.
|
||||
No gossiping takes place.
|
||||
|
||||
It is worth noting that a light node could get by with only using the `store`
|
||||
protocol to query for a recent time window, provided it is acceptable to do
|
||||
frequent polling.
|
||||
|
||||
#### Protobuf
|
||||
|
||||
TODO Consider adding a FilterResponse acting as a form of ACK
|
||||
|
||||
TODO Consider adding request id
|
||||
|
||||
TODO Clarify if Messages or a list of WakuMessage are pushed
|
||||
|
||||
TODO Specify unsubscribe mechanism and semantics
|
||||
|
||||
TODO Investigate if we need a way to communicate (handshake?) that we are a a client - server (full node - light node) or not.
|
||||
NOTE I would imagine this is implied from the contentFilter, especially as two nodes can play multiple roles.
|
||||
|
||||
|
||||
```protobuf
|
||||
message RPC {
|
||||
repeated ContentFilter contentFilter = 1;
|
||||
repeated FilterRequest filterRequest = 1;
|
||||
// space for optional FilterResponse
|
||||
repeated MessagePush messagePush = 3;
|
||||
}
|
||||
|
||||
message FilterRequest {
|
||||
// space for optional request id
|
||||
repeated ContentFilter contentFilter = 2;
|
||||
optional string topic = 3;
|
||||
|
||||
message ContentFilter {
|
||||
optional string contentTopic = 1;
|
||||
}
|
||||
}
|
||||
|
||||
message MessagePush {
|
||||
repeated Message message = 1;
|
||||
}
|
||||
```
|
||||
|
||||
##### FilterRequest
|
||||
|
||||
TODO Specify mechanism for telling it won't honor (normal-no service-spam case)
|
||||
|
||||
TODO Clarify exactly what we mean by connection and TTL
|
||||
|
||||
A node that sends the RPC with a filter request requests that the filter node
|
||||
SHOULD notify the light requesting node of messages matching this filter.
|
||||
|
||||
The filter matches when content filter and, optionally, a topic is matched.
|
||||
Content filter is matched when a `WakuMessage` `contentTopic` field is the same.
|
||||
|
||||
A filter node SHOULD honor this request, though it MAY choose not to do so. If
|
||||
it chooses not to do so it MAY tell the light why. The mechanism for doing this
|
||||
is currently not specified. For notifying the light node a filter node sends a
|
||||
MessagePush message.
|
||||
|
||||
Since such a filter node is doing extra work for a light node, it MAY also
|
||||
account for usage and be selective in how much service it provides. This
|
||||
mechanism is currently planned but underspecified.
|
||||
|
||||
##### MessagePush
|
||||
|
||||
A filter node that has received a filter request SHOULD push all messages that
|
||||
match this filter to a light node. These messages are likely to come from the
|
||||
`relay` protocol and be kept at the Node, but there MAY be other sources or
|
||||
protocols where this comes from. This is up to the consumer of the protocol.
|
||||
|
||||
A filter node MUST NOT send a push message for messages that have not been
|
||||
requested via a FilterRequest.
|
||||
|
||||
If a specific light node isn't connected to a filter node for some specific
|
||||
period of time (e.g. a TTL), then the filter node MAY choose to not push these
|
||||
messages to the node. This period is up to the consumer of the protocol and node
|
||||
implementation, though a reasonable default is one minute.
|
||||
|
||||
---
|
||||
|
||||
TODO(Oskar): Update changelog once we are in draft, which is when
|
||||
implementation matches spec
|
||||
|
||||
|
|
@ -278,6 +347,8 @@ Copyright and related rights waived via
|
|||
|
||||
8. [Message Filtering (Wikipedia)](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
|
||||
|
||||
9. [Libp2p PubSub spec - topic validation](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation)
|
||||
|
||||
<!--
|
||||
|
||||
# Underlying transports, etc
|
||||
|
|
|
|||
|
|
@ -47,6 +47,10 @@ enum
|
|||
et
|
||||
Ethereum
|
||||
extensibility
|
||||
FilterRequest
|
||||
filterRequest
|
||||
FilterResponse
|
||||
filterResponse
|
||||
FloodSub
|
||||
GCM
|
||||
github
|
||||
|
|
@ -82,6 +86,8 @@ localHash
|
|||
mailserver
|
||||
mailservers
|
||||
Markou
|
||||
messagePush
|
||||
MessagePush
|
||||
metainformation
|
||||
Mey
|
||||
mixnet
|
||||
|
|
|
|||
Loading…
Reference in New Issue