tturn 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,108 @@
+# Tturn (English)
+
+[English](./README.en.md) | [中文](./README.zh-CN.md)
+
+`tturn` is a high-performance TURN server package for Node.js.
+It uses an embedded native core (Rust + N-API), so you can install and run it directly from npm without Docker and without an external `turnserver.exe` runtime dependency.
+
+## 1) What this project is
+
+- Embedded TURN server for Node.js applications.
+- Native data plane implemented in Rust for better throughput and lower overhead than pure JavaScript TURN implementations.
+- Programmatic API and CLI are both provided.
+- Time-limited TURN credentials are generated with HMAC-SHA1 (standard TURN REST style).
+
+## 2) Current capabilities
+
+- Start / stop TURN service from Node.
+- Issue short-lived credentials.
+- Return WebRTC ICE `urls/username/credential` directly.
+- Health check (`running: boolean`).
+
+## 3) Install
+
+```bash
+npm i tturn
+```
+
+## 4) Quick start (Node API)
+
+```ts
+import { Tturn } from "tturn";
+
+const turn = new Tturn({
+  realm: "turn.example.com",
+  authSecret: "replace-with-your-secret",
+  publicIp: "1.2.3.4",
+  listenPort: 3478
+});
+
+await turn.start();
+
+const ice = turn.issueCredential({ ttlSec: 600, userId: "user-1001" });
+console.log(ice);
+
+// stop when exiting process
+await turn.stop();
+```
+
+## 5) CLI usage
+
+```bash
+# Start embedded TURN service
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn start
+
+# Print one ICE credential payload
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn credential
+```
+
+## 6) API options
+
+- `realm` (required): TURN realm/domain.
+- `authSecret` (required): shared secret for dynamic credentials.
+- `listenPort` (default `3478`): TURN listening port.
+- `publicIp` (optional, recommended): public relay IP exposed to clients.
+- `listeningIp` (default `0.0.0.0`): bind address.
+- `minPort` / `maxPort`: reserved for relay port range control in next iterations.
+
+## 7) Build from source
+
+Requirements:
+
+- Node.js >= 18
+- Rust toolchain (stable)
+
+Commands:
+
+```bash
+npm install
+npm run build:native
+./node_modules/.bin/tsc -p tsconfig.json
+```
+
+Then run demo app:
+
+```bash
+node dist/app.js
+```
+
+Edit fixed config in `src/app.ts` before running.
+
+## 8) Verify with Google WebRTC tool
+
+1. Start service (`node dist/app.js`).
+2. Copy printed `urls`, `username`, `credential`.
+3. Open Google Trickle ICE tool and paste the ICE server config.
+4. Gather candidates and confirm relay candidates are returned.
+
+## 9) Publish to npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+Notes:
+
+- npm package names must be lowercase, so publish as `tturn`.
+- For production users across multiple platforms, publish prebuilt `.node` artifacts for each target platform/arch.

package/README.md

@@ -0,0 +1,14 @@
+# Tturn
+
+[English](./README.en.md) | [中文](./README.zh-CN.md)
+
+`tturn` is a high-performance TURN server package for Node.js with an embedded native core (Rust + N-API).
+
+- No Docker runtime required.
+- No external `turnserver.exe` runtime dependency.
+- Programmatic API and CLI included.
+
+Please read full docs:
+
+- English: `README.en.md`
+- 中文：`README.zh-CN.md`

package/README.zh-CN.md

