@yydb/yyds 0.0.14 → 0.0.15

package/bin/yyds.mjs

@@ -1,9 +1,18 @@
 #!/usr/bin/env node
 import { loadYydsNative } from "../src/node/load.ts";
 import { parseStartOptions, runNodeStart } from "../src/node/runtime.ts";
+import { parseWebuiArgs, runWebui } from "../src/node/webui-cmd.ts";
 
 function usage() {
-    return "usage: yyds <init|start|status|stop> --data-dir DIR [--cluster-id ID --node-id ID] [--redis-port PORT] [--pgsql-port PORT] [--mysql-port PORT] [--mongo-port PORT] [--wire-port PORT]";
+    return "usage: yyds <init|start|status|stop|webui> ...";
+}
+
+function startUsage() {
+    return "usage: yyds start --data-dir DIR --cluster-id ID --node-id ID [--redis-port PORT] [--pgsql-port PORT] [--mysql-port PORT] [--mongo-port PORT] [--wire-port PORT]";
+}
+
+function webuiUsage() {
+    return "usage: yyds webui [--endpoint URL | --data-dir DIR --cluster-id ID --node-id ID [--wire-port PORT]] [--port NUMBER] [--no-open]";
 }
 
 function parseCommonArgs(command, args) {
@@ -70,7 +79,7 @@ function parseCommonArgs(command, args) {
     }
     if (!options.dataDir) throw new Error(usage());
     if ((command === "init" || command === "start") && (!options.clusterId || !options.nodeId)) {
-        throw new Error(usage());
+        throw new Error(startUsage());
     }
     return options;
 }
