From 9cb83847795b09b9353843a6455ce0c46bdbc4cc Mon Sep 17 00:00:00 2001 From: LordGhostX <47832826+LordGhostX@users.noreply.github.com> Date: Tue, 21 Nov 2023 14:19:52 +0100 Subject: [PATCH] add manage filter guide (#132) --- .cspell.json | 1 + diagrams/_filter-ping-flow.md | 12 +++++ docs/guides/js-waku/debug-waku-dapp.md | 2 +- docs/guides/js-waku/index.md | 3 +- docs/guides/js-waku/light-send-receive.md | 2 +- docs/guides/js-waku/manage-filter.md | 56 +++++++++++++++++++++++ docs/guides/nwaku/configure-nwaku.md | 2 +- sidebars.js | 1 + 8 files changed, 75 insertions(+), 4 deletions(-) create mode 100644 diagrams/_filter-ping-flow.md create mode 100644 docs/guides/js-waku/manage-filter.md diff --git a/.cspell.json b/.cspell.json index 71729c1..1d07c8c 100644 --- a/.cspell.json +++ b/.cspell.json @@ -71,6 +71,7 @@ "letsencrypt", "lightpushnode", "filternode", + "instanceof", ], "flagWords": [], "ignorePaths": [ diff --git a/diagrams/_filter-ping-flow.md b/diagrams/_filter-ping-flow.md new file mode 100644 index 0000000..7dd9ea7 --- /dev/null +++ b/diagrams/_filter-ping-flow.md @@ -0,0 +1,12 @@ +```mermaid +graph TD + A[Start Monitoring Filter Subscriptions] --> B{Check Peer Connection} + B -- Connected --> C[Send Ping] + C --> D{Ping Success?} + D -- Yes --> B + D -- No --> E[Handle Error/Reinitiate Subscription] + B -- Disconnected --> F[Check Intentional Disconnection/Unsubscription] + F -- Yes --> G[Stop Monitoring] + F -- No --> B + E --> B +``` \ No newline at end of file diff --git a/docs/guides/js-waku/debug-waku-dapp.md b/docs/guides/js-waku/debug-waku-dapp.md index eb982e8..81ba5de 100644 --- a/docs/guides/js-waku/debug-waku-dapp.md +++ b/docs/guides/js-waku/debug-waku-dapp.md @@ -1,5 +1,5 @@ --- -title: How to Debug Your Waku DApp and WebSocket +title: Debug Your Waku DApp and WebSocket --- This guide provides detailed steps to enable and use debug logs to troubleshoot your Waku DApp, whether in a NodeJS or browser environment and check your WebSocket connections in [nwaku](/guides/run-nwaku-node). diff --git a/docs/guides/js-waku/index.md b/docs/guides/js-waku/index.md index 4a4d652..71ccece 100644 --- a/docs/guides/js-waku/index.md +++ b/docs/guides/js-waku/index.md @@ -87,7 +87,8 @@ Have a look at the quick start guide and comprehensive tutorials to learn how to | [Bootstrap DApps Using @waku/create-app](/guides/js-waku/use-waku-create-app) | Learn how to use the [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) package to bootstrap your next `@waku/sdk` project from various example templates | | [Bootstrap Nodes and Discover Peers](/guides/js-waku/configure-discovery) | Learn how to bootstrap your node using [Static Peers](/overview/concepts/static-peers) and discover peers using [DNS Discovery](/overview/concepts/dns-discovery) | | [Run @waku/sdk in a NodeJS Application](/guides/js-waku/run-waku-nodejs) | Learn our suggested approach for using the `@waku/sdk` package within a NodeJS application | -| [How to Debug Your Waku DApp and WebSocket](/guides/js-waku/debug-waku-dapp) | Learn how to troubleshoot your Waku DApp using debug logs and check [WebSocket](/overview/concepts/transports) connections in [nwaku](/guides/run-nwaku-node) | +| [Debug Your Waku DApp and WebSocket](/guides/js-waku/debug-waku-dapp) | Learn how to troubleshoot your Waku DApp using debug logs and check [WebSocket](/overview/concepts/transports) connections in [nwaku](/guides/run-nwaku-node) | +| [Manage Your Filter Subscriptions](/guides/js-waku/manage-filter) | Learn how to manage [filter subscriptions](/overview/concepts/protocols#filter) and handle node disconnections in your application | :::tip Until [node incentivisation](/overview/reference/research-in-progress#prevention-of-denial-of-service-dos-and-node-incentivisation) is in place, you should [operate extra nodes](/guides/nodes-and-sdks#run-a-waku-node) alongside the ones provided by the Waku Network. When running a node, we recommend using the [DNS Discovery and Static Peers](/guides/js-waku/configure-discovery#configure-dns-discovery-and-static-peers) configuration to connect to both the Waku Network and your node. diff --git a/docs/guides/js-waku/light-send-receive.md b/docs/guides/js-waku/light-send-receive.md index 002f0ca..ce94d96 100644 --- a/docs/guides/js-waku/light-send-receive.md +++ b/docs/guides/js-waku/light-send-receive.md @@ -2,7 +2,7 @@ title: Send and Receive Messages Using Light Push and Filter --- -This guide provides detailed steps to start using the `@waku/sdk` package by setting up a Light Node to send messages using the [Light Push protocol](/overview/concepts/protocols#light-push), and receive messages using the [Filter protocol](/overview/concepts/protocols#filter). Have a look at the [installation guide](/guides/js-waku/#installation) for steps on adding `@waku/sdk` to your project. +This guide provides detailed steps to start using the `@waku/sdk` package by setting up a [Light Node](/overview/reference/glossary#light-node) to send messages using the [Light Push protocol](/overview/concepts/protocols#light-push), and receive messages using the [Filter protocol](/overview/concepts/protocols#filter). Have a look at the [installation guide](/guides/js-waku/#installation) for steps on adding `@waku/sdk` to your project. ## Create a Light Node diff --git a/docs/guides/js-waku/manage-filter.md b/docs/guides/js-waku/manage-filter.md new file mode 100644 index 0000000..7beb119 --- /dev/null +++ b/docs/guides/js-waku/manage-filter.md @@ -0,0 +1,56 @@ +--- +title: Manage Your Filter Subscriptions +--- + +This guide provides detailed steps to manage [Filter](/overview/concepts/protocols#filter) subscriptions and handle node disconnections in your application. Have a look at the [Filter guide](/guides/js-waku/light-send-receive) for receiving messages with the `Light Push and Filter protocol`. + +## Overview + +Occasionally, your `Filter` subscriptions might disconnect from the Waku Network, resulting in messages not being received by your application. To manage your subscriptions, periodically ping peers to check for an active connection. The error message `"peer has no subscriptions"` indicates a failed ping due to disconnection. You can stop the pings if the disconnection/unsubscription is deliberate. + +```mdx-code-block +import FilterPingFlow from "@site/diagrams/_filter-ping-flow.md"; + + +``` + +## Pinging Filter Subscriptions + +The `@waku/sdk` package provides a `Filter.ping()` function to ping subscriptions and check for an active connection. To begin, create a `Filter` subscription: + +```js +// Create a Filter subscription +const subscription = await node.filter.createSubscription(); + +// Subscribe to content topics and process new messages +await subscription.subscribe([decoder], callback); +``` + +Next, create a function to ping and reinitiate the subscription: + +```js +const pingAndReinitiateSubscription = async () => { + try { + // Ping the subscription + await subscription.ping(); + } catch (error) { + if ( + // Check if the error message includes "peer has no subscriptions" + error instanceof Error && + error.message.includes("peer has no subscriptions") + ) { + // Reinitiate the subscription if the ping fails + await subscription.subscribe([decoder], callback); + } else { + throw error; + } + } +}; + +// Periodically ping the subscription +await pingAndReinitiateSubscription(); +``` + +:::success Congratulations! +You have successfully managed your `Filter` subscriptions to handle node disconnections in your application. +::: \ No newline at end of file diff --git a/docs/guides/nwaku/configure-nwaku.md b/docs/guides/nwaku/configure-nwaku.md index 1a5635d..30aae3b 100644 --- a/docs/guides/nwaku/configure-nwaku.md +++ b/docs/guides/nwaku/configure-nwaku.md @@ -242,7 +242,7 @@ For example, consider a `nwaku` node that requests lightpush of published messag ./build/wakunode2 --lightpushnode=/dns4/node-01.ac-cn-hongkong-c.wakuv2.prod.statusim.net/tcp/30303/p2p/16Uiu2HAm4v86W3bmT1BiH6oSPzcsSr24iDQpSN5Qa992BCjjwgrD ``` -## Run a Node Behind a Reverse Proxy +## Run Nwaku Behind a Reverse Proxy When using a reverse proxy server for SSL/TLS encryption, you only want to announce the proxy server's IP or domain. Nwaku provides the `ext-multiaddr-only` and `ext-multiaddr` options for specifying published multiaddr: diff --git a/sidebars.js b/sidebars.js index c806cbe..118fea1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -78,6 +78,7 @@ const sidebars = { "guides/js-waku/configure-discovery", "guides/js-waku/run-waku-nodejs", "guides/js-waku/debug-waku-dapp", + "guides/js-waku/manage-filter", { type: 'html', value: '@waku/sdk Examples',