@yydb/yyds 0.0.13 → 0.0.15

package/bin/yyds.mjs

@@ -1,13 +1,31 @@
 #!/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] [--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) {
-    const options = { dataDir: "", clusterId: "", nodeId: "", redisPort: 6379, pgsqlPort: undefined, mysqlPort: undefined, wirePort: undefined };
+    const options = {
+        dataDir: "",
+        clusterId: "",
+        nodeId: "",
+        redisPort: 6379,
+        pgsqlPort: undefined,
+        mysqlPort: undefined,
+        mongoPort: undefined,
+        wirePort: undefined,
+    };
     for (let index = 0; index < args.length; index += 1) {
         const flag = args[index];
         const value = args[index + 1];
@@ -26,22 +44,32 @@ function parseCommonArgs(command, args) {
                 index += 1;
                 break;
             case "--redis-port":
-                if (command !== "start") throw new Error(`option ${flag} is not valid for this command`);
+                if (command !== "start")
+                    throw new Error(`option ${flag} is not valid for this command`);
                 options.redisPort = Number(value);
                 index += 1;
                 break;
             case "--pgsql-port":
-                if (command !== "start") throw new Error(`option ${flag} is not valid for this command`);
+                if (command !== "start")
+                    throw new Error(`option ${flag} is not valid for this command`);
                 options.pgsqlPort = Number(value);
                 index += 1;
                 break;
             case "--mysql-port":
-                if (command !== "start") throw new Error(`option ${flag} is not valid for this command`);
+                if (command !== "start")
+                    throw new Error(`option ${flag} is not valid for this command`);
                 options.mysqlPort = Number(value);
                 index += 1;
                 break;
+            case "--mongo-port":
+                if (command !== "start")
+                    throw new Error(`option ${flag} is not valid for this command`);
+                options.mongoPort = Number(value);
+                index += 1;
+                break;
             case "--wire-port":
-                if (command !== "start") throw new Error(`option ${flag} is not valid for this command`);
+                if (command !== "start")
+                    throw new Error(`option ${flag} is not valid for this command`);
                 options.wirePort = Number(value);
                 index += 1;
                 break;
@@ -51,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;
 }
@@ -59,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);
 
@@ -77,18 +111,21 @@ async function main(args) {
                 redisPort: options.redisPort,
                 pgsqlPort: options.pgsqlPort,
                 mysqlPort: options.mysqlPort,
+                mongoPort: options.mongoPort,
                 wirePort: options.wirePort,
             });
             return;
         case "status": {
             const snapshot = native.nodeInspect(options.dataDir);
-            console.log(JSON.stringify({
-                directory: snapshot.directory,
-                identity: JSON.parse(snapshot.identity),
-                ownership: snapshot.ownership,
-                runtime: snapshot.runtime ? JSON.parse(snapshot.runtime) : null,
-                health: snapshot.health,
-            }));
+            console.log(
+                JSON.stringify({
+                    directory: snapshot.directory,
+                    identity: JSON.parse(snapshot.identity),
+                    ownership: snapshot.ownership,
+                    runtime: snapshot.runtime ? JSON.parse(snapshot.runtime) : null,
+                    health: snapshot.health,
+                }),
+            );
             return;
         }
         case "stop": {
@@ -102,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.13",
+  "version": "0.0.15",
   "description": "Node.js facade, CLI, and native bindings for local YYDS nodes.",
   "license": "MPL-2.0",
   "type": "module",
@@ -32,18 +32,20 @@
   },
   "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",
     "url": "git+https://github.com/yy-database/yyds.git",
-    "directory": "projects/packages/yyds"
+    "directory": "projects/yyds.ts/packages/yyds"
   },
-  "homepage": "https://github.com/yy-database/yyds/tree/dev/projects/packages/yyds#readme",
+  "homepage": "https://github.com/yy-database/yyds/tree/dev/projects/yyds.ts/packages/yyds#readme",
   "bugs": {
     "url": "https://github.com/yy-database/yyds/issues"
   },
