@avelonjs/core 0.1.0

package/src/runtime/errands.ts

@@ -0,0 +1,148 @@
+import type { DeliveryMode, ListenerContext } from '../events'
+import type { QueueJob } from '../drivers/queue'
+import { Invalid } from '../errors'
+import { backoffSeconds, jobBoard } from './jobs'
+
+/** Job contract for background work with the same three delivery modes as listeners. */
+export interface ErrandDefinition<TPayload = unknown> {
+  /** Registered errand name used when dispatching. */
+  name: string
+  /** Delivery mode. `sync` is the default. */
+  delivery?: DeliveryMode
+  /** Named queue for `queued` delivery. */
+  queue?: string
+  /** Maximum attempts for `queued` delivery. */
+  tries?: number
+  /** Backoff in seconds, or a schedule indexed by attempt. */
+  backoff?: number | readonly number[]
+  /** Performs the work. */
+  handle(payload: TPayload, context: ListenerContext): Promise<void> | void
+}
+
+const registry = new Map<string, ErrandDefinition>()
+const afterJobs: Array<() => Promise<void>> = []
+
+/** Creates an errand definition while preserving its name and delivery mode. */
+export function defineErrand<TPayload>(
+  definition: ErrandDefinition<TPayload>,
+): ErrandDefinition<TPayload> {
+  return definition
+}
+
+/** Registers an errand so `Errands.dispatch` can find it by name. */
+export function registerErrand<TPayload>(definition: ErrandDefinition<TPayload>): void {
+  registry.set(definition.name, definition as ErrandDefinition)
+}
+
+/** Clears registered errands and scheduled after-response work. Intended for tests. */
+export function resetErrands(): void {
+  registry.clear()
+  afterJobs.length = 0
+}
+
+async function run(
+  definition: ErrandDefinition,
+  payload: unknown,
+  context: ListenerContext,
+): Promise<void> {
+  await definition.handle(payload, context)
+}
+
+/** Runs errands scheduled with `delivery: 'after'`. */
+export async function flushAfterErrands(): Promise<void> {
+  const pending = afterJobs.splice(0, afterJobs.length)
+  for (const job of pending) await job()
+}
+
+/** Background-work facade: dispatch, drain, failed table, retry, flush. */
+export const Errands = {
+  /** Registers one errand. */
+  register: registerErrand,
+
+  /** Runs or schedules an errand by name. */
+  async dispatch<TPayload>(name: string, payload: TPayload): Promise<string | undefined> {
+    const definition = registry.get(name)
+    if (definition === undefined) {
+      throw new Invalid(`Unknown errand '${name}'.`, {
+        metadata: { fields: { errand: [`${name} is not registered.`] } },
+      })
+    }
+    const delivery = definition.delivery ?? 'sync'
+    if (delivery === 'sync') {
+      await run(definition, payload, { delivery: 'sync' })
+      return undefined
+    }
+    if (delivery === 'after') {
+      const captured = { definition, payload }
+      afterJobs.push(() => run(captured.definition, captured.payload, { delivery: 'after' }))
+      return undefined
+    }
+    const tries = definition.tries ?? 1
+    const queue = definition.queue ?? 'default'
+    const job: QueueJob = { name: 'avelon.errand', payload: { errand: name, payload }, queue }
+    return jobBoard().enqueue(job, {
+      tries,
+      backoff: definition.backoff ?? 0,
+    })
+  },
+
+  /** Drains queued errands from the process-local failure table. */
+  async work(options: { queue?: string; limit?: number; now?: number } = {}): Promise<number> {
+    await flushAfterErrands()
+    const receipts = jobBoard().take({ ...options, name: 'avelon.errand' })
+    let handled = 0
+    for (const receipt of receipts) {
+      const body = receipt.job.payload as { errand: string; payload: unknown }
+      const definition = registry.get(body.errand)
+      if (definition === undefined) {
+        jobBoard().fail(
+          receipt,
+          new Invalid(`Unknown errand '${body.errand}'.`, {
+            metadata: { fields: { errand: [`${body.errand} is not registered.`] } },
+          }),
+        )
+        continue
+      }
+      const tries = definition.tries ?? 1
+      try {
+        await run(definition, body.payload, {
+          delivery: 'queued',
+          queue: receipt.job.queue ?? 'default',
+          attempt: receipt.attempt,
+          tries,
+        })
+        handled += 1
+      } catch (error) {
+        if (receipt.attempt < tries) {
+          jobBoard().enqueue(receipt.job, {
+            attempt: receipt.attempt,
+            availableAt:
+              (options.now ?? Date.now()) +
+              backoffSeconds(definition.backoff, receipt.attempt) * 1000,
+            tries,
+            backoff: definition.backoff ?? 0,
+          })
+        } else {
+          jobBoard().fail(receipt, error)
+        }
+      }
+    }
+    return handled
+  },
+
+  /** Lists retained terminal failures. */
+  failed(queue?: string) {
+    return jobBoard().failed(queue)
+  },
+
+  /** Releases a failed job. */
+  async retry(id: string, delaySeconds?: number): Promise<void> {
+    jobBoard().retry(id, delaySeconds)
+  },
+
+  /** Drops pending and failed jobs. */
+  flush(): void {
+    afterJobs.length = 0
+    jobBoard().flush()
+  },
+}

