threadforge 0.1.0

package/src/decorators/index.js

@@ -0,0 +1,571 @@
+/**
+ * ThreadForge Decorators — TC39 Stage 3
+ *
+ * Real standard decorators (not legacy/experimental).
+ * Work with TypeScript 5+, tsx, esbuild, and native when engines ship them.
+ *
+ * Decorator signature: (target: Function, context: DecoratorContext) => Function | void
+ *
+ * ═══════════════════════════════════════════════════════════════
+ * USAGE (TypeScript)
+ * ═══════════════════════════════════════════════════════════════
+ *
+ *   @Prefix('/api/users')
+ *   @Auth('required')
+ *   @RateLimit('1000/min')
+ *   class UserService extends Service {
+ *
+ *     @Route('GET', '/:id')
+ *     async getUser(data, auth, params) { ... }
+ *
+ *     @Route('POST', '/', { rateLimit: '10/min' })
+ *     @Emit('user.created')
+ *     @Validate({ name: 'string!', email: 'string!' })
+ *     async createUser(data, auth) { ... }
+ *
+ *     @Expose()                           // IPC only, no HTTP
+ *     async validateCredentials(data) { ... }
+ *
+ *     @Internal({ localOnly: true })      // same-process only
+ *     async getUserFromCache(id) { ... }
+ *
+ *     @On('billing', 'payment.received')
+ *     async onPayment(event) { ... }
+ *   }
+ *
+ * `forge generate` reads the resulting contract and produces:
+ *   - routes/users.yaml (ForgeProxy routing)
+ *   - routes/users.yaml (ForgeProxy routing manifest)
+ */
+
+// ─── Contract Storage ──────────────────────────────────────
+
+/**
+ * Global contract registry.
+ * Maps: ServiceClass → contract
+ * @type {WeakMap<Function, ServiceContract>}
+ */
+const CONTRACT_REGISTRY = new WeakMap();
+
+function getOrCreateContract(target) {
+  const cls = typeof target === "function" ? target : target.constructor;
+  if (!CONTRACT_REGISTRY.has(cls)) {
+    CONTRACT_REGISTRY.set(cls, {
+      methods: new Map(),
+      routes: [],
+      events: new Map(),
+      subscriptions: [],
+      prefix: null,
+      auth: "required",
+      rateLimit: null,
+    });
+  }
+  return CONTRACT_REGISTRY.get(cls);
+}
+
+/**
+ * Finalize contract from pending decorator metadata.
+ * Called by class decorators or lazily by getContract.
+ */
+function finalizeContract(cls, pending) {
+  const contract = getOrCreateContract(cls);
+
+  for (const route of pending.routes) {
+    if (!contract.routes.some((r) => r.handlerName === route.handlerName && r.path === route.path)) {
+      contract.routes.push(route);
+    }
+    if (!contract.methods.has(route.handlerName)) {
+      contract.methods.set(route.handlerName, { name: route.handlerName, options: {} });
+    }
+  }
+
+  for (const [name, meta] of Object.entries(pending.methods)) {
+    if (!contract.methods.has(name)) {
+      contract.methods.set(name, meta);
+    }
+  }
+
+  for (const [method, event] of Object.entries(pending.events)) {
+    contract.events.set(method, event);
+  }
+
+  for (const sub of pending.subscriptions) {
+    if (!contract.subscriptions.some((s) => s.handlerName === sub.handlerName)) {
+      contract.subscriptions.push(sub);
+    }
+  }
+
+  // Detect @Internal + @Route conflict
+  const routeHandlerNames = new Set(contract.routes.map(r => r.handlerName));
+  for (const [name, meta] of contract.methods) {
+    if (meta.options?.internal && routeHandlerNames.has(name)) {
+      throw new Error(`Method "${name}" cannot be both @Internal and @Route`);
+    }
+  }
+
+  return contract;
+}
+
+/**
+ * Get the contract for a service class.
+ */
+export function getContract(ServiceClass) {
+  // Already cached with content
+  let contract = CONTRACT_REGISTRY.get(ServiceClass);
+  if (contract && contract.methods.size > 0) return contract;
+
+  // Check for pending decorator metadata via Symbol.metadata
+  const metaKey = ServiceClass[Symbol.metadata];
+  if (metaKey && _classPending.has(metaKey)) {
+    const pending = _classPending.get(metaKey);
+    contract = finalizeContract(ServiceClass, pending);
+    if (ServiceClass.prefix) contract.prefix = ServiceClass.prefix;
+    if (ServiceClass.auth) contract.auth = ServiceClass.auth;
+    if (ServiceClass.rateLimit) contract.rateLimit = ServiceClass.rateLimit;
+    _classPending.delete(metaKey); // Prevent memory leak
+    return contract;
+  }
+
+  // Static contract fallback (plain JS)
+  if (ServiceClass.contract) {
+    return buildContractFromStatic(ServiceClass);
+  }
+
+  // Walk prototype chain to inherit parent contracts
+  let current = Object.getPrototypeOf(ServiceClass);
+  while (current && current !== Function.prototype) {
+    const parentContract = CONTRACT_REGISTRY.get(current);
+    if (parentContract && parentContract.methods.size > 0) {
+      // Clone parent contract for this subclass
+      contract = {
+        methods: new Map(parentContract.methods),
+        routes: [...parentContract.routes],
+        events: new Map(parentContract.events),
+        subscriptions: [...(parentContract.subscriptions || [])],
+        prefix: parentContract.prefix,
+        auth: parentContract.auth,
+        rateLimit: parentContract.rateLimit,
+      };
+      CONTRACT_REGISTRY.set(ServiceClass, contract);
+      return contract;
+    }
+    current = Object.getPrototypeOf(current);
+  }
+
+  if (contract) {
+    if (!(contract.methods instanceof Map)) contract.methods = new Map();
+    if (!Array.isArray(contract.routes)) contract.routes = [];
+    if (!(contract.events instanceof Map)) contract.events = new Map();
+    if (!Array.isArray(contract.subscriptions)) contract.subscriptions = [];
+  }
+
+  return contract || null;
+}
+
+// ─── Static Contract Fallback ──────────────────────────────
+
+function buildContractFromStatic(ServiceClass) {
+  const def = ServiceClass.contract;
+  const contract = {
+    methods: new Map(),
+    routes: [],
+    events: new Map(),
+    subscriptions: [],
+    prefix: ServiceClass.prefix ?? null,
+    auth: ServiceClass.auth ?? "required",
+    rateLimit: ServiceClass.rateLimit ?? null,
+  };
+
+  if (def.expose) {
+    for (const name of def.expose) {
+      contract.methods.set(name, { name, options: {} });
+    }
+  }
+
+  if (def.routes) {
+    for (const r of def.routes) {
+      contract.routes.push({
+        httpMethod: r.method,
+        path: r.path,
+        handlerName: r.handler,
+        auth: r.auth ?? null,
+        rateLimit: r.rateLimit ?? null,
+        cacheSecs: r.cacheSecs ?? r.cache ?? null,
+      });
+      if (!contract.methods.has(r.handler)) {
+        contract.methods.set(r.handler, { name: r.handler, options: {} });
+      }
+
+      // H5: Process r.validate — wrap handler with validation like @Validate
+      if (r.validate) {
+        const schema = r.validate;
+        const handlerName = r.handler;
+        const original = ServiceClass.prototype[handlerName];
+        if (typeof original === 'function') {
+          ServiceClass.prototype[handlerName] = async function (...args) {
+            const input = args[0];
+            const serviceName = this?.constructor?.name ?? 'Unknown';
+            const qualifiedName = `${serviceName}.${handlerName}`;
+
+            if (typeof schema === 'function') {
+              const error = schema(input);
+              if (error) throw new Error(`Validation failed for ${qualifiedName}: ${error}`);
+            } else if (typeof schema === 'object') {
+              const BLOCKED_FIELDS = new Set(['__proto__', 'constructor', 'prototype']);
+              for (const [field, type] of Object.entries(schema)) {
+                if (BLOCKED_FIELDS.has(field)) {
+                  throw new Error(`${qualifiedName}: "${field}" is a blocked field name`);
+                }
+                const fieldValue = Object.prototype.hasOwnProperty.call(input ?? {}, field) ? input[field] : undefined;
+                if (type.endsWith('!') && (fieldValue === undefined || fieldValue === null)) {
+                  throw new Error(`${qualifiedName}: "${field}" is required`);
+                }
+                const baseType = type.replace('!', '');
+                if (fieldValue !== undefined && fieldValue !== null) {
+                  if (baseType === 'array') {
+                    if (!Array.isArray(fieldValue)) {
+                      throw new Error(`${qualifiedName}: "${field}" must be an array`);
+                    }
+                  } else if (baseType === 'object') {
+                    if (typeof fieldValue !== 'object' || Array.isArray(fieldValue)) {
+                      throw new Error(`${qualifiedName}: "${field}" must be an object`);
+                    }
+                  } else if (typeof fieldValue !== baseType) {
+                    throw new Error(`${qualifiedName}: "${field}" must be ${baseType}`);
+                  }
+                  if (baseType === 'number' && typeof fieldValue === 'number' && Number.isNaN(fieldValue)) {
+                    throw new Error(`${qualifiedName}: "${field}" must be a valid number (NaN is not allowed)`);
+                  }
+                }
+              }
+            }
+
+            return original.apply(this, args);
+          };
+        }
+      }
+    }
+  }
+
+  if (def.emits) {
+    for (const [method, event] of Object.entries(def.emits)) {
+      contract.events.set(method, event);
+
+      // Wrap the method to auto-emit, matching @Emit decorator behavior
+      const original = ServiceClass.prototype[method];
+      if (typeof original === 'function') {
+        ServiceClass.prototype[method] = async function (...args) {
+          const result = await original.apply(this, args);
+          const emitFn = this.ctx?._emitEvent;
+          if (emitFn) {
+            try {
+              await emitFn(event, result);
+            } catch (err) {
+              this.ctx?.logger?.warn?.(`Failed to emit event "${event}": ${err.message}`);
+            }
+          }
+          return result;
+        };
+      }
+    }
+  }
+
+  if (def.on) {
+    for (const sub of def.on) {
+      contract.subscriptions.push({
+        service: sub.service,
+        event: sub.event,
+        handlerName: sub.handler,
+      });
+    }
+  }
+
+  // Detect @Internal + @Route conflict in static contracts
+  const staticRouteHandlers = new Set(contract.routes.map(r => r.handlerName));
+  for (const [name, meta] of contract.methods) {
+    if (meta.options?.internal && staticRouteHandlers.has(name)) {
+      throw new Error(`Method "${name}" cannot be both @Internal and @Route`);
+    }
+  }
+
+  CONTRACT_REGISTRY.set(ServiceClass, contract);
+  return contract;
+}
+
+// ─── Class Decorators ──────────────────────────────────────
+
+/**
+ * @Prefix('/api/users')
+ * Sets the URL prefix for all routes in this service.
+ */
+export function Prefix(path) {
+  return (target, context) => {
+    target.prefix = path;
+    // Finalize any pending method decorator metadata
+    const pending = _classPending.get(context.metadata);
+    if (pending) {
+      const contract = finalizeContract(target, pending);
+      contract.prefix = path;
+    }
+  };
+}
+
+/**
+ * @Auth('required' | 'optional' | 'none')
+ * Sets the default auth requirement for all routes.
+ */
+export function Auth(requirement) {
+  return (target, context) => {
+    target.auth = requirement;
+    const pending = _classPending.get(context.metadata);
+    if (pending) {
+      const contract = finalizeContract(target, pending);
+      contract.auth = requirement;
+    }
+  };
+}
+
+/**
+ * @RateLimit('1000/min')
+ * Sets the default rate limit for all routes.
+ */
+export function RateLimit(limit) {
+  return (target, context) => {
+    target.rateLimit = limit;
+    const pending = _classPending.get(context.metadata);
+    if (pending) {
+      const contract = finalizeContract(target, pending);
+      contract.rateLimit = limit;
+    }
+  };
+}
+
+/**
+ * Per-class pending storage.
+ * Method decorators write here; class decorators read and finalize.
+ * Keyed by context.metadata which is shared across all decorators on one class.
+ *
+ * D10: Decorator ordering — class decorators (@Prefix, @Auth, @RateLimit) finalize
+ * pending metadata accumulated by method decorators (@Route, @Expose, @Emit, @On).
+ * Class decorators must come AFTER (i.e., above) method decorators in the source.
+ * TC39 Stage 3 decorators evaluate bottom-up for methods, then class decorators.
+ *
+ * @type {Map<object, Object>}
+ */
+const _classPending = new WeakMap();
+
+// ─── Method Decorators ─────────────────────────────────────
+
+/**
+ * @Route('GET', '/users/:id', { auth?: 'required', rateLimit?: '100/min', cacheSecs?: 60 })
+ *
+ * Exposes a method via HTTP. ForgeProxy routes to it.
+ * Implies @Expose — the method is also callable via IPC.
+ *
+ * D6/D9: Route handler signature:
+ *   The decorated method receives `(body, params, query)` where:
+ *     - body: parsed JSON request body (or {} for GET)
+ *     - params: URL path parameters (e.g., { id: '123' } for /users/:id)
+ *     - query: parsed query string parameters
+ *   Return value is auto-serialized as JSON (201 for POST, 200 otherwise).
+ */
+const VALID_HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
+
+export function Route(httpMethod, path, options = {}) {
+  if (!VALID_HTTP_METHODS.has(httpMethod.toUpperCase())) {
+    throw new Error(`@Route: invalid HTTP method "${httpMethod}". Valid: ${[...VALID_HTTP_METHODS].join(', ')}`);
+  }
+  return (target, context) => {
+    const methodName = String(context.name);
+    const pending = _getClassPending(context);
+
+    pending.routes.push({
+      httpMethod: httpMethod.toUpperCase(),
+      path,
+      handlerName: methodName,
+      auth: options.auth ?? null,
+      rateLimit: options.rateLimit ?? null,
+      cacheSecs: options.cacheSecs ?? null,
+    });
+
+    pending.methods[methodName] = { name: methodName, options: {} };
+
+    return target;
+  };
+}
+
+/**
+ * @Expose(options?)
+ *
+ * Marks a method as callable via IPC by other services.
+ * If no @Route is applied, this method is backend-only.
+ */
+export function Expose(options = {}) {
+  return (target, context) => {
+    const methodName = String(context.name);
+    const pending = _getClassPending(context);
+    pending.methods[methodName] = { name: methodName, options };
+    return target;
+  };
+}
+
+/**
+ * @Internal(options?)
+ *
+ * Backend-only method. Never exposed via HTTP.
+ * Same as @Expose but makes intent explicit.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.localOnly] - Only callable within same process (zero-copy)
+ */
+export function Internal(options = {}) {
+  return (target, context) => {
+    const methodName = String(context.name);
+    const pending = _getClassPending(context);
+    pending.methods[methodName] = {
+      name: methodName,
+      options: { ...options, internal: true },
+    };
+    return target;
+  };
+}
+
+/**
+ * @Emit('user.created')
+ */
+export function Emit(eventName) {
+  return (target, context) => {
+    const methodName = String(context.name);
+    const pending = _getClassPending(context);
+    pending.events[methodName] = eventName;
+
+    // M-PLUGIN-7: Preserve method name for stack traces and debugging
+    const wrapper = async function (...args) {
+      const result = await target.apply(this, args);
+      // Capture emit function AFTER await to get current context
+      const emitFn = this.ctx?._emitEvent;
+      if (emitFn) {
+        try {
+          await emitFn(eventName, result);
+        } catch (err) {
+          this.ctx?.logger?.warn?.(`Failed to emit event "${eventName}": ${err.message}`);
+        }
+      }
+      return result;
+    };
+    Object.defineProperty(wrapper, 'name', { value: methodName, configurable: true });
+    return wrapper;
+  };
+}
+
+/**
+ * @On('billing', 'payment.received')
+ */
+export function On(serviceName, eventName) {
+  return (target, context) => {
+    const methodName = String(context.name);
+    const pending = _getClassPending(context);
+    pending.subscriptions.push({
+      service: serviceName,
+      event: eventName,
+      handlerName: methodName,
+    });
+    return target;
+  };
+}
+
+function _getClassPending(context) {
+  const key = context.metadata;
+  if (typeof key !== "object" || key === null) {
+    throw new Error(`Decorator context.metadata must be an object, got ${typeof key}`);
+  }
+  if (!_classPending.has(key)) {
+    _classPending.set(key, { routes: [], methods: {}, events: {}, subscriptions: [] });
+  }
+  return _classPending.get(key);
+}
+
+/**
+ * @Validate({ name: 'string!', email: 'string!' })
+ *
+ * Validates the first argument before method execution.
+ * '!' suffix means required.
+ */
+export function Validate(schema) {
+  return (target, context) => {
+    const methodName = String(context.name);
+
+    return async function (...args) {
+      const input = args[0];
+      const serviceName = this?.constructor?.name ?? 'Unknown';
+      const qualifiedName = `${serviceName}.${methodName}`;
+
+      if (typeof schema === "function") {
+        const error = schema(input);
+        if (error) throw new Error(`Validation failed for ${qualifiedName}: ${error}`);
+      } else if (typeof schema === "object") {
+        const BLOCKED_FIELDS = new Set(['__proto__', 'constructor', 'prototype']);
+        for (const [field, type] of Object.entries(schema)) {
+          if (BLOCKED_FIELDS.has(field)) {
+            throw new Error(`${qualifiedName}: "${field}" is a blocked field name`);
+          }
+          const fieldValue = Object.prototype.hasOwnProperty.call(input ?? {}, field) ? input[field] : undefined;
+          if (type.endsWith("!") && (fieldValue === undefined || fieldValue === null)) {
+            throw new Error(`${qualifiedName}: "${field}" is required`);
+          }
+          const baseType = type.replace("!", "");
+          if (fieldValue !== undefined && fieldValue !== null) {
+            if (baseType === "array") {
+              if (!Array.isArray(fieldValue)) {
+                throw new Error(`${qualifiedName}: "${field}" must be an array`);
+              }
+            } else if (baseType === "object") {
+              if (typeof fieldValue !== "object" || Array.isArray(fieldValue)) {
+                throw new Error(`${qualifiedName}: "${field}" must be an object`);
+              }
+            } else if (typeof fieldValue !== baseType) {
+              throw new Error(`${qualifiedName}: "${field}" must be ${baseType}`);
+            }
+            if (baseType === 'number' && typeof fieldValue === 'number' && Number.isNaN(fieldValue)) {
+              throw new Error(`${qualifiedName}: "${field}" must be a valid number (NaN is not allowed)`);
+            }
+          }
+        }
+      }
+
+      return target.apply(this, args);
+    };
+  };
+}
+
+// ─── Query Helpers ─────────────────────────────────────────
+
+/**
+ * Check if a method is internal-only (no HTTP route).
+ */
+export function isInternalMethod(ServiceClass, methodName) {
+  const contract = getContract(ServiceClass);
+  if (!contract) return false;
+  if (!contract.methods.has(methodName)) return false;
+  return !contract.routes.some((r) => r.handlerName === methodName);
+}
+
+/**
+ * Check if a method is local-only (direct call, no IPC).
+ */
+export function isLocalOnlyMethod(ServiceClass, methodName) {
+  const contract = getContract(ServiceClass);
+  if (!contract) return false;
+  const meta = contract.methods.get(methodName);
+  return meta?.options?.localOnly === true;
+}
+
+/**
+ * Get all internal (non-HTTP) methods for a service.
+ */
+export function getInternalMethods(ServiceClass) {
+  const contract = getContract(ServiceClass);
+  if (!contract) return [];
+  const routeHandlers = new Set(contract.routes.map((r) => r.handlerName));
+  return [...contract.methods.keys()].filter((m) => !routeHandlers.has(m));
+}