feat: group prototype journeys and simplify HTML preview

This commit is contained in:
2026-10-19 10:37:56 +08:00
parent adaa8e4edd
commit 49cd594233
25 changed files with 765 additions and 410 deletions
+218 -276
View File
@@ -1,310 +1,252 @@
#!/usr/bin/env node
/*
* Start a tiny local static server and expose it through Tailscale Serve.
* Node is used for the local server so the Tailscale route only needs to
* proxy a localhost port.
*/
'use strict';
// Serve existing HTML and static assets. No build step, proxy, or network configuration.
const fs = require('node:fs');
const http = require('node:http');
const net = require('node:net');
const os = require('node:os');
const path = require('node:path');
const { spawn, spawnSync } = require('node:child_process');
const crypto = require('node:crypto');
const net = require('node:net');
const { spawn } = require('node:child_process');
class PreviewError extends Error {}
function usage() {
return `Usage: node serve_file.js FILE [--mount-path PATH] [--port PORT] [--ttl SECONDS]
Expose FILE through Tailscale Serve. Node serves FILE's parent directory on
localhost; Tailscale proxies that local server to the tailnet.
`;
class PreviewError extends Error {
constructor(code, message) { super(message); this.code = code; }
}
const fail = (code, message) => { throw new PreviewError(code, message); };
const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const statusPath = '/.previewer-status';
const types = {
'.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8',
'.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
'.mjs': 'text/javascript; charset=utf-8', '.json': 'application/json; charset=utf-8',
'.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
'.gif': 'image/gif', '.webp': 'image/webp', '.ico': 'image/x-icon',
'.woff': 'font/woff', '.woff2': 'font/woff2', '.txt': 'text/plain; charset=utf-8',
'.pdf': 'application/pdf', '.wasm': 'application/wasm',
};
function parseArgs(argv) {
const args = {
file: null, root: null, mountPath: null, port: 80, localPort: 0,
ttl: 3600, tailscalePort: null, server: false,
};
for (let i = 0; i < argv.length; i += 1) {
const value = argv[i];
if (value === '--help' || value === '-h') {
console.log(usage());
process.exit(0);
}
if (value === '--server') {
args.server = true;
continue;
}
if (value === '--root') {
args.root = argv[++i];
continue;
}
if (value === '--mount-path') {
args.mountPath = argv[++i];
continue;
}
if (value === '--port') {
args.port = Number(argv[++i]);
continue;
}
if (value === '--local-port') {
args.localPort = Number(argv[++i]);
continue;
}
if (value === '--ttl') {
args.ttl = Number(argv[++i]);
continue;
}
if (value === '--tailscale-port') {
args.tailscalePort = Number(argv[++i]);
continue;
}
if (value.startsWith('-')) {
throw new PreviewError(`未知参数:${value}`);
}
if (args.file === null) {
args.file = value;
} else {
throw new PreviewError(`多余参数:${value}`);
}
const args = { host: '127.0.0.1', port: 0, ttl: 3600, file: null };
for (let index = 0; index < argv.length; index++) {
const value = argv[index];
if (['--host', '--port', '--ttl'].includes(value)) {
const next = argv[++index];
if (next === undefined || next.startsWith('--')) fail('ARGUMENT', 'Missing value for ' + value);
args[value.slice(2)] = value === '--host' ? next : Number(next);
} else if (value.startsWith('-')) {
fail('ARGUMENT', 'Unknown option: ' + value);
} else if (args.file === null) args.file = value;
else fail('ARGUMENT', 'Unexpected argument: ' + value);
}
if (!args.file) fail('ARGUMENT', 'An HTML or static file is required');
if (args.host === 'localhost') args.host = '127.0.0.1';
if (!net.isIP(args.host)) fail('ARGUMENT', '--host must be an IPv4 or IPv6 address');
if (!Number.isInteger(args.port) || args.port < 0 || args.port > 65535) fail('ARGUMENT', '--port must be 0..65535');
// Node timers use a signed 32-bit millisecond delay.
if (!Number.isInteger(args.ttl) || args.ttl < 1 || args.ttl > 2147483) fail('ARGUMENT', '--ttl must be 1..2147483 seconds');
try {
args.file = fs.realpathSync(path.resolve(args.file));
if (!fs.statSync(args.file).isFile()) fail('FILE_INVALID', 'Input is not a regular file');
} catch (error) {
if (error instanceof PreviewError) throw error;
fail('FILE_INVALID', 'File is unavailable: ' + path.resolve(args.file));
}
return args;
}
function validPort(port, name) {
if (!Number.isInteger(port) || port < 0 || port > 65535 || (name === 'port' && port === 0)) {
throw new PreviewError(`${name} 必须是有效端口`);
}
}
function validTtl(ttl) {
if (!Number.isInteger(ttl) || ttl <= 0) {
throw new PreviewError('ttl 必须是正整数秒数');
}
}
function normalizeMountPath(value) {
const mountPath = value.trim();
if (!mountPath.startsWith('/') || mountPath === '/') {
throw new PreviewError('mount path 必须以 / 开头且不能是根路径');
}
if (mountPath.includes('?') || mountPath.includes('#') || mountPath.includes('//')) {
throw new PreviewError('mount path 不能包含 query、fragment 或空路径段');
}
const parts = mountPath.split('/');
if (parts.some((part) => part === '.' || part === '..')) {
throw new PreviewError('mount path 不能包含 . 或 ..');
}
return mountPath.replace(/\/$/, '');
}
function defaultMountPath(directory) {
const slug = path.basename(directory).replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
if (!slug) {
throw new PreviewError('无法从文件目录生成 mount path,请显式提供 --mount-path');
}
return `/preview/${slug}`;
}
function run(command, commandArgs) {
const result = spawnSync(command, commandArgs, { encoding: 'utf8' });
if (result.error) {
throw new PreviewError(`无法运行 ${command}:${result.error.message}`);
}
return result;
}
function tailscaleIPv4() {
const result = run('tailscale', ['ip', '-4']);
if (result.status !== 0) {
throw new PreviewError(`Tailscale 节点不可用:${(result.stderr || result.stdout).trim() || 'tailscale ip -4 失败'}`);
}
const address = result.stdout.split(/\s+/).find((candidate) => net.isIPv4(candidate));
if (!address) {
throw new PreviewError('tailscale 没有返回 IPv4 地址;请确认节点已连接 tailnet');
}
return address;
}
function checkTailscaleServe() {
const result = run('tailscale', ['serve', 'status', '--json']);
if (result.status !== 0) {
throw new PreviewError(`无法读取 Tailscale Serve 状态:${(result.stderr || result.stdout).trim() || 'status 失败'}`);
}
}
function serveStatic(root, mountPath, port, ttl, tailscalePort) {
const contentTypes = {
'.css': 'text/css; charset=utf-8',
'.gif': 'image/gif',
'.html': 'text/html; charset=utf-8',
'.jpeg': 'image/jpeg',
'.jpg': 'image/jpeg',
'.js': 'text/javascript; charset=utf-8',
'.json': 'application/json; charset=utf-8',
'.png': 'image/png',
'.svg': 'image/svg+xml',
'.txt': 'text/plain; charset=utf-8',
'.webp': 'image/webp',
};
const server = http.createServer((request, response) => {
let pathname;
try {
pathname = decodeURIComponent(new URL(request.url, 'http://127.0.0.1').pathname);
} catch {
response.writeHead(400).end('Bad request');
return;
function urlHost(host) { return net.isIPv6(host) ? '[' + host + ']' : host; }
function probeHost(host) { return host === '0.0.0.0' ? '127.0.0.1' : host === '::' ? '::1' : host; }
function urlsFor(config, port) {
const filename = encodeURIComponent(path.basename(config.file));
const address = probeHost(config.host);
const local = 'http://' + urlHost(address) + ':' + port + '/' + filename;
const urls = [local];
if (config.host === '0.0.0.0' || config.host === '::') {
for (const entries of Object.values(os.networkInterfaces())) for (const entry of entries ?? []) {
if (entry.internal || entry.family !== 'IPv4') continue;
const url = 'http://' + entry.address + ':' + port + '/' + filename;
if (!urls.includes(url)) urls.push(url);
}
if (pathname === mountPath || pathname.startsWith(`${mountPath}/`)) {
pathname = pathname.slice(mountPath.length) || '/';
}
const relativePath = pathname.replace(/^\/+/, '');
const candidate = path.resolve(root, relativePath);
if (candidate !== root && !candidate.startsWith(`${root}${path.sep}`)) {
response.writeHead(403).end('Forbidden');
return;
}
fs.stat(candidate, (statError, info) => {
if (statError || !info.isFile()) {
response.writeHead(404).end('Not found');
}
return { url: local, urls };
}
function probe(state) {
return new Promise((resolve) => {
if (!state || !Number.isInteger(state.port) || typeof state.token !== 'string') return resolve(false);
const request = http.get({
host: probeHost(state.host), port: state.port, path: statusPath,
headers: { 'X-Previewer-Token': state.token }, timeout: 1000,
}, (response) => {
let body = '';
response.on('data', (chunk) => { body += chunk; });
response.on('end', () => {
try {
const actual = JSON.parse(body);
resolve(response.statusCode === 200 && actual.pid === state.pid && actual.key === state.key && actual.file === state.file);
} catch { resolve(false); }
});
response.on('error', () => resolve(false));
});
request.on('error', () => resolve(false));
request.on('timeout', () => { request.destroy(); resolve(false); });
});
}
function publicResult(state, reused) {
const { token, key, ...result } = state;
return { ...result, reused, stopCommand: 'kill -TERM ' + state.pid };
}
function startWorker(config) {
return new Promise((resolve, reject) => {
const child = spawn(process.execPath, [__filename, '--worker'], {
detached: true, stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
});
let diagnostics = '';
child.stderr.on('data', (chunk) => { diagnostics += chunk; });
const timer = setTimeout(() => {
child.kill();
reject(new PreviewError('START_TIMEOUT', 'Static server did not become ready'));
}, 5000);
child.once('message', (message) => {
clearTimeout(timer);
if (message.error) {
child.kill();
reject(new PreviewError(message.code ?? 'START_FAILED', message.error));
return;
}
response.setHeader('Content-Type', contentTypes[path.extname(candidate).toLowerCase()] || 'application/octet-stream');
fs.createReadStream(candidate).on('error', () => response.destroy()).pipe(response);
});
});
server.listen(port, '127.0.0.1', () => {
const address = server.address();
console.log(`READY ${address.port}`);
});
setTimeout(() => {
spawnSync('tailscale', [
'serve', `--http=${tailscalePort}`, `--set-path=${mountPath}`, 'off',
], { stdio: 'ignore' });
server.close(() => process.exit(0));
setTimeout(() => process.exit(0), 1000);
}, ttl * 1000);
}
function startDetachedServer(root, mountPath, localPort, ttl, tailscalePort) {
const child = spawn(process.execPath, [
__filename, '--server', '--root', root, '--mount-path', mountPath,
'--port', String(localPort), '--ttl', String(ttl), '--tailscale-port', String(tailscalePort),
], {
detached: true,
stdio: ['ignore', 'pipe', 'pipe'],
});
return new Promise((resolve, reject) => {
let output = '';
const timeout = setTimeout(() => {
child.kill();
reject(new PreviewError('Node 静态服务启动超时'));
}, 5000);
child.stdout.on('data', (chunk) => {
output += chunk.toString();
const match = output.match(/READY (\d+)/);
if (!match) return;
clearTimeout(timeout);
child.stdout.destroy();
child.disconnect();
child.stderr.destroy();
child.unref();
resolve({ pid: child.pid, port: Number(match[1]) });
resolve(message);
});
child.on('error', (error) => {
clearTimeout(timeout);
reject(new PreviewError(`Node 静态服务启动失败:${error.message}`));
child.once('error', (error) => {
clearTimeout(timer);
reject(new PreviewError('START_FAILED', error.message));
});
child.on('exit', (code) => {
if (code !== null && code !== 0) {
clearTimeout(timeout);
reject(new PreviewError(`Node 静态服务退出,code=${code}`));
}
child.once('exit', (code) => {
clearTimeout(timer);
reject(new PreviewError('START_FAILED', 'Static server exited: ' + code + ' ' + diagnostics.trim()));
});
child.send(config);
});
}
function stopChild(pid) {
if (!pid) return;
try {
process.kill(pid, 'SIGTERM');
} catch {
// The child may have exited while Tailscale was being configured.
}
}
async function launch(args) {
if (!args.file) throw new PreviewError('缺少要展示的文件');
validPort(args.port, 'port');
validPort(args.localPort, 'local-port');
validTtl(args.ttl);
const filePath = path.resolve(args.file);
let info;
try {
info = fs.statSync(filePath);
} catch {
throw new PreviewError(`输入文件不存在:${filePath}`);
}
if (!info.isFile()) throw new PreviewError(`输入不是普通文件:${filePath}`);
const root = path.dirname(filePath);
const mountPath = args.mountPath ? normalizeMountPath(args.mountPath) : defaultMountPath(root);
const ip = tailscaleIPv4();
checkTailscaleServe();
const child = await startDetachedServer(root, mountPath, args.localPort, args.ttl, args.port);
try {
const result = run('tailscale', [
'serve', '--bg', `--http=${args.port}`, `--set-path=${mountPath}`, '--yes',
`http://127.0.0.1:${child.port}`,
]);
if (result.status !== 0) {
throw new PreviewError(`Tailscale Serve 配置失败:${(result.stderr || result.stdout).trim() || 'serve 命令失败'}`);
async function launch(config) {
const root = path.dirname(config.file);
const key = crypto.createHash('sha256').update(JSON.stringify(config)).digest('hex');
const stateDir = path.join(os.tmpdir(), 'previewer-' + (process.getuid?.() ?? os.userInfo().username));
fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
const statePath = path.join(stateDir, key + '.json');
const lockPath = statePath + '.lock';
let locked = false;
for (let attempt = 0; attempt < 120; attempt++) {
try { fs.mkdirSync(lockPath); locked = true; break; }
catch (error) {
if (error.code !== 'EEXIST') throw error;
try {
// Recover an empty lock left by a launcher that crashed.
if (Date.now() - fs.statSync(lockPath).mtimeMs > 15000) fs.rmdirSync(lockPath);
} catch {}
await delay(50);
}
}
if (!locked) fail('BUSY', 'Another launcher is starting this preview; retry shortly');
let childState;
try {
let previous;
try { previous = JSON.parse(fs.readFileSync(statePath, 'utf8')); } catch {}
if (previous && await probe(previous)) return publicResult(previous, true);
childState = await startWorker({ ...config, root, key, statePath, token: crypto.randomUUID() });
if (!await probe(childState)) fail('VERIFY_FAILED', 'Static server readiness check failed');
fs.writeFileSync(statePath, JSON.stringify(childState), { mode: 0o600 });
return publicResult(childState, false);
} catch (error) {
stopChild(child.pid);
if (childState?.pid) { try { process.kill(childState.pid, 'SIGTERM'); } catch {} }
throw error;
} finally {
fs.rmdirSync(lockPath);
}
const relative = path.relative(root, filePath).split(path.sep).map(encodeURIComponent).join('/');
const suffix = args.port === 80 ? '' : `:${args.port}`;
const url = `http://${ip}${suffix}${mountPath}/${relative}`;
console.log(JSON.stringify({
file: filePath,
directory: root,
mountPath,
ip,
port: args.port,
localPort: child.port,
pid: child.pid,
ttl: args.ttl,
expiresAt: new Date(Date.now() + args.ttl * 1000).toISOString(),
url,
stopCommand: `kill ${child.pid} 2>/dev/null || true; tailscale serve --http=${args.port} --set-path=${mountPath} off`,
}));
}
async function main() {
const args = parseArgs(process.argv.slice(2));
if (args.server) {
if (!args.mountPath || !args.root || !args.tailscalePort) throw new PreviewError('内部参数不完整');
validPort(args.port, 'local-port');
validPort(args.tailscalePort, 'port');
validTtl(args.ttl);
serveStatic(path.resolve(args.root), args.mountPath, args.port, args.ttl, args.tailscalePort);
return;
function runWorker(config) {
let shuttingDown = false;
let timer;
let state;
const server = http.createServer((request, response) => {
if (!['GET', 'HEAD'].includes(request.method)) {
response.writeHead(405, { Allow: 'GET, HEAD' }).end('Method not allowed');
return;
}
let pathname;
try { pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname); }
catch { response.writeHead(400).end('Bad request'); return; }
if (pathname === statusPath) {
if (request.headers['x-previewer-token'] !== config.token) { response.writeHead(404).end('Not found'); return; }
response.setHeader('Content-Type', 'application/json');
response.end(request.method === 'HEAD' ? undefined : JSON.stringify(state));
return;
}
let candidate;
try {
const relative = pathname === '/' ? path.basename(config.file) : pathname.replace(/^\/+/, '');
candidate = fs.realpathSync(path.resolve(config.root, relative));
const inside = path.relative(config.root, candidate);
if (inside === '..' || inside.startsWith('..' + path.sep) || path.isAbsolute(inside)) {
response.writeHead(403).end('Forbidden');
return;
}
// Explicit filenames only; no directory listings.
if (!fs.statSync(candidate).isFile()) { response.writeHead(404).end('Not found'); return; }
} catch { response.writeHead(404).end('Not found'); return; }
response.writeHead(200, {
'Content-Type': types[path.extname(candidate).toLowerCase()] ?? 'application/octet-stream',
'Cache-Control': 'no-store',
'X-Content-Type-Options': 'nosniff',
});
if (request.method === 'HEAD') { response.end(); return; }
fs.createReadStream(candidate).on('error', () => response.destroy()).pipe(response);
});
function shutdown() {
if (shuttingDown) return;
shuttingDown = true;
clearTimeout(timer);
try {
const record = JSON.parse(fs.readFileSync(config.statePath, 'utf8'));
if (record.pid === process.pid && record.token === config.token) fs.unlinkSync(config.statePath);
} catch {}
server.close(() => process.exit(0));
setTimeout(() => process.exit(0), 1000).unref();
}
await launch(args);
process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);
server.once('error', (error) => {
process.send?.({ code: error.code === 'EADDRINUSE' ? 'PORT_IN_USE' : 'START_FAILED', error: error.message });
process.exitCode = 2;
});
server.listen(config.port, config.host, () => {
const port = server.address().port;
state = {
file: config.file, directory: config.root, host: config.host, port, pid: process.pid,
ttl: config.ttl, expiresAt: new Date(Date.now() + config.ttl * 1000).toISOString(),
...urlsFor(config, port), token: config.token, key: config.key,
};
timer = setTimeout(shutdown, config.ttl * 1000);
process.send?.(state);
});
}
main().catch((error) => {
console.error(`previewer: ${error.message}`);
process.exitCode = 2;
});
if (process.argv[2] === '--worker') {
process.once('message', runWorker);
} else if (process.argv.includes('--help') || process.argv.includes('-h')) {
console.log('Usage: node serve_file.js FILE [--host IP] [--port PORT] [--ttl SECONDS]\nServe existing HTML/static assets. Defaults: 127.0.0.1, automatic port, 3600 seconds.');
} else {
Promise.resolve().then(() => launch(parseArgs(process.argv.slice(2)))).then((result) => {
console.log(JSON.stringify(result));
}).catch((error) => {
console.error(JSON.stringify({ code: error.code ?? 'PREVIEW_FAILED', message: error.message }));
process.exitCode = 2;
});
}