package/src/runtime/gate.ts

@@ -0,0 +1,96 @@
+import { Forbidden, Unauthenticated } from '../errors'
+
+/** Actor shape accepted by the gate. `null` is an anonymous caller. */
+export type GateActor = { readonly id: string } | null
+
+/** Ability callback registered for a resource. The actor may be anonymous. */
+export type PolicyHandler = (actor: GateActor, resource?: unknown) => boolean | Promise<boolean>
+
+/** Map of ability names to handlers, matching `definePolicy(Post, { update, delete })`. */
+export type PolicyAbilities = Readonly<Record<string, PolicyHandler>>
+
+type ResourceKey = string | { readonly name: string }
+
+const policies = new Map<string, PolicyAbilities>()
+let currentActor: GateActor = null
+
+function resourceName(resource: ResourceKey | object): string {
+  if (typeof resource === 'string') return resource
+  if (typeof resource === 'function') return resource.name
+  const ctor = Reflect.get(resource, 'constructor')
+  if (typeof ctor === 'function' && typeof ctor.name === 'string' && ctor.name.length > 0) {
+    return ctor.name
+  }
+  if ('name' in resource && typeof resource.name === 'string') return resource.name
+  return 'Resource'
+}
+
+/** Registers a global ability used by `can:*` middleware. */
+export function defineAbility(ability: string, handler: PolicyHandler): void {
+  const existing = policies.get('Gate') ?? {}
+  policies.set('Gate', { ...existing, [ability]: handler })
+}
+
+/** Registers policy abilities for a resource class or name. */
+export function definePolicy(resource: ResourceKey, abilities: PolicyAbilities): void {
+  policies.set(resourceName(resource), abilities)
+}
+
+/** Clears registered policies and the request actor. Intended for tests. */
+export function resetPolicies(): void {
+  policies.clear()
+  currentActor = null
+}
+
+async function allows(actor: GateActor, ability: string, resource?: unknown): Promise<boolean> {
+  if (resource === undefined) return false
+  const name =
+    typeof resource === 'function' || typeof resource === 'string'
+      ? resourceName(resource)
+      : resourceName(resource as object)
+  const abilities = policies.get(name)
+  const handler = abilities?.[ability]
+  if (handler === undefined) return false
+  return handler(actor, typeof resource === 'function' ? undefined : resource)
+}
+
+/** Authorization helpers used by controllers. */
+export const Gate = {
+  /** Binds the request actor used when `authorize`/`can` omit one. */
+  setActor(actor: GateActor): void {
+    currentActor = actor
+  },
+
+  /** Returns the actor bound for this request, or `null`. */
+  actor(): GateActor {
+    return currentActor
+  },
+
+  /** Returns whether the actor may perform the ability. */
+  async can(
+    ability: string,
+    resource?: unknown,
+    actor: GateActor = currentActor,
+  ): Promise<boolean> {
+    return allows(actor, ability, resource)
+  },
+
+  /** Throws when the actor may not perform the ability. */
+  async authorize(
+    ability: string,
+    resource?: unknown,
+    actor: GateActor = currentActor,
+  ): Promise<void> {
+    if (actor === null) {
+      const handlerAllowsAnonymous = await allows(null, ability, resource)
+      if (handlerAllowsAnonymous) return
+      throw new Unauthenticated('Authentication is required.', { metadata: { guard: 'gate' } })
+    }
+    const allowed = await allows(actor, ability, resource)
+    if (!allowed) {
+      throw new Forbidden('This action is unauthorized.', {
+        metadata: { ability, resource: resourceName((resource ?? ability) as ResourceKey) },
+      })
+    }
+  },
+}

