@c9up/ream 0.1.3

package/src/rpc/RpcProvider.ts

@@ -0,0 +1,54 @@
+/**
+ * `RpcProvider` — wires a JSON-RPC 2.0 endpoint into the Ream pipeline.
+ *
+ *   - `register()` — bind a shared `RpcRouter` (with the IoC container, so
+ *     `namespace()` controllers are DI-resolved) under the token `'rpc'`. Apps
+ *     register methods by resolving it:
+ *
+ *       const rpc = app.container.make<RpcRouter>('rpc')
+ *       rpc.method('task.validate', handler).guard('jwt')
+ *       rpc.namespace('user', UserController)
+ *
+ *   - `boot()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
+ *     dispatching every request body (single or batch) to `RpcRouter.handle()`.
+ *
+ * @implements Story 24.1, 24.2
+ */
+
+import type { HttpContext } from '../http/HttpContext.js'
+import type { AppContext } from '../Provider.js'
+import { Provider } from '../Provider.js'
+import type { Router } from '../router/Router.js'
+import { RpcRouter } from './RpcRouter.js'
+
+export interface RpcProviderOptions {
+  /** Override the `RpcRouter` instance — used by tests. */
+  router?: RpcRouter
+}
+
+export interface RpcConfig {
+  /** HTTP path the JSON-RPC endpoint is mounted at. Default `/rpc`. */
+  path?: string
+}
+
+export class RpcProvider extends Provider {
+  readonly rpc: RpcRouter
+
+  constructor(app: AppContext, options: RpcProviderOptions = {}) {
+    super(app)
+    this.rpc = options.router ?? new RpcRouter()
+  }
+
+  override register(): void {
+    this.rpc.useContainer(this.app.container)
+    this.app.container.singleton('rpc', () => this.rpc)
+  }
+
+  override async boot(): Promise<void> {
+    const path = this.app.config.get<RpcConfig>('rpc')?.path ?? '/rpc'
+    const router = this.app.container.make<Router>('router')
+    // RpcRouter.handle() reads the registered methods at request time, so the
+    // mount can happen before apps finish registering methods.
+    router.post(path, (ctx: HttpContext) => this.rpc.handle(ctx))
+  }
+}

package/src/rpc/RpcRouter.ts

