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-beta1Protocol 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,168 +324,71 @@
syntax = "proto3";
-
-// 12/WAKU2-FILTER rfc: https://rfc.vac.dev/spec/12/
-package waku.filter.v2;
+message FilterRequest {
+ bool subscribe = 1;
+ string topic = 2;
+ repeated ContentFilter contentFilters = 3;
-// 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
- #
-
-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.
-
- Filter matching
- #
-
-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.
-
- Filter Subscribe Types
- #
-
-The following filter subscribe types are defined:
-
- SUBSCRIBER_PING
- #
-
-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.
-
- SUBSCRIBE
- #
+
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
-by providing additional filter criteria in a new request.
-A client MAY use this request type to refresh an existing subscription
-by providing the same filter criteria in a new request.
-The filter service node SHOULD respond with a success code if it successfully honored this request
-or an error code if not.
-The filter service node SHOULD respond with an error code and discard the request
-if the subscribe request does not contain valid filter criteria,
-i.e. both a pubsub_topic and a non-empty content_topics set.
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 filter client that sends a FilterSubscribeRequest with filter_subscribe_type set to UNSUBSCRIBE
-requests that the service node SHOULD stop pushing messages matching this filter to the client.
-The filter client MUST include the filter criteria it desires to unsubscribe from in the request.
-A client MAY use this request type to modify an existing subscription
-by providing a subset of the original filter criteria to unsubscribe from in a new request.
-The filter service node SHOULD respond with a success code if it successfully honored this request
-or an error code if not.
-The filter service node SHOULD respond with an error code and discard the request
-if the unsubscribe request does not contain valid filter criteria,
-i.e. both a pubsub_topic and a non-empty content_topics set.
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 client that sends a FilterSubscribeRequest with filter_subscribe_type set to UNSUBSCRIBE_ALL
-requests that the service node SHOULD stop pushing messages matching any filter to the client.
-The filter client SHOULD exclude any filter criteria from the request.
-The filter service node SHOULD remove any existing subscriptions for this client.
-It SHOULD respond with a success code if it successfully honored this request
-or an error code if not.
A filter client node MUST support the filter-push protocol -to allow filter service nodes to push messages matching registered subscriptions to this client.
-A filter service node SHOULD push all messages
-matching the filter criteria in a registered subscription
-to the subscribed filter client.
-These WakuMessages are likely to come from 11/WAKU2-RELAY,
-but there MAY be other sources or protocols where this comes from.
-This is up to the consumer of the protocol.
If a message push fails,
-the filter service node MAY consider the client node to be unreachable.
-If a specific filter client node is not reachable from the service node for a period of time,
-the filter service node MAY choose to stop pushing messages to the client and remove its subscription.
-This period is up to the service node implementation.
-We consider 1 minute to be a reasonable default.
Each message MUST be pushed in a MessagePush message.
-Each MessagePush MUST contain one (and only one) waku_message.
-If this message was received on a specific pubsub_topic,
-it SHOULD be included in the MessagePush.
-A filter client SHOULD NOT respond to a MessagePush.
-Since the filter protocol does not include caching or fault-tolerance,
-this is a best effort push service with no bundling
-or guaranteed retransmission of messages.
-A filter client SHOULD verify that each MessagePush it receives
-originated from a service node where the client has an active subscription
-and that it matches filter criteria belonging to that subscription.
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.