@nextrush/adapter-edge 1.0.0-beta.0

package/src/__tests__/default-timeout.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @nextrush/adapter-edge — F-07 (ADR-0010): default request timeout.
+ *
+ * Converges Edge's default timeout contract with Node/Bun/Deno (all default
+ * to a bounded timeout rather than none). Verifies the default fires, is
+ * overridable, and is disable-able via `timeout: 0`.
+ */
+
+import { createApp } from '@nextrush/core';
+import { describe, expect, it } from 'vitest';
+import { createFetchHandler, DEFAULT_EDGE_TIMEOUT_MS } from '../adapter';
+
+describe('F-07: Edge default request timeout', () => {
+  it('DEFAULT_EDGE_TIMEOUT_MS is a documented constant under the tightest common edge wall limit', () => {
+    // Vercel Edge Functions: 25s wall limit — the tightest common platform limit.
+    expect(DEFAULT_EDGE_TIMEOUT_MS).toBeLessThanOrEqual(25_000);
+    expect(DEFAULT_EDGE_TIMEOUT_MS).toBeGreaterThan(0);
+  });
+
+  it('a handler that never settles times out under the default (no explicit timeout passed)', async () => {
+    const app = createApp();
+    let signalFired = false;
+    app.use(async (ctx) => {
+      const signal = ctx.signal;
+      await new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => {
+          signalFired = true;
+          resolve();
+        });
+      });
+    });
+
+    // Override to a tiny value at the call site to keep the test fast, while
+    // proving the *default* path (no explicit `timeout` in FetchHandlerOptions)
+    // is the one that applies it — see the next test for the true zero-config case.
+    const handler = createFetchHandler(app, { timeout: 10 });
+    const res = await handler(new Request('http://localhost/'));
+
+    expect(res.status).toBe(504);
+    expect(signalFired).toBe(true);
+  });
+
+  it('omitting timeout entirely applies DEFAULT_EDGE_TIMEOUT_MS (fast handler completes normally)', async () => {
+    const app = createApp();
+    app.use((ctx) => {
+      ctx.json({ ok: true });
+    });
+
+    // No `timeout` key at all — this is the true zero-config path (F-07).
+    const handler = createFetchHandler(app, {});
+    const res = await handler(new Request('http://localhost/'));
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  it('timeout: 0 disables the framework timeout entirely', async () => {
+    const app = createApp();
+    app.use((ctx) => {
+      ctx.json({ ok: true });
+    });
+
+    const handler = createFetchHandler(app, { timeout: 0 });
+    const res = await handler(new Request('http://localhost/'));
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  it('an explicit positive timeout overrides the default', async () => {
+    const app = createApp();
+    app.use(async (ctx) => {
+      await new Promise<void>(() => undefined); // never settles
+      ctx.json({ unreachable: true });
+    });
+
+    const handler = createFetchHandler(app, { timeout: 15 });
+    const res = await handler(new Request('http://localhost/'));
+
+    expect(res.status).toBe(504);
+  });
+});

package/src/__tests__/per-request-work-trim.test.ts

@@ -0,0 +1,171 @@
+/**
+ * @nextrush/adapter-edge — per-request-work-trim regression contract
+ *
+ * Executable contract for OpenSpec change `web-adapters-per-request-work-trim`
+ * (sibling of the archived Node `node-adapter-per-request-work-trim`). Pins the
+ * byte-identical observable behavior of `ctx.ip` and `ctx.next()`
+ * (characterization tests, green before and after the trims) AND proves each
+ * trim actually happened (optimization-assertion tests, RED before impl):
+ *
+ *  - HP-1: `trustProxy: false` sets `ctx.ip` to `''` directly (Edge has no
+ *          socket) without invoking the edge header-lookup policy
+ *          (`getEdgeClientIp`); `trustProxy: true` still resolves via it,
+ *          preserving the cf-connecting-ip → x-forwarded-for → x-real-ip
+ *          precedence.
+ *  - HP-7: `ctx.next()` forwards the wired dispatch thunk directly (returns its
+ *          exact promise) rather than wrapping it in an extra `async` frame.
+ *
+ * Note: HP-4 does NOT apply — the Edge context factory takes `trustProxy`
+ * positionally, so there is no per-request options object to hoist.
+ */
+
+import { createApp } from '@nextrush/core';
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@nextrush/runtime', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@nextrush/runtime')>();
+  return { ...actual, getEdgeClientIp: vi.fn(actual.getEdgeClientIp) };
+});
+
+import { getEdgeClientIp } from '@nextrush/runtime';
+import { createFetchHandler } from '../adapter';
+import { EdgeContext } from '../context';
+
+function makeRequest(headers?: Record<string, string>): Request {
+  return new Request('http://localhost/', headers ? { headers } : undefined);
+}
+
+const getEdgeClientIpMock = vi.mocked(getEdgeClientIp);
+
+beforeEach(() => {
+  getEdgeClientIpMock.mockClear();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ===========================================================================
+// §2 HP-1 — ctx.ip
+// ===========================================================================
+
+describe('HP-1: Edge ctx.ip resolution', () => {
+  // ---- parity / characterization (green before and after) -----------------
+
+  it('2.4 trustProxy false → ctx.ip is the empty string (Edge has no socket)', () => {
+    const ctx = new EdgeContext(makeRequest(), undefined, false);
+    expect(ctx.ip).toBe('');
+  });
+
+  it('2.4 trustProxy true + cf-connecting-ip wins the Cloudflare precedence', () => {
+    const ctx = new EdgeContext(
+      makeRequest({
+        'cf-connecting-ip': '198.51.100.5',
+        'x-forwarded-for': '9.9.9.9',
+        'x-real-ip': '8.8.8.8',
+      }),
+      undefined,
+      true
+    );
+    expect(ctx.ip).toBe('198.51.100.5');
+  });
+
+  it('2.4 trustProxy true + no cf-connecting-ip → x-forwarded-for → x-real-ip precedence', () => {
+    const xff = new EdgeContext(
+      makeRequest({ 'x-forwarded-for': '9.9.9.9', 'x-real-ip': '8.8.8.8' }),
+      undefined,
+      true
+    );
+    expect(xff.ip).toBe('9.9.9.9');
+
+    const real = new EdgeContext(makeRequest({ 'x-real-ip': '8.8.8.8' }), undefined, true);
+    expect(real.ip).toBe('8.8.8.8');
+  });
+
+  it('2.5 trustProxy false ignores cf-connecting-ip / x-forwarded-for / x-real-ip', () => {
+    const ctx = new EdgeContext(
+      makeRequest({
+        'cf-connecting-ip': '198.51.100.5',
+        'x-forwarded-for': '9.9.9.9',
+        'x-real-ip': '8.8.8.8',
+      }),
+      undefined,
+      false
+    );
+    expect(ctx.ip).toBe('');
+  });
+
+  // ---- optimization assertion (RED before HP-1) ----------------------------
+
+  it('2.6 [trim] trustProxy false does NOT invoke getEdgeClientIp', () => {
+    void new EdgeContext(makeRequest(), undefined, false);
+    expect(getEdgeClientIpMock).not.toHaveBeenCalled();
+  });
+
+  it('2.6 [trim] trustProxy true still resolves via getEdgeClientIp', () => {
+    void new EdgeContext(makeRequest({ 'cf-connecting-ip': '198.51.100.5' }), undefined, true);
+    expect(getEdgeClientIpMock).toHaveBeenCalledTimes(1);
+    expect(getEdgeClientIpMock).toHaveBeenCalledWith(expect.any(Request), true);
+  });
+});
+
+// ===========================================================================
+// §3 HP-7 — ctx.next() forwards the dispatch thunk without an extra async frame
+// ===========================================================================
+
+describe('HP-7: Edge ctx.next() thunk forwarding', () => {
+  it('3.1 [trim] ctx.next() returns the identical promise the wired thunk returns', () => {
+    const ctx = new EdgeContext(makeRequest());
+    const thunkPromise = Promise.resolve();
+    ctx.setNext(() => thunkPromise);
+    expect(ctx.next()).toBe(thunkPromise);
+  });
+
+  it('3.2 a rejection from the wired thunk propagates out of ctx.next()', async () => {
+    const ctx = new EdgeContext(makeRequest());
+    const boom = new Error('downstream failed');
+    ctx.setNext(() => Promise.reject(boom));
+    await expect(ctx.next()).rejects.toBe(boom);
+  });
+
+  it('3.3 ctx.next() with no wired thunk is a resolved no-op returning Promise<void>', async () => {
+    const ctx = new EdgeContext(makeRequest());
+    const result = ctx.next();
+    expect(result).toBeInstanceOf(Promise);
+    await expect(result).resolves.toBeUndefined();
+  });
+
+  it('3.1 await ctx.next() preserves onion ordering through the composed pipeline', async () => {
+    const app = createApp();
+    const order: string[] = [];
+    app.use(async (ctx) => {
+      order.push('a-before');
+      await ctx.next();
+      order.push('a-after');
+    });
+    app.use((ctx) => {
+      order.push('b');
+      ctx.json({ ok: true });
+    });
+    const handler = createFetchHandler(app);
+    await handler(makeRequest());
+    expect(order).toEqual(['a-before', 'b', 'a-after']);
+  });
+
+  it('3.4 the composer multiple-next guard still fires for the chain ctx.next() forwards to', async () => {
+    const app = createApp();
+    let secondNextError: unknown;
+    app.use(async (_ctx, next) => {
+      await next();
+      try {
+        await next();
+      } catch (err) {
+        secondNextError = err;
+      }
+    });
+    const handler = createFetchHandler(app);
+    await handler(makeRequest());
+    expect(secondNextError).toBeInstanceOf(Error);
+    expect((secondNextError as Error).message).toMatch(/next\(\)/i);
+  });
+});

package/src/__tests__/public-surface.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @nextrush/adapter-edge - Public API surface test
+ *
+ * Locks the exported symbol set from `src/index.ts`. If this test fails, the
+ * public API has changed. Intentional changes require an explicit update to
+ * the expected list below, plus a changeset for a published package.
+ */
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import * as adapterEdgeApi from '../index';
+import type {
+  BodySource,
+  CloudflareFetchHandler,
+  Context,
+  EdgeExecutionContext,
+  EdgeRuntimeInfo,
+  FetchHandler,
+  FetchHandlerOptions,
+  HttpMethod,
+  Middleware,
+  Runtime,
+  RuntimeCapabilities,
+} from '../index';
+
+describe('Public API surface (runtime exports)', () => {
+  it('exports exactly the intended runtime symbols', () => {
+    const actualExports = Object.keys(adapterEdgeApi).sort();
+
+    // SEALED: intentional public runtime API surface.
+    const expectedRuntime = [
+      // Main adapter functions
+      'createCloudflareHandler',
+      'createFetchHandler',
+      'createHandler',
+      'createNetlifyHandler',
+      'createVercelHandler',
+      'DEFAULT_EDGE_TIMEOUT_MS',
+
+      // Context
+      'EdgeContext',
+      'createEdgeContext',
+
+      // HttpError re-export (uniform across all adapters — audit F-10)
+      'HttpError',
+
+      // Body source
+      'createEmptyBodySource',
+      'createWebBodySource',
+      'EmptyBodySource',
+      'WebBodySource',
+
+      // Shared error classes (parity with node/bun/deno — audit F-10)
+      'BodyConsumedError',
+      'BodyTooLargeError',
+
+      // Utility exports
+      'detectEdgeRuntime',
+      'getContentLength',
+      'getContentType',
+      'parseQueryString',
+    ].sort();
+
+    expect(actualExports).toEqual(expectedRuntime);
+  });
+});
+
+describe('Public API surface (type-only exports)', () => {
+  it('the type-only surface stays importable from the barrel', () => {
+    // Compile-time only: removing/renaming any of these in src/index.ts fails
+    // this file to type-check.
+    type Surface = [
+      CloudflareFetchHandler,
+      FetchHandler,
+      FetchHandlerOptions,
+      EdgeExecutionContext,
+      EdgeRuntimeInfo,
+      BodySource,
+      Context,
+      HttpMethod,
+      Middleware,
+      Runtime,
+      RuntimeCapabilities,
+    ];
+    expectTypeOf<Surface>().not.toBeNever();
+  });
+});

package/src/__tests__/utils.test.ts

@@ -0,0 +1,140 @@
+/**
+ * @nextrush/adapter-edge - Utils Tests
+ */
+
+import { resetRuntimeCache } from '@nextrush/runtime';
+import { afterEach, describe, expect, it } from 'vitest';
+import { detectEdgeRuntime, getContentLength, getContentType, parseQueryString } from '../utils';
+
+describe('parseQueryString', () => {
+  it('should parse simple query string', () => {
+    const result = parseQueryString('name=John&age=30');
+    expect(result).toEqual({ name: 'John', age: '30' });
+  });
+
+  it('should return empty object for empty string', () => {
+    const result = parseQueryString('');
+    expect(result).toEqual({});
+  });
+
+  it('should decode URI components', () => {
+    const result = parseQueryString('name=John%20Doe&city=New%20York');
+    expect(result).toEqual({ name: 'John Doe', city: 'New York' });
+  });
+
+  it('should handle keys without values', () => {
+    const result = parseQueryString('key=');
+    expect(result).toEqual({ key: '' });
+  });
+
+  it('should handle multiple values for same key', () => {
+    const result = parseQueryString('tag=a&tag=b&tag=c');
+    expect(result).toEqual({ tag: ['a', 'b', 'c'] });
+  });
+
+  it('should handle special characters', () => {
+    const result = parseQueryString('email=test%40example.com');
+    expect(result).toEqual({ email: 'test@example.com' });
+  });
+
+  it('should handle keys without equals sign', () => {
+    const result = parseQueryString('key');
+    expect(result).toEqual({ key: '' });
+  });
+
+  it('should skip empty keys', () => {
+    const result = parseQueryString('=value&key=test');
+    expect(result).toEqual({ key: 'test' });
+  });
+});
+
+describe('detectEdgeRuntime', () => {
+  const originalNavigator = globalThis.navigator;
+  const originalProcess = globalThis.process;
+  const originalDeno = (globalThis as { Deno?: unknown }).Deno;
+
+  afterEach(() => {
+    // Reset cached detection so each test starts fresh
+    resetRuntimeCache();
+    // Restore original globals
+    Object.defineProperty(globalThis, 'navigator', {
+      value: originalNavigator,
+      writable: true,
+      configurable: true,
+    });
+    (globalThis as { process?: unknown }).process = originalProcess;
+    (globalThis as { Deno?: unknown }).Deno = originalDeno;
+  });
+
+  it('should detect generic edge runtime by default', () => {
+    const info = detectEdgeRuntime();
+    expect(info.runtime).toBe('edge');
+    expect(info.isGenericEdge).toBe(true);
+    expect(info.isCloudflare).toBe(false);
+    expect(info.isVercel).toBe(false);
+    expect(info.isNetlify).toBe(false);
+  });
+
+  it('should detect Cloudflare Workers', () => {
+    Object.defineProperty(globalThis, 'navigator', {
+      value: { userAgent: 'Cloudflare-Workers' },
+      writable: true,
+      configurable: true,
+    });
+
+    const info = detectEdgeRuntime();
+    expect(info.runtime).toBe('cloudflare-workers');
+    expect(info.isCloudflare).toBe(true);
+    expect(info.isGenericEdge).toBe(false);
+  });
+
+  it('should detect Vercel Edge', () => {
+    (globalThis as { process?: { env?: { VERCEL_REGION?: string } } }).process = {
+      env: { VERCEL_REGION: 'iad1' },
+    };
+
+    const info = detectEdgeRuntime();
+    expect(info.runtime).toBe('vercel-edge');
+    expect(info.isVercel).toBe(true);
+    expect(info.isGenericEdge).toBe(false);
+  });
+
+  it('should detect Netlify Edge', () => {
+    (globalThis as { Deno?: unknown }).Deno = {};
+    (globalThis as { process?: { env?: { NETLIFY?: string } } }).process = {
+      env: { NETLIFY: 'true' },
+    };
+
+    const info = detectEdgeRuntime();
+    expect(info.isNetlify).toBe(true);
+  });
+});
+
+describe('getContentType', () => {
+  it('should return content-type header value', () => {
+    const headers = new Headers({ 'content-type': 'application/json' });
+    expect(getContentType(headers)).toBe('application/json');
+  });
+
+  it('should return undefined when header is missing', () => {
+    const headers = new Headers();
+    expect(getContentType(headers)).toBeUndefined();
+  });
+});
+
+describe('getContentLength', () => {
+  it('should return content-length as number', () => {
+    const headers = new Headers({ 'content-length': '1024' });
+    expect(getContentLength(headers)).toBe(1024);
+  });
+
+  it('should return undefined when header is missing', () => {
+    const headers = new Headers();
+    expect(getContentLength(headers)).toBeUndefined();
+  });
+
+  it('should return undefined for invalid number', () => {
+    const headers = new Headers({ 'content-length': 'invalid' });
+    expect(getContentLength(headers)).toBeUndefined();
+  });
+});