@@ -0,0 +1,243 @@
+/**
+ * JSON-RPC 2.0 Router — dispatches RPC method calls to handlers.
+ *
+ * Same middleware/guard/validate pipeline as REST routes.
+ *
+ * Usage:
+ *   rpc.method('task.validate', handler).guard('jwt').role('cs_member')
+ *   rpc.namespace('task', TaskController)  // every public method, DI-resolved per call
+ *   rpc.group({ guard: 'jwt' }, (r) => { r.method('user.find', handler) })
+ *
+ * @implements MISS-27
+ */
+
+import type { HttpContext } from '../http/HttpContext.js'
+
+export type RpcHandler = (ctx: HttpContext, params: unknown) => Promise<unknown> | unknown
+
+export interface RpcMethodDefinition {
+  name: string
+  handler: RpcHandler
+  guards: string[]
+  roles: string[]
+  permissions: string[]
+  middleware: string[]
+  validator?: string
+}
+
+export class RpcMethodBuilder {
+  #def: RpcMethodDefinition
+
+  constructor(def: RpcMethodDefinition) {
+    this.#def = def
+  }
+
+  guard(...guards: string[]): this {
+    this.#def.guards.push(...guards)
+    return this
+  }
+
+  role(...roles: string[]): this {
+    this.#def.roles.push(...roles)
+    return this
+  }
+
+  permission(...permissions: string[]): this {
+    this.#def.permissions.push(...permissions)
+    return this
+  }
+
+  validate(validator: string): this {
+    this.#def.validator = validator
+    return this
+  }
+
+  middleware(...names: string[]): this {
+    this.#def.middleware.push(...names)
+    return this
+  }
+}
+
+interface RpcErrorResponse {
+  jsonrpc: '2.0'
+  error: { code: number; message: string }
+  id: unknown
+}
+
+/** Build a JSON-RPC 2.0 error envelope. */
+function rpcError(code: number, message: string, id: unknown): RpcErrorResponse {
+  return { jsonrpc: '2.0', error: { code, message }, id }
+}
+
+type ParsedRpcRequest =
+  | { ok: true; method: string; params: unknown; id: unknown }
+  | { ok: false; response: RpcErrorResponse }
+
+/** Validate the JSON-RPC envelope and extract method/params/id. */
+function parseRpcRequest(request: unknown): ParsedRpcRequest {
+  if (!request || typeof request !== 'object') {
+    return { ok: false, response: rpcError(-32600, 'Invalid Request', null) }
+  }
+  // request is narrowed to a non-null object by the typeof check above.
+  const jsonrpc =
+    'jsonrpc' in request && typeof request.jsonrpc === 'string' ? request.jsonrpc : undefined
+  const method =
+    'method' in request && typeof request.method === 'string' ? request.method : undefined
+  const params = 'params' in request ? request.params : undefined
+  const id = 'id' in request ? request.id : undefined
+  if (jsonrpc !== '2.0' || !method) {
+    return { ok: false, response: rpcError(-32600, 'Invalid Request', id ?? null) }
+  }
+  return { ok: true, method, params, id }
+}
+
+/**
+ * Enforce the method's guards/roles/permissions against the request auth state.
+ * Returns the JSON-RPC error code+message to reject with, or undefined when the
+ * caller is authorized.
+ */
+function checkRpcAuthorization(
+  ctx: HttpContext,
+  def: RpcMethodDefinition,
+): { code: number; message: string } | undefined {
+  const needsAuth = def.guards.length > 0 || def.roles.length > 0 || def.permissions.length > 0
+  if (needsAuth && !ctx.auth?.authenticated) {
+    return { code: -32003, message: 'Unauthorized' }
+  }
+  if (def.roles.length > 0) {
+    const userRoles = ctx.auth?.roles ?? []
+    if (!def.roles.some((r: string) => userRoles.includes(r))) {
+      return { code: -32003, message: 'Insufficient role' }
+    }
+  }
+  if (def.permissions.length > 0) {
+    const userPerms = ctx.auth?.permissions ?? []
+    if (!def.permissions.every((p: string) => userPerms.includes(p))) {
+      return { code: -32003, message: 'Insufficient permissions' }
+    }
+  }
+  return undefined
+}
+
+export class RpcRouter {
+  #methods: Map<string, RpcMethodDefinition> = new Map()
+  #groupConfig: { guards: string[]; roles: string[]; middleware: string[] } | null = null
+  #container?: { make<T>(target: new (...args: unknown[]) => T): T }
+
+  /**
+   * Set the IoC container used to resolve `namespace()` controllers — mirrors
+   * `GraphQLEngine.useContainer()` so RPC and GraphQL resolve class handlers the
+   * same way (fresh DI per call). Without a container, controllers fall back to
+   * `new Controller()`.
+   */
+  useContainer(container: { make<T>(target: new (...args: unknown[]) => T): T }): void {
+    this.#container = container
+  }
+
+  /** Register an RPC method. */
+  method(name: string, handler: RpcHandler): RpcMethodBuilder {
+    const def: RpcMethodDefinition = {
+      name,
+      handler,
+      guards: [...(this.#groupConfig?.guards ?? [])],
+      roles: [...(this.#groupConfig?.roles ?? [])],
+      permissions: [],
+      middleware: [...(this.#groupConfig?.middleware ?? [])],
+    }
+    this.#methods.set(name, def)
+    return new RpcMethodBuilder(def)
+  }
+
+  /** Register methods from a controller — auto-registers all public methods. */
+  namespace(
+    prefix: string,
+    controller: new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>,
+  ): void {
+    const proto = controller.prototype
+    const methods = Object.getOwnPropertyNames(proto).filter(
+      (m) => m !== 'constructor' && typeof proto[m] === 'function',
+    )
+    for (const methodName of methods) {
+      this.method(`${prefix}.${methodName}`, async (ctx, params) => {
+        // Resolve through the container on every call (fresh DI per request,
+        // like GraphQLEngine), falling back to a bare `new` when unset.
+        const instance = this.#container ? this.#container.make(controller) : new controller()
+        return instance[methodName](ctx, params)
+      })
+    }
+  }
+
+  /** Group methods with shared guards/middleware. */
+  group(
+    config: { guard?: string; guards?: string[]; middleware?: string[] },
+    callback: (rpc: RpcRouter) => void,
+  ): void {
+    const prevConfig = this.#groupConfig
+    this.#groupConfig = {
+      guards: [...(config.guards ?? []), ...(config.guard ? [config.guard] : [])],
+      roles: [],
+      middleware: config.middleware ?? [],
+    }
+    callback(this)
+    this.#groupConfig = prevConfig
+  }
+
+  /** Handle an incoming JSON-RPC request. */
+  async handle(ctx: HttpContext): Promise<void> {
+    const body = ctx.request.body()
+
+    // Batch support (max 50 to prevent DoS)
+    if (Array.isArray(body)) {
+      if (body.length > 50) {
+        ctx.response.status(400).json({
+          jsonrpc: '2.0',
+          error: { code: -32600, message: 'Batch too large (max 50)' },
+          id: null,
+        })
+        return
+      }
+      // Note: batch items share the same ctx (auth state). Each is processed sequentially.
+      const results: unknown[] = []
+      for (const req of body) {
+        results.push(await this.#processOne(ctx, req))
+      }
+      ctx.response.status(200).json(results)
+      return
+    }
+
+    const result = await this.#processOne(ctx, body)
+    ctx.response.status(200).json(result)
+  }
+
+  async #processOne(ctx: HttpContext, request: unknown): Promise<unknown> {
+    const parsed = parseRpcRequest(request)
+    if (!parsed.ok) return parsed.response
+    const { method, params, id } = parsed
+
+    const def = this.#methods.get(method)
+    if (!def) return rpcError(-32601, 'Method not found', id)
+
+    try {
+      const denied = checkRpcAuthorization(ctx, def)
+      if (denied) return rpcError(denied.code, denied.message, id)
+
+      const result = await def.handler(ctx, params)
+      return { jsonrpc: '2.0', result, id }
+    } catch (err) {
+      // Don't leak internal error details to caller
+      const isDev = process.env.NODE_ENV !== 'production'
+      const message = isDev && err instanceof Error ? err.message : 'Internal error'
+      return rpcError(-32603, message, id)
+    }
+  }
+
+  /** Get all registered method names. */
+  getMethods(): string[] {
+    return [...this.#methods.keys()]
+  }
+
+  /** Get method definition for introspection. */
+  getMethod(name: string): RpcMethodDefinition | undefined {
+    return this.#methods.get(name)
+  }
+}

package/src/scheduler/Schedule.ts

@@ -0,0 +1,96 @@
+/**
+ * `@Schedule('cron-expr')` method decorator — declares a recurring task.
+ *
+ * Tasks are discovered at boot by `ScheduleProvider` iterating the IoC
+ * service registry, reading this metadata, and registering each entry
+ * with the Rust-backed `Scheduler` (Story 28.1). The Rust ticker owns
+ * the loop; TypeScript only declares *what* runs and *when*.
+ *
+ * @implements Story 28.2
+ */
+
+import 'reflect-metadata'
+import { ReamError } from '../errors/ReamError.js'
+import type { Constructor } from '../helpers/types.js'
+
+export const SCHEDULE_METADATA_KEY = Symbol('ream:schedule')
+
+export interface ScheduleMetadata {
+  cronExpr: string
+  methodName: string | symbol
+  target: Constructor
+}
+
+/**
+ * Declares that a method should run on a cron schedule.
+ *
+ * Expressions are standard 5-field cron (minute hour day-of-month month
+ * day-of-week), evaluated in **UTC** by the Rust core — callers that
+ * want local-time semantics must pre-translate.
+ *
+ * Multiple `@Schedule` decorators on different methods of the same class
+ * accumulate into an array rather than overwriting each other. Metadata
+ * is stored with `Reflect.defineMetadata` under a stable symbol key on
+ * the class constructor; inherited metadata is NOT shared (each class
+ * owns its own array — subclasses that add schedules do not mutate the
+ * base class's array).
+ *
+ * Getters, setters, and static methods are rejected at decoration time
+ * with a clear `ReamError` so that misuse surfaces early rather than at
+ * first fire.
+ *
+ * Usage:
+ * ```ts
+ * @Service()
+ * class Cleanup {
+ *   @Schedule('0 *\/5 * * *')
+ *   async runCleanup() { ... }
+ * }
+ * ```
+ */
+export function Schedule(cronExpr: string): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    // Reject static methods. For a static, `target` IS the constructor
+    // (callable function); for an instance method, `target` is the
+    // prototype. We need the real class either way.
+    if (typeof target === 'function') {
+      throw new ReamError(
+        'SCHEDULE_INVALID_TARGET',
+        `@Schedule cannot be applied to static method '${String(propertyKey)}'`,
+        {
+          hint: 'Move the scheduled logic to an instance method, or register the task manually via Scheduler.register().',
+        },
+      )
+    }
+
+    // Reject getters/setters — `descriptor.value` is `undefined` for
+    // accessors, and the ticker needs a callable method.
+    if (descriptor && typeof descriptor.value !== 'function') {
+      throw new ReamError(
+        'SCHEDULE_INVALID_TARGET',
+        `@Schedule cannot be applied to non-method '${String(propertyKey)}' (getters and setters are not supported)`,
+        {
+          hint: 'Apply @Schedule to a regular method, not to an accessor.',
+        },
+      )
+    }
+
+    const ctor = target.constructor as Constructor
+    // getOwnMetadata — do NOT walk the prototype chain. A subclass must
+    // not mutate the base class's shared array; each class owns its own
+    // schedule list. Matches the convention in decorators/Service.ts.
+    const existing: ScheduleMetadata[] = Reflect.getOwnMetadata(SCHEDULE_METADATA_KEY, ctor) ?? []
+    existing.push({ cronExpr, methodName: propertyKey, target: ctor })
+    Reflect.defineMetadata(SCHEDULE_METADATA_KEY, existing, ctor)
+  }
+}
+
+/**
+ * Return every `@Schedule` entry declared on `target` (empty array if
+ * none). Returns a shallow copy so callers cannot mutate the stored
+ * metadata by accident.
+ */
+export function getScheduleMetadata(target: Constructor): ScheduleMetadata[] {
+  const stored: ScheduleMetadata[] = Reflect.getOwnMetadata(SCHEDULE_METADATA_KEY, target) ?? []
+  return [...stored]
+}

package/src/scheduler/ScheduleProvider.ts

@@ -0,0 +1,177 @@
+/**
+ * `ScheduleProvider` — wires `@Schedule`-decorated methods into the
+ * Rust-backed [`Scheduler`].
+ *
+ * Lifecycle:
+ *   - `boot()` — walks the IoC service registry, reads each class's
+ *     `@Schedule` metadata, and registers a callback per entry.
+ *     Idempotent: calling `boot()` twice is a no-op on the second call.
+ *     Partial failures are rolled back — if the Nth task's registration
+ *     throws, tasks 1..N-1 registered in the same boot are unregistered
+ *     before the error propagates, so the scheduler is never left in a
+ *     half-registered state.
+ *   - `start()` — launches the Rust tick loop.
+ *   - `shutdown()` — cancels the Rust tick loop.
+ *
+ * The registered callback resolves the service **at invocation time**
+ * (not registration time) via `container.make(target)`, so every run
+ * receives freshly-DI'd dependencies for transient-scoped services.
+ *
+ * @implements Story 28.2
+ */
+
+import { getServiceRegistry } from '../decorators/Service.js'
+import { ReamError } from '../errors/ReamError.js'
+import type { AppContext } from '../Provider.js'
+import { Provider } from '../Provider.js'
+import { getScheduleMetadata } from './Schedule.js'
+import { Scheduler } from './Scheduler.js'
+
+export interface ScheduleProviderOptions {
+  /**
+   * Override the `Scheduler` instance — used by tests to inject a
+   * mock. Production code relies on the default (`new Scheduler()`).
+   */
+  scheduler?: Scheduler
+}
+
+export class ScheduleProvider extends Provider {
+  readonly scheduler: Scheduler
+  #booted = false
+
+  constructor(app: AppContext, options: ScheduleProviderOptions = {}) {
+    super(app)
+    this.scheduler = options.scheduler ?? new Scheduler()
+  }
+
+  /**
+   * Phase 1 — bind the scheduler into the IoC container under the
+   * stable token `'scheduler'`. CLI entrypoints
+   * (`ream schedule:list` / `ream schedule:run <name>`) retrieve the
+   * scheduler via `container.resolve('scheduler')` once the app has
+   * been booted through `Ignitor`. Consumers that import the
+   * provider directly still read the `readonly scheduler` field.
+   *
+   * Idempotent: re-registering the same provider instance (hot
+   * reload, repeated `app.start()` in tests) re-binds the same
+   * scheduler without error. A DIFFERENT `ScheduleProvider` trying
+   * to claim the `'scheduler'` token throws
+   * `SCHEDULE_PROVIDER_ALREADY_REGISTERED` so dueling providers do
+   * not silently overwrite each other.
+   */
+  override register(): void {
+    const scheduler = this.scheduler
+    const container = this.app.container
+    // Probe for an existing binding. The `make` / `resolve` API
+    // throws when unbound; use it to distinguish "same instance"
+    // from "another provider already claimed the token".
+    let existing: unknown
+    try {
+      existing = container.resolve('scheduler')
+    } catch {
+      existing = undefined
+    }
+    if (existing !== undefined) {
+      if (existing === scheduler) {
+        // Same provider re-running its register phase — no-op.
+        return
+      }
+      throw new ReamError(
+        'SCHEDULE_PROVIDER_ALREADY_REGISTERED',
+        "Container token 'scheduler' is already bound to a different instance",
+        {
+          hint: 'Only one ScheduleProvider can own the scheduler binding. Remove the duplicate provider from your reamrc.ts.',
+        },
+      )
+    }
+    container.singleton('scheduler', () => scheduler)
+  }
+
+  override async boot(): Promise<void> {
+    if (this.#booted) return
+    const registry = getServiceRegistry()
+    const registered: string[] = []
+
+    try {
+      for (const [target] of registry) {
+        const schedules = getScheduleMetadata(target)
+        if (schedules.length === 0) continue
+
+        if (!target.name) {
+          throw new ReamError(
+            'SCHEDULE_ANONYMOUS_CLASS',
+            'Anonymous classes cannot declare @Schedule — task names would collide',
+            {
+              hint: 'Name the class explicitly (e.g. `export class Jobs { ... }`) so task names are unique and debuggable.',
+            },
+          )
+        }
+
+        for (const { cronExpr, methodName } of schedules) {
+          // Reject symbol method keys — `String(Symbol('x'))` yields
+          // `Symbol(x)` which collides across distinct symbol instances
+          // sharing the same description. String keys are the
+          // documented contract.
+          if (typeof methodName === 'symbol') {
+            throw new ReamError(
+              'SCHEDULE_SYMBOL_METHOD',
+              `@Schedule on symbol-keyed method is not supported on class '${target.name}'`,
+              {
+                hint: 'Use a regular named method so the task can be addressed uniquely.',
+              },
+            )
+          }
+
+          const taskName = `${target.name}.${methodName}`
+          try {
+            this.scheduler.register(taskName, cronExpr, async () => {
+              // Resolve from the container on every fire so transient
+              // services get a fresh instance each run.
+              const instance = this.app.container.make<Record<string, unknown>>(target)
+              const method = instance[methodName]
+              if (typeof method !== 'function') {
+                throw new ReamError(
+                  'SCHEDULE_METHOD_NOT_FOUND',
+                  `Scheduled method ${taskName} is not callable on resolved instance`,
+                )
+              }
+              await (method as (...args: unknown[]) => unknown).call(instance)
+            })
+            registered.push(taskName)
+          } catch (cause) {
+            const inner = cause as ReamError & { message?: string; hint?: string }
+            throw new ReamError(
+              'SCHEDULE_INVALID_CRON',
+              `Failed to register scheduled task '${taskName}': ${inner.message ?? String(cause)}`,
+              {
+                context: { task: taskName, cronExpr },
+                hint: inner.hint,
+              },
+            )
+          }
+        }
+      }
+      this.#booted = true
+    } catch (err) {
+      // Roll back any partial registrations so a retry does not hit
+      // DUPLICATE_TASK and the scheduler is never half-initialized.
+      for (const name of registered) {
+        try {
+          this.scheduler.unregister(name)
+        } catch {
+          // Best-effort rollback; swallow secondary failures so the
+          // original error reaches the caller unchanged.
+        }
+      }
+      throw err
+    }
+  }
+
+  override async start(): Promise<void> {
+    this.scheduler.start()
+  }
+
+  override async shutdown(): Promise<void> {
+    this.scheduler.stop()
+  }
+}