diff --git a/spec/12/index.html b/spec/12/index.html index 6905c25b2..d5786b438 100644 --- a/spec/12/index.html +++ b/spec/12/index.html @@ -5,15 +5,13 @@ - + - + @@ -197,18 +195,9 @@
previous versions: 00
-WakuFilter
is a protocol that enables subscribing to messages that a peer receives. This is a more lightweight version of WakuRelay
specifically designed for bandwidth restricted devices. This is due to the fact that light nodes subscribe to full-nodes and only receive the messages they desire.
WakuFilter
is a protocol that enables subscribing to messages that a peer receives. This is a more lightweight version of WakuRelay
specifically designed for bandwidth restricted devices. This is due to the fact that light nodes subscribe to full-nodes and only receive the messages they desire.
Protocol identifiers:
-/vac/waku/filter-subscribe/2.0.0-beta1
/vac/waku/filter-push/2.0.0-beta1
Protocol identifier*: /vac/waku/filter/2.0.0-beta1
Content filtering is a way to do message-based
filtering.
Currently the only content filter being applied is on contentTopic
. This
@@ -341,103 +324,223 @@
syntax = "proto3";
+message FilterRequest {
+ bool subscribe = 1;
+ string topic = 2;
+ repeated ContentFilter contentFilters = 3;
-// 12/WAKU2-FILTER rfc: https://rfc.vac.dev/spec/12/
-package waku.filter.v2;
-
-// Protocol identifier: /vac/waku/filter-subscribe/2.0.0-beta1
-message FilterSubscribeRequest {
- enum FilterSubscribeType {
- SUBSCRIBER_PING = 0;
- SUBSCRIBE = 1;
- UNSUBSCRIBE = 2;
- UNSUBSCRIBE_ALL = 3;
+ message ContentFilter {
+ string contentTopic = 1;
}
-
- string request_id = 1;
- FilterSubscribeType filter_subscribe_type = 2;
-
- // Filter criteria
- optional string pubsub_topic = 10;
- repeated string content_topics = 11;
}
-message FilterSubscribeResponse {
- string request_id = 1;
- uint32 status_code = 10;
- optional string status_desc = 11;
+message MessagePush {
+ repeated WakuMessage messages = 1;
}
-// Protocol identifier: /vac/waku/filter-push/2.0.0-beta1
-message MessagePush {
- WakuMessage waku_message = 1;
- optional string pubsub_topic = 2;
+message FilterRPC {
+ string requestId = 1;
+ FilterRequest request = 2;
+ MessagePush push = 3;
}
-
- Filter-Subscribe
- #
-
-A filter service node MUST support the filter-subscribe protocol
-to allow filter clients to subscribe, modify, refresh and unsubscribe a desired set of filter criteria.
-The combination of different filter criteria for a specific filter client node is termed a “subscription”.
-A filter client is interested in receiving messages matching the filter criteria in its registered subscriptions.
-Since a filter service node is consuming resources to provide this service,
-it MAY account for usage and adapt its service provision to certain clients.
-An incentive mechanism is currently planned but underspecified.
-
- Filter Subscribe Request
- #
-
-A client node MUST send all filter requests in a FilterSubscribeRequest
message.
-This request MUST contain a request_id
.
-The request_id
MUST be a uniquely generated string.
-Each request MUST include a filter_subscribe_type
, indicating the type of request.
-
- Filter Subscribe Response
- #
+
A node MUST send all Filter messages (FilterRequest
, MessagePush
) wrapped inside a
+FilterRPC
this allows the node handler to determine how to handle a message as the Waku
+Filter protocol is not a request response based protocol but instead a push based system.
The requestId
MUST be a uniquely generated string. When a MessagePush
is sent
+the requestId
MUST match the requestId
of the subscribing FilterRequest
whose filters
+matched the message causing it to be pushed.
A FilterRequest
contains an optional topic, zero or more content filters and
+a boolean signifying whether to subscribe or unsubscribe to the given filters.
+True signifies ‘subscribe’ and false signifies ‘unsubscribe’.
A node that sends the RPC with a filter request and subscribe
set to ’true’
+requests that the filter node SHOULD notify the light requesting node of messages
+matching this filter.
A node that sends the RPC with a filter request and subscribe
set to ‘false’
+requests that the filter node SHOULD stop notifying the light requesting node
+of messages matching this filter if it is currently doing so.
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.
+A filter node that has received a filter request SHOULD push all messages that
+match this filter to a light node. These WakuMessage
’s 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.
+Anonymous filter subscription: This feature guarantees that nodes can anonymously subscribe for a message filter (i.e., without revealing their exact content filter). As such, no adversary in the WakuFilter
protocol would be able to link nodes to their subscribed content filers. The current version of the WakuFilter
protocol does not provide anonymity as the subscribing node has a direct connection to the full node and explicitly submits its content filter to be notified about the matching messages. However, one can consider preserving anonymity through one of the following ways:
FilterRPC
does not embody any piece of PII, otherwise, such data fields must be treated carefully to achieve anonymity.In return to any FilterSubscribeRequest
,
-a filter service node SHOULD respond with a FilterSubscribeResponse
with a requestId
matching that of the request.
-This response MUST contain a status_code
indicating if the request was successful or not.
-Successful status codes are in the 2xx
range.
-Client nodes SHOULD consider all other status codes as error codes and assume that the requested operation had failed.
-In addition, the filter service node MAY choose to provide a more detailed status description in the status_desc
field.
In the description of each request type below,
-the term “filter criteria” refers to the combination of pubsub_topic
and a set of content_topics
.
-The request MAY include filter criteria, conditional to the selected filter_subscribe_type
.
-If the request contains filter criteria,
-it MUST contain a pubsub_topic
-and the content_topics
set MUST NOT be empty.
-A WakuMessage
matches filter criteria when its content_topic
is in the content_topics
set
-and it was published on a matching pubsub_topic
.
Initial draft version. Released 2020-10-28
+subscribe
an explicit boolean indication. Edit protobuf field order to be consistent with libp2p.The following filter subscribe types are defined:
-A filter client that sends a FilterSubscribeRequest
with filter_subscribe_type
set to SUBSCRIBER_PING
-requests that the service node SHOULD indicate if it has any active subscriptions for this client.
-The filter client SHOULD exclude any filter criteria from the request.
-The filter service node SHOULD respond with a success code if it has any active subscriptions for this client
-or an error code if not.
-The filter service node SHOULD ignore any filter criteria in the request.
A filter client that sends a FilterSubscribeRequest
with filter_subscribe_type
set to SUBSCRIBE
-requests that the service node SHOULD push messages matching this filter to the client.
-The filter client MUST include the desired filter criteria in the request.
-A client MAY use this request type to modify an existing subscription
+
Initial draft version. Released 2020-10-05
+Copyright and related rights waived via +CC0.
+