@beignet/next 0.0.3 → 0.0.4

package/src/index.ts

@@ -7,9 +7,16 @@ import {
 } from "@beignet/core/outbox";
 import type { AnyPorts, StoragePort } from "@beignet/core/ports";
 import type {
-  ProvidedPortsOfList,
+  InferProviderPorts,
   ServiceProvider,
 } from "@beignet/core/providers";
+import { resolveProviderInstrumentationPort } from "@beignet/core/providers";
+import {
+  createInlineScheduleRunner,
+  type ScheduleDef,
+  type ScheduleInstrumentation,
+  type StandardSchema,
+} from "@beignet/core/schedules";
 import type {
   ContractLike,
   CreateServerOptions,
@@ -17,6 +24,7 @@ import type {
   HttpRequestLike,
   ResolveContract,
   RouteDef,
+  ServerInstance,
   StandardSchemaV1,
 } from "@beignet/core/server";
 import { createServer } from "@beignet/core/server";
@@ -27,11 +35,14 @@ import { createFetchHandler, toWebResponse } from "@beignet/web";
  * Server types re-exported for Next.js apps.
  */
 export type {
+  AnyUseCaseLike,
   CreateServerOptions,
+  HandlerRouteDef,
   RouteDef,
   RouteGroup,
   RouteHook,
   ServerInstance,
+  UseCaseRouteDef,
 } from "@beignet/core/server";
 /**
  * Server helpers re-exported for Next.js apps.
@@ -39,9 +50,9 @@ export type {
 export {
   contractsFromRoutes,
   createServer,
+  defaultBinderInput,
   defineRoute,
   defineRouteGroup,
-  defineRouteHook,
   defineRoutes,
 } from "@beignet/core/server";
 
@@ -54,7 +65,11 @@ type AnyProvider = ServiceProvider<
   unknown,
   // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
   StandardSchemaV1<any, any>,
-  AnyPorts
+  AnyPorts,
+  // biome-ignore lint/suspicious/noExplicitAny: provider context types are erased at this level
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: provider service-input types are erased at this level
+  any
 >;
 
 /**
@@ -202,7 +217,7 @@ type OutboxDrainLogger = {
   error(message: string, metadata?: Record<string, unknown>): void;
 };
 
-type OutboxDrainDevtools = {
+type OutboxDrainInstrumentation = {
   record(event: {
     type: "custom";
     watcher: string;
@@ -220,7 +235,8 @@ type OutboxDrainPorts = {
   eventBus?: DrainOutboxOptions["eventBus"];
   jobs?: DrainOutboxOptions["jobs"];
   logger?: OutboxDrainLogger;
-  devtools?: OutboxDrainDevtools;
+  devtools?: OutboxDrainInstrumentation;
+  instrumentation?: OutboxDrainInstrumentation;
 };
 
 type OutboxDrainContext = {
@@ -266,6 +282,59 @@ export type CreateOutboxDrainRouteOptions<Ctx extends OutboxDrainContext> = {
   headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
 };
 
+type ScheduleRouteLogger = {
+  error(message: string, metadata?: Record<string, unknown>): void;
+};
+
+type ScheduleRoutePorts = {
+  logger?: ScheduleRouteLogger;
+  devtools?: ScheduleInstrumentation;
+  instrumentation?: ScheduleInstrumentation;
+};
+
+type ScheduleRouteContext = {
+  requestId?: string;
+  traceId?: string;
+  ports: ScheduleRoutePorts;
+};
+
+/**
+ * Options for creating a serverless-safe schedule trigger route.
+ */
+export type CreateScheduleRouteOptions<Ctx extends ScheduleRouteContext> = {
+  /**
+   * Beignet Next server that owns app context and ports.
+   */
+  server: Pick<NextServer<Ctx, Ctx["ports"]>, "createContextFromNext">;
+  /**
+   * Registered schedules, usually the `schedules` array from
+   * `server/schedules.ts`.
+   */
+  schedules: readonly ScheduleDef<string, StandardSchema, Ctx>[];
+  /**
+   * Name of the schedule this route triggers. Unknown names throw when the
+   * route module loads so misconfigured routes fail at build or boot time.
+   */
+  schedule: string;
+  /**
+   * Shared secret expected in the `Authorization: Bearer <secret>` header.
+   *
+   * Missing secrets fail closed with a 500 response so deployments do not
+   * accidentally expose an unauthenticated trigger route.
+   */
+  secret?: string;
+  /**
+   * Run source label recorded on run metadata and devtools events.
+   *
+   * @default "next-cron-route"
+   */
+  source?: string;
+  /**
+   * Additional response headers.
+   */
+  headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
+};
+
 type UploadRouteContext = {
   params?:
     | Promise<Record<string, string | string[] | undefined>>
@@ -275,7 +344,11 @@ type UploadRouteContext = {
 /**
  * Beignet server adapted for Next.js route handlers and server components.
  */
-export interface NextServer<Ctx, Ports extends AnyPorts = AnyPorts> {
+export interface NextServer<
+  Ctx,
+  Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
+> {
   /**
    * Catch-all Next.js route handler.
    */
@@ -294,6 +367,25 @@ export interface NextServer<Ctx, Ports extends AnyPorts = AnyPorts> {
    * Create app context from `next/headers` for Server Components.
    */
   createContextFromNext: () => Promise<Ctx>;
+  /**
+   * Build a fully assembled request context from a framework-neutral request.
+   */
+  createRequestContext: ServerInstance<
+    Ctx,
+    Ports,
+    ServiceInput
+  >["createRequestContext"];
+  /**
+   * Build a fully assembled service context for schedules, outbox drains,
+   * commands, and background work.
+   *
+   * Requires `context.service` to be declared in `createNextServer(...)`.
+   */
+  createServiceContext: ServerInstance<
+    Ctx,
+    Ports,
+    ServiceInput
+  >["createServiceContext"];
   /**
    * Registered contract inputs.
    */
@@ -683,7 +775,7 @@ export function createUploadRoute(
   };
 }
 
-function outboxDrainJson(
+function cronRouteJson(
   body: unknown,
   status: number,
   headers: HeadersInit | undefined,
@@ -694,6 +786,39 @@ function outboxDrainJson(
   });
 }
 
+/**
+ * Compare two strings without leaking length or prefix timing.
+ *
+ * Both values are hashed with SHA-256 so the XOR comparison always runs over
+ * fixed-size digests, which keeps the check edge-compatible and constant-time.
+ */
+async function timingSafeStringEqual(a: string, b: string): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const [digestA, digestB] = await Promise.all([
+    crypto.subtle.digest("SHA-256", encoder.encode(a)),
+    crypto.subtle.digest("SHA-256", encoder.encode(b)),
+  ]);
+  const bytesA = new Uint8Array(digestA);
+  const bytesB = new Uint8Array(digestB);
+
+  let mismatch = 0;
+  for (let index = 0; index < bytesA.length; index++) {
+    mismatch |= (bytesA[index] ?? 0) ^ (bytesB[index] ?? 0);
+  }
+
+  return mismatch === 0;
+}
+
+async function isAuthorizedCronRequest(
+  req: Request,
+  secret: string,
+): Promise<boolean> {
+  return timingSafeStringEqual(
+    req.headers.get("authorization") ?? "",
+    `Bearer ${secret}`,
+  );
+}
+
 /**
  * Create Next.js route handlers that drain one durable outbox batch.
  *
@@ -712,7 +837,7 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
     const secret = options.secret;
 
     if (!secret) {
-      return outboxDrainJson(
+      return cronRouteJson(
         {
           ok: false,
           error: "CRON_SECRET is not configured.",
@@ -722,12 +847,8 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
       );
     }
 
-    if (req.headers.get("authorization") !== `Bearer ${secret}`) {
-      return outboxDrainJson(
-        { ok: false, error: "Unauthorized" },
-        401,
-        headers,
-      );
+    if (!(await isAuthorizedCronRequest(req, secret))) {
+      return cronRouteJson({ ok: false, error: "Unauthorized" }, 401, headers);
     }
 
     let ctx: Ctx | undefined;
@@ -743,7 +864,11 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
         batchSize: options.batchSize,
         leaseMs: options.leaseMs,
         retryDelayMs: options.retryDelayMs,
-        instrumentation: drainCtx.ports.devtools,
+        instrumentation: resolveProviderInstrumentationPort(drainCtx.ports),
+        instrumentationContext: {
+          requestId: drainCtx.requestId,
+          traceId: drainCtx.traceId,
+        },
         onError(error, message) {
           drainCtx.ports.logger?.error("Outbox delivery failed", {
             error,
@@ -756,7 +881,7 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
       });
 
       try {
-        await drainCtx.ports.devtools?.record({
+        await resolveProviderInstrumentationPort(drainCtx.ports)?.record({
           type: "custom",
           watcher: "outbox",
           name: "outbox.drain",
@@ -767,12 +892,15 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
           details: result,
         });
       } catch (error) {
-        drainCtx.ports.logger?.error("Outbox drain devtools recording failed", {
-          error,
-        });
+        drainCtx.ports.logger?.error(
+          "Outbox drain instrumentation recording failed",
+          {
+            error,
+          },
+        );
       }
 
-      return outboxDrainJson(
+      return cronRouteJson(
         {
           ok: true,
           result,
@@ -783,7 +911,7 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
     } catch (error) {
       ctx?.ports.logger?.error("Outbox drain failed", { error });
 
-      return outboxDrainJson(
+      return cronRouteJson(
         {
           ok: false,
           error: "Outbox drain failed.",
@@ -800,6 +928,105 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
   };
 }
 
+/**
+ * Create Next.js route handlers that trigger one registered schedule.
+ *
+ * This helper is intended for serverless cron routes. It authenticates the
+ * caller with a timing-safe bearer comparison, creates app context, runs the
+ * schedule inline, and records `schedule` events through the resolved
+ * provider instrumentation port (`ports.instrumentation`, then
+ * `ports.devtools`) when one is installed.
+ */
+export function createScheduleRoute<Ctx extends ScheduleRouteContext>(
+  options: CreateScheduleRouteOptions<Ctx>,
+): {
+  GET: (req: Request) => Promise<Response>;
+  POST: (req: Request) => Promise<Response>;
+} {
+  const schedule = options.schedules.find(
+    (candidate) => candidate.name === options.schedule,
+  );
+
+  if (!schedule) {
+    const available = options.schedules
+      .map((candidate) => candidate.name)
+      .sort();
+
+    throw new Error(
+      available.length > 0
+        ? `Unknown schedule "${options.schedule}". Available schedules: ${available.join(", ")}.`
+        : `Unknown schedule "${options.schedule}". No schedules were passed to createScheduleRoute(...).`,
+    );
+  }
+
+  const runScheduleFromRequest = async (req: Request): Promise<Response> => {
+    const headers = resolveHeaders(options.headers, req);
+    const secret = options.secret;
+
+    if (!secret) {
+      return cronRouteJson(
+        {
+          ok: false,
+          error: "CRON_SECRET is not configured.",
+          scheduleName: schedule.name,
+        },
+        500,
+        headers,
+      );
+    }
+
+    if (!(await isAuthorizedCronRequest(req, secret))) {
+      return cronRouteJson({ ok: false, error: "Unauthorized" }, 401, headers);
+    }
+
+    try {
+      const ctx = await options.server.createContextFromNext();
+      const runner = createInlineScheduleRunner<Ctx>({
+        ctx,
+        instrumentation: resolveProviderInstrumentationPort(ctx.ports),
+        instrumentationContext: {
+          requestId: ctx.requestId,
+          traceId: ctx.traceId,
+        },
+        onError({ error }) {
+          ctx.ports.logger?.error("Schedule failed", {
+            error,
+            scheduleName: schedule.name,
+          });
+        },
+      });
+
+      await runner.run(schedule, {
+        source: options.source ?? "next-cron-route",
+      });
+
+      return cronRouteJson(
+        {
+          ok: true,
+          scheduleName: schedule.name,
+        },
+        200,
+        headers,
+      );
+    } catch {
+      return cronRouteJson(
+        {
+          ok: false,
+          error: "Schedule failed.",
+          scheduleName: schedule.name,
+        },
+        500,
+        headers,
+      );
+    }
+  };
+
+  return {
+    GET: runScheduleFromRequest,
+    POST: runScheduleFromRequest,
+  };
+}
+
 /**
  * Create a Beignet server adapted for Next.js.
  *
@@ -810,11 +1037,14 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
 export async function createNextServer<
   Ctx,
   Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
   Routes extends readonly RouteDef<Ctx>[] = readonly RouteDef<Ctx>[],
   Providers extends readonly AnyProvider[] = readonly AnyProvider[],
 >(
-  options: CreateServerOptions<Ctx, Ports, Routes, Providers>,
-): Promise<NextServer<Ctx, Ports & ProvidedPortsOfList<Providers>>> {
+  options: CreateServerOptions<Ctx, Ports, ServiceInput, Routes, Providers>,
+): Promise<
+  NextServer<Ctx, Ports & InferProviderPorts<Providers>, ServiceInput>
+> {
   const runtime = await createServer(options);
 
   return {
@@ -823,14 +1053,16 @@ export async function createNextServer<
       handle: (fn) => createFetchHandler(runtime.route(contract).handle(fn)),
     }),
     createContextFromNext: async () => {
-      const { cookies, headers } = await import("next/headers");
+      // "next" ships no package exports map, so Node-style ESM resolution
+      // (NodeNext) needs the explicit .js subpath. Bundlers resolve it the same.
+      const { cookies, headers } = await import("next/headers.js");
       const h = await headers();
       const c = await cookies();
 
       // Minimal Request-like object for Next.js Server Components.
       // Note: Server Components don't have a real HTTP URL; this is a synthetic placeholder.
       // Do not rely on `url` for routing, security, or network behavior.
-      // Extended with cookies property for easier access in createContext.
+      // Extended with cookies property for easier access in context factories.
       // The json() and text() methods return empty values since there's no actual HTTP request body.
       const req: HttpRequestLike & {
         cookies?: { get: (key: string) => string | undefined };
@@ -851,11 +1083,10 @@ export async function createNextServer<
         },
       };
 
-      return options.createContext({
-        req,
-        ports: runtime.ports,
-      });
+      return runtime.createRequestContext(req);
     },
+    createRequestContext: runtime.createRequestContext,
+    createServiceContext: runtime.createServiceContext,
     contracts: runtime.contracts,
     stop: () => runtime.stop(),
     ports: runtime.ports,