@@ -0,0 +1,107 @@
+# Tturn（中文）
+
+[English](./README.en.md) | [中文](./README.zh-CN.md)
+
+`tturn` 是一个高性能的 Node.js TURN 服务包。
+它使用内嵌原生核心（Rust + N-API），可以直接通过 npm 安装并运行，不依赖 Docker，也不需要额外安装 `turnserver.exe` 作为运行时。
+
+## 1）项目介绍
+
+- `tturn` 是一个可直接在 Node.js 中运行的 TURN 服务包。
+- 底层是 Rust + N-API 原生实现，性能和资源效率优于纯 JS TURN 实现。
+- 不依赖 Docker，也不需要额外安装 `turnserver.exe` 作为运行时。
+- 同时提供 Node API 和 CLI 两种使用方式。
+
+## 2）当前功能
+
+- 在 Node 中启动 / 停止 TURN 服务。
+- 生成短时效 TURN 凭证（HMAC-SHA1）。
+- 直接输出 WebRTC 所需的 ICE 参数（`urls/username/credential`）。
+- 基础健康状态检查（`running: boolean`）。
+
+## 3）安装
+
+```bash
+npm i tturn
+```
+
+## 4）Node API 快速使用
+
+```ts
+import { Tturn } from "tturn";
+
+const turn = new Tturn({
+  realm: "turn.example.com",
+  authSecret: "replace-with-your-secret",
+  publicIp: "1.2.3.4",
+  listenPort: 3478
+});
+
+await turn.start();
+
+const ice = turn.issueCredential({ ttlSec: 600, userId: "user-1001" });
+console.log(ice);
+
+await turn.stop();
+```
+
+## 5）CLI 用法
+
+```bash
+# 启动内置 TURN 服务
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn start
+
+# 生成一组 ICE 凭证
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn credential
+```
+
+## 6）配置参数说明
+
+- `realm`（必填）：TURN realm / 域名。
+- `authSecret`（必填）：动态凭证签名密钥。
+- `listenPort`（默认 `3478`）：TURN 监听端口。
+- `publicIp`（建议配置）：客户端访问的公网 IP。
+- `listeningIp`（默认 `0.0.0.0`）：本地绑定地址。
+- `minPort` / `maxPort`：预留给后续中继端口范围控制。
+
+## 7）源码构建
+
+环境要求：
+
+- Node.js >= 18
+- Rust 稳定版工具链
+
+构建命令：
+
+```bash
+npm install
+npm run build:native
+./node_modules/.bin/tsc -p tsconfig.json
+```
+
+运行示例：
+
+```bash
+node dist/app.js
+```
+
+运行前请先修改 `src/app.ts` 中的固定配置项。
+
+## 8）使用 Google WebRTC 工具验证
+
+1. 启动服务：`node dist/app.js`
+2. 复制控制台打印的 `urls`、`username`、`credential`
+3. 打开 Google Trickle ICE 页面，填入 ICE Server
+4. 执行采集并确认出现 relay candidate
+
+## 9）发布到 npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+说明：
+
+- npm 包名必须小写，所以发布名为 `tturn`。
+- 生产环境建议按平台预编译并发布对应 `.node` 二进制文件。

