threadforge 0.1.1 → 0.2.1

package/dist/core/Router.js

@@ -0,0 +1,285 @@
+const ROUTE_CACHE_MAX = 10_000;
+/**
+ * Simple pattern-matching HTTP router.
+ * P11: Includes a route matching cache.
+ */
+export class Router {
+    routes;
+    middleware;
+    _cache;
+    constructor() {
+        this.routes = new Map();
+        this.middleware = [];
+        // P11: Route cache — URL→handler lookups
+        this._cache = new Map();
+    }
+    use(fn) {
+        this.middleware.push(fn);
+    }
+    get(pattern, handler) {
+        this._add("GET", pattern, handler);
+    }
+    post(pattern, handler) {
+        this._add("POST", pattern, handler);
+    }
+    put(pattern, handler) {
+        this._add("PUT", pattern, handler);
+    }
+    patch(pattern, handler) {
+        this._add("PATCH", pattern, handler);
+    }
+    delete(pattern, handler) {
+        this._add("DELETE", pattern, handler);
+    }
+    _add(method, pattern, handler) {
+        const paramNames = [];
+        const isWildcard = pattern.endsWith("/*");
+        // Count literal (non-param, non-wildcard) segments for specificity ranking
+        const segments = pattern.replace(/\/\*$/, "").split("/").filter(Boolean);
+        const literalCount = segments.filter((s) => !s.startsWith(":")).length;
+        const totalSegments = segments.length;
+        const base = isWildcard ? pattern.slice(0, -2) : pattern;
+        // Escape regex-special characters before replacing :param placeholders
+        const escaped = base.replace(/([.*+?^${}()|[\]\\])/g, "\\$1");
+        const regexStr = escaped.replace(/:(\w+)/g, (_, name) => {
+            paramNames.push(name);
+            return "([^/]+)";
+        });
+        if (paramNames.length > 10) {
+            throw new Error(`Route "${pattern}" has ${paramNames.length} params (max 10)`);
+        }
+        let regex;
+        if (isWildcard) {
+            regex = new RegExp(`^${regexStr}(?:/(.*))?$`);
+        }
+        else {
+            regex = new RegExp(`^${regexStr}$`);
+        }
+        const route = {
+            method,
+            pattern,
+            regex,
+            paramNames,
+            handler,
+            isWildcard,
+            literalCount,
+            totalSegments,
+        };
+        if (!this.routes.has(method))
+            this.routes.set(method, []);
+        this.routes.get(method).push(route);
+        // Invalidate route cache when routes change
+        this._cache.clear();
+    }
+    _parseQuery(searchParams) {
+        const result = {};
+        for (const key of searchParams.keys()) {
+            if (key in result)
+                continue; // already processed via getAll
+            const values = searchParams.getAll(key);
+            result[key] = values.length > 1 ? values : values[0];
+        }
+        return result;
+    }
+    _autoOptions(normalized, query) {
+        const methods = new Set();
+        for (const [method, bucket] of this.routes) {
+            for (const route of bucket) {
+                if (normalized.match(route.regex)) {
+                    methods.add(method);
+                    break;
+                }
+            }
+        }
+        if (methods.size === 0)
+            return null;
+        methods.add("OPTIONS");
+        if (methods.has("GET"))
+            methods.add("HEAD");
+        const allow = [...methods].sort().join(", ");
+        return {
+            handler: (_req, res) => {
+                res.writeHead(204, { Allow: allow });
+                res.end();
+            },
+            params: {},
+            query,
+            pattern: "OPTIONS(auto)",
+        };
+    }
+    match(method, url) {
+        // H-SEC-1: Cache by method:pathname only (not full URL with query string).
+        // This prevents cache poisoning via unique query parameters while still
+        // providing the performance benefit of caching route matching.
+        // The query string is still passed to _matchUncached for parsing.
+        const qIdx = url.indexOf("?");
+        const pathname = qIdx === -1 ? url : url.slice(0, qIdx);
+        const cacheKey = `${method}:${pathname}`;
+        const cached = this._cache.get(cacheKey);
+        if (cached !== undefined) {
+            // LRU: Move to end of Map so eviction removes least-recently-used entries
+            this._cache.delete(cacheKey);
+            this._cache.set(cacheKey, cached);
+            // Re-parse query from original url for the cached result
+            if (cached) {
+                let query = {};
+                if (qIdx !== -1) {
+                    try {
+                        query = this._parseQuery(new URL(url, "http://localhost").searchParams);
+                    }
+                    catch {
+                        return null; // Malformed URL — caller should return 400
+                    }
+                }
+                return { ...cached, query };
+            }
+            return cached;
+        }
+        const result = this._matchUncached(method, url);
+        // P11: Store in cache (evict 20% when full). Don't cache null (unmatched)
+        // to prevent attackers filling the cache with misses.
+        if (result !== null) {
+            if (this._cache.size >= ROUTE_CACHE_MAX) {
+                const deleteCount = Math.ceil(ROUTE_CACHE_MAX * 0.2);
+                const iter = this._cache.keys();
+                for (let i = 0; i < deleteCount; i++) {
+                    const key = iter.next().value;
+                    if (key !== undefined)
+                        this._cache.delete(key);
+                }
+            }
+            this._cache.set(cacheKey, result);
+        }
+        return result;
+    }
+    _matchUncached(method, url) {
+        // Reject null bytes — path traversal / request smuggling vector
+        if (url.includes("\0"))
+            return null;
+        let parsed;
+        try {
+            parsed = new URL(url, "http://localhost");
+        }
+        catch {
+            return null; // Malformed URL — caller should return 400
+        }
+        // P-3: Reuse the already-parsed pathname instead of constructing a second URL.
+        // URL constructor already normalizes encoded traversals (e.g. ..%2F).
+        let normalized = parsed.pathname;
+        // Strip trailing slashes (except root "/")
+        if (normalized.length > 1 && normalized.endsWith("/")) {
+            normalized = normalized.slice(0, -1);
+        }
+        const query = this._parseQuery(parsed.searchParams);
+        // HEAD requests match GET routes (RFC 7231 § 4.3.2)
+        const isHead = method === "HEAD";
+        const effectiveMethod = isHead ? "GET" : method;
+        // Collect route buckets to search — only the relevant method(s)
+        const buckets = [];
+        if (this.routes.has(effectiveMethod))
+            buckets.push(this.routes.get(effectiveMethod));
+        if (isHead && this.routes.has("HEAD"))
+            buckets.push(this.routes.get("HEAD"));
+        // Priority tiers: exact > parameterized > wildcard
+        let bestParam = null;
+        let bestParamScore = -1;
+        let bestWildcard = null;
+        let bestWildcardScore = -1;
+        for (const bucket of buckets) {
+            for (const route of bucket) {
+                const match = normalized.match(route.regex);
+                if (!match)
+                    continue;
+                const params = {};
+                let paramTraversal = false;
+                let decodeError = false;
+                route.paramNames.forEach((name, i) => {
+                    let val;
+                    try {
+                        val = decodeURIComponent(match[i + 1]);
+                    }
+                    catch {
+                        decodeError = true;
+                        return;
+                    }
+                    // Detect double-encoding by attempting further decodes (up to 2 iterations)
+                    for (let d = 0; d < 2; d++) {
+                        try {
+                            const decoded = decodeURIComponent(val);
+                            if (decoded === val)
+                                break;
+                            val = decoded;
+                        }
+                        catch {
+                            break;
+                        }
+                    }
+                    if (val.includes("..") || val.includes("\0") || val.includes("%00"))
+                        paramTraversal = true;
+                    params[name] = val;
+                });
+                if (decodeError)
+                    return null;
+                if (paramTraversal)
+                    continue;
+                // Wildcard routes — lowest priority tier
+                if (route.isWildcard) {
+                    const wildcardIndex = route.paramNames.length + 1;
+                    params["*"] = match[wildcardIndex] ?? "";
+                    params.wildcard = params["*"];
+                    const score = route.literalCount * 1000 + route.totalSegments;
+                    if (score > bestWildcardScore) {
+                        bestWildcardScore = score;
+                        bestWildcard = { handler: route.handler, params, query, pattern: route.pattern };
+                    }
+                    continue;
+                }
+                // Exact match (no params) — highest priority, return immediately
+                if (route.paramNames.length === 0) {
+                    return { handler: route.handler, params, query, pattern: route.pattern };
+                }
+                // Parameterized route — pick the most specific
+                const score = route.literalCount * 1000 + route.totalSegments;
+                if (score > bestParamScore) {
+                    bestParamScore = score;
+                    bestParam = { handler: route.handler, params, query, pattern: route.pattern };
+                }
+            }
+        }
+        if (bestParam)
+            return bestParam;
+        if (bestWildcard)
+            return bestWildcard;
+        // Auto OPTIONS if no explicit handler matched
+        if (method === "OPTIONS") {
+            return this._autoOptions(normalized, query);
+        }
+        // 405 Method Not Allowed — path matches but method doesn't
+        const allowedMethods = new Set();
+        for (const [routeMethod, bucket] of this.routes) {
+            for (const route of bucket) {
+                if (normalized.match(route.regex)) {
+                    allowedMethods.add(routeMethod);
+                    break;
+                }
+            }
+        }
+        if (allowedMethods.size > 0) {
+            allowedMethods.add("OPTIONS");
+            if (allowedMethods.has("GET"))
+                allowedMethods.add("HEAD");
+            const allow = [...allowedMethods].sort().join(", ");
+            return {
+                handler: (_req, res) => {
+                    res.writeHead(405, { "Content-Type": "application/json", Allow: allow });
+                    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+                },
+                params: {},
+                query,
+                pattern: "405(auto)",
+            };
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=Router.js.map

package/dist/core/Router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Router.js","sourceRoot":"","sources":["../../src/core/Router.ts"],"names":[],"mappings":"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"}

package/dist/core/RoutingStrategy.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Routing Strategies
+ *
+ * When a service has multiple workers, the proxy needs to decide
+ * which worker handles each request. Different strategies suit
+ * different service patterns.
+ *
+ * Strategies:
+ *
+ *   round-robin     Default. Cycles through workers sequentially.
+ *                   Best for: stateless services, uniform workloads.
+ *
+ *   hash            Routes by a key (e.g., userId). Same key always
+ *                   goes to the same worker. Uses consistent hashing
+ *                   so adding/removing workers only remaps ~1/N keys.
+ *                   Best for: stateful services, in-memory caches,
+ *                   services that benefit from data locality.
+ *
+ *   least-pending   Routes to the worker with fewest in-flight requests.
+ *                   Best for: variable-latency services (DB queries,
+ *                   external API calls).
+ *
+ *   broadcast       Sends to ALL workers. Returns the first response.
+ *                   Best for: search/aggregation across sharded data.
+ *
+ *   primary         Always routes to worker 0. Others are standbys.
+ *                   Best for: singleton services (cron scheduler,
+ *                   leader election).
+ */
+interface WorkerEntry {
+    key: string;
+    socket: unknown;
+    pending: number;
+}
+interface CallContext {
+    __forge_args?: unknown[];
+    __forge_hash?: string | number;
+    [key: string]: unknown;
+}
+interface HashStrategyOptions {
+    key?: string;
+    vnodes?: number;
+    salt?: string;
+}
+interface RoutingStrategy {
+    pick(workers: WorkerEntry[], callContext?: CallContext | null): WorkerEntry | WorkerEntry[] | null;
+    readonly name: string;
+}
+export declare class RoundRobinStrategy implements RoutingStrategy {
+    index: number;
+    constructor();
+    pick(workers: WorkerEntry[], _callContext?: CallContext | null): WorkerEntry | null;
+    get name(): string;
+}
+export declare class HashStrategy implements RoutingStrategy {
+    keyField: string | null;
+    vnodes: number;
+    private _ring;
+    private _workerCacheKey;
+    private _ringHashes;
+    private _ringKeys;
+    private _fallbackCounter;
+    private _salt;
+    constructor(options?: HashStrategyOptions);
+    pick(workers: WorkerEntry[], callContext?: CallContext | null): WorkerEntry | null;
+    private _extractKey;
+    private _buildRing;
+    private _findOnRing;
+    /**
+     * Pre-compute a keyed SHA-256 hash for ring building (called at build time).
+     */
+    private _computeHash;
+    /**
+     * P-1: Fast FNV-1a hash for runtime routing decisions.
+     * Salted to prevent predictable distribution from external input.
+     */
+    private _simpleHash;
+    get name(): string;
+}
+export declare class LeastPendingStrategy implements RoutingStrategy {
+    private _pending;
+    private _lastWorkerKeys;
+    constructor();
+    /**
+     * Pick the worker with the fewest in-flight requests.
+     */
+    pick(workers: WorkerEntry[], _callContext?: CallContext | null): WorkerEntry | null;
+    /** Call when dispatching a request to a worker */
+    acquire(workerKey: string): void;
+    /** Call when a request to a worker completes */
+    release(workerKey: string): void;
+    get name(): string;
+}
+export declare class BroadcastStrategy implements RoutingStrategy {
+    /**
+     * Returns ALL workers. The caller is responsible for sending
+     * to all of them and handling multiple responses.
+     */
+    pick(workers: WorkerEntry[], _callContext?: CallContext | null): WorkerEntry[];
+    get name(): string;
+    get isBroadcast(): boolean;
+}
+export declare class PrimaryStrategy implements RoutingStrategy {
+    /**
+     * Always routes to worker index 0. If worker 0 is down,
+     * routes to the next available.
+     */
+    pick(workers: WorkerEntry[], _callContext?: CallContext | null): WorkerEntry | null;
+    get name(): string;
+}
+/**
+ * Create a routing strategy by name.
+ */
+export declare function createStrategy(name: string, options?: HashStrategyOptions): RoutingStrategy;
+export {};
+//# sourceMappingURL=RoutingStrategy.d.ts.map

package/dist/core/RoutingStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoutingStrategy.d.ts","sourceRoot":"","sources":["../../src/core/RoutingStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,WAAW;IACnB,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,mBAAmB;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,UAAU,eAAe;IACvB,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC;IACnG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAeD,qBAAa,kBAAmB,YAAW,eAAe;IACxD,KAAK,EAAE,MAAM,CAAC;;IAMd,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI;IAOnF,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAID,qBAAa,YAAa,YAAW,eAAe;IAClD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IAEf,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,GAAE,mBAAwB;IAU7C,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI;IA4BlF,OAAO,CAAC,WAAW;IAyBnB,OAAO,CAAC,UAAU;IA+BlB,OAAO,CAAC,WAAW;IAiBnB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAInB,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAID,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAsB;IAEtC,OAAO,CAAC,eAAe,CAAS;;IAOhC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI;IA4BnF,kDAAkD;IAClD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIhC,gDAAgD;IAChD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAgBhC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAID,qBAAa,iBAAkB,YAAW,eAAe;IACvD;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,EAAE;IAI9E,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;CACF;AAID,qBAAa,eAAgB,YAAW,eAAe;IACrD;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI;IAKnF,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAYD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,eAAe,CAM/F"}