@c9up/ream 0.1.3

package/src/index.ts

@@ -0,0 +1,263 @@
+/**
+ * @module @c9up/ream
+ * @description Ream — Rust-powered Node.js application framework
+ * @implements FR11, FR12, FR13, FR14, FR16, FR17, FR18, FR19, FR20, FR21
+ */
+
+import 'reflect-metadata'
+
+// ─── Core ───────────────────────────────────────────────────
+
+export { Application } from './Application.js'
+export { defineModuleConfig, env, ConfigStore } from './ConfigLoader.js'
+export { Container } from './container/Container.js'
+export type { Binding, ServiceFactory, ServiceScope, ServiceToken } from './container/types.js'
+
+// ─── HTTP (new — AdonisJS-compatible) ───────────────────────
+
+export {
+  E_FORBIDDEN,
+  E_HTTP_EXCEPTION,
+  E_ROUTE_NOT_FOUND,
+  E_ROW_NOT_FOUND,
+  E_UNAUTHORIZED,
+  E_VALIDATION_ERROR,
+  Exception,
+  ExceptionHandler,
+} from './http/Exception.js'
+export type { AuthState, RouteInfo } from './http/HttpContext.js'
+export { HttpContext } from './http/HttpContext.js'
+export { RedirectBuilder } from './http/RedirectBuilder.js'
+export type { RawRequest } from './http/Request.js'
+export { Request } from './http/Request.js'
+export { Response } from './http/Response.js'
+
+// ─── Session ────────────────────────────────────────────────
+
+export { CookieDriver as SessionCookieDriver } from './session/drivers/CookieDriver.js'
+export { MemoryDriver as SessionMemoryDriver } from './session/drivers/MemoryDriver.js'
+export type { SessionConfig, SessionDriver } from './session/Session.js'
+export { Session } from './session/Session.js'
+export { default as SessionMiddleware } from './session/SessionMiddleware.js'
+
+// ─── Body Parser ────────────────────────────────────────────
+
+export type { BodyParserConfig } from './bodyparser/BodyParserMiddleware.js'
+export { default as BodyParserMiddleware } from './bodyparser/BodyParserMiddleware.js'
+export type { FileValidationOptions } from './bodyparser/MultipartFile.js'
+export { MultipartFile } from './bodyparser/MultipartFile.js'
+
+// ─── JSON-RPC ───────────────────────────────────────────────
+
+export type { RpcConfig, RpcProviderOptions } from './rpc/RpcProvider.js'
+export { RpcProvider } from './rpc/RpcProvider.js'
+export type { RpcHandler, RpcMethodDefinition } from './rpc/RpcRouter.js'
+export { RpcMethodBuilder, RpcRouter } from './rpc/RpcRouter.js'
+
+// ─── GraphQL ────────────────────────────────────────────────
+
+export type {
+  GraphQLConfig,
+  ResolverOptions,
+  SelectionField,
+} from './graphql/GraphQLEngine.js'
+export { GraphQLEngine } from './graphql/GraphQLEngine.js'
+export type { GraphQLProviderOptions } from './graphql/GraphQLProvider.js'
+export { GraphQLProvider } from './graphql/GraphQLProvider.js'
+
+// ─── OpenAPI ────────────────────────────────────────────────
+
+export type { OpenApiConfig } from './openapi/OpenApiGenerator.js'
+export { OpenApiGenerator } from './openapi/OpenApiGenerator.js'
+export type { OpenApiMiddlewareConfig } from './openapi/OpenApiMiddleware.js'
+export { OpenApiMiddleware } from './openapi/OpenApiMiddleware.js'
+export type {
+  OpenApiDocsConfig,
+  OpenApiProviderOptions,
+} from './openapi/OpenApiProvider.js'
+export { OpenApiProvider } from './openapi/OpenApiProvider.js'
+
+// ─── API Resources / Serializers ────────────────────────────
+
+export type { PaginationMeta } from './resources/ApiResource.js'
+export { ApiResource } from './resources/ApiResource.js'
+
+// ─── Static Files ───────────────────────────────────────────
+
+export type { StaticConfig } from './storage/StaticMiddleware.js'
+export { StaticMiddleware } from './storage/StaticMiddleware.js'
+export type { StaticProviderOptions } from './storage/StaticProvider.js'
+export { StaticProvider } from './storage/StaticProvider.js'
+
+// ─── Security ───────────────────────────────────────────────
+
+// Request-filter security (CSRF, XSS, rate-limit, CORS, headers, path/param)
+// lives in @c9up/blackhole. ream core keeps only the crypto primitives.
+export { CookieSigner } from './security/CookieSigner.js'
+export {
+  setNapi,
+  constantTimeEq,
+  hasNativeCrypto,
+  hmacSign,
+  hmacVerify,
+  randomBytesBase64,
+  randomHex,
+} from './security/crypto.js'
+export type { SignedUrlConfig } from './security/SignedUrl.js'
+export { SignedUrl } from './security/SignedUrl.js'
+
+// ─── Decorators ─────────────────────────────────────────────
+
+export { createLazyProxy, getLazyParams, Lazy } from './decorators/Lazy.js'
+export {
+  clearServiceRegistry,
+  getServiceMetadata,
+  getServiceRegistry,
+  Inject,
+  inject,
+  Service,
+} from './decorators/Service.js'
+
+// ─── Router ─────────────────────────────────────────────────
+
+export type {
+  ControllerAction,
+  MatchResult,
+  ParamMatcher,
+  RouteDefinition,
+  RouteHandler,
+  RouteHandlerFunction,
+} from './router/Router.js'
+export { GroupBuilder, matchers, OnRouteBuilder, RouteBuilder, Router } from './router/Router.js'
+
+// ─── Middleware ──────────────────────────────────────────────
+
+export type { MiddlewareFunction } from './middleware/Pipeline.js'
+export { compose, MiddlewareRegistry } from './middleware/Pipeline.js'
+
+// ─── HttpKernel ─────────────────────────────────────────────
+
+export type { HttpKernelConfig } from './HttpKernel.js'
+export { createHttpKernel } from './HttpKernel.js'
+
+// ─── Server ─────────────────────────────────────────────────
+
+export type {
+  ErrorHandlerClass,
+  LazyImport,
+  MiddlewareClass,
+  MiddlewareEntry,
+} from './server/Server.js'
+export { resolveMiddlewareEntry, Server } from './server/Server.js'
+
+// ─── Ignitor ────────────────────────────────────────────────
+
+export type { Command } from './console/CommandRunner.js'
+export { CommandRunner } from './console/CommandRunner.js'
+export type { AppEnvironment, HyperServerLike, IgnitorConfig, ReamrcConfig } from './Ignitor.js'
+export { ConsoleKernel, defineConfig, Ignitor, prettyPrintError } from './Ignitor.js'
+
+// ─── Providers ──────────────────────────────────────────────
+
+export type { AppContext, ProviderContract } from './Provider.js'
+export { Provider } from './Provider.js'
+
+// ─── Codemods ───────────────────────────────────────────────
+
+export type { Codemods } from './Codemods.js'
+export { createCodemods } from './Codemods.js'
+
+// ─── Errors ─────────────────────────────────────────────────
+
+export type { ErrorEmitter, ErrorEvent, ErrorSeverity } from './ErrorBoundary.js'
+export { ErrorBoundary } from './ErrorBoundary.js'
+export { didYouMean, findClosestMatches, levenshtein } from './errors/FuzzyMatcher.js'
+export {
+  AtlasError,
+  ContainerError,
+  EventsError,
+  ForgeError,
+  PipelineError,
+  RouterError,
+  RuneError,
+  WardenError,
+} from './errors/ModuleErrors.js'
+export type { PipelineStageName } from './errors/PipelineStageError.js'
+export {
+  createPipelineError,
+  PIPELINE_STAGES,
+  validatePipelineConfig,
+} from './errors/PipelineStageError.js'
+export { ReamError } from './errors/ReamError.js'
+
+// ─── Utilities ──────────────────────────────────────────────
+
+export type { ShutdownHandle, ShutdownOptions } from './GracefulShutdown.js'
+export { installGracefulShutdown } from './GracefulShutdown.js'
+export type { HealthChecker, HealthCheckResult, HealthStatus } from './HealthCheck.js'
+export { HealthCheck } from './HealthCheck.js'
+export type { HotReloadOptions } from './HotReload.js'
+export { startHotReload } from './HotReload.js'
+
+// ─── Types ──────────────────────────────────────────────────
+
+export type {
+  AsyncOrSync,
+  Constructor,
+  Dict,
+  ExtractFunctions,
+  InferRouteParams,
+  OneOrMore,
+  Opaque,
+  Prettify,
+  UnwrapOpaque,
+} from './types/helpers.js'
+
+// ─── Services ───────────────────────────────────────────────
+
+export { setApp } from './services/app.js'
+export { setRouter } from './services/router.js'
+export { setServer } from './services/server.js'
+
+// ─── Scheduler ──────────────────────────────────────────────
+
+// ─── Events (event bus — ream core) ───
+// Native-free surface only. The Rust-backed `EventsProvider` / `EventBus`
+// (which load `events.<platform>.node` at import time) live on the
+// `@c9up/ream/events` subpath so importing the main barrel stays lazy.
+export type { EventsConfig } from './events/config.js'
+export { defineConfig as defineEventsConfig } from './events/config.js'
+export {
+  BaseEvent,
+  type ContainerResolver,
+  Emitter,
+  type ListenerClass,
+} from './events/Emitter.js'
+export type {
+  ErrorReporter,
+  LockBackend,
+  RunTaskOutcome,
+  ScheduleEvent,
+  ScheduleEventSink,
+  ScheduleInvocation,
+  ScheduleMetadata,
+  ScheduleProviderOptions,
+  SchedulerOptions,
+  ScheduleTaskCompletedEvent,
+  ScheduleTaskFailedEvent,
+  ScheduleTaskSkippedEvent,
+  ScheduleTaskStartedEvent,
+  TaskInfo,
+  TaskStats,
+} from './scheduler/index.js'
+export {
+  getScheduleMetadata,
+  MemoryLockBackend,
+  SCHEDULE_METADATA_KEY,
+  Schedule,
+  ScheduleProvider,
+  Scheduler,
+  StatsTracker,
+} from './scheduler/index.js'
+
+export const VERSION = '0.1.0'

