From d95ea334755d4cde2b58f9c63914d061e2393782 Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie <76216657+AtibQur@users.noreply.github.com> Date: Mon, 23 Dec 2024 15:24:17 +0100 Subject: [PATCH] Added netmap and state update requirements (#193) --- .../src/content/docs/11-guides/Networking.md | 27 ++++- .../12-reference/00-CheerpX-Linux-create.md | 102 ++++++++++++++++++ 2 files changed, 126 insertions(+), 3 deletions(-) diff --git a/sites/cheerpx/src/content/docs/11-guides/Networking.md b/sites/cheerpx/src/content/docs/11-guides/Networking.md index 5ebda2cb..c1c6613a 100644 --- a/sites/cheerpx/src/content/docs/11-guides/Networking.md +++ b/sites/cheerpx/src/content/docs/11-guides/Networking.md @@ -76,6 +76,12 @@ const cx = await CheerpX.Linux.create({ networkInterface: { authKey: "AuthKeyStringGoesHere", controlUrl: "https://my.url.com/", + stateUpdateCb: (state) => { + console.log("Network state changed to:", state); + }, + netmapUpdateCb: (map) => { + console.log("Network mapping updated:", map); + }, }, }); ``` @@ -85,8 +91,10 @@ const cx = await CheerpX.Linux.create({ What is happening here? -- `controlUrl` is a string URL of the Tailscale control plane which verifies the user's identity. You only need to pass this option if you are [self-hosting Tailscale](/docs/guides/Networking#self-hosting-headscale). -- `authKey` is string with an auth key to register new users/devices that are pre-authenticated. You can create an auth key [here](https://login.tailscale.com/admin/settings/keys). +- [authKey]: A string containing an authentication key for registering pre-authenticated users or devices. You can generate one [here](https://login.tailscale.com/admin/settings/keys). +- [controlUrl]: The URL of the control plane, which coordinates network access and identity verification. When [self-hosting Tailscale](/docs/guides/Networking#self-hosting-headscale), you need to provide the control plane URL of your Headscale server. By default, the main Tailscale control plane is used. +- [stateUpdateCb]: A required callback function that monitors and reports changes in network status. +- [netmapUpdateCb]: A required callback function that provides updates on the network map, enabling access to the list of devices for the network. Example to prompt the user for manual login on a different tab: @@ -105,14 +113,27 @@ const cx = await CheerpX.Linux.create({ loginElem.target = "_blank"; // continue with login }, + stateUpdateCb: (state) => { + console.log("Network state changed:", state); + }, + netmapUpdateCb: (map) => { + console.log("Received network map:", map); + }, }, }); ``` What is happening here? -- `loginUrlCb` expects the base URL of a control server that will continue and finish the login process. This callback is executed when it is time to prompt the user to log in to Tailscale via the UI. +- [loginUrlCb] expects the base URL of a control server that will continue and finish the login process. This callback is executed when prompting the user to log in interactively with Tailscale. +- [stateUpdateCb] and [netmapUpdateCb] are necessary for tracking network status and updates to network maps. ## Self-hosting Headscale Headscale is an open-source and self-hosted implementation of the Tailscale control server. The upstream version of Headscale does not yet properly support the WebSocket transport. For the time being, please use [our fork](https://github.com/leaningtech/headscale). + +[controlUrl]: /docs/reference/CheerpX-Linux-create#controlurl +[authKey]: /docs/reference/CheerpX-Linux-create#authkey +[stateUpdateCb]: /docs/reference/CheerpX-Linux-create#stateupdatecb +[netmapUpdateCb]: /docs/reference/CheerpX-Linux-create#netmapupdatecb +[loginUrlCb]: /docs/reference/CheerpX-Linux-create#loginurlcb diff --git a/sites/cheerpx/src/content/docs/12-reference/00-CheerpX-Linux-create.md b/sites/cheerpx/src/content/docs/12-reference/00-CheerpX-Linux-create.md index 49f192a9..21330688 100644 --- a/sites/cheerpx/src/content/docs/12-reference/00-CheerpX-Linux-create.md +++ b/sites/cheerpx/src/content/docs/12-reference/00-CheerpX-Linux-create.md @@ -78,4 +78,106 @@ networkInterface?: NetworkInterface; This option configures network settings, which allows CheerpX to communicate over networks. For more detailed information about how CheerpX handles networking, including the use of Tailscale and overcoming browser limitations, see the [Networking](/docs/guides/Networking) guide. +### `authKey` + +```ts +authKey?: string; +``` + +The `authKey` is a string containing an authentication key for registering pre-authenticated users or devices. You can generate one [here](https://login.tailscale.com/admin/settings/keys). + +Example: + +```js +const cx = await CheerpX.Linux.create({ + mounts: mountPoints, + networkInterface: { authKey: "YOUR KEY" }, +}); +``` + +### `controlUrl` + +```ts +controlUrl?: string; +``` + +The `controlUrl` is an optional string used to specify the URL of a [self-hosted Headscale server](/docs/guides/Networking#self-hosting-headscale). + +Example: + +```js +const cx = await CheerpX.Linux.create({ + mounts: mountPoints, + networkInterface: { controlUrl: "YOUR URL" }, +}); +``` + +### `loginUrlCb` + +```ts +loginUrlCb?: (url: string) => void; +``` + +The `loginUrlCb` is a callback function that handles login URLs during the authentication process. It receives the URL that should be visited to continue the login process. This is necessary when authenticating with Tailscale. + +Example: + +```js +const cx = await CheerpX.Linux.create({ + mounts: mountPoints, + networkInterface: { loginUrlCb }, +}); + +function loginUrlCb(url) { + console.log("Login URL is ready:", url); + // Open the login URL in a new tab or window + window.open(url, "_blank"); +} +``` + +### stateUpdateCb + +```ts +stateUpdateCb?: (state: number) => void; +``` + +The `stateUpdateCb` is a callback that runs when the connection state changes. The `state` parameter represents the connection status. + +Example: + +```js +const cx = await CheerpX.Linux.create({ + mounts: mountPoints, + networkInterface: { stateUpdateCb }, +}); + +function stateUpdateCb(state) { + if (state === 6) { + console.log("Connected"); + } +} +``` + +### netmapUpdateCb + +```ts +netmapUpdateCb?: (map: any) => void; +``` + +The `netmapUpdateCb` is a callback that runs whenever the network configuration updates. It provides details about the current network configuration. + +Example: + +```ts +const cx = await CheerpX.Linux.create({ + mounts: mountPoints, + networkInterface: { netmapUpdateCb }, +}); + +function netmapUpdateCb(map) { + const currentIp = map.self.addresses[0]; + console.log(`Current IP: ${currentIp}`); +} +``` + [Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise