@nextrush/adapter-edge 1.0.0-beta.0

package/src/adapter.ts

@@ -0,0 +1,333 @@
+/**
+ * @nextrush/adapter-edge - Edge Runtime Adapter
+ *
+ * Connects NextRush Application to Edge runtimes via fetch handlers.
+ *
+ * @remarks
+ * **Size optimization**: Edge runtimes have strict bundle-size constraints
+ * (e.g. Cloudflare Workers 1 MB limit). Import only the packages you need:
+ *
+ * - Import `@nextrush/core` and `@nextrush/adapter-edge` only.
+ * - Avoid `@nextrush/di` unless you need DI (adds `reflect-metadata`).
+ * - Tree-shake unused middleware — each middleware is a separate package.
+ * - Use `@nextrush/router` only if you have dynamic routes; for simple
+ *   handlers, use the application directly.
+ *
+ * @packageDocumentation
+ */
+
+import type { Application } from '@nextrush/core';
+import { jsonErrorResponse } from '@nextrush/runtime';
+import type { AdapterContextFactory, FetchAdapter } from '@nextrush/types';
+import { createEdgeContext, EdgeContext, type EdgeExecutionContext } from './context';
+
+/**
+ * Default request timeout applied when the caller specifies none (F-07,
+ * ADR-0010), converging Edge's default contract with Node/Bun/Deno (which all
+ * default to a bounded timeout rather than none).
+ *
+ * @remarks
+ * 25 000 ms — below the tightest common edge-platform wall limit (Vercel Edge
+ * Functions: 25 s), comfortably above typical handler durations, so the
+ * framework's clean `504` fires before the platform terminates the isolate.
+ * Pass `timeout: 0` to disable the framework timeout entirely (platform limit
+ * alone applies) or a positive value to override the default.
+ */
+export const DEFAULT_EDGE_TIMEOUT_MS = 25_000;
+
+/**
+ * Options for the fetch handler
+ */
+export interface FetchHandlerOptions {
+  /**
+   * Custom error handler
+   */
+  onError?: (error: Error, ctx: EdgeContext) => Response | Promise<Response>;
+
+  /**
+   * Request timeout in milliseconds. The handler races the application logic
+   * against a timer and returns a 504 Gateway Timeout if the timer fires
+   * first, cancelling the still-running handler via `ctx.signal`.
+   *
+   * @remarks
+   * Defaults to {@link DEFAULT_EDGE_TIMEOUT_MS} (25 000 ms) when omitted
+   * (F-07/ADR-0010) — below the tightest common edge-platform wall limit
+   * (Vercel Edge: 25 s), so the framework's clean `504` fires before the
+   * platform terminates the isolate. Pass `0` to disable the framework
+   * timeout entirely (the platform's own limit still applies).
+   *
+   * Per-platform CPU/wall limits for context when overriding:
+   * - Cloudflare Workers: 30 000 (30 s CPU limit)
+   * - Vercel Edge:        25 000 (25 s wall limit)
+   *
+   * @default DEFAULT_EDGE_TIMEOUT_MS (25000)
+   */
+  timeout?: number;
+}
+
+/**
+ * Standard edge fetch handler type
+ */
+export type FetchHandler = (
+  request: Request,
+  ctx?: EdgeExecutionContext
+) => Response | Promise<Response>;
+
+/**
+ * Create a fetch handler for Edge runtimes
+ *
+ * @param app - NextRush Application instance
+ * @param options - Handler options
+ * @returns Fetch handler function
+ *
+ * @example
+ * ```typescript
+ * // Cloudflare Workers
+ * import { createApp } from '@nextrush/core';
+ * import { createFetchHandler } from '@nextrush/adapter-edge';
+ *
+ * const app = createApp();
+ * const handler = createFetchHandler(app);
+ *
+ * export default {
+ *   fetch: handler
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Vercel Edge Functions
+ * import { createApp } from '@nextrush/core';
+ * import { createFetchHandler } from '@nextrush/adapter-edge';
+ *
+ * const app = createApp();
+ * export const config = { runtime: 'edge' };
+ * export default createFetchHandler(app);
+ * ```
+ */
+export function createFetchHandler(
+  app: Application,
+  options: FetchHandlerOptions = {}
+): FetchHandler {
+  const run = createRequestRunner(app, options);
+  return (request: Request, executionContext?: EdgeExecutionContext): Promise<Response> =>
+    run(request, executionContext);
+}
+
+/**
+ * Internal request runner shared by every edge entry point.
+ *
+ * @remarks
+ * Centralizes booting, context creation (threading Cloudflare `env` — F-03),
+ * timeout racing with cooperative cancellation (F-08), the header-preserving
+ * finalize path (F-02), and error handling — so Cloudflare/Vercel/Netlify
+ * handlers cannot drift.
+ */
+function createRequestRunner(
+  app: Application,
+  options: FetchHandlerOptions
+): (request: Request, executionContext?: EdgeExecutionContext, env?: unknown) => Promise<Response> {
+  // F-07/ADR-0010: default to DEFAULT_EDGE_TIMEOUT_MS when the caller specifies
+  // none (`undefined`); `0` remains an explicit opt-out (no framework timeout).
+  const timeout = options.timeout ?? DEFAULT_EDGE_TIMEOUT_MS;
+  const trustProxy = app.options.proxy ?? false;
+
+  /** Sentinel value returned by the timeout racer */
+  const TIMEOUT_SENTINEL = Symbol('timeout');
+
+  // Edge has no serve()/start() phase, so the deferred boot barrier runs lazily
+  // on the first request (idempotent). The boot promise caches the snapshotted
+  // request handler, so every request awaits and reuses the same one.
+  let bootPromise: Promise<ReturnType<Application['callback']>> | null = null;
+  const ensureBooted = (): Promise<ReturnType<Application['callback']>> => {
+    bootPromise ??= app.ready().then(() => {
+      const handler = app.callback();
+      // F-14: mark the app running so `app.isRunning` is consistent with the
+      // server adapters. Edge has no server lifetime, so close()/destroy() are
+      // intentionally never called — that no-teardown contract is documented
+      // on createFetchHandler.
+      app.start();
+      return handler;
+    });
+    return bootPromise;
+  };
+
+  return async (
+    request: Request,
+    executionContext?: EdgeExecutionContext,
+    env?: unknown
+  ): Promise<Response> => {
+    const handler = await ensureBooted();
+    const ctx = createEdgeContext(request, executionContext, trustProxy, env);
+
+    try {
+      if (timeout > 0) {
+        let timerId: ReturnType<typeof setTimeout> | undefined;
+        try {
+          const result = await Promise.race([
+            handler(ctx).then(() => undefined),
+            new Promise<typeof TIMEOUT_SENTINEL>((resolve) => {
+              timerId = setTimeout(() => {
+                resolve(TIMEOUT_SENTINEL);
+              }, timeout);
+            }),
+          ]);
+
+          if (result === TIMEOUT_SENTINEL) {
+            // F-08: cancel the still-running handler cooperatively via ctx.signal.
+            ctx.triggerTimeout();
+            return jsonErrorResponse(504, 'Gateway Timeout');
+          }
+        } finally {
+          // F-08: always clear the timer, on both handler-wins and timeout paths.
+          if (timerId !== undefined) clearTimeout(timerId);
+        }
+      } else {
+        await handler(ctx);
+      }
+
+      // F-02: finalize through the context so headers set via ctx.set() survive
+      // an implicit/empty response. The 404 default body is written through the
+      // same builder, preserving those headers too.
+      if (!ctx.responded && ctx.status === 404) {
+        ctx.json({ error: 'Not Found' });
+      }
+      return ctx.getResponse();
+    } catch (error) {
+      // Custom error handler
+      if (options.onError) {
+        return options.onError(error as Error, ctx);
+      }
+
+      // Default error handling
+      app.logger.error('Request error:', error);
+
+      return jsonErrorResponse(500, 'Internal Server Error');
+    }
+  };
+}
+
+/**
+ * Cloudflare Workers fetch handler type
+ *
+ * Cloudflare's module format passes `(request, env, ctx)` where:
+ * - `env` contains bindings (KV, D1, R2, secrets, etc.)
+ * - `ctx` provides `waitUntil()` and `passThroughOnException()`
+ *
+ * @typeParam Env - The shape of the Worker's bindings.
+ */
+export type CloudflareFetchHandler<Env = Record<string, unknown>> = (
+  request: Request,
+  env: Env,
+  ctx: EdgeExecutionContext
+) => Response | Promise<Response>;
+
+/**
+ * Create Cloudflare Workers module export
+ *
+ * @param app - NextRush Application instance
+ * @param options - Handler options
+ * @returns Cloudflare Workers module export object with correct `(request, env, ctx)` signature
+ *
+ * @remarks
+ * The Cloudflare `env` argument (KV, D1, R2, Durable Objects, Queues, secrets)
+ * is threaded onto the context as `ctx.env` (audit F-03). Pass a binding type
+ * as the generic to make `ctx.env` fully typed inside handlers.
+ *
+ * @example
+ * ```typescript
+ * interface Env { MY_KV: KVNamespace }
+ * export default createCloudflareHandler<Env>(app);
+ * // inside a handler: ctx.env.MY_KV.get('key')
+ * ```
+ */
+export function createCloudflareHandler<Env = Record<string, unknown>>(
+  app: Application,
+  options: FetchHandlerOptions = {}
+): { fetch: CloudflareFetchHandler<Env> } {
+  const run = createRequestRunner(app, options);
+
+  return {
+    fetch: (request: Request, env: Env, ctx: EdgeExecutionContext): Promise<Response> =>
+      run(request, ctx, env),
+  };
+}
+
+/**
+ * Create Vercel Edge Function handler
+ *
+ * @param app - NextRush Application instance
+ * @param options - Handler options
+ * @returns Vercel Edge Function handler
+ *
+ * @example
+ * ```typescript
+ * // api/hello.ts
+ * import { createApp } from '@nextrush/core';
+ * import { createVercelHandler } from '@nextrush/adapter-edge';
+ *
+ * const app = createApp();
+ *
+ * app.use(async (ctx) => {
+ *   ctx.json({
+ *     message: 'Hello from Vercel Edge!',
+ *     region: process.env.VERCEL_REGION
+ *   });
+ * });
+ *
+ * export const config = { runtime: 'edge' };
+ * export default createVercelHandler(app);
+ * ```
+ */
+export function createVercelHandler(
+  app: Application,
+  options: FetchHandlerOptions = {}
+): FetchHandler {
+  return createFetchHandler(app, options);
+}
+
+/**
+ * Create Netlify Edge Function handler
+ *
+ * @param app - NextRush Application instance
+ * @param options - Handler options
+ * @returns Netlify Edge Function handler
+ *
+ * @example
+ * ```typescript
+ * // netlify/edge-functions/api.ts
+ * import { createApp } from '@nextrush/core';
+ * import { createNetlifyHandler } from '@nextrush/adapter-edge';
+ *
+ * const app = createApp();
+ *
+ * app.use(async (ctx) => {
+ *   ctx.json({ message: 'Hello from Netlify Edge!' });
+ * });
+ *
+ * export default createNetlifyHandler(app);
+ * ```
+ */
+export function createNetlifyHandler(
+  app: Application,
+  options: FetchHandlerOptions = {}
+): FetchHandler {
+  return createFetchHandler(app, options);
+}
+
+// Alias for backwards compatibility and consistency
+export const createHandler = createFetchHandler;
+
+// F-01: compile-time conformance guard. If the exported fetch-adapter shape
+// drifts from the shared `FetchAdapter` contract, this stops compiling.
+const _edgeConformance: FetchAdapter<Application, EdgeExecutionContext> = { createFetchHandler };
+void _edgeConformance;
+
+// RFC-NEXTRUSH-ADAPTER-CONTRACT: prove the context factory produces an
+// AdapterContext over the shared Context contract. A drift in createEdgeContext's
+// return type stops compiling here.
+const _edgeContextFactory: AdapterContextFactory<
+  [Request, EdgeExecutionContext?, boolean?, unknown?],
+  EdgeContext
+> = createEdgeContext;
+void _edgeContextFactory;

package/src/body-source.ts

@@ -0,0 +1,19 @@
+/**
+ * @nextrush/adapter-edge - Body Source
+ *
+ * The bespoke `EdgeBodySource`/`EmptyBodySource`/`concatUint8Arrays` have been
+ * collapsed onto the shared cross-runtime {@link WebBodySource} in
+ * `@nextrush/runtime` (audit F-04a). Body-reading behavior is now identical
+ * across the Web adapters (Bun/Deno/Edge) and fixed in one place.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  createEmptyBodySource,
+  createWebBodySource,
+  EmptyBodySource,
+  WebBodySource,
+} from '@nextrush/runtime';
+
+export { createEmptyBodySource, createWebBodySource, EmptyBodySource, WebBodySource };

package/src/context.ts

@@ -0,0 +1,122 @@
+/**
+ * @nextrush/adapter-edge - Context Implementation
+ *
+ * Edge-specific Context implementation for Cloudflare Workers, Vercel Edge, etc.
+ *
+ * @remarks
+ * Extends the shared {@link WebContextBase} (F-08, ADR-0010), which owns the
+ * response-building logic (json/send/html/redirect/set/getResponse and body
+ * suppression, composed from {@link WebResponseBuilder}), the lazy `raw`/
+ * `signal`/`triggerTimeout`, the streaming methods, and
+ * `get`/`next`/`throw`/`assert` — defined once across the Web adapters rather
+ * than copy-pasted per runtime. This file supplies only what is genuinely
+ * Edge-specific: `cf-connecting-ip`-aware IP resolution, platform bindings
+ * (`env`), and `waitUntil`/`executionContext`.
+ *
+ * @packageDocumentation
+ */
+
+import { detectEdgeRuntime, getEdgeClientIp, WebContextBase } from '@nextrush/runtime';
+import { runNDJSONStream, runSSEStream, runTextStream } from '@nextrush/stream';
+
+/**
+ * Edge execution context interface
+ *
+ * @remarks
+ * Provides access to edge-specific features like `waitUntil` and `passThroughOnException`.
+ */
+export interface EdgeExecutionContext {
+  /** Extend request lifetime for async operations */
+  waitUntil(promise: Promise<unknown>): void;
+
+  /** Pass through to origin on exception */
+  passThroughOnException?(): void;
+}
+
+/**
+ * Edge Context implementation
+ *
+ * @remarks
+ * Works with any edge runtime that implements the Web Fetch API:
+ * - Cloudflare Workers
+ * - Vercel Edge Functions
+ * - Netlify Edge Functions
+ *
+ * The response is built internally (via the inherited {@link WebResponseBuilder}
+ * composition) and returned via `getResponse()`.
+ *
+ * @example
+ * ```typescript
+ * const ctx = new EdgeContext(request);
+ * ctx.json({ message: 'Hello from Edge!' });
+ * const response = ctx.getResponse();
+ * ```
+ */
+export class EdgeContext<Env = unknown> extends WebContextBase {
+  /** Edge execution context (for waitUntil, etc.) */
+  readonly executionContext?: EdgeExecutionContext;
+
+  /**
+   * Platform bindings passed by the runtime (audit F-03).
+   *
+   * @remarks
+   * On Cloudflare Workers this is the `env` argument of
+   * `fetch(request, env, ctx)` — KV, D1, R2, Durable Objects, Queues, secrets.
+   * `undefined` on runtimes that do not supply bindings (e.g. Vercel Edge).
+   */
+  readonly env?: Env;
+
+  constructor(
+    request: Request,
+    executionContext?: EdgeExecutionContext,
+    trustProxy = false,
+    env?: Env
+  ) {
+    // Get client IP from CF headers or standard headers.
+    //
+    // HP-1 trim: Edge has no socket, so when `trustProxy` is false (default) the
+    // client IP is `''` — returned directly, with no per-request header-lookup
+    // closure and no `getEdgeClientIp` policy call (byte-identical to
+    // `getEdgeClientIp(request, false)`, whose `directIp` is `''`). When true,
+    // resolution still goes through `getEdgeClientIp`, preserving the Cloudflare
+    // `cf-connecting-ip` → `x-forwarded-for` → `x-real-ip` precedence.
+    const ip = trustProxy ? getEdgeClientIp(request, true) : '';
+
+    // Detect specific edge runtime
+    const runtime = detectEdgeRuntime().runtime;
+
+    super(request, ip, runtime, { runTextStream, runSSEStream, runNDJSONStream });
+
+    this.executionContext = executionContext;
+    this.env = env;
+  }
+
+  // ===========================================================================
+  // Edge-Specific Methods
+  // ===========================================================================
+
+  /**
+   * Extend request lifetime for async operations
+   *
+   * @remarks
+   * Use this for fire-and-forget operations that should complete
+   * after the response is sent (logging, analytics, etc.)
+   */
+  waitUntil(promise: Promise<unknown>): void {
+    if (this.executionContext?.waitUntil) {
+      this.executionContext.waitUntil(promise);
+    }
+  }
+}
+
+/**
+ * Create a new EdgeContext
+ */
+export function createEdgeContext<Env = unknown>(
+  request: Request,
+  executionContext?: EdgeExecutionContext,
+  trustProxy = false,
+  env?: Env
+): EdgeContext<Env> {
+  return new EdgeContext<Env>(request, executionContext, trustProxy, env);
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * @nextrush/adapter-edge - Edge Runtime Adapter for NextRush
+ *
+ * Provides universal Edge runtime support for:
+ * - Cloudflare Workers
+ * - Vercel Edge Functions
+ * - Netlify Edge Functions
+ * - Any runtime supporting the Fetch API
+ *
+ * @packageDocumentation
+ * @module @nextrush/adapter-edge
+ */
+
+// Main adapter functions
+export {
+  createCloudflareHandler,
+  createFetchHandler,
+  createHandler,
+  createNetlifyHandler,
+  createVercelHandler,
+  DEFAULT_EDGE_TIMEOUT_MS,
+  type CloudflareFetchHandler, // Alias
+  type FetchHandler,
+  type FetchHandlerOptions,
+} from './adapter';
+
+// Context exports
+export { EdgeContext, createEdgeContext, type EdgeExecutionContext } from './context';
+
+// HttpError re-export (uniform across all adapters — audit F-10)
+export { HttpError } from '@nextrush/errors';
+
+// Body source exports (F-10: previously only `EdgeBodySource` was exported;
+// the rest were dead. Now the full shared surface is wired up.)
+export {
+  createEmptyBodySource,
+  createWebBodySource,
+  EmptyBodySource,
+  WebBodySource,
+} from './body-source';
+
+// Shared error classes (parity with node/bun/deno — audit F-10)
+export { BodyConsumedError, BodyTooLargeError } from '@nextrush/runtime';
+
+// Utility exports
+/* eslint-disable @typescript-eslint/no-deprecated -- F-09: intentional compat re-export, not a usage site */
+export {
+  detectEdgeRuntime,
+  getContentLength,
+  getContentType,
+  parseQueryString,
+  type EdgeRuntimeInfo,
+} from './utils';
+/* eslint-enable @typescript-eslint/no-deprecated */
+
+// Re-export types for convenience (parity with node/bun/deno — audit F-10)
+export type {
+  BodySource,
+  Context,
+  HttpMethod,
+  Middleware,
+  Runtime,
+  RuntimeCapabilities,
+} from '@nextrush/types';

package/src/utils.ts

@@ -0,0 +1,34 @@
+/**
+ * @nextrush/adapter-edge - Utility Functions
+ *
+ * @packageDocumentation
+ */
+
+export { detectEdgeRuntime, parseQueryString } from '@nextrush/runtime';
+export type { EdgeRuntimeInfo } from '@nextrush/runtime';
+
+/**
+ * Get Content-Type header value
+ *
+ * @deprecated F-09: unused internally (superseded by `@nextrush/body-parser`'s
+ * own content-type parsing). Kept for backward compatibility per the public-API
+ * contract (deprecate-before-remove); will be removed in a future major.
+ */
+export function getContentType(headers: Headers): string | undefined {
+  return headers.get('content-type') ?? undefined;
+}
+
+/**
+ * Get Content-Length header as number
+ *
+ * @deprecated F-09: unused internally (superseded by `@nextrush/body-parser`'s
+ * own content-length handling). Kept for backward compatibility per the
+ * public-API contract (deprecate-before-remove); will be removed in a future
+ * major.
+ */
+export function getContentLength(headers: Headers): number | undefined {
+  const value = headers.get('content-length');
+  if (value === null) return undefined;
+  const num = parseInt(value, 10);
+  return Number.isNaN(num) ? undefined : num;
+}