package/src/runtime/index.ts

@@ -0,0 +1,81 @@
+export {
+  auth,
+  capabilityMatrix,
+  DB,
+  defineConfig,
+  disks,
+  getConfig,
+  mailers,
+  queues,
+  resetConfig,
+  resolveNamedDriver,
+  type AvelonConfig,
+  type AvelonDrivers,
+  type MaybeNamed,
+  type NamedDrivers,
+} from './config'
+export {
+  createEventDispatcher,
+  eventDispatcher,
+  Events,
+  InProcessEventDispatcher,
+} from './dispatcher'
+export {
+  defineErrand,
+  Errands,
+  flushAfterErrands,
+  registerErrand,
+  resetErrands,
+  type ErrandDefinition,
+} from './errands'
+export {
+  defineAbility,
+  definePolicy,
+  Gate,
+  resetPolicies,
+  type GateActor,
+  type PolicyAbilities,
+  type PolicyHandler,
+} from './gate'
+export {
+  createKernel,
+  finishResponse,
+  mapKernelException,
+  redirect,
+  view,
+  type ControllerClass,
+  type ControllerMethod,
+  type CreateKernelOptions,
+  type KernelMiddleware,
+} from './kernel'
+export { backoffSeconds, jobBoard, MemoryJobBoard } from './jobs'
+export {
+  defineRequest,
+  validateRequest,
+  type FormRequest,
+  type FormRequestDefinition,
+  type RequestSchema,
+} from './requests'
+export { holdUntilCommit, isInTransaction, resetTransaction, runInTransaction } from './transaction'
+export {
+  compilePredicateToSql,
+  compileWardPolicy,
+  compileWardShorthand,
+  defineWard,
+  detectPolicyDrift,
+  detectWardDrift,
+  evaluatePredicate,
+  injectWard,
+  refusedWardShapes,
+  resetWards,
+  resolveWard,
+  rowAllowedByWard,
+  withWard,
+  type CompiledSql,
+  type WardAbilities,
+  type WardAction,
+  type WardDrift,
+  type WardFixture,
+  type WardInput,
+  type WardShorthand,
+} from './wards'

package/src/runtime/jobs.ts

@@ -0,0 +1,126 @@
+import { Invalid } from '../errors'
+import type { FailedQueueJob, QueueJob, QueueReceipt } from '../drivers/queue'
+
+interface MemoryJob {
+  id: string
+  job: QueueJob
+  attempt: number
+  availableAt: number
+  tries: number
+  backoff: number | readonly number[]
+}
+
+/** Process-local job board used when no queue driver is wired. */
+export class MemoryJobBoard {
+  readonly #pending = new Map<string, MemoryJob>()
+  readonly #failed = new Map<string, FailedQueueJob>()
+  #nextId = 1
+
+  /** Enqueues a job for delivery no earlier than `availableAt`. */
+  enqueue(
+    job: QueueJob,
+    options: {
+      availableAt?: number
+      tries?: number
+      backoff?: number | readonly number[]
+      attempt?: number
+    } = {},
+  ): string {
+    const id = `job-${this.#nextId++}`
+    this.#pending.set(id, {
+      id,
+      job: { name: job.name, payload: job.payload, queue: job.queue },
+      attempt: options.attempt ?? 0,
+      availableAt: options.availableAt ?? Date.now(),
+      tries: options.tries ?? 1,
+      backoff: options.backoff ?? 0,
+    })
+    return id
+  }
+
+  /** Takes currently visible jobs, incrementing attempt, up to `limit`. */
+  take(
+    options: { queue?: string; limit?: number; now?: number; name?: string } = {},
+  ): QueueReceipt[] {
+    const now = options.now ?? Date.now()
+    const selected = [...this.#pending.values()]
+      .filter((entry) => entry.availableAt <= now)
+      .filter((entry) => options.queue === undefined || entry.job.queue === options.queue)
+      .filter((entry) => options.name === undefined || entry.job.name === options.name)
+      .sort((left, right) => left.id.localeCompare(right.id))
+      .slice(0, options.limit ?? Number.POSITIVE_INFINITY)
+
+    return selected.map((entry) => {
+      this.#pending.delete(entry.id)
+      const attempt = entry.attempt + 1
+      entry.attempt = attempt
+      return { id: entry.id, job: entry.job, attempt }
+    })
+  }
+
+  /** Records a terminal failure. */
+  fail(receipt: QueueReceipt, error: unknown, failedAt = new Date()): void {
+    this.#failed.set(receipt.id, {
+      id: receipt.id,
+      job: receipt.job,
+      attempt: receipt.attempt,
+      error: error instanceof Error ? error.message : String(error),
+      failedAt,
+    })
+  }
+
+  /** Releases a failed job for another attempt. */
+  retry(id: string, delaySeconds = 0): void {
+    const failed = this.#failed.get(id)
+    if (failed === undefined) {
+      throw new Invalid(`Unknown failed job ${id}.`, {
+        metadata: { fields: { job: [`${id} is not in the failed table.`] } },
+      })
+    }
+    this.#failed.delete(id)
+    this.#pending.set(id, {
+      id,
+      job: failed.job,
+      attempt: failed.attempt,
+      availableAt: Date.now() + delaySeconds * 1000,
+      tries: failed.attempt + 1,
+      backoff: delaySeconds,
+    })
+  }
+
+  /** Permanently removes a retained terminal failure. */
+  forget(id: string): void {
+    this.#failed.delete(id)
+  }
+
+  /** Lists retained terminal failures. */
+  failed(queue?: string): readonly FailedQueueJob[] {
+    return [...this.#failed.values()].filter(
+      (entry) => queue === undefined || entry.job.queue === queue,
+    )
+  }
+
+  /** Drops pending and failed jobs. */
+  flush(): void {
+    this.#pending.clear()
+    this.#failed.clear()
+  }
+}
+
+const shared = new MemoryJobBoard()
+
+/** Returns the process-local job board used by events and errands. */
+export function jobBoard(): MemoryJobBoard {
+  return shared
+}
+
+/** Delay in seconds for a one-based attempt. */
+export function backoffSeconds(
+  backoff: number | readonly number[] | undefined,
+  attempt: number,
+): number {
+  if (backoff === undefined) return 0
+  if (typeof backoff === 'number') return backoff
+  const last = backoff[backoff.length - 1]
+  return backoff[attempt - 1] ?? last ?? 0
+}

