threadforge 0.1.0 → 0.2.1

package/dist/decorators/ServiceProxy.d.ts

@@ -0,0 +1,175 @@
+/**
+ * ServiceProxy v2
+ *
+ * Auto-generates proxy clients with:
+ *   - Pluggable routing strategies (round-robin, hash, least-pending)
+ *   - Interceptor chains (deadline, logging, circuit breaker, retry)
+ *   - Pending request tracking (for least-pending routing)
+ *   - Contract-based method validation
+ */
+import http from "node:http";
+import type { ForgeContext } from "../core/ForgeContext.js";
+import { type RpcConfig } from "../core/RpcConfig.js";
+import type { ServiceClassLike, ServiceContract } from "./index.js";
+interface RetryConfig {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+interface LocalServiceInstance {
+    service: Record<string, unknown>;
+    ctx: ForgeContext;
+}
+interface ConcurrencyLimiterConfig {
+    initialLimit?: number;
+    minLimit?: number;
+    maxLimit?: number;
+    smoothing?: number;
+    tolerance?: number;
+}
+interface ProxyOptions {
+    interceptors?: Record<string, unknown>;
+    routingStrategy?: string;
+    retry?: RetryConfig | false;
+    circuitBreaker?: import("../core/RpcConfig.js").CircuitBreakerOptions;
+    bulkhead?: import("../core/RpcConfig.js").BulkheadOptions;
+    concurrency?: ConcurrencyLimiterConfig;
+    defaultTimeout?: number;
+    rpcConfig?: RpcConfig;
+    pool?: RpcPoolConfig;
+}
+export interface ServiceInstance {
+    ctx?: {
+        serviceName?: string;
+    } | null;
+    constructor: Function;
+    onMessage: (from: string, payload: unknown) => Promise<unknown>;
+    [key: string]: unknown;
+}
+interface ProxyRequestPayload {
+    __forge_method?: string;
+    __forge_args?: unknown[];
+    __forge_deadline?: number | string;
+    __forge_event?: string;
+    __forge_data?: unknown;
+    [key: string]: unknown;
+}
+interface ConcurrencyStats {
+    [name: string]: unknown;
+}
+/**
+ * Default pool limits for the shared HTTP agent used by remote RPC.
+ * Configurable via environment variables:
+ *   FORGE_RPC_MAX_SOCKETS — max concurrent sockets across all hosts (default 256)
+ *   FORGE_RPC_MAX_SOCKETS_PER_HOST — max concurrent sockets per host (default 64)
+ *   FORGE_RPC_KEEPALIVE_MS — keepalive timeout in ms (default 30000)
+ * Also configurable via ProxyOptions.pool.
+ */
+export interface RpcPoolConfig {
+    maxSockets?: number;
+    maxSocketsPerHost?: number;
+    keepAliveMs?: number;
+}
+/**
+ * Get or create the shared HTTP agent for remote RPC connections.
+ * Uses connection pooling with keepalive to avoid per-request TCP setup.
+ */
+export declare function _getRpcAgent(config?: RpcPoolConfig): http.Agent;
+/**
+ * Destroy the shared RPC agent (for test teardown / graceful shutdown).
+ */
+export declare function _destroyRpcAgent(): void;
+/**
+ * Stop the signature cache (for cleanup/testing).
+ */
+export declare function _stopSignatureCache(): void;
+/** Start (or restart) the periodic rate-limit bucket cleanup timer. */
+export declare function _startRateLimitCleanup(): void;
+/** Stop the periodic rate-limit bucket cleanup timer (for test teardown). */
+export declare function _stopRateLimitCleanup(): void;
+/** Sentinel returned by handleProxyRequest when the message isn't a proxy request. */
+export declare const NOT_HANDLED: unique symbol;
+/** Expose for status endpoints */
+export declare function getAllConcurrencyStats(): ConcurrencyStats;
+/**
+ * Build proxy clients for all services this service connects to.
+ */
+export declare function buildServiceProxies(ctx: ForgeContext, serviceClasses: Map<string, ServiceClassLike>, localServices?: Map<string, LocalServiceInstance>, options?: ProxyOptions): Record<string, unknown>;
+/**
+ * Create a proxy client for a single target service.
+ */
+export declare function createServiceProxy(ctx: ForgeContext, targetName: string, contract: ServiceContract | null, localInstance: LocalServiceInstance | null, options: ProxyOptions): Record<string, unknown>;
+/**
+ * Handle an incoming proxy-style RPC request on the receiving service.
+ *
+ * Detects the __forge_method convention, checks deadlines,
+ * validates the method is exposed, and dispatches.
+ */
+export declare function handleProxyRequest(service: ServiceInstance, from: string, payload: ProxyRequestPayload | null | undefined): unknown | typeof NOT_HANDLED;
+/**
+ * Auto-register HTTP routes from @Route decorator / contract metadata.
+ *
+ * For every route declared via `@Route(method, path)` or the plain-JS
+ * `static contract = { routes: [...] }`, this function registers the
+ * corresponding handler on the service's HTTP router.
+ *
+ * **Contract route handler signature:**
+ *
+ *   async handler(body, params, query) -> result
+ *
+ * - `body`   — parsed request body (`req.body`)
+ * - `params` — URL path parameters (`req.params`), e.g. `{ id: '42' }` for `/users/:id`
+ * - `query`  — query-string parameters (`req.query`), e.g. `{ page: '2' }`
+ * - Return value is automatically serialized as JSON via `res.json(result)`.
+ *   POST routes respond with 201; all other methods respond with 200.
+ *   Errors are caught and returned as `{ error: message }` with 404 (if the
+ *   message contains "not found") or 500.
+ *
+ * **How this differs from manual `ctx.router` routes:**
+ *
+ * When you register routes manually in `onStart(ctx)`, the handler receives
+ * the raw `(req, res)` pair and you are responsible for sending the response:
+ *
+ *   ctx.router.get('/health', (req, res) => {
+ *     res.json({ ok: true });
+ *   });
+ *
+ * Contract-based handlers are higher-level: the framework supplies the
+ * individual pieces of the request as arguments and handles serialization
+ * and status codes for you.
+ *
+ * @example
+ * // ── Contract / decorator approach ──────────────────────
+ * // Handler receives (body, params, query) and returns a value.
+ *
+ * class UserService extends Service {
+ *   \@Expose()
+ *   \@Route('GET', '/users/:id')
+ *   async getUser(body, params, query) {
+ *     return this.db.findUser(params.id);  // auto-serialized, 200 OK
+ *   }
+ *
+ *   \@Expose()
+ *   \@Route('POST', '/users')
+ *   async createUser(body, params, query) {
+ *     return this.db.insert(body);         // auto-serialized, 201 Created
+ *   }
+ * }
+ *
+ * // ── Manual approach (in onStart) ──────────────────────
+ * // Handler receives (req, res) and must call res.json() itself.
+ *
+ * async onStart(ctx) {
+ *   ctx.router.get('/users/:id', async (req, res) => {
+ *     const user = await this.db.findUser(req.params.id);
+ *     res.json(user);                      // you choose the status code
+ *   });
+ * }
+ */
+export declare function autoRegisterRoutes(service: ServiceInstance, ctx: ForgeContext): void;
+/**
+ * Auto-wire event subscriptions from @On decorators.
+ */
+export declare function autoWireSubscriptions(service: ServiceInstance, _ctx: ForgeContext): void;
+export {};
+//# sourceMappingURL=ServiceProxy.d.ts.map

package/dist/decorators/ServiceProxy.d.ts.map

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