@@ -78,6 +87,12 @@ function parseCommonArgs(command, args) {
 async function main(args) {
     const command = args[0];
     const rest = args.slice(1);
+
+    if (command === "webui") {
+        await runWebui(parseWebuiArgs(rest));
+        return;
+    }
+
     const native = loadYydsNative();
     const options = parseCommonArgs(command, rest);
 
@@ -124,7 +139,7 @@ async function main(args) {
             return;
         }
         default:
-            throw new Error(command ? `unknown command '${command}'` : usage());
+            throw new Error(command ? `unknown command '${command}'` : `${usage()}\n${startUsage()}\n${webuiUsage()}`);
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yydb/yyds",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Node.js facade, CLI, and native bindings for local YYDS nodes.",
   "license": "MPL-2.0",
   "type": "module",
@@ -32,11 +32,13 @@
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "webui"
   ],
   "scripts": {
+    "build": "node scripts/bundle-webui.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "node --experimental-strip-types --test \"./tests/**/*.test.ts\""
+    "test": "node --experimental-strip-types --test \"./tests/**/*.test.ts\" \"./src/node/**/*.test.ts\""
   },
   "repository": {
     "type": "git",
@@ -57,13 +59,14 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@yydb/yyds-win32-x64": "0.0.14",
-    "@yydb/yyds-linux-x64": "0.0.14",
-    "@yydb/yyds-darwin-x64": "0.0.14",
-    "@yydb/yyds-darwin-arm64": "0.0.14"
+    "@yydb/yyds-win32-x64": "0.0.15",
+    "@yydb/yyds-linux-x64": "0.0.15",
+    "@yydb/yyds-darwin-x64": "0.0.15",
+    "@yydb/yyds-darwin-arm64": "0.0.15"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",
+    "@yydb/yyds-webui": "0.0.15",
     "typescript": "^5.9.2"
   },
   "engines": {

package/readme.md

@@ -10,7 +10,7 @@ Node.js facade for running a local YYDS node: native lifecycle blocks, a small C
 | `@yydb/yyds/node/cluster` | `launchYydsServer` for `redis-server`, `mysqld`, `postgres` |
 | `@yydb/yyds/node/runtime` | `runNodeStart`, `parseStartOptions` |
 
-The `yyds` binary provides `init`, `start`, `status`, and `stop`. Native addons for your platform are pulled in automatically as optional dependencies.
+The `yyds` binary provides `init`, `start`, `status`, `stop`, and `webui`. Native addons for your platform are pulled in automatically as optional dependencies.
 
 ## Example
 
@@ -30,10 +30,11 @@ yyds init --data-dir ./node-data --cluster-id local --node-id node-1
 yyds start --data-dir ./node-data --cluster-id local --node-id node-1
 yyds status --data-dir ./node-data
 yyds stop --data-dir ./node-data
+yyds webui --data-dir ./node-data --cluster-id local --node-id node-1
 ```
 
 ## Related packages
 
-- [`@yydb/redis`](https://github.com/yy-database/yyds/tree/dev/projects/yyds.ts/packages/redis) �?Redis protocol disguise
-- [`@yydb/mysql`](https://github.com/yy-database/yyds/tree/dev/projects/yyds.ts/packages/mysql) �?MySQL protocol disguise
-- [`@yydb/postgresql`](https://github.com/yy-database/yyds/tree/dev/projects/yyds.ts/packages/postgresql) �?PostgreSQL protocol disguise
+- [`@yydb/redis`](https://github.com/yy-database/yyds/tree/dev/projects/yyds.ts/packages/redis) �?Redis protocol disguise
+- [`@yydb/mysql`](https://github.com/yy-database/yyds/tree/dev/projects/yyds.ts/packages/mysql) �?MySQL protocol disguise
+- [`@yydb/postgresql`](https://github.com/yy-database/yyds/tree/dev/projects/yyds.ts/packages/postgresql) �?PostgreSQL protocol disguise

package/src/node/webui-cmd.ts

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import { join } from "node:path";
+import type { ChildProcess } from "node:child_process";
+import type { Server } from "node:http";
+
+import {
+    openBrowser,
+    resolveWebuiDist,
+    spawnStart,
+    startStaticServer,
+    waitForWire,
+    wsEndpointFromWirePort,
+} from "./webui-static.ts";
+
+export interface WebuiOptions {
+    dataDir: string;
+    clusterId: string;
+    nodeId: string;
+    wirePort: number;
+    webuiPort: number;
+    endpoint?: string;
+    open: boolean;
+}
+
+function parsePort(raw: string | undefined, fallback: number, label: string): number {
+    const value = Number(raw ?? fallback);
+    if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        throw new Error(`invalid ${label}: ${raw ?? fallback}`);
+    }
+    return value;
+}
+
+export function parseWebuiArgs(args: string[]): WebuiOptions {
+    const options: WebuiOptions = {
+        dataDir: "",
+        clusterId: "",
+        nodeId: "",
+        wirePort: 7700,
+        webuiPort: 8780,
+        open: true,
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        const value = args[index + 1];
+        switch (flag) {
+            case "--data-dir":
+                options.dataDir = value ?? "";
+                index += 1;
+                break;
+            case "--cluster-id":
+                options.clusterId = value ?? "";
+                index += 1;
+                break;
+            case "--node-id":
+                options.nodeId = value ?? "";
+                index += 1;
+                break;
+            case "--wire-port":
+                options.wirePort = parsePort(value, options.wirePort, "wire-port");
+                index += 1;
+                break;
+            case "--port":
+                options.webuiPort = parsePort(value, options.webuiPort, "port");
+                index += 1;
+                break;
+            case "--endpoint":
+                options.endpoint = value ?? "";
+                index += 1;
+                break;
+            case "--no-open":
+                options.open = false;
+                break;
+            default:
+                throw new Error(`unknown option '${flag}'`);
+        }
+    }
+    if (!options.endpoint && (!options.dataDir || !options.clusterId || !options.nodeId)) {
+        throw new Error(
+            "webui requires --endpoint or --data-dir with --cluster-id and --node-id",
+        );
+    }
+    return options;
+}
+
+export async function runWebui(options: WebuiOptions): Promise<void> {
+    const endpoint = options.endpoint ?? wsEndpointFromWirePort(options.wirePort);
+    const distRoot = resolveWebuiDist();
+    if (!fs.existsSync(join(distRoot, "index.html"))) {
+        throw new Error(
+            "WebUI assets not found. Run `pnpm --filter @yydb/yyds build` to bundle webui/.",
+        );
+    }
+
+    let startChild: ChildProcess | null = null;
+    if (!options.endpoint) {
+        startChild = spawnStart({
+            dataDir: options.dataDir,
+            clusterId: options.clusterId,
+            nodeId: options.nodeId,
+            wirePort: options.wirePort,
+        });
+        startChild.stdout?.on("data", (chunk) => process.stdout.write(chunk));
+        startChild.stderr?.on("data", (chunk) => process.stderr.write(chunk));
+        startChild.on("exit", (code) => {
+            if (code && code !== 0) {
+                console.error(`yyds start exited with code ${code}`);
+            }
+        });
+        await waitForWire(endpoint, 8000);
+    }
+
+    const server = await startStaticServer(distRoot, options.webuiPort);
+    const pageUrl = `http://127.0.0.1:${options.webuiPort}/?endpoint=${encodeURIComponent(endpoint)}`;
+
+    console.log(`WebUI ${pageUrl}`);
+    console.log(`Wire ${endpoint}`);
+
+    if (options.open) {
+        openBrowser(pageUrl);
+    }
+
+    await waitForShutdown(server, startChild);
+}
+
+function waitForShutdown(server: Server, startChild: ChildProcess | null): Promise<void> {
+    return new Promise((resolveWait) => {
+        const shutdown = () => {
+            server.close();
+            if (startChild && !startChild.killed) {
+                startChild.kill();
+            }
+            resolveWait();
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}

package/src/node/webui-static.test.ts

@@ -0,0 +1,12 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { wsEndpointFromWirePort } from "./webui-static.ts";
+
+test("wsEndpointFromWirePort maps loopback wire port to WebSocket URL", () => {
+    assert.equal(wsEndpointFromWirePort(7700), "ws://127.0.0.1:7700/wire");
+});
+
+test("wsEndpointFromWirePort accepts custom host", () => {
+    assert.equal(wsEndpointFromWirePort(9001, "10.0.0.5"), "ws://10.0.0.5:9001/wire");
+});

package/src/node/webui-static.ts

@@ -0,0 +1,137 @@
+import { createRequire } from "node:module";
+import { createServer, type Server } from "node:http";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, type ChildProcess } from "node:child_process";
+
+const MIME: Record<string, string> = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".woff2": "font/woff2",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+};
+
+function contentType(path: string): string {
+    const extension = path.slice(path.lastIndexOf("."));
+    return MIME[extension] ?? "application/octet-stream";
+}
+
+export function resolveWebuiDist(): string {
+    const bundled = join(dirname(fileURLToPath(import.meta.url)), "../../webui");
+    if (existsSync(join(bundled, "index.html"))) {
+        return bundled;
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const pkgJson = require.resolve("@yydb/yyds-webui/package.json");
+        const external = join(dirname(pkgJson), "dist", "cdn");
+        if (existsSync(join(external, "index.html"))) {
+            return external;
+        }
+    } catch {
+        // @yydb/yyds-webui not installed
+    }
+    return bundled;
+}
+
+export function wsEndpointFromWirePort(wirePort: number, host = "127.0.0.1"): string {
+    return `ws://${host}:${wirePort}/wire`;
+}
+
+export function startStaticServer(root: string, port: number): Promise<Server> {
+    const absRoot = resolve(root);
+    return new Promise((resolvePromise, reject) => {
+        const server = createServer((request, response) => {
+            const pathname = decodeURIComponent(new URL(request.url ?? "/", "http://localhost").pathname);
+            const relative = pathname === "/" ? "index.html" : pathname.replace(/^\//, "");
+            const target = resolve(absRoot, relative);
+            if (!target.startsWith(absRoot)) {
+                response.writeHead(403);
+                response.end("forbidden");
+                return;
+            }
+            try {
+                const bytes = readFileSync(target);
+                response.writeHead(200, { "Content-Type": contentType(target) });
+                response.end(bytes);
+            } catch {
+                response.writeHead(404);
+                response.end("not found");
+            }
+        });
+        server.listen(port, "127.0.0.1", () => resolvePromise(server));
+        server.on("error", reject);
+    });
+}
+
+export interface StartSpawnOptions {
+    dataDir: string;
+    clusterId: string;
+    nodeId: string;
+    wirePort: number;
+}
+
+export function spawnStart(options: StartSpawnOptions): ChildProcess {
+    const cli = fileURLToPath(new URL("../../bin/yyds.mjs", import.meta.url));
+    const args = [
+        cli,
+        "start",
+        "--data-dir",
+        options.dataDir,
+        "--cluster-id",
+        options.clusterId,
+        "--node-id",
+        options.nodeId,
+        "--wire-port",
+        String(options.wirePort),
+    ];
+    return spawn(process.execPath, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: process.env,
+    });
+}
+
+export function openBrowser(url: string): void {
+    const platform = process.platform;
+    if (platform === "win32") {
+        spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" });
+        return;
+    }
+    const opener = platform === "darwin" ? "open" : "xdg-open";
+    spawn(opener, [url], { detached: true, stdio: "ignore" });
+}
+
+export function sleep(ms: number): Promise<void> {
+    return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+export async function waitForWire(endpoint: string, timeoutMs = 8000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const socket = new WebSocket(endpoint);
+            const opened = await new Promise<boolean>((resolveOpen) => {
+                const timer = setTimeout(() => resolveOpen(false), 500);
+                socket.addEventListener("open", () => {
+                    clearTimeout(timer);
+                    resolveOpen(true);
+                });
+                socket.addEventListener("error", () => {
+                    clearTimeout(timer);
+                    resolveOpen(false);
+                });
+            });
+            socket.close();
+            if (opened) return;
+        } catch {
+            await sleep(400);
+            return;
+        }
+        await sleep(200);
+    }
+}