docs.waku.org/assets/js/e610d71e.fa8fa915.js

"use strict";(self.webpackChunkwaku_guide=self.webpackChunkwaku_guide||[]).push([[6936],{5349:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>d,contentTitle:()=>c,default:()=>h,frontMatter:()=>r,metadata:()=>o,toc:()=>l});const o=JSON.parse('{"id":"guides/js-waku/debug-waku-dapp","title":"Debug Your Waku DApp and WebSocket","description":"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.","source":"@site/docs/guides/js-waku/debug-waku-dapp.md","sourceDirName":"guides/js-waku","slug":"/guides/js-waku/debug-waku-dapp","permalink":"/guides/js-waku/debug-waku-dapp","draft":false,"unlisted":false,"editUrl":"https://github.com/waku-org/docs.waku.org/tree/develop/docs/guides/js-waku/debug-waku-dapp.md","tags":[],"version":"current","lastUpdatedAt":null,"frontMatter":{"title":"Debug Your Waku DApp and WebSocket","hide_table_of_contents":true},"sidebar":"guides","previous":{"title":"Run @waku/sdk in a NodeJS Application","permalink":"/guides/js-waku/run-waku-nodejs"},"next":{"title":"Manage Your Filter Subscriptions","permalink":"/guides/js-waku/manage-filter"}}');var t=s(74848),i=s(28453);const r={title:"Debug Your Waku DApp and WebSocket",hide_table_of_contents:!0},c=void 0,d={},l=[{value:"Enabling debug logs",id:"enabling-debug-logs",level:2},{value:"NodeJS environments",id:"nodejs-environments",level:3},{value:"Browser environments",id:"browser-environments",level:3},{value:"Checking WebSocket setup",id:"checking-websocket-setup",level:2},{value:"Try Websocat for connection",id:"try-websocat-for-connection",level:3},{value:"Check certificate validity",id:"check-certificate-validity",level:3},{value:"Check WebSocket port accessibility",id:"check-websocket-port-accessibility",level:3}];function a(e){const n={a:"a",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.p,{children:["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 ",(0,t.jsx)(n.a,{href:"/guides/nwaku/run-node",children:"nwaku"}),"."]}),"\n",(0,t.jsx)(n.h2,{id:"enabling-debug-logs",children:"Enabling debug logs"}),"\n",(0,t.jsxs)(n.p,{children:["When resolving issues in your Waku DApp, debug logs can be helpful. The ",(0,t.jsx)(n.code,{children:"@waku/sdk"})," and ",(0,t.jsx)(n.code,{children:"libp2p"})," packages use the debug tool to handle and show logs that help you debug effectively."]}),"\n",(0,t.jsx)(n.h3,{id:"nodejs-environments",children:"NodeJS environments"}),"\n",(0,t.jsxs)(n.p,{children:["To enable debug logs for ",(0,t.jsx)(n.code,{children:"@waku/sdk"})," on NodeJS, you must set the ",(0,t.jsx)(n.code,{children:"DEBUG"})," environment variable. To only enable debug logs for ",(0,t.jsx)(n.code,{children:"@waku/sdk"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"export DEBUG=waku*\n"})}),"\n",(0,t.jsxs)(n.p,{children:["To enable debug logs for both ",(0,t.jsx)(n.code,{children:"@waku/sdk"})," and ",(0,t.jsx)(n.code,{children:"libp2p"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"export DEBUG=waku*,libp2p*\n"})}),"\n",(0,t.jsx)(n.p,{children:"To enable debug logs for all components:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"export DEBUG=*\n"})}),"\n",(0,t.jsx)(n.h3,{id:"browser-environments",children:"Browser environments"}),"\n",(0,t.jsxs)(n.p,{children:["To view debug logs in your browser's console, modify the local storage and add the ",(0,t.jsx)(n.code,{children:"debug"})," key. Here are guides for various modern browsers:"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"https://developer.chrome.com/docs/devtools/storage/localstorage/",children:"Google Chrome"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"https://firefox-source-docs.mozilla.org/devtools-user/storage_inspector/local_storage_session_storage/index.html",children:"Firefox"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage",children:"JavaScript"})}),"\n"]}),"\n",(0,t.jsxs)(n.table,{children:[(0,t.jsx)(n.thead,{children:(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.th,{children:"KEY"}),(0,t.jsx)(n.th,{children:"VALUE"}),(0,t.jsx)(n.th,{children:"DESCRIPTION"})]})}),(0,t.jsxs)(n.tbody,{children:[(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"debug"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"waku*"})}),(0,t.jsxs)(n.td,{children:["Enables ",(0,t.jsx)(n.code,{children:"@waku/sdk"})," debug logs"]})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"debug"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"waku*,libp2p*"})}),(0,t.jsxs)(n.td,{children:["Enables ",(0,t.jsx)(n.code,{children:"@waku/sdk"})," and ",(0,t.jsx)(n.code,{children:"libp2p"})," debug logs"]})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"debug"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"*"})}),(0,t.jsx)(n.td,{children:"Enables all debug logs"})]})]})]}),"\n",(0,t.jsx)(n.h2,{id:"checking-websocket-setup",children:"Checking WebSocket setup"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"/guides/nwaku/run-node",children:"Nwaku"})," provides native support for WebSocket (",(0,t.jsx)(n.code,{children:"ws"}),") and WebSocket Secure (",(0,t.jsx)(n.code,{children:"wss"}),") protocols. These are the only ",(0,t.jsx)(n.a,{href:"/learn/concepts/transports",children:"transports"})," supported for connecting to the Waku Network via browsers."]}),"\n",(0,t.jsx)(n.p,{children:"It's important to note that browsers impose certain limitations on WebSocket usage:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Secure Context Requirement"}),": Insecure subroutines are prohibited in secure contexts. On an ",(0,t.jsx)(n.code,{children:"https://"})," webpage, only ",(0,t.jsx)(n.code,{children:"wss"})," connections are permitted, while ",(0,t.jsx)(n.code,{children:"ws"})," connections are not allowed. This restriction does not apply if the webpage is served locally, like on ",(0,t.jsx)(n.code,{children:"localhost"})," or ",(0,t.jsx)(n.code,{children:"127.0.0.1"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Certificate Validation"}),": Certificate validation rules are consistent for ",(0,t.jsx)(n.code,{children:"https"})," and ",(0,t.jsx)(n.code,{children:"wss"})," connections. Certificates must not be expired, issued by a recognized Certificate Authority (CA), and match the domain name, among other criteria."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"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."]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["If you encounter difficulties when connecting to a remote node using ",(0,t.jsx)(n.code,{children:"wss"}),", follow these steps:"]}),"\n",(0,t.jsx)(n.h3,{id:"try-websocat-for-connection",children:"Try Websocat for connection"}),"\n",(0,t.jsxs)(n.p,{children:["Attempt to connect using ",(0,t.jsx)(n.a,{href:"https://github.com/vi/websocat",children:"websocat"}),", a tool for WebSocket interactions. Test the WebSocket port using the command:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"websocat -v wss://[WEBSOCKET HOST]:[WEBSOCKET PORT]\n"})}),"\n",(0,t.jsxs)(n.p,{children:["For example, consider a ",(0,t.jsx)(n.code,{children:"nwaku"})," node with the multiaddr as ",(0,t.jsx)(n.code,{children:"/dns4/nwakunode.com/tcp/1234/wss/p2p/16..."}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"$ websocat -v wss://nwakunode.com:1234\n# ...\n[INFO  websocat::ws_client_peer] Connected to ws\n"})}),"\n",(0,t.jsxs)(n.p,{children:["The connection works if the ",(0,t.jsx)(n.code,{children:"[INFO  websocat::ws_client_peer] Connected to ws"})," log entry appears. If not, ",(0,t.jsx)(n.a,{href:"#check-certificate-validity",children:"check that the certificate is valid"})]}),"\n",(0,t.jsx)(n.h3,{id:"check-certificate-validity",children:"Check certificate validity"}),"\n",(0,t.jsxs)(n.p,{children:["Verify the certificate's validity by passing the ",(0,t.jsx)(n.code,{children:"-k"})," or ",(0,t.jsx)(n.code,{children:"--insecure"})," flag to handle invalid certificates in ",(0,t.jsx)(n.code,{children:"websocat"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"websocat -v -k wss://nwakunode.com:1234\n"})}),"\n",(0,t.jsxs)(n.p,{children:["If this works, the certificate's invalidity is the problem, and you should investigate the cause of the error if not, ",(0,t.jsx)(n.a,{href:"#check-websocket-port-accessibility",children:"check if the WebSocket port is accessible"}),"."]}),"\n",(0,t.jsx)(n.h3,{id:"check-websocket-port-accessibility",children:"Check WebSocket port accessibility"}),"\n",(0,t.jsxs)(n.p,{children:["Use ",(0,t.jsx)(n.code,{children:"telnet"})," or another networking tool to verify if the WebSocket port is open and accessible. For example, if the multiaddr is ",(0,t.jsx)(n.code,{children:"/dns4/nwakunode.com/tcp/1234/wss/p2p/16..."}),", use the command:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"$ telnet nwakunode.com 1234\nTrying 123.123.123.123...\nConnected to nwakunode.com.\n# ...\n"})}),"\n",(0,t.jsxs)(n.p,{children:["If the connection succeeds, there might be an issue with ",(0,t.jsx)(n.code,{children:"nwaku"}),". Consider seeking support on the ",(0,t.jsx)(n.a,{href:"https://discord.waku.org",children:"Waku Discord"})," or ",(0,t.jsx)(n.a,{href:"https://github.com/waku-org/nwaku/issues/new",children:"raise an issue"}),". If the connection fails, ensure that the WebSocket port is open."]})]})}function h(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(a,{...e})}):a(e)}},28453:(e,n,s)=>{s.d(n,{R:()=>r,x:()=>c});var o=s(96540);const t={},i=o.createContext(t);function r(e){const n=o.useContext(i);return o.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:r(e.components),o.createElement(i.Provider,{value:n},e.children)}}}]);