@beignet/core 0.0.1

package/src/schedules/index.ts

@@ -0,0 +1,442 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+export type MaybePromise<T> = T | Promise<T>;
+
+export type InferSchemaOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+export type ScheduleDateInput = Date | string | number;
+
+export interface ScheduleRunContext {
+  readonly id?: string;
+  readonly scheduledAt?: Date;
+  readonly triggeredAt: Date;
+  readonly source?: string;
+}
+
+export interface SchedulePayloadDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+> {
+  readonly name: Name;
+  readonly payload: Payload;
+}
+
+export interface ScheduleDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+  Ctx = unknown,
+> extends SchedulePayloadDef<Name, Payload> {
+  readonly kind: "schedule";
+  readonly cron: string;
+  readonly timezone?: string;
+  readonly description?: string;
+  createPayload?(
+    args: ScheduleCreatePayloadArgs<ScheduleDef<Name, Payload, Ctx>>,
+  ): MaybePromise<InferSchemaOutput<Payload>>;
+  handle(
+    args: ScheduleHandleArgs<ScheduleDef<Name, Payload, Ctx>, Ctx>,
+  ): MaybePromise<void>;
+}
+
+export type InferSchedulePayload<S extends SchedulePayloadDef> =
+  S["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+
+export interface ScheduleCreatePayloadArgs<S extends SchedulePayloadDef> {
+  schedule: S;
+  run: ScheduleRunContext;
+}
+
+export interface ScheduleHandleArgs<S extends ScheduleDef, Ctx> {
+  schedule: S;
+  payload: InferSchedulePayload<S>;
+  ctx: Ctx;
+  run: ScheduleRunContext;
+}
+
+export interface DefineScheduleOptions<
+  Name extends string,
+  Payload extends StandardSchema,
+  Ctx,
+> {
+  cron: string;
+  timezone?: string;
+  payload: Payload;
+  description?: string;
+  createPayload?(
+    args: ScheduleCreatePayloadArgs<ScheduleDef<Name, Payload, Ctx>>,
+  ): MaybePromise<InferSchemaOutput<Payload>>;
+  handle(
+    args: ScheduleHandleArgs<ScheduleDef<Name, Payload, Ctx>, Ctx>,
+  ): MaybePromise<void>;
+}
+
+export interface ScheduleRunOptions<Payload = unknown> {
+  payload?: Payload;
+  id?: string;
+  scheduledAt?: ScheduleDateInput;
+  triggeredAt?: ScheduleDateInput;
+  source?: string;
+}
+
+export type ScheduleRunArgs<
+  Ctx,
+  Payload = unknown,
+> = ScheduleRunOptions<Payload> & {
+  ctx: Ctx;
+};
+
+export interface ScheduleLifecycleArgs<S extends ScheduleDef = ScheduleDef> {
+  schedule: S;
+  payload: InferSchedulePayload<S>;
+  run: ScheduleRunContext;
+}
+
+export interface ScheduleErrorArgs<S extends ScheduleDef = ScheduleDef> {
+  schedule: S;
+  payload?: InferSchedulePayload<S>;
+  run: ScheduleRunContext;
+  error: unknown;
+}
+
+export type ScheduleHookName = "start" | "success" | "error";
+
+export interface ScheduleHookErrorArgs<S extends ScheduleDef = ScheduleDef> {
+  schedule: S;
+  payload?: InferSchedulePayload<S>;
+  run: ScheduleRunContext;
+  hook: ScheduleHookName;
+  error: unknown;
+  scheduleError?: unknown;
+}
+
+export interface InlineScheduleRunnerOptions<Ctx> {
+  ctx?: Ctx | (() => MaybePromise<Ctx>);
+  now?: () => Date;
+  onStart?<S extends ScheduleDef<string, StandardSchema, Ctx>>(
+    args: ScheduleLifecycleArgs<S>,
+  ): MaybePromise<void>;
+  onSuccess?<S extends ScheduleDef<string, StandardSchema, Ctx>>(
+    args: ScheduleLifecycleArgs<S>,
+  ): MaybePromise<void>;
+  onError?<S extends ScheduleDef<string, StandardSchema, Ctx>>(
+    args: ScheduleErrorArgs<S>,
+  ): MaybePromise<void>;
+  onHookError?<S extends ScheduleDef<string, StandardSchema, Ctx>>(
+    args: ScheduleHookErrorArgs<S>,
+  ): MaybePromise<void>;
+}
+
+export interface ScheduleRunnerPort<Ctx = unknown> {
+  run<S extends ScheduleDef<string, StandardSchema, Ctx>>(
+    schedule: S,
+    options?: ScheduleRunOptions<InferSchedulePayload<S>>,
+  ): Promise<void>;
+}
+
+export interface InlineScheduleRunner<Ctx = unknown>
+  extends ScheduleRunnerPort<Ctx> {}
+
+export interface ScheduleHandlers<Ctx> {
+  defineSchedule<Name extends string, Payload extends StandardSchema>(
+    name: Name,
+    options: DefineScheduleOptions<Name, Payload, Ctx>,
+  ): ScheduleDef<Name, Payload, Ctx>;
+
+  createInlineScheduleRunner(
+    options?: InlineScheduleRunnerOptions<Ctx>,
+  ): InlineScheduleRunner<Ctx>;
+}
+
+export class ScheduleValidationError extends Error {
+  readonly issues: readonly StandardSchemaV1.Issue[];
+
+  constructor(args: {
+    name: string;
+    issues: readonly StandardSchemaV1.Issue[];
+  }) {
+    super(
+      `Schedule "${args.name}" payload validation failed: ${formatIssues(args.issues)}`,
+    );
+    this.name = "ScheduleValidationError";
+    this.issues = args.issues;
+  }
+}
+
+export class ScheduleRunContextError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScheduleRunContextError";
+  }
+}
+
+function formatPath(path: StandardSchemaV1.Issue["path"]): string {
+  if (!path?.length) return "";
+
+  return path
+    .map((segment) =>
+      typeof segment === "object" && segment !== null && "key" in segment
+        ? String(segment.key)
+        : String(segment),
+    )
+    .join(".");
+}
+
+function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  return issues
+    .map((issue) => {
+      const path = formatPath(issue.path);
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join("; ");
+}
+
+async function parsePayload<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  input: unknown,
+  args: { name: string },
+): Promise<InferSchemaOutput<Schema>> {
+  const result = await schema["~standard"].validate(input);
+
+  if (result.issues?.length) {
+    throw new ScheduleValidationError({
+      name: args.name,
+      issues: result.issues,
+    });
+  }
+
+  if ("value" in result) {
+    return result.value as InferSchemaOutput<Schema>;
+  }
+
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+function normalizeDate(
+  value: ScheduleDateInput | undefined,
+  field: string,
+  fallback: () => Date,
+): Date {
+  if (value === undefined) return fallback();
+
+  const date =
+    value instanceof Date ? new Date(value.getTime()) : new Date(value);
+
+  if (Number.isNaN(date.getTime())) {
+    throw new ScheduleRunContextError(
+      `Schedule run ${field} must be a valid date.`,
+    );
+  }
+
+  return date;
+}
+
+function normalizeOptionalDate(
+  value: ScheduleDateInput | undefined,
+  field: string,
+): Date | undefined {
+  if (value === undefined) return undefined;
+  return normalizeDate(value, field, () => new Date());
+}
+
+function createRunContext(
+  options: ScheduleRunOptions<unknown>,
+  now: () => Date,
+): ScheduleRunContext {
+  return {
+    id: options.id,
+    scheduledAt: normalizeOptionalDate(options.scheduledAt, "scheduledAt"),
+    triggeredAt: normalizeDate(options.triggeredAt, "triggeredAt", now),
+    source: options.source,
+  };
+}
+
+async function resolveCtx<Ctx>(
+  ctx: Ctx | (() => MaybePromise<Ctx>) | undefined,
+): Promise<Ctx> {
+  if (typeof ctx === "function") {
+    return (ctx as () => MaybePromise<Ctx>)();
+  }
+
+  return ctx as Ctx;
+}
+
+async function resolveSchedulePayload<S extends ScheduleDef>(
+  schedule: S,
+  options: ScheduleRunOptions<InferSchedulePayload<S>>,
+  run: ScheduleRunContext,
+): Promise<InferSchedulePayload<S>> {
+  const hasExplicitPayload = Object.hasOwn(options, "payload");
+  const rawPayload = hasExplicitPayload
+    ? options.payload
+    : await schedule.createPayload?.({ schedule, run });
+
+  return parseSchedulePayload(schedule, rawPayload);
+}
+
+async function reportHookError<
+  Ctx,
+  S extends ScheduleDef<string, StandardSchema, Ctx>,
+>(
+  onHookError: InlineScheduleRunnerOptions<Ctx>["onHookError"] | undefined,
+  args: ScheduleHookErrorArgs<S>,
+): Promise<void> {
+  try {
+    await onHookError?.(args);
+  } catch {
+    // Hook failures are isolated from schedule execution.
+  }
+}
+
+async function runLifecycleHook<
+  Ctx,
+  S extends ScheduleDef<string, StandardSchema, Ctx>,
+>(
+  hook: Exclude<ScheduleHookName, "error">,
+  handler: ((args: ScheduleLifecycleArgs<S>) => MaybePromise<void>) | undefined,
+  onHookError: InlineScheduleRunnerOptions<Ctx>["onHookError"] | undefined,
+  args: ScheduleLifecycleArgs<S>,
+): Promise<void> {
+  try {
+    await handler?.(args);
+  } catch (error) {
+    await reportHookError(onHookError, { ...args, hook, error });
+  }
+}
+
+async function runErrorHook<
+  Ctx,
+  S extends ScheduleDef<string, StandardSchema, Ctx>,
+>(
+  handler: ((args: ScheduleErrorArgs<S>) => MaybePromise<void>) | undefined,
+  onHookError: InlineScheduleRunnerOptions<Ctx>["onHookError"] | undefined,
+  args: ScheduleErrorArgs<S>,
+): Promise<void> {
+  try {
+    await handler?.(args);
+  } catch (error) {
+    await reportHookError(onHookError, {
+      schedule: args.schedule,
+      payload: args.payload,
+      run: args.run,
+      hook: "error",
+      error,
+      scheduleError: args.error,
+    });
+  }
+}
+
+export function defineSchedule<
+  Name extends string,
+  Payload extends StandardSchema,
+  Ctx = unknown,
+>(
+  name: Name,
+  options: DefineScheduleOptions<Name, Payload, Ctx>,
+): ScheduleDef<Name, Payload, Ctx> {
+  return {
+    kind: "schedule",
+    name,
+    cron: options.cron,
+    timezone: options.timezone,
+    payload: options.payload,
+    description: options.description,
+    createPayload: options.createPayload as
+      | ScheduleDef<Name, Payload, Ctx>["createPayload"]
+      | undefined,
+    handle: options.handle as ScheduleDef<Name, Payload, Ctx>["handle"],
+  };
+}
+
+export async function parseSchedulePayload<S extends SchedulePayloadDef>(
+  schedule: S,
+  payload: unknown,
+): Promise<InferSchedulePayload<S>> {
+  return (await parsePayload(schedule.payload, payload, {
+    name: schedule.name,
+  })) as InferSchedulePayload<S>;
+}
+
+export async function runSchedule<
+  Ctx,
+  S extends ScheduleDef<string, StandardSchema, Ctx>,
+>(
+  schedule: S,
+  args: ScheduleRunArgs<Ctx, InferSchedulePayload<S>>,
+): Promise<void> {
+  const run = createRunContext(args, () => new Date());
+  const payload = await resolveSchedulePayload(schedule, args, run);
+
+  await schedule.handle({
+    schedule,
+    payload,
+    ctx: args.ctx,
+    run,
+  });
+}
+
+export function createInlineScheduleRunner<Ctx>(
+  options: InlineScheduleRunnerOptions<Ctx> = {},
+): InlineScheduleRunner<Ctx> {
+  const now = options.now ?? (() => new Date());
+
+  return {
+    async run<S extends ScheduleDef<string, StandardSchema, Ctx>>(
+      schedule: S,
+      runOptions: ScheduleRunOptions<InferSchedulePayload<S>> = {},
+    ) {
+      const run = createRunContext(runOptions, now);
+      let payload: InferSchedulePayload<S> | undefined;
+
+      try {
+        payload = await resolveSchedulePayload(schedule, runOptions, run);
+
+        const lifecycleArgs = { schedule, payload, run };
+        await runLifecycleHook(
+          "start",
+          options.onStart,
+          options.onHookError,
+          lifecycleArgs,
+        );
+        await schedule.handle({
+          schedule,
+          payload,
+          ctx: await resolveCtx(options.ctx),
+          run,
+        });
+        await runLifecycleHook(
+          "success",
+          options.onSuccess,
+          options.onHookError,
+          lifecycleArgs,
+        );
+      } catch (error) {
+        await runErrorHook(options.onError, options.onHookError, {
+          error,
+          schedule,
+          payload,
+          run,
+        });
+        throw error;
+      }
+    },
+  };
+}
+
+export function createScheduleHandlers<Ctx>(): ScheduleHandlers<Ctx> {
+  return {
+    defineSchedule<Name extends string, Payload extends StandardSchema>(
+      name: Name,
+      options: DefineScheduleOptions<Name, Payload, Ctx>,
+    ): ScheduleDef<Name, Payload, Ctx> {
+      return defineSchedule(name, options);
+    },
+
+    createInlineScheduleRunner(
+      options: InlineScheduleRunnerOptions<Ctx> = {},
+    ): InlineScheduleRunner<Ctx> {
+      return createInlineScheduleRunner(options);
+    },
+  };
+}

package/src/server/contract-like.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export contract resolution utilities for the server runtime.
+ */
+export {
+  type ContractLike,
+  type ResolveContract,
+  resolveContract,
+} from "../contracts";

package/src/server/health.ts

@@ -0,0 +1,82 @@
+/**
+ * Health check handler
+ * Health check handler for Beignet server adapters.
+ */
+
+import type { AnyPorts } from "../ports";
+import type { HttpRequestLike, HttpResponseLike } from "./types";
+
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+  ok: boolean;
+  details?: Record<string, { ok: boolean; message?: string }>;
+}
+
+/**
+ * Health check configuration
+ */
+export interface HealthConfig<Ports> {
+  /** Enable health endpoint (default: false) */
+  enabled?: boolean;
+  /**
+   * Suggested path for the health endpoint (e.g., "/api/health").
+   * NOTE: This field is for documentation/metadata only and does not control routing.
+   * You must manually wire the healthHandler to your desired route.
+   */
+  suggestedPath?: string;
+  /** Custom health check function */
+  check?: (ports: Ports) => Promise<HealthCheckResult>;
+}
+
+/**
+ * Application environment type
+ */
+export type AppEnvironment = "development" | "production" | "test";
+
+/**
+ * Create a health check handler
+ * Returns a function that can be called with an HttpRequestLike to get an HttpResponseLike
+ */
+export function createHealthHandler<Ports extends AnyPorts>(
+  ports: Ports,
+  healthConfig: HealthConfig<Ports> | undefined,
+  env: AppEnvironment,
+): (req: HttpRequestLike) => Promise<HttpResponseLike> {
+  return async (_req: HttpRequestLike): Promise<HttpResponseLike> => {
+    let result: HealthCheckResult;
+    if (healthConfig?.check) {
+      try {
+        result = await healthConfig.check(ports);
+      } catch (error) {
+        // Health check function threw - treat as unhealthy
+        // Only include error details in development/test to avoid leaking sensitive info
+        const includeErrorDetails = env === "development" || env === "test";
+        result = {
+          ok: false,
+          details: {
+            error: {
+              ok: false,
+              message: includeErrorDetails
+                ? error instanceof Error
+                  ? error.message
+                  : String(error)
+                : "Health check failed",
+            },
+          },
+        };
+      }
+    } else {
+      result = { ok: true };
+    }
+
+    const status = result.ok ? 200 : 503;
+
+    return {
+      status,
+      body: result,
+      headers: { "Content-Type": "application/json" },
+    };
+  };
+}