package/dist/app.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/app.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const APP_CONFIG = {
+    realm: "turn.example.com",
+    authSecret: "replace-with-your-secret",
+    publicIp: "1.2.3.4",
+    listenPort: 3478,
+    ttlSec: 600
+};
+async function main() {
+    const service = new index_1.Tturn({
+        realm: APP_CONFIG.realm,
+        authSecret: APP_CONFIG.authSecret,
+        publicIp: APP_CONFIG.publicIp,
+        listenPort: APP_CONFIG.listenPort
+    });
+    await service.start();
+    const ice = service.issueCredential({ ttlSec: APP_CONFIG.ttlSec, userId: "google-test" });
+    console.log("[tturn] started.");
+    console.log("[tturn] use this ICE server in Google WebRTC tool:");
+    console.log(JSON.stringify(ice, null, 2));
+    console.log("[tturn] health:", service.health());
+    console.log("[tturn] press Ctrl+C to stop.");
+    await waitForSignal();
+    await service.stop();
+    console.log("[tturn] stopped.");
+}
+function waitForSignal() {
+    return new Promise((resolve) => {
+        const keepAlive = setInterval(() => {
+            // Keep Node event loop active while native TURN runs.
+        }, 60000);
+        const onSignal = () => {
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            clearInterval(keepAlive);
+            resolve();
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+    });
+}
+main().catch((error) => {
+    console.error(`[tturn] startup failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+async function run() {
+    const command = process.argv[2];
+    if (command === "credential") {
+        const secret = mustGetEnv("TURN_SECRET");
+        const realm = mustGetEnv("TURN_REALM");
+        const service = (0, index_1.createTurnService)({ realm, authSecret: secret, publicIp: process.env.TURN_PUBLIC_IP });
+        const ice = service.issueCredential({
+            ttlSec: process.env.TTURN_TTL_SEC ? Number(process.env.TTURN_TTL_SEC) : 3600,
+            userId: process.env.TTURN_USER_ID
+        });
+        process.stdout.write(`${JSON.stringify(ice, null, 2)}\n`);
+        return;
+    }
+    if (command === "start") {
+        const secret = mustGetEnv("TURN_SECRET");
+        const realm = mustGetEnv("TURN_REALM");
+        const service = (0, index_1.createTurnService)({
+            realm,
+            authSecret: secret,
+            publicIp: process.env.TURN_PUBLIC_IP,
+            listenPort: process.env.TURN_PORT ? Number(process.env.TURN_PORT) : 3478
+        });
+        await service.start();
+        process.stdout.write("tturn started\n");
+        await waitForSignal();
+        await service.stop();
+        process.stdout.write("tturn stopped\n");
+        return;
+    }
+    printUsage();
+    process.exitCode = 1;
+}
+function mustGetEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required env: ${name}`);
+    }
+    return value;
+}
+function printUsage() {
+    process.stdout.write([
+        "tturn usage:",
+        "  tturn start       # starts embedded native TURN service",
+        "  tturn credential  # prints one ICE server credential JSON",
+        "",
+        "required env:",
+        "  TURN_REALM, TURN_SECRET",
+        "optional env:",
+        "  TURN_PUBLIC_IP, TURN_PORT, TTURN_TTL_SEC, TTURN_USER_ID"
+    ].join("\n") + "\n");
+}
+function waitForSignal() {
+    return new Promise((resolve) => {
+        const keepAlive = setInterval(() => {
+            // Keep Node event loop active while native TURN runs.
+        }, 60000);
+        const onSignal = () => {
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            clearInterval(keepAlive);
+            resolve();
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+    });
+}
+run().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/credentials.d.ts

@@ -0,0 +1,2 @@
+import { IssueCredentialOptions, TurnCredential } from "./types";
+export declare function createTurnCredential(authSecret: string, options?: IssueCredentialOptions): TurnCredential;

package/dist/credentials.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTurnCredential = createTurnCredential;
+const node_crypto_1 = require("node:crypto");
+const DEFAULT_TTL_SEC = 3600;
+function createTurnCredential(authSecret, options = {}) {
+    const ttlSec = Math.max(60, options.ttlSec ?? DEFAULT_TTL_SEC);
+    const expiresAt = Math.floor(Date.now() / 1000) + ttlSec;
+    const userPrefix = options.userId ? `${options.userId}:` : "";
+    const username = `${userPrefix}${expiresAt}`;
+    const password = (0, node_crypto_1.createHmac)("sha1", authSecret).update(username).digest("base64");
+    return { username, password, ttlSec, expiresAt };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { createTurnCredential } from "./credentials";
+import { TurnService } from "./service";
+import { TurnServiceOptions } from "./types";
+export * from "./types";
+export { createTurnCredential, TurnService };
+export declare class Tturn extends TurnService {
+}
+export declare function createTurnService(options: TurnServiceOptions): TurnService;

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tturn = exports.TurnService = exports.createTurnCredential = void 0;
+exports.createTurnService = createTurnService;
+const credentials_1 = require("./credentials");
+Object.defineProperty(exports, "createTurnCredential", { enumerable: true, get: function () { return credentials_1.createTurnCredential; } });
+const service_1 = require("./service");
+Object.defineProperty(exports, "TurnService", { enumerable: true, get: function () { return service_1.TurnService; } });
+__exportStar(require("./types"), exports);
+class Tturn extends service_1.TurnService {
+}
+exports.Tturn = Tturn;
+function createTurnService(options) {
+    return new service_1.TurnService(options);
+}

package/dist/native-binding.d.ts

@@ -0,0 +1,22 @@
+import { TurnServiceOptions } from "./types";
+interface NativeCredential {
+    username: string;
+    password: string;
+    ttlSec: number;
+    expiresAt: number;
+}
+interface NativeTurnService {
+    start(detached?: boolean): void;
+    stop(): void;
+    issueCredential(ttlSec?: number, userId?: string): NativeCredential;
+    getIceUrls(): string[];
+    health(): {
+        running: boolean;
+    };
+}
+interface NativeBinding {
+    NativeTurnService: new (options: TurnServiceOptions) => NativeTurnService;
+}
+declare const binding: NativeBinding;
+export type { NativeTurnService, NativeCredential };
+export { binding };

package/dist/native-binding.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.binding = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function loadNativeBinding() {
+    const root = (0, node_path_1.join)(__dirname, "..");
+    const candidates = [
+        (0, node_path_1.join)(root, "index.node"),
+        (0, node_path_1.join)(root, "native", "index.node"),
+        (0, node_path_1.join)(root, binaryName())
+    ];
+    for (const filePath of candidates) {
+        if (!(0, node_fs_1.existsSync)(filePath)) {
+            continue;
+        }
+        return require(filePath);
+    }
+    throw new Error([
+        "Native binding not found.",
+        "Run `npm run build:native` before using Tturn in development.",
+        "For published builds, ensure prebuilt `.node` artifacts are bundled."
+    ].join(" "));
+}
+function binaryName() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === "win32") {
+        return `tturn.${platform}-${arch}-msvc.node`;
+    }
+    return `tturn.${platform}-${arch}.node`;
+}
+const binding = loadNativeBinding();
+exports.binding = binding;

package/dist/service.d.ts

@@ -0,0 +1,12 @@
+import { IceServer, IssueCredentialOptions, StartOptions, TurnServiceOptions } from "./types";
+export declare class TurnService {
+    private readonly native;
+    constructor(options: TurnServiceOptions);
+    start(startOptions?: StartOptions): Promise<void>;
+    stop(): Promise<void>;
+    issueCredential(issueOptions?: IssueCredentialOptions): IceServer;
+    getIceUrls(): string[];
+    health(): {
+        running: boolean;
+    };
+}

package/dist/service.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnService = void 0;
+const native_binding_1 = require("./native-binding");
+class TurnService {
+    constructor(options) {
+        this.native = new native_binding_1.binding.NativeTurnService({
+            ...options,
+            listenPort: options.listenPort ?? 3478,
+            minPort: options.minPort ?? 49152,
+            maxPort: options.maxPort ?? 65535,
+            publicIp: options.publicIp ?? options.realm,
+            listeningIp: options.listeningIp ?? "0.0.0.0"
+        });
+    }
+    async start(startOptions = {}) {
+        this.native.start(Boolean(startOptions.detached));
+    }
+    async stop() {
+        this.native.stop();
+    }
+    issueCredential(issueOptions = {}) {
+        const out = this.native.issueCredential(issueOptions.ttlSec, issueOptions.userId);
+        return {
+            urls: this.native.getIceUrls(),
+            username: out.username,
+            credential: out.password
+        };
+    }
+    getIceUrls() {
+        return this.native.getIceUrls();
+    }
+    health() {
+        return this.native.health();
+    }
+}
+exports.TurnService = TurnService;

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+export interface TurnCredential {
+    username: string;
+    password: string;
+    ttlSec: number;
+    expiresAt: number;
+}
+export interface IceServer {
+    urls: string[];
+    username: string;
+    credential: string;
+}
+export interface IssueCredentialOptions {
+    ttlSec?: number;
+    userId?: string;
+}
+export interface TurnServiceOptions {
+    realm: string;
+    authSecret: string;
+    listenPort?: number;
+    minPort?: number;
+    maxPort?: number;
+    publicIp?: string;
+    listeningIp?: string;
+}
+export interface StartOptions {
+    detached?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "tturn",
+  "version": "0.1.0",
+  "description": "High-performance TURN server for Node.js with embedded native core",
+  "keywords": [
+    "turn",
+    "webrtc",
+    "napi",
+    "rust",
+    "stun",
+    "relay"
+  ],
+  "license": "MIT",
+  "author": "",
+  "homepage": "https://github.com/txzh007/ttrun",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/txzh007/ttrun.git"
+  },
+  "bugs": {
+    "url": "https://github.com/txzh007/ttrun/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "tturn": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "index.node",
+    "tturn.*.node",
+    "README.md",
+    "README.en.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build:native": "node scripts/build-native.js",
+    "build": "npm run build:native && tsc -p tsconfig.json",
+    "build:ts": "tsc -p tsconfig.json"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  }
+}