@needle-tools/engine/src/engine-components/Networking.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import type { INetworkingWebsocketUrlProvider } from "../engine/engine_networking.js";
import { isLocalNetwork } from "../engine/engine_networking_utils.js";
import { serializable } from "../engine/engine_serialization.js";
import { getParam } from "../engine/engine_utils.js";
import { Behaviour } from "./Component.js";

const debug = getParam("debugnet");

/**
 * Provides configuration to the built-in networking system.
 * This component supplies websocket URLs for establishing connections.
 * It implements the {@link INetworkingWebsocketUrlProvider} interface.
 * 
 * @category Networking
 * @group Components
 */
export class Networking extends Behaviour implements INetworkingWebsocketUrlProvider {

    /** 
     * The websocket URL to connect to for networking functionality.
     * Can be a complete URL or a relative path that will be resolved against the current origin.
     */
    @serializable()
    url: string | null = null;

    /** 
     * Name of the URL parameter that can override the websocket connection URL.
     * When set, the URL will be overridden by the parameter value from the browser URL.
     * For example, with `urlParameterName="ws"`, adding `?ws=ws://localhost:8080` to the browser URL will override the connection URL.
     */
    @serializable()
    urlParameterName: string | null = null;

    /** 
     * Alternative URL to use when running on a local network.
     * This is particularly useful for development, when the server is running on the same machine as the client.
     */
    @serializable()
    localhost: string | null = null;

    /** @internal */
    awake() {
        if (debug)
            console.log(this);
        this.context.connection.registerProvider(this);
    }

    /** 
     * Determines the websocket URL to use for networking connections.
     * Processes the configured URL, applying localhost fallbacks when appropriate and
     * handling URL parameter overrides if specified.
     * @returns The formatted websocket URL string or null if no valid URL could be determined
     * @internal
     */
    getWebsocketUrl(): string | null {

        let socketurl = this.url ? Networking.GetUrl(this.url, this.localhost) : null;

        if (this.urlParameterName) {
            const res = getParam(this.urlParameterName);
            if (res && typeof res === "string") {
                socketurl = res;
            }
        }

        if (!socketurl) return null;

        // regex https://regex101.com/r/JQ5WqB/1
        const regex = new RegExp("(((https?)|(?<socket_prefix>wss?)):\/\/)?(www\.)?(?<url>.+)", "gm");
        const match = regex.exec(socketurl);
        if (!match?.groups) return null;
        // if the url has a ws or wss prefix already assume the whole url is in the correct format
        const socketPrefix = match?.groups["socket_prefix"];
        if (socketPrefix) return socketurl;
        // otherwise add the ws prefix
        return "wss://" + match?.groups["url"];
    }

    /**
     * Processes a URL string applying various transformations based on network environment.
     * Handles relative paths and localhost fallbacks for local network environments.
     * @param url The original URL to process
     * @param localhostFallback Alternative URL to use when on a local network
     * @returns The processed URL string or null/undefined if input was invalid
     */
    public static GetUrl(url: string | null | undefined, localhostFallback?: string | null): string | null | undefined {

        let result = url;

        const useLocalHostUrl = Networking.IsLocalNetwork() && localhostFallback;
        if (useLocalHostUrl) {
            result = localhostFallback;
        }

        if (url?.startsWith("/")) {
            const base = useLocalHostUrl ? result : window.location.origin;
            if(base?.endsWith("/") && url.startsWith("/"))
                url = url.substring(1);
            result = base + url;
        }

        return result;
    }

    /**
     * Determines if the current connection is on a local network.
     * Useful for applying different networking configurations in local development environments.
     * This is the same as calling {@link isLocalNetwork}.
     * @param hostname Optional hostname to check instead of the current window location
     * @returns True if the connection is on a local network, false otherwise
     */
    public static IsLocalNetwork(hostname = window.location.hostname) {
        return isLocalNetwork(hostname);
    }
}