@@ -57,13 +59,14 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@yydb/yyds-win32-x64": "0.0.13",
-    "@yydb/yyds-linux-x64": "0.0.13",
-    "@yydb/yyds-darwin-x64": "0.0.13",
-    "@yydb/yyds-darwin-arm64": "0.0.13"
+    "@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/packages/redis) — Redis protocol disguise
-- [`@yydb/mysql`](https://github.com/yy-database/yyds/tree/dev/projects/packages/mysql) — MySQL protocol disguise
-- [`@yydb/postgresql`](https://github.com/yy-database/yyds/tree/dev/projects/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/bindings.ts

@@ -7,9 +7,18 @@ export interface YydsBindings {
         acquire(dataDir: string, identity: unknown): unknown;
     };
     LocalExecutorHandle: new (dataDir: string) => unknown;
-    RedisServiceHandle: new (lease: unknown, port: number, executor: unknown) => RedisServiceBinding;
+    RedisServiceHandle: new (
+        lease: unknown,
+        port: number,
+        executor: unknown,
+    ) => RedisServiceBinding;
     PgsqlServiceHandle: new (lease: unknown, port: number) => PgsqlServiceBinding;
     MysqlServiceHandle: new (lease: unknown, port: number) => MysqlServiceBinding;
+    MongoServiceHandle: new (
+        lease: unknown,
+        port: number,
+        executor: unknown,
+    ) => MongoServiceBinding;
     WireServerHandle: new (port: number, executor: unknown) => WireServiceBinding;
     nodeInit(dataDir: string, identity: unknown): void;
     nodeInspect(dataDir: string): NodeStatusBinding;
@@ -30,6 +39,7 @@ export interface ServiceBinding {
 export type RedisServiceBinding = ServiceBinding;
 export type PgsqlServiceBinding = ServiceBinding;
 export type MysqlServiceBinding = ServiceBinding;
+export type MongoServiceBinding = ServiceBinding;
 export type WireServiceBinding = ServiceBinding;
 
 export interface NodeStatusBinding {

package/src/node/runtime.ts

@@ -12,6 +12,7 @@ export interface StartNodeOptions {
     redisPort?: number;
     pgsqlPort?: number;
     mysqlPort?: number;
+    mongoPort?: number;
     wirePort?: number;
 }
 
@@ -33,7 +34,8 @@ export function parseStartOptions(protocol: YydsProtocol, args: string[]): Start
         const argument = args[index];
         if (["--port", "-p", "-P"].includes(argument)) {
             const value = Number(args[++index]);
-            if (!Number.isInteger(value) || value < 0) throw new Error(`missing port after ${argument}`);
+            if (!Number.isInteger(value) || value < 0)
+                throw new Error(`missing port after ${argument}`);
             if (protocol === "redis") options.redisPort = value;
             if (protocol === "mysql") options.mysqlPort = value;
             if (protocol === "postgresql") options.pgsqlPort = value;
@@ -63,6 +65,10 @@ export function parseStartOptions(protocol: YydsProtocol, args: string[]): Start
             options.mysqlPort = Number(args[++index]);
             continue;
         }
+        if (argument === "--mongo-port") {
+            options.mongoPort = Number(args[++index]);
+            continue;
+        }
         if (argument === "--wire-port") {
             options.wirePort = Number(args[++index]);
             continue;
@@ -89,10 +95,27 @@ export async function runNodeStart(options: StartNodeOptions): Promise<void> {
     const identity = new native.NodeIdentityHandle(options.clusterId, options.nodeId);
     const lease = native.NodeLeaseHandle.acquire(options.dataDir, identity);
     const executor = new native.LocalExecutorHandle(options.dataDir);
-    const redis = new native.RedisServiceHandle(lease, options.redisPort ?? DEFAULT_REDIS_PORT, executor);
-    const pgsql = options.pgsqlPort === undefined ? undefined : new native.PgsqlServiceHandle(lease, options.pgsqlPort);
-    const mysql = options.mysqlPort === undefined ? undefined : new native.MysqlServiceHandle(lease, options.mysqlPort);
-    const wire = options.wirePort === undefined ? undefined : new native.WireServerHandle(options.wirePort, executor);
+    const redis = new native.RedisServiceHandle(
+        lease,
+        options.redisPort ?? DEFAULT_REDIS_PORT,
+        executor,
+    );
+    const pgsql =
+        options.pgsqlPort === undefined
+            ? undefined
+            : new native.PgsqlServiceHandle(lease, options.pgsqlPort);
+    const mysql =
+        options.mysqlPort === undefined
+            ? undefined
+            : new native.MysqlServiceHandle(lease, options.mysqlPort);
+    const mongo =
+        options.mongoPort === undefined
+            ? undefined
+            : new native.MongoServiceHandle(lease, options.mongoPort, executor);
+    const wire =
+        options.wirePort === undefined
+            ? undefined
+            : new native.WireServerHandle(options.wirePort, executor);
 
     const runtime = {
         version: 1,
@@ -107,7 +130,7 @@ export async function runNodeStart(options: StartNodeOptions): Promise<void> {
     native.nodeWriteRuntimeStatus(options.dataDir, JSON.stringify(runtime));
 
     process.stdout.write(
-        `yyds running pid=${runtime.pid} redis=${runtime.redisAddress} pgsql=${runtime.pgsqlAddress ?? "null"} mysql=${runtime.mysqlAddress ?? "null"} wire=${runtime.wireAddress ?? "null"}\n`,
+        `yyds running pid=${runtime.pid} redis=${runtime.redisAddress} pgsql=${runtime.pgsqlAddress ?? "null"} mysql=${runtime.mysqlAddress ?? "null"} mongo=${mongo?.address() ?? "null"} wire=${runtime.wireAddress ?? "null"}\n`,
     );
 
     while (true) {
@@ -115,6 +138,7 @@ export async function runNodeStart(options: StartNodeOptions): Promise<void> {
         if (redis.isFinished()) break;
         if (pgsql?.isFinished()) break;
         if (mysql?.isFinished()) break;
+        if (mongo?.isFinished()) break;
         if (wire?.isFinished()) break;
         await sleep(50);
     }
@@ -122,6 +146,7 @@ export async function runNodeStart(options: StartNodeOptions): Promise<void> {
     redis.stop();
     pgsql?.stop();
     mysql?.stop();
+    mongo?.stop();
     wire?.stop();
     native.nodeClearRuntimeArtifacts(options.dataDir, runtime.generation);
 }

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);
+    }
+}