From de38b6fc6ee0edf069f47c19d7d05b1c021459ca Mon Sep 17 00:00:00 2001 From: status-im-auto Date: Tue, 26 Sep 2023 08:54:04 +0000 Subject: [PATCH] Update documentation --- spec/12/index.html | 257 +++++++++++++++++++++++++++++++++------------ 1 file changed, 190 insertions(+), 67 deletions(-) diff --git a/spec/12/index.html b/spec/12/index.html index ae526d874..145cb71ac 100644 --- a/spec/12/index.html +++ b/spec/12/index.html @@ -5,13 +5,15 @@ - + - + @@ -192,9 +194,18 @@

  • Adversarial Model @@ -267,12 +278,18 @@

    • -

    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.

    +

    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.

    Content filtering #

    -

    Protocol identifier*: /vac/waku/filter/2.0.0-beta1

    +

    Protocol identifiers:

    +

    Content filtering is a way to do message-based filtering. Currently the only content filter being applied is on contentTopic. This @@ -321,71 +338,168 @@

    Protobuf #

    -
    message FilterRequest {
-  bool subscribe = 1;
-  string topic = 2;
-  repeated ContentFilter contentFilters = 3;
+
    syntax = "proto3";
+
+// 12/WAKU2-FILTER rfc: https://rfc.vac.dev/spec/12/
+package waku.filter.v2;
 
-  message ContentFilter {
-    string contentTopic = 1;
+// Protocol identifier: /vac/waku/filter-subscribe/2.0.0-beta1
+message FilterSubscribeRequest {
+  enum FilterSubscribeType {
+    SUBSCRIBER_PING = 0;
+    SUBSCRIBE = 1;
+    UNSUBSCRIBE = 2;
+    UNSUBSCRIBE_ALL = 3;
   }
+
+  string request_id = 1;
+  FilterSubscribeType filter_subscribe_type = 2;
+
+  // Filter criteria
+  optional string pubsub_topic = 10;
+  repeated string content_topics = 11;
 }
 
-message MessagePush {
-  repeated WakuMessage messages = 1;
+message FilterSubscribeResponse {
+  string request_id = 1;
+  uint32 status_code = 10;
+  optional string status_desc = 11;
 }
 
-message FilterRPC {
-  string requestId = 1;
-  FilterRequest request = 2;
-  MessagePush push = 3;
+// Protocol identifier: /vac/waku/filter-push/2.0.0-beta1
+message MessagePush {
+  WakuMessage waku_message = 1;
+  optional string pubsub_topic = 2;
 }
-
    
-  FilterRPC
-  #
+

    + 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 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.

    -

    - FilterRequest - # +

    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.

    +

    + UNSUBSCRIBE + #

    -

    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.

    -

    - MessagePush - # +

    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.

    +

    + UNSUBSCRIBE_ALL + #

    -

    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.

    +

    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.

    +

    + Filter-Push + # +

    +

    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.

    +

    + Message Push + # +

    +

    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.

    Future Work @@ -490,9 +604,18 @@

  • Adversarial Model