mirror of
https://github.com/logos-messaging/docs.waku.org.git
synced 2026-01-07 23:33:12 +00:00
add js-waku debug guide (#111)
* add debug guide * add ws notes * add NodeJS recommendations
This commit is contained in:
LordGhostX
GitHub
parent
b4cb1d7456
commit
b2e5396be5
@ -56,6 +56,8 @@
|
||||
"trilemma",
|
||||
"Alvaro",
|
||||
"keyturn",
|
||||
"websocat",
|
||||
"nwakunode",
|
||||
],
|
||||
"flagWords": [],
|
||||
"ignorePaths": [
|
||||
|
||||
@ -5,7 +5,7 @@ title: Bootstrap Nodes and Discover Peers
|
||||
This guide provides detailed steps to bootstrap your your node using [Static Peers](/overview/concepts/static-peers) and discover peers in the Waku Network using [DNS Discovery](/overview/concepts/dns-discovery).
|
||||
|
||||
:::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.
|
||||
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](#configure-dns-discovery-and-static-peers) configuration to connect to both the Waku Network and your node.
|
||||
:::
|
||||
|
||||
## Default Bootstrap Method
|
||||
@ -61,13 +61,13 @@ const node = await createLightNode({
|
||||
});
|
||||
```
|
||||
|
||||
For example, consider a node that connects to two static peers on the same local host (IP: `0.0.0.0`) using TCP ports `60002` and `60003`:
|
||||
For example, consider a node that connects to two static peers on the same local host (IP: `0.0.0.0`) using TCP ports `60002` and `60003` with WebSocket enabled:
|
||||
|
||||
```js
|
||||
// Define the list of static peers to bootstrap
|
||||
const peers = [
|
||||
"/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H",
|
||||
"/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ",
|
||||
"/ip4/0.0.0.0/tcp/60002/ws/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H",
|
||||
"/ip4/0.0.0.0/tcp/60003/ws/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ",
|
||||
];
|
||||
|
||||
// Bootstrap node using the static peers
|
||||
@ -80,6 +80,10 @@ const node = await createLightNode({
|
||||
});
|
||||
```
|
||||
|
||||
:::tip
|
||||
For local development using a `nwaku` node, use a `ws` address instead of `wss`. Remember that this setup is functional only when your web server is running locally.
|
||||
:::
|
||||
|
||||
## Configure DNS Discovery
|
||||
|
||||
To bootstrap a node using [DNS Discovery](/overview/concepts/dns-discovery), first install the `@waku/dns-discovery` package:
|
||||
@ -159,8 +163,8 @@ import { enrTree, wakuDnsDiscovery } from "@waku/dns-discovery";
|
||||
|
||||
// Define the list of static peers to bootstrap
|
||||
const peers = [
|
||||
"/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H",
|
||||
"/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ",
|
||||
"/ip4/0.0.0.0/tcp/60002/ws/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H",
|
||||
"/ip4/0.0.0.0/tcp/60003/ws/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ",
|
||||
];
|
||||
|
||||
// Define node requirements
|
||||
|
||||
99
docs/guides/js-waku/debug-waku-dapp.md
Normal file
99
docs/guides/js-waku/debug-waku-dapp.md
Normal file
@ -0,0 +1,99 @@
|
||||
---
|
||||
title: How to 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).
|
||||
|
||||
## Enabling Debug Logs
|
||||
|
||||
When resolving issues in your Waku DApp, debug logs can be helpful. The `@waku/sdk` and `libp2p` packages use the debug tool to handle and show logs that help you debug effectively.
|
||||
|
||||
### NodeJS Environments
|
||||
|
||||
To enable debug logs for `@waku/sdk` on NodeJS, you must set the `DEBUG` environment variable. To only enable debug logs for `@waku/sdk`:
|
||||
|
||||
```shell
|
||||
export DEBUG=waku*
|
||||
```
|
||||
|
||||
To enable debug logs for both `@waku/sdk` and `libp2p`:
|
||||
|
||||
```shell
|
||||
export DEBUG=waku*,libp2p*
|
||||
```
|
||||
|
||||
To enable debug logs for all components:
|
||||
|
||||
```shell
|
||||
export DEBUG=*
|
||||
```
|
||||
|
||||
### Browser Environments
|
||||
|
||||
To view debug logs in your browser's console, modify the local storage and add the `debug` key. Here are guides for various modern browsers:
|
||||
|
||||
- [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/storage_inspector/local_storage_session_storage/index.html)
|
||||
- [Google Chrome](https://developer.chrome.com/docs/devtools/storage/localstorage/)
|
||||
|
||||
| KEY | VALUE | DESCRIPTION |
|
||||
| - | - | - |
|
||||
| `debug` | `waku*` | Enables `@waku/sdk` debug logs |
|
||||
| `debug` | `waku*,libp2p*` | Enables `@waku/sdk` and `libp2p` debug logs |
|
||||
| `debug` | `*` | Enables all debug logs |
|
||||
|
||||
## Checking WebSocket Setup
|
||||
|
||||
[Nwaku](/guides/run-nwaku-node) provides native support for WebSocket (`ws`) and WebSocket Secure (`wss`) protocols. These are the only [transports](/overview/concepts/transports) supported for connecting to the Waku Network via browsers.
|
||||
|
||||
It's important to note that browsers impose certain limitations on WebSocket usage:
|
||||
|
||||
- **Secure Context Requirement**: Insecure subroutines are prohibited in secure contexts. This means that on an `https://` webpage, only `wss` connections are permitted, while `ws` connections are not allowed.
|
||||
- **Certificate Validation**: Certificate validation rules are consistent for `https` and `wss` connections. Certificates must not be expired, issued by a recognized Certificate Authority (CA), and match the domain name, among other criteria.
|
||||
- **User Feedback on Errors**: Web browsers do not display errors related to subroutines to the user. If a WebSocket connection encounters an issue, users won't be alerted directly; you'll need to check the browser's console for error details.
|
||||
|
||||
:::info
|
||||
The mentioned restrictions are not applicable if the webpage is served locally, like on `localhost` or `127.0.0.1`.
|
||||
:::
|
||||
|
||||
If you encounter difficulties when connecting to a remote node using `wss`, follow these steps:
|
||||
|
||||
### Try Websocat for Connection
|
||||
|
||||
Attempt to connect using [websocat](https://github.com/vi/websocat), a tool for WebSocket interactions. Test the WebSocket port using the command:
|
||||
|
||||
```shell
|
||||
websocat -v wss://[WEBSOCKET HOST]:[WEBSOCKET PORT]
|
||||
```
|
||||
|
||||
For example, consider a `nwaku` node with the multiaddr as `/dns4/nwakunode.com/tcp/1234/wss/p2p/16...`:
|
||||
|
||||
```shell
|
||||
$ websocat -v wss://nwakunode.com:1234
|
||||
# ...
|
||||
[INFO websocat::ws_client_peer] Connected to ws
|
||||
```
|
||||
|
||||
The connection works if the `[INFO websocat::ws_client_peer] Connected to ws` log entry appears. If not, [check that the certificate is valid](#check-certificate-validity)
|
||||
|
||||
### Check Certificate Validity
|
||||
|
||||
Verify the certificate's validity by passing the `-k` or `--insecure` flag to handle invalid certificates in `websocat`:
|
||||
|
||||
```shell
|
||||
websocat -v -k wss://nwakunode.com:1234
|
||||
```
|
||||
|
||||
If this works, the certificate's invalidity is the problem, and you should investigate the cause of the error if not, [check if the WebSocket port is accessible](#check-websocket-port-accessibility).
|
||||
|
||||
### Check WebSocket Port Accessibility
|
||||
|
||||
Use `telnet` or another networking tool to verify if the WebSocket port is open and accessible. For example, if the multiaddr is `/dns4/nwakunode.com/tcp/1234/wss/p2p/16...`, use the command:
|
||||
|
||||
```shell
|
||||
$ telnet nwakunode.com 1234
|
||||
Trying 123.123.123.123...
|
||||
Connected to nwakunode.com.
|
||||
# ...
|
||||
```
|
||||
|
||||
If the connection succeeds, there might be an issue with `nwaku`. Consider seeking support on the [Waku Discord](https://discord.waku.org) or [raise an issue](https://github.com/waku-org/nwaku/issues/new). If the connection fails, ensure that the WebSocket port is open.
|
||||
@ -85,6 +85,12 @@ Have a look at the quick start guide and comprehensive tutorials to learn how to
|
||||
| [Retrieve Messages Using Store Protocol](/guides/js-waku/store-retrieve-messages) | Learn how to retrieve and filter historical messages on light nodes using the [Store protocol](/overview/concepts/protocols#store) |
|
||||
| [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) |
|
||||
|
||||
:::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.
|
||||
:::
|
||||
|
||||
<!-- | [Build React DApps Using @waku/react](/guides/js-waku/use-waku-react) | Learn how to use the [@waku/react](https://www.npmjs.com/package/@waku/react) package seamlessly integrate `@waku/sdk` into a React application | -->
|
||||
|
||||
|
||||
35
docs/guides/js-waku/run-waku-nodejs.md
Normal file
35
docs/guides/js-waku/run-waku-nodejs.md
Normal file
@ -0,0 +1,35 @@
|
||||
---
|
||||
title: "Run @waku/sdk in a NodeJS Application"
|
||||
---
|
||||
|
||||
While the `@waku/sdk` package is primarily designed for browser environments, you can use it in a NodeJS application. However, there are certain limitations and considerations to keep in mind. This guide provides a comprehensive overview of using `@waku/sdk` in NodeJS.
|
||||
|
||||
## Limitations
|
||||
|
||||
### API Compatibility
|
||||
|
||||
`@waku/sdk` prioritises browser compatibility, avoiding NodeJS APIs for simpler bundling. This design choice enhances browser API compatibility but sacrifices NodeJS optimisation. While many browser APIs work in NodeJS, they might need better optimisation.
|
||||
|
||||
### Protocol Implementation
|
||||
|
||||
`@waku/sdk` focuses on the client side of the [Request/Response protocol](/overview/concepts/network-domains#requestresponse-domain). We'll have to replicate all the functionalities added to [nwaku](/guides/run-nwaku-node) to implement extra features.
|
||||
|
||||
### Codebase Complexity
|
||||
|
||||
Balancing browser and NodeJS compatibility while maintaining simplicity adds complexity. A potential fix is making a NodeJS package that wraps `@waku/sdk` for smoother NodeJS development.
|
||||
|
||||
### Browser-Specific Logic
|
||||
|
||||
Certain features in `@waku/sdk` are tailored for browsers and might not translate seamlessly to NodeJS. For example, [Relay protocol](/overview/concepts/protocols#relay) in browsers requires unique [transport methods](/overview/concepts/transports) such as `WebTransport` or `WebRTC`, which might not align with NodeJS networking capabilities.
|
||||
|
||||
### Peer Management
|
||||
|
||||
`@waku/sdk` default peer management caters to the browser's ephemeral nature, which is different for NodeJS. This is why [DNS Discovery](/overview/concepts/dns-discovery) and [Peer Exchange](/overview/concepts/peer-exchange) are the default discovery mechanisms for the browser but not for NodeJS and desktop applications.
|
||||
|
||||
## Recommendations
|
||||
|
||||
Considering these limitations, consider your use case before opting for `@waku/sdk` in NodeJS. For a more optimised solution, we recommend [running nwaku in a Docker container](/guides/nwaku/run-docker) and consuming its [JSON RPC API](https://rfc.vac.dev/spec/16/).
|
||||
|
||||
## Future Developments
|
||||
|
||||
There are plans to release a NodeJS package based on [nwaku](/guides/run-nwaku-node) to streamline the process of using Waku Network features in NodeJS applications. You can track the progress and updates here: <https://github.com/waku-org/nwaku/issues/1332>.
|
||||
@ -66,7 +66,9 @@ Here are the available node configuration options, along with their default valu
|
||||
| `rln-relay-bandwidth-threshold` | `0 # to maintain backwards compatibility` | Message rate in bytes/sec after which verification of proofs should happen |
|
||||
| `staticnode` | | Peer multiaddr to directly connect with. Argument may be repeated |
|
||||
| `keep-alive` | `false` | Enable keep-alive for idle connections: true\|false |
|
||||
| `topic` | `["/waku/2/default-waku/proto"]` | Default topic to subscribe to. Argument may be repeated |
|
||||
| `topic` | `["/waku/2/default-waku/proto"]` | Default topic to subscribe to. Argument may be repeated. Deprecated! Please use `pubsub-topic` and/or `content-topic` instead |
|
||||
| `pubsub-topic` | | Default pubsub topic to subscribe to. Argument may be repeated |
|
||||
| `content-topic` | | Default content topic to subscribe to. Argument may be repeated |
|
||||
|
||||
## Store and Message Store Config
|
||||
|
||||
|
||||
@ -75,9 +75,11 @@ const sidebars = {
|
||||
"guides/js-waku/store-retrieve-messages",
|
||||
"guides/js-waku/use-waku-create-app",
|
||||
"guides/js-waku/configure-discovery",
|
||||
"guides/js-waku/run-waku-nodejs",
|
||||
"guides/js-waku/debug-waku-dapp",
|
||||
{
|
||||
type: 'html',
|
||||
value: '<a href="https://examples.waku.org" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Examples<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M11.1918 4H3.42848V2.85715H13.1428V12.5714H11.9999V4.80813L3.83254 12.9755L3.02441 12.1674L11.1918 4Z" fill="white"/></svg>',
|
||||
value: '<a href="https://examples.waku.org" target="_blank" rel="noopener noreferrer" class="menu__link external-link">@waku/sdk Examples<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M11.1918 4H3.42848V2.85715H13.1428V12.5714H11.9999V4.80813L3.83254 12.9755L3.02441 12.1674L11.1918 4Z" fill="white"/></svg>',
|
||||
},
|
||||
{
|
||||
type: 'html',
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user