pi-freeflow 1.2.0 → 1.2.1

package/src/proxy.ts

@@ -0,0 +1,467 @@
+/**
+ * Single-port local HTTP proxy and dynamic upstream router for pi-freeflow
+ *
+ * Provides loopback proxying on port 18080 (shared across parent and subagents),
+ * intelligent routing to OpenCode Zen and KiloCode Gateway, and failover support.
+ */
+
+import { randomUUID } from "node:crypto";
+import * as http from "node:http";
+import * as https from "node:https";
+import { Readable } from "node:stream";
+import type { ReadableStream as WebReadableStream } from "node:stream/web";
+import { getAliveCatalog } from "./catalog.ts";
+import {
+	ALLOWED_METHODS,
+	ALLOWED_PATH_PATTERN,
+	HOST,
+	KILO_CHAT_URL,
+	PATH_TRAVERSAL_PATTERN,
+	PORT,
+	STRIP_HEADERS,
+	UPSTREAM_OPENCODE,
+	opencodeHeaders,
+} from "./config.ts";
+import { isDebugEnabled, log } from "./logger.ts";
+import { KILO_MODEL_IDS } from "./models.ts";
+import { normalizeRequestBody } from "./normalizer.ts";
+import { checkRateLimit } from "./rate-limiter.ts";
+import { relayFetch } from "./relay.ts";
+import { getActiveRelayState } from "./relay-state.ts";
+import { pipeUpstreamStream } from "./stream-pipe.ts";
+import type { Upstream } from "./types.ts";
+
+/**
+ * Extract client IP address from incoming HTTP request.
+ */
+export function getClientIP(req: http.IncomingMessage): string {
+	const addr = req.socket.remoteAddress;
+	if (!addr) return "unknown";
+	return addr.startsWith("::ffff:") ? addr.slice(7) : addr;
+}
+
+/**
+ * Validate that the request URL matches allowed API path patterns and prevents path traversal.
+ */
+export function validatePath(rawUrl: string): URL | null {
+	const cleaned = rawUrl.replace(/^\/+/, "");
+	if (!ALLOWED_PATH_PATTERN.test(`/${cleaned}`)) return null;
+	if (PATH_TRAVERSAL_PATTERN.test(cleaned)) return null;
+	try {
+		const decoded = decodeURIComponent(cleaned);
+		if (decoded !== cleaned && !ALLOWED_PATH_PATTERN.test(`/${decoded}`)) {
+			return null;
+		}
+	} catch {
+		return null;
+	}
+	try {
+		return new URL(cleaned, `${UPSTREAM_OPENCODE}/`);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Sanitize and inject standard headers before forwarding request to upstream.
+ */
+export function sanitizeHeaders(
+	incoming: http.IncomingHttpHeaders,
+	targetHost: string,
+): Record<string, string> {
+	const sanitized: Record<string, string> = {};
+	for (const [key, value] of Object.entries(incoming)) {
+		const lower = key.toLowerCase();
+		if (STRIP_HEADERS.has(lower) || lower.startsWith(":")) continue;
+		if (typeof value === "string") sanitized[lower] = value;
+		else if (Array.isArray(value)) sanitized[lower] = value.join(", ");
+	}
+	sanitized.host = targetHost;
+	// Drop the client's own user-agent so opencodeHeaders() cannot produce a
+	// duplicate (case-differing) User-Agent pair — upstream resets connections
+	// that send two conflicting User-Agent headers.
+	delete sanitized["user-agent"];
+	Object.assign(sanitized, opencodeHeaders());
+	sanitized["accept-encoding"] = "identity";
+	sanitized.connection = "keep-alive";
+	return sanitized;
+}
+
+/**
+ * Probe whether an existing pi-freeflow proxy daemon is running and responsive on a given port.
+ */
+export async function isProxyAlive(port: number): Promise<boolean> {
+	try {
+		const res = await fetch(`http://${HOST}:${port}/v1/models`, {
+			signal: AbortSignal.timeout(500),
+		});
+		const ct = res.headers.get("content-type") || "";
+		return res.ok && ct.includes("application/json");
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Start the local HTTP proxy daemon.
+ *
+ * Implements master/worker single-port reuse: if port 18080 is already held by a live
+ * parent or sibling OMP session, resolves immediately with { server: null, port: 18080 }.
+ */
+export function startProxy(
+	overridePort?: number,
+): Promise<{ server: http.Server | null; port: number }> {
+	const basePort = overridePort ?? PORT;
+
+	const server = http.createServer((req, res) => {
+		const clientIP = getClientIP(req);
+		const reqId = randomUUID().slice(0, 8);
+		if (isDebugEnabled()) {
+			log(
+				"debug",
+				`incoming ${req.method} ${req.url} from ${clientIP}`,
+				{ ip: clientIP, method: req.method, url: req.url },
+				reqId,
+			);
+		}
+
+		if (!ALLOWED_METHODS.has(req.method ?? "")) {
+			res.writeHead(405, { "content-type": "application/json" });
+			res.end(JSON.stringify({ error: "method not allowed" }));
+			return;
+		}
+
+		if (req.method === "OPTIONS") {
+			res.writeHead(204, {
+				"access-control-allow-origin": "*",
+				"access-control-allow-methods": "GET, POST, OPTIONS",
+				"access-control-max-age": "86400",
+			});
+			res.end();
+			return;
+		}
+
+		// Serve ONLY our registered free models. Never forward /v1/models to upstream
+		// to prevent paid/proprietary upstream models from leaking into the model picker.
+		if (
+			req.method === "GET" &&
+			(req.url === "/v1/models" || req.url === "/v1/models/")
+		) {
+			const alive = getAliveCatalog();
+			const body = JSON.stringify({
+				object: "list",
+				data: alive.map((m) => ({
+					id: m.id,
+					object: "model",
+					created: 0,
+					owned_by: m.source === "kilo" ? "kilocode" : "opencode",
+				})),
+			});
+			res.writeHead(200, {
+				"content-type": "application/json",
+				"content-length": Buffer.byteLength(body),
+			});
+			res.end(body);
+			return;
+		}
+
+		const target = validatePath(req.url ?? "/");
+		if (!target) {
+			res.writeHead(403, { "content-type": "application/json" });
+			res.end(JSON.stringify({ error: "forbidden" }));
+			return;
+		}
+
+		// Buffer request body to inspect model ID for upstream routing
+		const bodyChunks: Buffer[] = [];
+		req.on("error", (err) => {
+			log(
+				"warn",
+				"client request error during body buffering",
+				{ error: String(err) },
+				reqId,
+			);
+			if (!res.headersSent) {
+				res.writeHead(400, { "content-type": "application/json" });
+			}
+			res.end(JSON.stringify({ error: "bad request" }));
+		});
+
+		req.on("data", (chunk: Buffer) => bodyChunks.push(chunk));
+
+		req.on("end", async () => {
+			const bodyStr = Buffer.concat(bodyChunks).toString();
+			let isKilo = false;
+			let parsedBody: Record<string, unknown> | null = null;
+
+			try {
+				parsedBody = JSON.parse(bodyStr);
+				if (
+					typeof parsedBody?.model === "string" &&
+					KILO_MODEL_IDS.has(parsedBody.model)
+				) {
+					isKilo = true;
+				}
+			} catch {}
+
+			const upstream: Upstream = isKilo ? "kilo" : "opencode";
+			const isStream = parsedBody?.stream === true;
+
+			if (!checkRateLimit(clientIP, upstream)) {
+				res.writeHead(429, { "content-type": "application/json" });
+				res.end(JSON.stringify({ error: "rate limit exceeded" }));
+				return;
+			}
+
+			try {
+				if (isKilo && parsedBody) {
+					const kiloBodyObj = structuredClone(parsedBody);
+					normalizeRequestBody(kiloBodyObj, true, isKilo, reqId);
+					const response = await relayFetch(
+						KILO_CHAT_URL,
+						{
+							method: "POST",
+							headers: {
+								"Content-Type": "application/json",
+								Authorization: "Bearer kilo-free",
+							},
+							body: JSON.stringify(kiloBodyObj),
+							signal: AbortSignal.timeout(300_000),
+						},
+						reqId,
+					);
+
+					if (isStream && response.ok && response.body) {
+						const ct =
+							response.headers.get("content-type") || "text/event-stream";
+						res.writeHead(response.status, {
+							"content-type": ct,
+							"cache-control": "no-cache, no-transform",
+							connection: "keep-alive",
+							"x-accel-buffering": "no",
+						});
+						pipeUpstreamStream(
+							Readable.fromWeb(
+								response.body as unknown as WebReadableStream,
+							),
+							res,
+							req,
+							reqId,
+						);
+					} else {
+						const data = await response.text();
+						const ct =
+							response.headers.get("content-type") || "application/json";
+						res.writeHead(response.status, { "content-type": ct });
+						res.end(data);
+					}
+				} else {
+					// OpenCode routing — relay when enabled, else direct upstream
+					const relayState = getActiveRelayState();
+					if (
+						relayState.enabled &&
+						(relayState.url || relayState.relays.length > 0)
+					) {
+						const fullUrl = `${UPSTREAM_OPENCODE}${req.url ?? "/"}`;
+						const activeHost = relayState.url
+							? new URL(relayState.url).host
+							: "opencode.ai";
+						const relayHeaders = sanitizeHeaders(req.headers, activeHost);
+
+						try {
+							if (parsedBody) {
+								const relayBodyObj = structuredClone(parsedBody);
+								normalizeRequestBody(relayBodyObj, true, isKilo, reqId);
+								const relayBody = Buffer.from(JSON.stringify(relayBodyObj));
+								const response = await relayFetch(
+									fullUrl,
+									{
+										method: req.method || "POST",
+										headers: relayHeaders,
+										body: relayBody,
+										signal: AbortSignal.timeout(300_000),
+									},
+									reqId,
+								);
+
+								if (isStream && response.ok && response.body) {
+									const ct =
+										response.headers.get("content-type") ||
+										"text/event-stream";
+									res.writeHead(response.status, {
+										"content-type": ct,
+										"cache-control": "no-cache, no-transform",
+										connection: "keep-alive",
+										"x-accel-buffering": "no",
+									});
+									pipeUpstreamStream(
+										Readable.fromWeb(
+											response.body as unknown as WebReadableStream,
+										),
+										res,
+										req,
+										reqId,
+									);
+								} else {
+									const data = await response.text();
+									const ct =
+										response.headers.get("content-type") ||
+										"application/json";
+									res.writeHead(response.status, { "content-type": ct });
+									res.end(data);
+								}
+								return; // relay handled successfully
+							}
+						} catch (e) {
+							log(
+								"warn",
+								"opencode relay failed, falling back to direct upstream",
+								{ error: String(e) },
+								reqId,
+							);
+							if (res.headersSent) return; // cannot recover mid-stream
+						}
+					}
+
+					// Direct path — with debug trace and thinking-aware normalization
+					let directBody = Buffer.concat(bodyChunks);
+					if (parsedBody) {
+						const directBodyObj = structuredClone(parsedBody);
+						normalizeRequestBody(directBodyObj, false, isKilo, reqId);
+						directBody = Buffer.from(JSON.stringify(directBodyObj));
+					}
+
+					if (isDebugEnabled()) {
+						log(
+							"debug",
+							`direct upstream ${target.hostname}${target.pathname} (${directBody.length}B)`,
+							{ model: parsedBody?.model, isKilo },
+							reqId,
+						);
+					}
+
+					const fwd = sanitizeHeaders(req.headers, target.hostname);
+					if (directBody.length > 0) {
+						fwd["content-length"] = String(directBody.byteLength);
+					}
+
+					const proxy = https.request(
+						{
+							method: req.method,
+							hostname: target.hostname,
+							port: 443,
+							path: target.pathname + target.search,
+							headers: fwd,
+						},
+						(upstream) => {
+							const outHeaders: Record<string, string> = {};
+							for (const h of [
+								"content-type",
+								"cache-control",
+								"x-request-id",
+							]) {
+								const val = upstream.headers[h];
+								if (typeof val === "string") outHeaders[h] = val;
+							}
+							outHeaders["x-content-type-options"] = "nosniff";
+							res.writeHead(upstream.statusCode ?? 502, outHeaders);
+							upstream.on("error", (streamErr) => {
+								log(
+									"error",
+									"upstream stream error in direct proxy",
+									{ error: String(streamErr) },
+									reqId,
+								);
+								if (!res.writableEnded) res.end();
+							});
+							upstream.pipe(res);
+						},
+					);
+
+					proxy.on("error", (proxyErr) => {
+						log(
+							"error",
+							"proxy socket error",
+							{ error: String(proxyErr) },
+							reqId,
+						);
+						if (!res.headersSent) {
+							res.writeHead(502, { "content-type": "application/json" });
+							res.end(JSON.stringify({ error: "upstream error" }));
+						} else if (!res.writableEnded) {
+							res.end();
+						}
+					});
+
+					proxy.setTimeout(300_000, () => {
+						proxy.destroy(new Error("timeout"));
+					});
+
+					// Premature client disconnect guard.
+					// Node >= 19 emits req 'close' right after the request body 'end',
+					// so destroying on req close/aborted kills every healthy upstream
+					// socket milliseconds after creation. Only tear down when the
+					// client response connection actually drops mid-flight.
+					const destroyIfClientGone = () => {
+						if (!res.writableEnded && !proxy.destroyed) proxy.destroy();
+					};
+					req.on("error", destroyIfClientGone);
+					res.on("close", destroyIfClientGone);
+
+					proxy.end(directBody);
+				}
+			} catch (err) {
+				log("error", "proxy error", { error: String(err) }, reqId);
+				if (!res.headersSent) {
+					res.writeHead(502, { "content-type": "application/json" });
+				}
+				res.end(JSON.stringify({ error: "internal error" }));
+			}
+		});
+	});
+
+	return new Promise<{ server: http.Server | null; port: number }>(
+		(resolve, reject) => {
+			let attempt = 0;
+			let settled = false;
+
+			const tryListen = async (port: number) => {
+				server.once("error", async (err: NodeJS.ErrnoException) => {
+					if (settled) return;
+					if (err.code === "EADDRINUSE") {
+						// Re-check if the base port is alive (attached master race)
+						if (await isProxyAlive(basePort)) {
+							settled = true;
+							log(
+								"info",
+								`attached to running proxy on http://${HOST}:${basePort}`,
+							);
+							resolve({ server: null, port: basePort });
+							return;
+						}
+						if (attempt < 20) {
+							attempt++;
+							log("warn", `port ${port} taken — trying ${port + 1}`);
+							tryListen(port + 1);
+							return;
+						}
+					}
+					settled = true;
+					log("error", "server error", { code: err.code, message: err.message });
+					reject(err);
+				});
+
+				server.listen(port, HOST, () => {
+					if (settled) return;
+					settled = true;
+					const addr = server.address();
+					const realPort = addr && typeof addr === "object" ? addr.port : port;
+					log("info", `proxy listening on http://${HOST}:${realPort}`);
+					resolve({ server, port: realPort });
+				});
+			};
+
+			tryListen(basePort);
+		},
+	);
+}

package/src/rate-limiter.ts

@@ -0,0 +1,148 @@
+/**
+ * Memory-safe sliding rate limiter for pi-freeflow
+ * Enforces:
+ *  - OpenCode Zen: 200 requests per UTC day per IP
+ *  - KiloCode Gateway: 200 requests per 1-hour window per IP
+ */
+
+import { RATE_LIMIT_MAX } from "./config.ts";
+import type { RateLimitEntry, RateLimitStatus, Upstream } from "./types.ts";
+
+const rateLimitMap = new Map<string, RateLimitEntry>();
+let lastCleanupAt = 0;
+const CLEANUP_INTERVAL_MS = 60_000; // 1 minute
+const MAX_MAP_SIZE_BEFORE_CLEANUP = 500;
+
+/**
+ * Calculate the next reset timestamp in epoch milliseconds.
+ */
+export function rateLimitResetAt(upstream: Upstream, now: number): number {
+	if (upstream === "kilo") {
+		return now + 60 * 60_000; // 1 hour sliding window
+	}
+	// OpenCode resets at 00:00:00.000 UTC of next day
+	const nextUtcDay = new Date(now);
+	nextUtcDay.setUTCHours(24, 0, 0, 0);
+	return nextUtcDay.getTime();
+}
+
+/**
+ * Construct a cache key for an upstream + client IP.
+ */
+export function rateLimitKey(
+	upstream: Upstream,
+	ip: string,
+	now: number = Date.now(),
+): string {
+	const safeIp = ip.trim() || "127.0.0.1";
+	if (upstream === "kilo") {
+		return `kilo:${safeIp}`;
+	}
+	const utcDate = new Date(now).toISOString().slice(0, 10);
+	return `opencode:${utcDate}:${safeIp}`;
+}
+
+/**
+ * Purge expired rate limit buckets to guarantee bounded memory usage.
+ * Returns the number of evicted entries.
+ */
+export function cleanupRateLimits(now: number = Date.now()): number {
+	let evicted = 0;
+	for (const [key, entry] of rateLimitMap.entries()) {
+		if (entry.resetAt <= now) {
+			rateLimitMap.delete(key);
+			evicted++;
+		}
+	}
+	lastCleanupAt = now;
+	return evicted;
+}
+
+/**
+ * Trigger cleanup if interval elapsed or map has grown past the high watermark.
+ */
+function maybeCleanup(now: number): void {
+	if (
+		now - lastCleanupAt > CLEANUP_INTERVAL_MS ||
+		rateLimitMap.size > MAX_MAP_SIZE_BEFORE_CLEANUP
+	) {
+		cleanupRateLimits(now);
+	}
+}
+
+/**
+ * Check and consume a quota token for the given IP and upstream.
+ * Returns true if request is permitted, false if rate limit exceeded.
+ */
+export function checkRateLimit(
+	ip: string,
+	upstream: Upstream,
+	now: number = Date.now(),
+): boolean {
+	maybeCleanup(now);
+
+	const key = rateLimitKey(upstream, ip, now);
+	const entry = rateLimitMap.get(key);
+	const maxLimit = RATE_LIMIT_MAX[upstream] ?? 200;
+
+	if (!entry || entry.resetAt <= now) {
+		rateLimitMap.set(key, {
+			count: 1,
+			resetAt: rateLimitResetAt(upstream, now),
+		});
+		return true;
+	}
+
+	if (entry.count >= maxLimit) {
+		return false;
+	}
+
+	entry.count++;
+	return true;
+}
+
+/**
+ * Query current rate limit quota and remaining requests without mutating count.
+ */
+export function getRateLimitStatus(
+	ip: string,
+	upstream: Upstream,
+	now: number = Date.now(),
+): RateLimitStatus {
+	const key = rateLimitKey(upstream, ip, now);
+	const entry = rateLimitMap.get(key);
+	const limit = RATE_LIMIT_MAX[upstream] ?? 200;
+
+	if (!entry || entry.resetAt <= now) {
+		return {
+			allowed: true,
+			remaining: limit,
+			resetAt: rateLimitResetAt(upstream, now),
+			limit,
+			count: 0,
+		};
+	}
+
+	const remaining = Math.max(0, limit - entry.count);
+	return {
+		allowed: remaining > 0,
+		remaining,
+		resetAt: entry.resetAt,
+		limit,
+		count: entry.count,
+	};
+}
+/**
+ * Clear all rate limit records (primarily for testing and reset commands).
+ */
+export function resetRateLimits(): void {
+	rateLimitMap.clear();
+	lastCleanupAt = Date.now();
+}
+
+/**
+ * Get active count of entries in the rate limit table.
+ */
+export function getRateLimitMapSize(): number {
+	return rateLimitMap.size;
+}