From a060043bfbfb5af1c8eddcbd97d07b83e1c505ab Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Sat, 11 Nov 2023 08:52:24 +0100 Subject: [PATCH] add guide content --- .cspell.json | 1 + diagrams/_filter-ping-flow.md | 12 +++++ docs/guides/js-waku/debug-waku-dapp.md | 2 +- docs/guides/js-waku/index.md | 4 +- docs/guides/js-waku/light-send-receive.md | 2 +- docs/guides/js-waku/manage-filter.md | 55 ++++++++++++++++++++++- 6 files changed, 70 insertions(+), 6 deletions(-) create mode 100644 diagrams/_filter-ping-flow.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 ea0fc57..71ccece 100644 --- a/docs/guides/js-waku/index.md +++ b/docs/guides/js-waku/index.md @@ -87,8 +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) | -| [Manage Your Filter Subscription](/guides/js-waku/manage-filter) | Learn how to manage [filter subscriptions](/overview/concepts/protocols#filter) and handle node disconnections in your application | +| [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 index 211fede..7beb119 100644 --- a/docs/guides/js-waku/manage-filter.md +++ b/docs/guides/js-waku/manage-filter.md @@ -1,5 +1,56 @@ --- -title: Manage Your Filter Subscription +title: Manage Your Filter Subscriptions --- -This guide provides detailed steps to manage [filter subscriptions](/overview/concepts/protocols#filter) 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 `Filter protocol`. \ No newline at end of file +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