package/src/middleware/Pipeline.ts

@@ -0,0 +1,136 @@
+/**
+ * Unified Middleware Pipeline — typed for HttpContext.
+ *
+ * @implements FR22, FR27
+ *
+ * Pipeline order (fixed):
+ * 1. Global middleware
+ * 2. Route/handler named middleware
+ * 3. Route inline middleware
+ * 4. Guard (auth + roles + permissions)
+ * 5. Handler
+ */
+
+import { ReamError } from '../errors/ReamError.js'
+import { E_FORBIDDEN, E_UNAUTHORIZED } from '../http/Exception.js'
+import type { HttpContext } from '../http/HttpContext.js'
+
+export type MiddlewareFunction = (
+  ctx: HttpContext,
+  next: () => Promise<void>,
+) => Promise<void> | void
+
+/** Named middleware registry. */
+export class MiddlewareRegistry {
+  #global: MiddlewareFunction[] = []
+  #named: Map<string, MiddlewareFunction> = new Map()
+
+  /** Register a global middleware (runs on every request). */
+  use(middleware: MiddlewareFunction): void {
+    this.#global.push(middleware)
+  }
+
+  /** Register a named middleware. */
+  register(name: string, middleware: MiddlewareFunction): void {
+    this.#named.set(name, middleware)
+  }
+
+  /** Get a named middleware. */
+  get(name: string): MiddlewareFunction | undefined {
+    return this.#named.get(name)
+  }
+
+  /** Get all global middleware. */
+  getGlobal(): MiddlewareFunction[] {
+    return [...this.#global]
+  }
+
+  /** Build the execution chain for a request. */
+  buildChain(
+    namedMiddleware: string[],
+    inlineMiddleware: MiddlewareFunction[],
+    handler: MiddlewareFunction,
+    options?: { guards?: string[]; roles?: string[]; permissions?: string[] },
+  ): MiddlewareFunction {
+    const stack: MiddlewareFunction[] = [
+      // 1. Global middleware
+      ...this.#global,
+      // 2. Named middleware
+      ...namedMiddleware
+        .map((name) => this.#named.get(name))
+        .filter((mw): mw is MiddlewareFunction => mw !== undefined),
+      // 3. Inline middleware
+      ...inlineMiddleware,
+      // 4. Guard enforcement (throws exceptions instead of setting response)
+      ...((options?.guards?.length ?? 0) > 0 ||
+      (options?.roles?.length ?? 0) > 0 ||
+      (options?.permissions?.length ?? 0) > 0
+        ? [createGuardMiddleware(options?.guards ?? [], options?.roles, options?.permissions)]
+        : []),
+      // 5. Handler
+      handler,
+    ]
+
+    return compose(stack)
+  }
+}
+
+/** Compose middleware into a single handler (onion pattern). */
+function compose(middleware: MiddlewareFunction[]): MiddlewareFunction {
+  return async (ctx: HttpContext, finalNext: () => Promise<void>) => {
+    let index = -1
+
+    async function dispatch(i: number): Promise<void> {
+      if (i <= index) {
+        throw new ReamError('PIPELINE_DOUBLE_NEXT', 'next() called multiple times', {
+          hint: 'A middleware called next() more than once. Each middleware should call next() at most once.',
+        })
+      }
+      index = i
+
+      const fn = i < middleware.length ? middleware[i] : finalNext
+      if (!fn) return
+
+      await fn(ctx, () => dispatch(i + 1))
+    }
+
+    await dispatch(0)
+  }
+}
+
+/**
+ * Guard enforcement middleware.
+ * Throws E_UNAUTHORIZED / E_FORBIDDEN exceptions (caught by ExceptionHandler).
+ */
+function createGuardMiddleware(
+  guards: string[],
+  roles?: string[],
+  permissions?: string[],
+): MiddlewareFunction {
+  return async (ctx, next) => {
+    const needsAuth =
+      guards.length > 0 || (roles && roles.length > 0) || (permissions && permissions.length > 0)
+    if (needsAuth && !ctx.auth.authenticated) {
+      throw new E_UNAUTHORIZED()
+    }
+
+    if (roles && roles.length > 0) {
+      const userRoles = ctx.auth.roles ?? []
+      const hasAnyRole = roles.some((r) => userRoles.includes(r))
+      if (!hasAnyRole) {
+        throw new E_FORBIDDEN('Insufficient role', roles)
+      }
+    }
+
+    if (permissions && permissions.length > 0) {
+      const userPerms = ctx.auth.permissions ?? []
+      if (!permissions.every((p) => userPerms.includes(p))) {
+        throw new E_FORBIDDEN('Insufficient permissions', permissions)
+      }
+    }
+
+    await next()
+  }
+}
+
+export { compose }

package/src/openapi/OpenApiGenerator.ts

@@ -0,0 +1,254 @@
+/**
+ * OpenApiGenerator — auto-generates OpenAPI 3.1 spec from registered routes and Rune schemas.
+ *
+ * Zero manual spec writing. Routes, validators, guards, and versions are introspected at boot.
+ *
+ * Usage:
+ *   const spec = new OpenApiGenerator(router, { title: 'My API', version: '1.0.0' }).generate()
+ *
+ * @implements MISS-22
+ */
+
+import type { RouteDefinition, Router } from '../router/Router.js'
+
+export interface OpenApiConfig {
+  title: string
+  version: string
+  description?: string
+  servers?: Array<{ url: string; description?: string }>
+  contact?: { name?: string; email?: string; url?: string }
+  license?: { name: string; url?: string }
+}
+
+// `type` (not `interface`) so the generated spec is assignable to
+// `Record<string, unknown>` — OpenApiMiddleware accepts the spec as a plain
+// record, and a `type` alias carries the implicit index signature an
+// (augmentable) interface would not.
+type OpenApiSpec = {
+  openapi: string
+  info: {
+    title: string
+    version: string
+    description?: string
+    contact?: Record<string, string>
+    license?: Record<string, string>
+  }
+  servers?: Array<{ url: string; description?: string }>
+  paths: Record<string, Record<string, unknown>>
+  components: {
+    securitySchemes: Record<string, unknown>
+    schemas: Record<string, unknown>
+  }
+}
+
+/** Map a guard name to its OpenAPI security-scheme object. */
+function buildSecurityScheme(guard: string): Record<string, unknown> {
+  if (guard === 'jwt') {
+    return { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }
+  }
+  if (guard === 'api-key' || guard === 'apikey') {
+    return { type: 'apiKey', in: 'header', name: 'X-API-Key' }
+  }
+  return { type: 'http', scheme: 'bearer' }
+}
+
+export class OpenApiGenerator {
+  #router: Router
+  #config: OpenApiConfig
+  #runeSchemas: Map<string, Record<string, unknown>>
+
+  constructor(
+    router: Router,
+    config: OpenApiConfig,
+    runeSchemas?: Map<string, Record<string, unknown>>,
+  ) {
+    this.#router = router
+    this.#config = config
+    this.#runeSchemas = runeSchemas ?? new Map()
+  }
+
+  /** Register a Rune validation schema for OpenAPI spec generation. */
+  registerSchema(name: string, definition: Record<string, unknown>): void {
+    this.#runeSchemas.set(name, definition)
+  }
+
+  /** Generate the complete OpenAPI 3.1 spec. */
+  generate(): OpenApiSpec {
+    const spec: OpenApiSpec = {
+      openapi: '3.1.0',
+      info: {
+        title: this.#config.title,
+        version: this.#config.version,
+        ...(this.#config.description ? { description: this.#config.description } : {}),
+        ...(this.#config.contact ? { contact: this.#config.contact } : {}),
+        ...(this.#config.license ? { license: this.#config.license } : {}),
+      },
+      ...(this.#config.servers ? { servers: this.#config.servers } : {}),
+      paths: {},
+      components: {
+        securitySchemes: {},
+        schemas: {},
+      },
+    }
+
+    // Build paths from router
+    const routes = this.#getRoutes()
+    const securitySchemesUsed = new Set<string>()
+
+    for (const route of routes) {
+      const method = route.method.toLowerCase()
+      if (method === '*') continue // skip wildcard routes
+
+      const path = this.#convertPath(route.path)
+
+      if (!spec.paths[path]) spec.paths[path] = {}
+
+      spec.paths[path][method] = this.#buildOperation(
+        route,
+        method,
+        path,
+        securitySchemesUsed,
+        spec.components.schemas,
+      )
+    }
+
+    // Security schemes
+    for (const guard of securitySchemesUsed) {
+      spec.components.securitySchemes[guard] = buildSecurityScheme(guard)
+    }
+
+    return spec
+  }
+
+  /**
+   * Build the OpenAPI operation object for one route. Records any guard names in
+   * `securitySchemesUsed` and registers validator request-body schemas into the
+   * shared `schemas` component map.
+   */
+  #buildOperation(
+    route: RouteDefinition,
+    method: string,
+    path: string,
+    securitySchemesUsed: Set<string>,
+    schemas: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const operation: Record<string, unknown> = {
+      summary: this.#generateSummary(route),
+      responses: {
+        '200': { description: 'Success' },
+        ...(route.guards.length > 0 ? { '401': { description: 'Unauthorized' } } : {}),
+        ...(route.roles.length > 0 || route.permissions.length > 0
+          ? { '403': { description: 'Forbidden' } }
+          : {}),
+      },
+    }
+
+    // Tags from path prefix
+    const tag = path.split('/').filter(Boolean)[1] // e.g., /api/v1/tasks → "v1"
+    if (tag) operation.tags = [tag]
+
+    if (route.version) operation['x-api-version'] = route.version
+
+    if (route.deprecates) {
+      operation.deprecated = true
+      operation['x-sunset'] = route.deprecates.sunset
+    }
+
+    const params = this.#extractPathParams(route.path)
+    if (params.length > 0) {
+      operation.parameters = params.map((p) => ({
+        name: p,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      }))
+    }
+
+    if (route.guards.length > 0) {
+      operation.security = route.guards.map((g) => ({ [g]: [] }))
+      for (const g of route.guards) securitySchemesUsed.add(g)
+    }
+
+    if (route.validators.length > 0 && ['post', 'put', 'patch'].includes(method)) {
+      const validatorName = route.validators[0]
+      const schema = this.#runeSchemas.get(validatorName)
+      if (schema) {
+        operation.requestBody = {
+          required: true,
+          content: { 'application/json': { schema: this.#runeToJsonSchema(schema) } },
+        }
+        schemas[validatorName] = this.#runeToJsonSchema(schema)
+      } else {
+        operation.requestBody = {
+          required: true,
+          content: { 'application/json': { schema: { type: 'object' } } },
+        }
+      }
+    }
+
+    return operation
+  }
+
+  /** Convert Express-style path params to OpenAPI format. */
+  #convertPath(path: string): string {
+    return path.replace(/:(\w+)\??/g, '{$1}')
+  }
+
+  /** Extract parameter names from path. */
+  #extractPathParams(path: string): string[] {
+    const matches = path.matchAll(/:(\w+)\??/g)
+    return [...matches].map((m) => m[1])
+  }
+
+  /** Generate a summary from route metadata. */
+  #generateSummary(route: RouteDefinition): string {
+    if (route.controller) {
+      return `${route.controller.target.name}.${route.controller.method}`
+    }
+    if (route.name) return route.name
+    return `${route.method} ${route.path}`
+  }
+
+  /** Convert a Rune schema (Record<string, RuleChain>) to JSON Schema. */
+  #runeToJsonSchema(schema: Record<string, unknown>): Record<string, unknown> {
+    const properties: Record<string, unknown> = {}
+    const required: string[] = []
+
+    for (const [field, chainRaw] of Object.entries(schema)) {
+      const chain = chainRaw as {
+        rules?: ReadonlyArray<{ name: string; param?: number }>
+        isOptionalField?: boolean
+      }
+      let type = 'string'
+      const constraints: Record<string, unknown> = {}
+
+      for (const rule of chain.rules ?? []) {
+        if (rule.name === 'string') type = 'string'
+        else if (rule.name === 'number') type = 'number'
+        else if (rule.name === 'boolean') type = 'boolean'
+        else if (rule.name === 'email') constraints.format = 'email'
+        else if (rule.name === 'min' && rule.param !== undefined) {
+          if (type === 'string') constraints.minLength = rule.param
+          else constraints.minimum = rule.param
+        } else if (rule.name === 'max' && rule.param !== undefined) {
+          if (type === 'string') constraints.maxLength = rule.param
+          else constraints.maximum = rule.param
+        }
+      }
+
+      properties[field] = { type, ...constraints }
+      if (!chain.isOptionalField) required.push(field)
+    }
+
+    return {
+      type: 'object',
+      properties,
+      ...(required.length > 0 ? { required } : {}),
+    }
+  }
+
+  /** Get all routes from the router via public API. */
+  #getRoutes(): RouteDefinition[] {
+    return this.#router.getRoutes()
+  }
+}