From 31857c7434fa17efc00e3cd648d90448797d107b Mon Sep 17 00:00:00 2001 From: Dean Eigenmann <7621705+decanus@users.noreply.github.com> Date: Sat, 10 Oct 2020 12:26:52 +0200 Subject: [PATCH] fix/update-filter-spec (#203) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update waku-filter.md * Update waku-filter.md * Update waku-filter.md * Update waku-filter.md * Update waku-v2.md * Update waku-filter.md * Update waku-filter.md * Update waku-filter.md * Update waku-filter.md * Update specs/waku/v2/waku-filter.md Co-authored-by: Oskar Thorén * Update waku-filter.md * Update waku-filter.md * Update wordlist.txt * Update waku-filter.md * Update waku-filter.md Co-authored-by: Oskar Thorén --- specs/waku/v2/waku-filter.md | 66 +++++++++++++++++------------------- specs/waku/v2/waku-v2.md | 4 +-- wordlist.txt | 1 + 3 files changed, 34 insertions(+), 37 deletions(-) diff --git a/specs/waku/v2/waku-filter.md b/specs/waku/v2/waku-filter.md index 5e6b14d33..0c11a17ec 100644 --- a/specs/waku/v2/waku-filter.md +++ b/specs/waku/v2/waku-filter.md @@ -1,28 +1,34 @@ --- title: Waku -version: 2.0.0-alpha5 -status: Raw -authors: Oskar Thorén +version: 2.0.0-beta1 +status: Draft +authors: Oskar Thorén , Dean Eigenmann --- # Table of Contents -TODO +- [Abstract](#abstract) +- [Content filtering](#content-filtering) + * [Rationale](#rationale) + * [Protobuf](#protobuf) +- [Changelog](#changelog) +- [Copyright](#copyright) +- [References](#references) # Abstract -Filter spec. +`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 +# Content filtering -**Protocol identifier***: `/vac/waku/filter/2.0.0-alpha6` +**Protocol identifier***: `/vac/waku/filter/2.0.0-beta1` 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. -#### Rationale +## Rationale Unlike the `store` protocol for historical messages, this protocol allows for native lower latency scenarios such as instant messaging. It is thus @@ -38,28 +44,15 @@ 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 ```protobuf message FilterRequest { - // space for optional request id - repeated ContentFilter contentFilters = 2; - optional string topic = 3; + string topic = 1; + ContentFilter contentFilters = 2; message ContentFilter { - optional string contentTopics = 1; + string contentTopics = 1; } } @@ -68,25 +61,23 @@ message MessagePush { } message FilterRPC { - string request_id = 1; + string requestId = 1; FilterRequest request = 2; MessagePush push = 3; } ``` -##### FilterRPC +#### FilterRPC 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 `request_id` MUST be a uniquely generated string. - -##### FilterRequest - -TODO Specify mechanism for telling it won't honor (normal-no service-spam case) +The `requestId` MUST be a uniquely generated string. When a `MessagePush` is sent +the `requestId` MUST match the `requestId` of the `FilterRequest` whose filters +matched the message causing it to be pushed. -TODO Clarify exactly what we mean by connection and TTL +#### FilterRequest 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. @@ -103,10 +94,10 @@ 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 +#### 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 +match this filter to a light node. These [`WakuMessage`'s](./waku-message.md) 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. @@ -120,6 +111,11 @@ implementation, though a reasonable default is one minute. --- +# Changelog + +2.0.0-beta1 +Initial draft version. Released 2020-10-05 + # Copyright Copyright and related rights waived via diff --git a/specs/waku/v2/waku-v2.md b/specs/waku/v2/waku-v2.md index 16e1cf389..64876bc1d 100644 --- a/specs/waku/v2/waku-v2.md +++ b/specs/waku/v2/waku-v2.md @@ -101,9 +101,9 @@ offline. See [WakuStore](waku-store.md) spec for more details. -### Content filtering (experimental, alpha) +### Content filtering -**Protocol identifier***: `/vac/waku/filter/2.0.0-alpha5` +**Protocol identifier***: `/vac/waku/filter/2.0.0-beta1` See [WakuFilter](waku-filter.md) spec for more details. diff --git a/wordlist.txt b/wordlist.txt index 7a55a47dd..a4ee861e9 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -126,6 +126,7 @@ RemoteLog req Req requestID +requestId retransmission retransmissions retransmit