package/src/server/hooks/auth.ts

@@ -0,0 +1,147 @@
+import {
+  type AuthPort,
+  type AuthSession,
+  AuthUnauthorizedError,
+} from "../../ports";
+import type { HttpRequestLike, HttpResponse, ServerHook } from "../types";
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type AuthHookMode = "public" | "optional" | "required";
+export type AuthHookModeInput = AuthHookMode | boolean | null | undefined;
+
+export type CtxWithAuthPort = {
+  ports: {
+    auth: AuthPort;
+  };
+};
+
+export type AuthHookArgs<Ctx> = {
+  req: HttpRequestLike;
+  ctx: Ctx;
+  contract: {
+    metadata?: Record<string, unknown>;
+  };
+  path: unknown;
+  query: unknown;
+  headers: unknown;
+  body: unknown;
+};
+
+export type AuthHookAssignArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
+  session: Session | null;
+};
+
+export type AuthHookUnauthorizedArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
+  session: Session | null;
+};
+
+export type AuthHooksOptions<Ctx, Session> = {
+  name?: string;
+  mode?: (args: AuthHookArgs<Ctx>) => MaybePromise<AuthHookModeInput>;
+  getSession?: (args: AuthHookArgs<Ctx>) => MaybePromise<Session | null>;
+  isAuthenticated?: (session: Session | null) => boolean;
+  assign?: (args: AuthHookAssignArgs<Ctx, Session>) => MaybePromise<Ctx>;
+  unauthorized?: (
+    args: AuthHookUnauthorizedArgs<Ctx, Session>,
+  ) => MaybePromise<HttpResponse>;
+};
+
+type InferAuthSession<TAuth> =
+  TAuth extends AuthPort<infer User, infer SessionMetadata>
+    ? AuthSession<User, SessionMetadata>
+    : unknown;
+
+function modeFromInput(input: AuthHookModeInput): AuthHookMode {
+  if (input === true || input === "required") return "required";
+  if (input === "optional") return "optional";
+  return "public";
+}
+
+function defaultMode<Ctx>(args: AuthHookArgs<Ctx>): AuthHookMode {
+  return modeFromInput(args.contract.metadata?.auth as AuthHookModeInput);
+}
+
+async function defaultGetSession<Ctx>(
+  args: AuthHookArgs<Ctx>,
+): Promise<unknown | null> {
+  const auth = (args.ctx as { ports?: { auth?: AuthPort } }).ports?.auth;
+  if (!auth) {
+    throw new Error(
+      "createAuthHooks requires ctx.ports.auth or an explicit getSession option.",
+    );
+  }
+
+  return auth.getSession(args.req);
+}
+
+function defaultIsAuthenticated<Session>(session: Session | null): boolean {
+  return session !== null;
+}
+
+export function createAuthHooks<Ctx extends CtxWithAuthPort>(
+  options?: AuthHooksOptions<Ctx, InferAuthSession<Ctx["ports"]["auth"]>>,
+): ServerHook<Ctx, Ctx["ports"]>;
+export function createAuthHooks<Ctx, Session>(
+  options: AuthHooksOptions<Ctx, Session> & {
+    getSession: (args: AuthHookArgs<Ctx>) => MaybePromise<Session | null>;
+  },
+): ServerHook<Ctx>;
+export function createAuthHooks<Ctx, Session>(
+  options: AuthHooksOptions<Ctx, Session> = {},
+): ServerHook<Ctx> {
+  return {
+    name: options.name ?? "auth",
+    beforeHandle: async ({
+      req,
+      ctx,
+      contract,
+      path,
+      query,
+      headers,
+      body,
+    }) => {
+      const args: AuthHookArgs<Ctx> = {
+        req,
+        ctx,
+        contract,
+        path,
+        query,
+        headers,
+        body,
+      };
+      const mode = modeFromInput(
+        options.mode ? await options.mode(args) : defaultMode(args),
+      );
+
+      if (mode === "public") {
+        return undefined;
+      }
+
+      const session = options.getSession
+        ? await options.getSession(args)
+        : ((await defaultGetSession(args)) as Session | null);
+      const isAuthenticated =
+        options.isAuthenticated?.(session) ?? defaultIsAuthenticated(session);
+
+      if (mode === "required" && !isAuthenticated) {
+        if (options.unauthorized) {
+          return {
+            ctx,
+            response: await options.unauthorized({ ...args, session }),
+          };
+        }
+
+        throw new AuthUnauthorizedError();
+      }
+
+      if (!options.assign) {
+        return undefined;
+      }
+
+      return {
+        ctx: await options.assign({ ...args, session }),
+      };
+    },
+  };
+}