package/src/runtime/kernel.ts

@@ -0,0 +1,202 @@
+import type {
+  ActionResult,
+  HttpRequest,
+  Kernel,
+  KernelResult,
+  RedirectResult,
+  RouteDefinition,
+  ViewResult,
+} from '../adapter'
+import { Forbidden, Invalid, NotFound, Unauthenticated } from '../errors'
+import { Gate, type GateActor } from './gate'
+import { Events } from './dispatcher'
+import { flushAfterErrands } from './errands'
+
+/** Controller method signature accepted by the default kernel. */
+export type ControllerMethod = (
+  request: HttpRequest,
+  ...bindings: unknown[]
+) => Promise<KernelResult | unknown> | KernelResult | unknown
+
+/** Constructable controller with action methods. */
+export type ControllerClass = new () => object
+
+/** Middleware invoked before controller dispatch. */
+export type KernelMiddleware = (
+  request: HttpRequest,
+  route: RouteDefinition<ControllerClass>,
+) => Promise<void> | void
+
+/** Options for {@link createKernel}. */
+export interface CreateKernelOptions {
+  /** Resolves a route-model binding name to a hydrated value. */
+  resolveBinding?: (name: string, value: string) => Promise<unknown>
+  /** Resolves the request actor for `auth` and `can:*` middleware. */
+  resolveActor?: (request: HttpRequest) => Promise<GateActor> | GateActor
+  /** Named middleware aliases in addition to the built-in `auth` and `can:*` handlers. */
+  middleware?: Readonly<Record<string, KernelMiddleware>>
+  /** Maps framework errors to kernel results. */
+  mapException?: (error: unknown) => KernelResult | undefined
+}
+
+function hasHeader(headers: Readonly<Record<string, string>>, name: string): boolean {
+  const target = name.toLowerCase()
+  return Object.entries(headers).some(
+    ([key, value]) => key.toLowerCase() === target && value.length > 0,
+  )
+}
+
+/** Maps framework errors onto transport-neutral kernel results. */
+export function mapKernelException(error: unknown): KernelResult | undefined {
+  if (error instanceof Invalid) {
+    return {
+      type: 'action',
+      ok: false,
+      errors: error.metadata.fields ?? { _form: [error.message] },
+      status: 422,
+    } satisfies ActionResult
+  }
+  if (error instanceof Unauthenticated) {
+    return {
+      type: 'redirect',
+      location: '/login',
+      status: 302,
+    } satisfies RedirectResult
+  }
+  if (error instanceof Forbidden) {
+    return {
+      type: 'action',
+      ok: false,
+      errors: { _form: [error.message] },
+      status: 403,
+    } satisfies ActionResult
+  }
+  if (error instanceof NotFound) {
+    return {
+      type: 'action',
+      ok: false,
+      errors: { _form: [error.message] },
+      status: 404,
+    } satisfies ActionResult
+  }
+  return undefined
+}
+
+/**
+ * Creates the default request pipeline kernel.
+ *
+ * Adapters mount routes into this dispatcher rather than reimplementing middleware, binding, or
+ * exception mapping.
+ */
+export function createKernel(options: CreateKernelOptions = {}): Kernel<ControllerClass> {
+  return {
+    async dispatch(route, request) {
+      try {
+        if (options.resolveActor) {
+          Gate.setActor(await options.resolveActor(request))
+        }
+        await runMiddleware(route, request, options)
+        const bindings = await resolveBindings(route, request, options.resolveBinding)
+        const controller = new route.controller()
+        const action = Reflect.get(controller, route.action)
+        if (typeof action !== 'function') {
+          throw new NotFound(`Controller action ${route.action} was not found.`, {
+            metadata: { resource: 'controller_action', identifier: route.action },
+          })
+        }
+        const result = await (action as ControllerMethod).call(controller, request, ...bindings)
+        return normalizeResult(result)
+      } catch (error) {
+        const mapped = options.mapException?.(error) ?? mapKernelException(error)
+        if (mapped !== undefined) return mapped
+        throw error
+      }
+    },
+  }
+}
+
+async function runMiddleware(
+  route: RouteDefinition<ControllerClass>,
+  request: HttpRequest,
+  options: CreateKernelOptions,
+): Promise<void> {
+  for (const name of route.middleware) {
+    const custom = options.middleware?.[name]
+    if (custom !== undefined) {
+      await custom(request, route)
+      continue
+    }
+    if (name === 'auth') {
+      const actor = options.resolveActor ? await options.resolveActor(request) : Gate.actor()
+      const signedIn =
+        actor !== null ||
+        hasHeader(request.headers, 'authorization') ||
+        hasHeader(request.headers, 'cookie')
+      if (!signedIn) {
+        throw new Unauthenticated('Authentication is required.', { metadata: { guard: 'auth' } })
+      }
+      continue
+    }
+    if (name.startsWith('can:')) {
+      const ability = name.slice(4)
+      const actor = options.resolveActor ? await options.resolveActor(request) : Gate.actor()
+      await Gate.authorize(ability, 'Gate', actor)
+      continue
+    }
+  }
+}
+
+async function resolveBindings(
+  route: RouteDefinition<ControllerClass>,
+  request: HttpRequest,
+  resolveBinding?: CreateKernelOptions['resolveBinding'],
+): Promise<unknown[]> {
+  const bindings: unknown[] = []
+  for (const [param, model] of Object.entries(route.bindings)) {
+    const value = request.params[param]
+    if (value === undefined) {
+      throw new NotFound(`Route parameter ${param} is missing.`, {
+        metadata: { resource: model, identifier: param },
+      })
+    }
+    bindings.push(resolveBinding ? await resolveBinding(model, value) : value)
+  }
+  return bindings
+}
+
+function normalizeResult(result: unknown): KernelResult {
+  if (isKernelResult(result)) return result
+  return { type: 'action', ok: true, data: result } satisfies ActionResult
+}
+
+function isKernelResult(value: unknown): value is KernelResult {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'type' in value &&
+    (value.type === 'action' ||
+      value.type === 'redirect' ||
+      value.type === 'view' ||
+      value.type === 'stream')
+  )
+}
+
+/** Helper that builds a view result with an opaque adapter-owned reference. */
+export function view<TView, TProps extends object>(
+  viewRef: TView,
+  props: TProps,
+  status = 200,
+): ViewResult<TView, TProps> {
+  return { type: 'view', view: viewRef, props, status }
+}
+
+/** Helper that builds a redirect result. */
+export function redirect(location: string, status: RedirectResult['status'] = 302): RedirectResult {
+  return { type: 'redirect', location, status }
+}
+
+/** Flushes `after` listeners once the adapter has sent a response. */
+export async function finishResponse(): Promise<void> {
+  await Events.flushAfterResponse()
+  await flushAfterErrands()
+}