freertc 0.1.0

package/README.md

@@ -0,0 +1,246 @@
+# freertc Cloudflare Worker (WebSocket + D1)
+
+This project provides a Cloudflare Worker signaling relay for WebRTC peers using the [Peer Signaling Protocol (PSP)](https://github.com/draeder/Peer-Signaling-Protocol-Specification) envelope shape.
+
+## Install from npm
+
+Local project install:
+
+```bash
+npm install freertc
+```
+
+Global install:
+
+```bash
+npm install -g freertc
+```
+
+When you run the CLI from your project directory, `freertc` copies the required worker files into that directory on first run:
+
+- `src/index.js`
+- `public/index.html`
+- `public/app.js`
+- `scripts/d1-schema.sql`
+- `wrangler.template.jsonc`
+- `wrangler.workers-dev.jsonc`
+
+## What this worker does
+
+- Accepts WebSocket client connections at `/ws`.
+- Validates [PSP](https://github.com/draeder/Peer-Signaling-Protocol-Specification) message envelopes (`psp_version`, `type`, `network`, `from`, `message_id`, `timestamp`).
+- Supports discovery, negotiation, control, and extension message types.
+- Stores peer announcements in Cloudflare D1 (`psp_announcements`).
+- Stores directed signaling messages in Cloudflare D1 (`psp_relay`).
+- Exposes a simple relay registry at `/api/v1/relays` when D1 is configured.
+- Delivers queued relay messages when peers reconnect.
+- Serves the browser demo from `public/`.
+
+## Runtime scope
+
+- The checked-in Cloudflare Worker runtime is `src/index.js` with Cloudflare D1 (`DB` binding).
+- The Rust/WASM worker lives in `src/lib.rs` and is optional; the default template now uses the JS worker path.
+- The built-in browser demo served by the Worker is `public/index.html` + `public/app.js`.
+- `src/kv.js` and `demo/src/*` are legacy/experimental code paths and are not used by `wrangler dev` or `wrangler deploy` in the current setup.
+
+## Supported message types
+
+- Discovery: `announce`, `withdraw`, `discover`, `peer_list`, `redirect`
+- Negotiation: `connect_request`, `connect_accept`, `connect_reject`, `offer`, `answer`, `ice_candidate`, `ice_end`, `renegotiate`
+- Control: `ping`, `pong`, `bye`, `error`, `ack`
+- Extension: `ext`
+
+## Wrangler install wizard (recommended)
+
+Use the interactive wizard from the project directory where you want the worker files and Wrangler config to live:
+
+```bash
+npx freertc wizard
+```
+
+The default command runs full setup mode (`both`):
+
+```bash
+npx freertc
+```
+
+You can also preselect full setup mode explicitly:
+
+```bash
+npx freertc setup
+```
+
+Global install flow:
+
+```bash
+freertc wizard
+freertc
+```
+
+After install, freertc prints a quick-start reminder with the exact next command.
+
+The wizard can:
+
+- Copy the worker runtime files into your current project when they are missing.
+- Verify Wrangler CLI.
+- Create `wrangler.jsonc` from `wrangler.template.jsonc` if needed.
+- Set Worker name automatically to `freertc-<your-domain>` when a domain is provided.
+- Initialize local D1 schema for `wrangler dev`.
+- Initialize remote D1 schema for deploy.
+- Detect Rust build configs and install `worker-build`/WASM target automatically when required.
+- Check existing Wrangler auth and only run `wrangler login` when needed.
+- Optionally run `npm run dev:cf` and `npm run deploy`.
+
+## Manual setup
+
+### 1. Install dependencies
+
+```bash
+npm install
+```
+
+If you installed the npm package instead of cloning the repo, use `npx freertc wizard` instead of the repository scripts below.
+
+### 2. Configure Wrangler
+
+- If needed, copy `wrangler.template.jsonc` to `wrangler.jsonc`.
+- Set your Worker name, route(s), and D1 database values.
+- Ensure `d1_databases[0].binding` is `DB`.
+
+### 3. Initialize D1 schema
+
+Local (for `wrangler dev`):
+
+```bash
+npm run d1:init:local
+```
+
+Remote (for production):
+
+```bash
+npm run d1:init:remote
+```
+
+If your database name is not `freertc-signal`, use Wrangler directly:
+
+```bash
+wrangler d1 execute <your-db-name> --local --file scripts/d1-schema.sql
+wrangler d1 execute <your-db-name> --remote --file scripts/d1-schema.sql
+```
+
+## Local development
+
+```bash
+npm run dev
+```
+
+`npm run dev` now runs the non-Cloudflare local runtime (plain Node.js + WebSocket).
+
+Cloudflare/Wrangler runtime:
+
+```bash
+npm run dev:cf
+```
+
+Shortcut alias (same behavior):
+
+```bash
+npm run dev:local
+```
+
+You can also choose host/port:
+
+```bash
+HOST=127.0.0.1 PORT=8788 npm run dev:node
+```
+
+`npm run dev:cf` checks local Rust Worker prerequisites automatically:
+
+- Uses `wrangler.workers-dev.jsonc` automatically when `wrangler.jsonc` is not present.
+- Only installs `worker-build` and the WebAssembly Rust target when the selected Wrangler config uses a `worker-build` command.
+- The checked-in `wrangler.workers-dev.jsonc` now points to `src/index.js`, so standard demo runs do not require Rust/WASM setup.
+
+Endpoints:
+
+- WebSocket: `ws://127.0.0.1:8788/ws` (`npm run dev`)
+- Health: `http://127.0.0.1:8788/health` (`npm run dev`)
+- Demo UI: `http://127.0.0.1:8788/` (`npm run dev`)
+
+Cloudflare/Wrangler endpoints (default):
+
+- WebSocket: `ws://127.0.0.1:8787/ws` (`npm run dev:cf`)
+- Health: `http://127.0.0.1:8787/health` (`npm run dev:cf`)
+- Demo UI: `http://127.0.0.1:8787/` (`npm run dev:cf`)
+- Relay registry: `http://127.0.0.1:8787/api/v1/relays` (`GET`/`POST`, when D1 is configured)
+
+## Deploy
+
+```bash
+npx freertc deploy
+```
+
+If you installed freertc globally:
+
+```bash
+freertc deploy
+```
+
+Repository-only scripts:
+
+- `npm run build` builds the Rust/WASM worker via `worker-build --release`.
+- `npm run deploy:raw` deploys without `--env production`.
+- `npm run check` runs `cargo check --target wasm32-unknown-unknown` for the Rust worker path.
+- `npm run dev` runs the standalone local relay (non-Cloudflare).
+- `npm run dev:cf` runs Wrangler/Cloudflare local dev.
+- `npm run dev:node` runs a standalone local relay without Cloudflare/Wrangler.
+- `npm run dev:local` is a no-env shortcut for the standalone local relay.
+
+## Troubleshooting custom domain deploys
+
+If your custom domain returns:
+
+```json
+{"error":"API key is missing"}
+```
+
+that error is usually from Cloudflare routing/auth config, not from this Worker runtime.
+
+Quick checks:
+
+1. Compare `https://<workers-subdomain>/health` and `https://<custom-domain>/health`.
+2. Confirm your route/custom domain points to this Worker.
+3. Review Cloudflare Access/API Shield/WAF rules on the custom hostname.
+4. If deploying with `--env production`, verify that environment is the one bound to the route.
+
+Expected `/health` response includes JSON like:
+
+```json
+{"ok":true,"version":"1.0","peers":0}
+```
+
+## Auto WebRTC two-tab test
+
+The demo defaults to Auto WebRTC and performs real offer/answer + ICE exchange over this Worker.
+
+1. Open `http://127.0.0.1:8787/` in two tabs.
+2. Set both tabs to the same `network` and `session_id`.
+3. Set opposite peer IDs using random hex strings:
+   - Tab A `from`: `fc2142e44ec5c76f1bd46ccbb1eb2ed48f66f64260a5299c871f37ac742fa0c9`
+   - Tab B `from`: `3e45d44c4ce4f9304a53f42b978fd13d23f85df4d97a88f8eb33ec13a2f8f7b1`
+4. Set each tab `to` to the other tab `from`, or leave `to` empty for auto-discovery.
+5. Connect both sockets and click Start Auto Handshake in both tabs.
+6. When DataChannel is open, send chat messages.
+
+## Minimal client expectations
+
+- Send `announce` first to bind socket identity (`from`, `network`).
+- Include `session_id` for negotiation messages.
+- Include `to` for directed messages.
+- Use periodic `announce` to refresh presence TTL and receive queued relay messages.
+- Use `ping` for liveness (`pong`) and keepalive.
+
+## Notes
+
+- TTL is enforced using `timestamp + ttl_ms` (default 30 seconds, max 120 seconds).
+- Malformed envelopes produce [PSP](https://github.com/draeder/Peer-Signaling-Protocol-Specification) `error` responses.
+

package/bin/freertc.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { ensureProjectFiles, resolveProjectRoot, resolveWranglerCommand } from '../scripts/project-bootstrap.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..');
+const PROJECT_ROOT = resolveProjectRoot(process.cwd());
+
+function printHelp() {
+  console.log(`freertc CLI
+
+Usage:
+  freertc
+  freertc wizard
+  freertc setup
+  freertc init
+  freertc install
+  freertc deploy [-- <deploy-args>]
+  freertc dev [-- <dev-args>]
+  freertc dev:cf [-- <dev-args>]
+
+Examples:
+  npx freertc
+  npx freertc wizard
+  npx freertc setup
+  freertc
+  npx freertc deploy
+`);
+}
+
+function runInProject(command, args, { bootstrap = false } = {}) {
+  if (bootstrap) {
+    ensureProjectFiles(PROJECT_ROOT);
+  }
+
+  const result = spawnSync(command, args, {
+    cwd: PROJECT_ROOT,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      FREERTC_PACKAGE_ROOT: PACKAGE_ROOT
+    }
+  });
+
+  if (typeof result.status === 'number') {
+    process.exit(result.status);
+  }
+
+  process.exit(1);
+}
+
+function requireWranglerConfig() {
+  const configPath = path.join(PROJECT_ROOT, 'wrangler.jsonc');
+  if (fs.existsSync(configPath)) {
+    return;
+  }
+
+  console.error(`Missing ${configPath}. Run "npx freertc" or "npx freertc wizard" from this project directory first.`);
+  process.exit(1);
+}
+
+const [, , subcommand, ...rest] = process.argv;
+
+if (!subcommand) {
+  runInProject(process.execPath, [path.join(PACKAGE_ROOT, 'scripts', 'wrangler-install-wizard.mjs'), '--mode', 'both'], { bootstrap: true });
+}
+
+if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+  printHelp();
+  process.exit(0);
+}
+
+if (subcommand === 'wizard') {
+  runInProject(process.execPath, [path.join(PACKAGE_ROOT, 'scripts', 'wrangler-install-wizard.mjs'), ...rest], { bootstrap: true });
+}
+
+if (subcommand === 'setup') {
+  runInProject(process.execPath, [path.join(PACKAGE_ROOT, 'scripts', 'wrangler-install-wizard.mjs'), '--mode', 'both', ...rest], { bootstrap: true });
+}
+
+if (subcommand === 'init' || subcommand === 'install') {
+  runInProject(process.execPath, [path.join(PACKAGE_ROOT, 'scripts', 'wrangler-install-wizard.mjs'), '--mode', 'both', ...rest], { bootstrap: true });
+}
+
+if (subcommand === 'deploy') {
+  ensureProjectFiles(PROJECT_ROOT);
+  requireWranglerConfig();
+  const wrangler = resolveWranglerCommand(PROJECT_ROOT);
+  runInProject(wrangler.command, [...wrangler.baseArgs, 'deploy', '--env', 'production', ...rest]);
+}
+
+if (subcommand === 'dev') {
+  runInProject(process.execPath, [path.join(PACKAGE_ROOT, 'scripts', 'non-cloudflare-server.mjs'), ...rest], { bootstrap: true });
+}
+
+if (subcommand === 'dev:cf' || subcommand === 'dev-cf') {
+  runInProject(process.execPath, [path.join(PACKAGE_ROOT, 'scripts', 'dev-server.mjs'), ...rest], { bootstrap: true });
+}
+
+console.error(`Unknown command: ${subcommand}\n`);
+printHelp();
+process.exit(1);

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "freertc",
+  "version": "0.1.0",
+  "description": "Cloudflare Worker signaling relay for WebRTC peers with D1 storage.",
+  "keywords": [
+    "webrtc",
+    "signaling",
+    "cloudflare-workers",
+    "cloudflare-d1",
+    "websocket"
+  ],
+  "homepage": "https://github.com/draeder/freertc#readme",
+  "bugs": {
+    "url": "https://github.com/draeder/freertc/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/draeder/freertc.git"
+  },
+  "bin": {
+    "freertc": "bin/freertc.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "README.md",
+    "bin/",
+    "public/",
+    "scripts/d1-schema.sql",
+    "scripts/dev-server.mjs",
+    "scripts/non-cloudflare-server.mjs",
+    "scripts/postinstall-message.mjs",
+    "scripts/project-bootstrap.mjs",
+    "scripts/wrangler-install-wizard.mjs",
+    "src/index.js",
+    "wrangler.template.jsonc",
+    "wrangler.workers-dev.jsonc"
+  ],
+  "scripts": {
+    "build": "worker-build --release",
+    "dev": "node scripts/non-cloudflare-server.mjs",
+    "dev:cf": "node scripts/dev-server.mjs",
+    "dev:node": "node scripts/non-cloudflare-server.mjs",
+    "dev:local": "npm run dev:node",
+    "deploy": "wrangler deploy --env production",
+    "deploy:raw": "wrangler deploy",
+    "check": "cargo check --target wasm32-unknown-unknown",
+    "d1:init:local": "wrangler d1 execute freertc-signal --local --file scripts/d1-schema.sql",
+    "d1:init:remote": "wrangler d1 execute freertc-signal --remote --file scripts/d1-schema.sql",
+    "postinstall": "node scripts/postinstall-message.mjs",
+    "wizard": "node scripts/wrangler-install-wizard.mjs",
+    "config:validate": "node scripts/validate-config.mjs",
+    "config:gen": "node scripts/generate-prod-config.mjs",
+    "dev:prod": "npm run config:validate && npm run config:gen && node scripts/prod-server.mjs",
+    "deploy:local-prod": "npm run config:validate && npm run config:gen && docker-compose -f docker-compose.prod.yml up -d",
+    "deploy:local-prod:logs": "docker-compose -f docker-compose.prod.yml logs -f",
+    "deploy:local-prod:stop": "docker-compose -f docker-compose.prod.yml down"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "wrangler": "^3.114.0"
+  }
+}