/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { AppAddress, asError, HttpEndpoint, HttpEndpointFactory, Logger, NetworkError } from "@matter/general"; import { existsSync, ReadStream, rmSync, statSync } from "node:fs"; import type { Server, ServerResponse } from "node:http"; import { createServer as createHttpServer, IncomingMessage } from "node:http"; import { createServer as createHttpsServer } from "node:https"; import { ListenOptions } from "node:net"; import { normalize } from "node:path"; import { Duplex } from "node:stream"; // Node's ReadableStream type definition do not exactly match the standard version so we need to import to support casts import type { ReadableStream as NodeReadableStream } from "node:stream/web"; import { WsAdapter } from "./WsAdapter.js"; const logger = new Logger("NodeJsHttpEndpoint"); /** * An implementation of {@link HttpEndpoint} that uses Node.js's standard {@link Server}. * * WebSocket support is optional. You can install by importing `@matter/nodejs-ws`. * * This implementation is a little ugly because the native Node.js HTTP server API is pre-async and has some design * flaws. Other runtimes tend build on WinterTC standards and adapters will be much simpler. */ export class NodeJsHttpEndpoint implements HttpEndpoint { #server: Server; #ready: Promise; #http?: HttpEndpoint.HttpHandler; #httpListener?: (req: IncomingMessage, res: ServerResponse) => void; #ws?: HttpEndpoint.WsHandler; #wsListener?: (req: IncomingMessage, socket: Duplex, head: Buffer) => void; #notFound: (res: ServerResponse) => void; #wsAdapter?: WsAdapter; #wsAdapterFactory?: WsAdapter.Factory; static async create(config: HttpEndpoint.Configuration): Promise { const endpoint = new NodeJsHttpEndpoint(config); await endpoint.ready; return endpoint; } /** * Create a new endpoint. * * You may pass an existing {@link Server} or pass {@link HttpEndpoint.Configuration} to create a server dedicated * to this endpoint. */ constructor(config: Server | HttpEndpoint.Configuration) { let close, ready, server, notFound; if ("on" in config) { ({ close, ready, server, notFound } = this.#bindToServer(config)); } else { ({ close, ready, server, notFound } = this.#createDedicatedServer(config)); } this.#server = server; this.#ready = ready; this.close = close; this.#notFound = notFound; } get server() { return this.#server; } #bindToServer(server: Server) { return { server, ready: Promise.resolve(), close: async () => { this.http = undefined; this.ws = undefined; }, notFound: () => undefined, }; } #createDedicatedServer(options: HttpEndpoint.Configuration) { const address = AppAddress.for(options.address); let server; if (address.isTls) { if (options.certificate === undefined || options.key === undefined) { throw new NetworkError( `Cannot create HTTPS endpoint for ${address} because no certificate and/or key is present`, ); } server = createHttpsServer({ keepAlive: true, cert: options.certificate, key: options.key, }); } else { server = createHttpServer({ keepAlive: true }); } const opts = {} as ListenOptions; const { transport } = address; switch (transport.kind) { case "ip": if (!address.isWildcardHost) { opts.host = address.hostname; } // A concrete port is required. A wildcard ("0") port is deliberately not bound: an OS-assigned // ephemeral port is undiscoverable to peers, so node's listen() is left to reject the attempt. if (!address.isWildcardPort) { opts.port = address.portNum; } break; case "unix": opts.path = normalize(decodeURIComponent(address.hostname)); if (existsSync(opts.path)) { if (statSync(opts.path).isSocket()) { try { rmSync(opts.path); } catch (e) { throw new NetworkError( `Error deleting previous socket at ${opts.path}: ${asError(e).message}`, ); } } else { throw new NetworkError(`UNIX socket path ${opts.path} exists and is not a socket`); } } break; default: throw new NetworkError( `Unsupported address type "${(options.address as any)?.type}" for HTTP endpoint`, ); } server.listen(opts); return { server, ready: new Promise((resolve, reject) => { let settled = false; server.once("listening", () => { if (settled) { return; } settled = true; resolve(); }); server.on("error", error => { if (settled) { logger.warn("HTTP server error:", error.message); return; } settled = true; reject(error); }); }), close: async () => { return new Promise((resolve, reject) => { server.close(err => { if (err) { reject(err); return; } resolve(); }); }); }, notFound: (res: ServerResponse) => respondError(res, 404), }; } get ready() { return this.#ready; } set http(handler: HttpEndpoint.HttpHandler | undefined) { this.#http = handler; if (!this.#http) { if (this.#httpListener) { this.#server.off("request", this.#httpListener); } return; } if (this.#httpListener) { return; } this.#httpListener = (req, res) => { this.#handleHttp(req, res).catch(error => { logger.warn("Unhandled error in HTTP endpoint handler", error); respondError(res, 500); }); }; this.#server.on("request", this.#httpListener); } set ws(handler: HttpEndpoint.WsHandler | undefined) { this.#ws = handler; if (!this.#ws) { if (this.#wsListener) { this.#server.off("upgrade", this.#wsListener); } return; } let adapter = this.#wsAdapter; if (!adapter) { const factory = this.#wsAdapterFactory ?? WsAdapter.defaultFactory; if (!factory) { logger.warn( "WebSocket support disabled because no adapter is installed; please import @matter/nodejs-ws or equivalent", ); return; } adapter = this.#wsAdapter = factory(); } this.#wsListener = (req, socket, head) => { this.#handleUpgrade(adapter, req, socket, head).catch(error => { logger.warn("Unhandled error WebSocket endpoint", error); }); }; this.#server.on("upgrade", this.#wsListener); } close: () => Promise; async #handleHttp(req: IncomingMessage, res: ServerResponse) { if (!this.#http) { return; } const request = new NodeJsHttpRequest(req); const response = await this.#http(request); if (!response) { this.#notFound(res); return; } res.statusCode = response.status; res.statusMessage = response.statusText; response.headers.forEach(([name, value]) => res.appendHeader(name, value)); if (response.body === null) { res.end(); return; } const nodeBodyStream = ReadStream.fromWeb(response.body as NodeReadableStream); nodeBodyStream.on("error", error => { logger.warn("Error transmitting HTTP body", error); respondError(res, 500); }); nodeBodyStream.pipe(res); } async #handleUpgrade(adapter: WsAdapter, req: IncomingMessage, socket: Duplex, head: Buffer) { if (req.headers.upgrade !== "websocket") { // Not clear how to send a 426 with Node's API socket.destroy(); return; } // This shouldn't happen if (!this.#ws) { socket.destroy(); return; } const request = new NodeJsHttpRequest(req); try { await this.#ws(request, async () => { return adapter.handle(req, socket, head); }); } finally { // Node API is fairly broken and offers no way to indicate we've skipped the socket so we must destroy it // if not already handled if (!socket.destroyed) { socket.destroy(); } } } } class NodeJsHttpRequest extends Request { constructor(message: IncomingMessage) { const { method, rawHeaders } = message; const url = `http://${message.headers.host ?? "unknown"}${message.url ?? "/"}`; const headers = new Headers(); for (let i = 0; i < message.rawHeaders.length; i += 2) { headers.append(rawHeaders[i], rawHeaders[i + 1]); } const init = { method, headers, duplex: "half", // Not in RequestInit type but required by node } as RequestInit; if (method !== "GET" && method !== "HEAD") { init.body = IncomingMessage.toWeb(message) as unknown as ReadableStream; } super(url, init); } } function respondError(res: ServerResponse, code: number) { if (res.closed) { return; } try { if (!res.headersSent) { res.statusCode = code; res.setHeader("Content-Type", "text/plain"); res.end(`HTTP error ${code}\n`); } else { res.end(); } } catch (e) { logger.warn(`Error conveying ${code} error:`, asError(e).message); } } export namespace NodeJsHttpEndpoint { export class Factory extends HttpEndpointFactory { async create(config: HttpEndpoint.Configuration) { return NodeJsHttpEndpoint.create(config); } } }