@johnhenry/letterpress 0.0.3 → 0.2.0

package/test/route.mjs

@@ -87,6 +87,43 @@ describe("createRoute", () => {
     assert.strictEqual(await response.text(), "STREAMED");
   });
 
+  it("should accumulate repeated header names instead of overwriting (letterpress #8)", async () => {
+    // Regression test: headers.set() was called for every header line
+    // found while parsing the template, so a second Set-Cookie line
+    // silently overwrote the first instead of both surviving.
+    const route = createRoute()`HTTP/1.1 200 OK
+Set-Cookie: a=1
+Set-Cookie: b=2
+Content-Type: text/plain
+
+hello`;
+    const response = await route(new Request("https://example.com"));
+    const cookies = response.headers.getSetCookie
+      ? response.headers.getSetCookie()
+      : [...response.headers.entries()]
+          .filter(([key]) => key === "set-cookie")
+          .map(([, value]) => value);
+    assert.deepStrictEqual(cookies, ["a=1", "b=2"]);
+  });
+
+  it("should not reinterpret a substituted value as new header syntax (letterpress #8)", async () => {
+    // Regression test: a stringified substitution was re-fed through the
+    // same line tokenizer used for the template's own literal text, so a
+    // substitution containing "\n" or ":" could end the header section
+    // early or appear to start a new header line.
+    const route = createRoute()`HTTP/1.1 200 OK
+X-Note: ${"value: with: colons: inside"}
+Content-Type: text/plain
+
+${"body text"}`;
+    const response = await route(new Request("https://example.com"));
+    assert.strictEqual(
+      response.headers.get("X-Note"),
+      "value: with: colons: inside"
+    );
+    assert.strictEqual(await response.text(), "body text");
+  });
+
   it("should handle streaming responses", async () => {
     const route = createRoute({ streaming: true })`
       ${async (_, { response }) => {

package/test/router.mjs

@@ -171,6 +171,87 @@ test("Router - Function handler", async () => {
   assert.equal(response.status, 200);
 });
 
+test("Router - mount delegates matching requests with the prefix stripped", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /users``sub: ${(_, { params }) => "users"}`;
+  router.mount("/api", sub);
+
+  const response = await router(new Request("http://example.com/api/users"));
+  assert.equal(response.status, 200);
+  assert.equal(await response.text(), "sub: users");
+});
+
+test("Router - mount forwards mountPrefix to the sub-router's own handlers via ctx", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /users`((_, ctx) => new Response(ctx.mountPrefix));
+  router.mount("/api", sub);
+
+  const response = await router(new Request("http://example.com/api/users"));
+  assert.equal(await response.text(), "/api");
+});
+
+test("Router - a caller-supplied ctx reaches matched handlers and defaultHandler alike", async () => {
+  const router = createRouter({
+    defaultHandler: (_, ctx) => new Response(`default:${ctx.tag}`),
+  });
+  router.endpoint`GET /hit`((_, ctx) => new Response(`hit:${ctx.tag}`));
+
+  const hit = await router(new Request("http://example.com/hit"), { tag: "x" });
+  assert.equal(await hit.text(), "hit:x");
+
+  const miss = await router(new Request("http://example.com/miss"), { tag: "y" });
+  assert.equal(await miss.text(), "default:y");
+});
+
+test("Router - mount matches the bare prefix itself (no trailing segment)", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /``root`;
+  router.mount("/api", sub);
+
+  const response = await router(new Request("http://example.com/api"));
+  assert.equal(await response.text(), "root");
+});
+
+test("Router - mount falls through to the outer router's 404 for non-matching paths", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /users``sub: users`;
+  router.mount("/api", sub);
+
+  const response = await router(new Request("http://example.com/other"));
+  assert.equal(response.status, 404);
+});
+
+test("Router - mount accepts an object exposing .fetch (so a router can mount another router)", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /ping``pong`;
+  // `sub` is itself callable (Route & RouterExtension), but this exercises
+  // the `.fetch` branch explicitly by wrapping it in a plain object.
+  router.mount("/api", { fetch: sub });
+
+  const response = await router(new Request("http://example.com/api/ping"));
+  assert.equal(await response.text(), "pong");
+});
+
+test("Router - mount preserves query strings and method/body on the forwarded request", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /search`(async (request) => {
+    const url = new URL(request.url);
+    return new Response(url.search);
+  });
+  router.mount("/api", sub);
+
+  const response = await router(
+    new Request("http://example.com/api/search?q=hello")
+  );
+  assert.equal(await response.text(), "?q=hello");
+});
+
 // Commented out tests
 /*
 test("Router - InlineParam", async () => {

package/test/tag-req-res.mjs

@@ -0,0 +1,253 @@
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { tagRequest, tagResponse } from "../index.mjs";
+
+const createReadableStream = (data) =>
+  new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(data));
+      controller.close();
+    },
+  });
+
+await test("tagRequest", async (t) => {
+  await t.test("basic request, Host header from template", async () => {
+    const request = await tagRequest()`POST /users HTTP/1.1
+Host: example.com
+Content-Type: application/x-www-form-urlencoded
+
+name=A+B&email=a%40b.com`;
+    assert.equal(request.method, "POST");
+    // Host: example.com in the template sets the Host *header* -- it does
+    // not change which baseUrl a relative "/users" path resolves against
+    // (that's the separate `baseUrl` option, matching createRequest).
+    assert.equal(request.url, "http://localhost/users");
+    assert.equal(request.headers.get("host"), "example.com");
+    assert.equal(
+      request.headers.get("content-type"),
+      "application/x-www-form-urlencoded"
+    );
+    assert.equal(await request.text(), "name=A+B&email=a%40b.com");
+    assert.equal(request.headers.get("content-length"), "24");
+  });
+
+  await t.test("host sugar key", async () => {
+    const request = await tagRequest({ host: "example.com" })`GET /path HTTP/1.1
+Accept: application/json`;
+    assert.equal(request.headers.get("host"), "example.com");
+    assert.equal(request.headers.get("accept"), "application/json");
+  });
+
+  await t.test("host sugar key conflicts with explicit headers.host -- throws", () => {
+    assert.throws(
+      () => tagRequest({ host: "a", headers: { Host: "b" } }),
+      TypeError
+    );
+  });
+
+  await t.test(
+    "defaults.headers is a fallback, template headers win per-key",
+    async () => {
+      const request = await tagRequest({
+        headers: { "X-Default": "from-defaults", "Content-Type": "text/x-default" },
+      })`POST /x HTTP/1.1
+Content-Type: text/plain
+
+body`;
+      assert.equal(request.headers.get("x-default"), "from-defaults");
+      assert.equal(request.headers.get("content-type"), "text/plain");
+    }
+  );
+
+  await t.test("missing request line throws", async () => {
+    await assert.rejects(
+      () => tagRequest()`Content-Type: text/plain
+
+oops`,
+      TypeError
+    );
+  });
+
+  await t.test(
+    "a substituted header value containing a colon is not truncated",
+    async () => {
+      const request = await tagRequest()`POST /x HTTP/1.1
+X-Note: ${"value: with: colons: inside"}
+Content-Type: text/plain
+
+body`;
+      assert.equal(
+        request.headers.get("x-note"),
+        "value: with: colons: inside"
+      );
+      assert.equal(await request.text(), "body");
+    }
+  );
+
+  await t.test(
+    "a substituted value cannot inject a new header or end headers early",
+    async () => {
+      // If the parser re-scanned this substitution's text for structure,
+      // it would register a second "injected" header and/or end the
+      // header section early. The platform's Headers validation rejects
+      // a raw embedded newline in a header value outright, which is the
+      // correct outcome -- it proves the value was handed to Headers.set
+      // as one literal string, not re-tokenized into separate lines.
+      await assert.rejects(
+        () =>
+          tagRequest()`POST /x HTTP/1.1
+X-Note: ${"line1\ninjected: value"}
+Content-Type: text/plain
+
+body`,
+        TypeError
+      );
+    }
+  );
+
+  await t.test("repeated header name accumulates (not last-wins)", async () => {
+    const request = await tagRequest()`POST /x HTTP/1.1
+X-Tag: a
+X-Tag: b
+Content-Type: text/plain
+
+body`;
+    // Headers folds repeated non-Set-Cookie values with ", " on .get() --
+    // the point here is both survive, rather than "b" silently winning.
+    assert.equal(request.headers.get("x-tag"), "a, b");
+  });
+
+  await t.test("Headers object substitution merges directly", async () => {
+    const extra = new Headers({ "X-From-Headers-Object": "yes" });
+    const request = await tagRequest()`POST /x HTTP/1.1
+${extra}
+Content-Type: text/plain
+
+body`;
+    assert.equal(request.headers.get("x-from-headers-object"), "yes");
+  });
+
+  await t.test("binary body passthrough (Uint8Array)", async () => {
+    const bin = new Uint8Array([1, 2, 3]);
+    const request = await tagRequest()`POST /up HTTP/1.1
+
+${bin}`;
+    const buf = await request.arrayBuffer();
+    assert.deepEqual([...new Uint8Array(buf)], [1, 2, 3]);
+    assert.equal(request.headers.get("content-type"), "application/octet-stream");
+  });
+
+  await t.test("binary body passthrough (ReadableStream)", async () => {
+    const request = await tagRequest()`POST /up HTTP/1.1
+
+${createReadableStream("streamed")}`;
+    assert.equal(await request.text(), "streamed");
+  });
+
+  await t.test(
+    "binary body substitution mixed with other body content throws",
+    async () => {
+      const bin = new Uint8Array([1, 2, 3]);
+      await assert.rejects(
+        () => tagRequest()`POST /up HTTP/1.1
+
+prefix ${bin}`,
+        TypeError
+      );
+      await assert.rejects(
+        () => tagRequest()`POST /up HTTP/1.1
+
+${bin}${new Uint8Array([9])}`,
+        TypeError
+      );
+    }
+  );
+
+  await t.test("Content-Length auto-filled only when absent", async () => {
+    const auto = await tagRequest()`POST /x HTTP/1.1
+Content-Type: text/plain
+
+hello`;
+    assert.equal(auto.headers.get("content-length"), "5");
+
+    const explicit = await tagRequest()`POST /x HTTP/1.1
+Content-Type: text/plain
+Content-Length: 999
+
+hello`;
+    assert.equal(
+      explicit.headers.get("content-length"),
+      "999",
+      "an explicitly-declared Content-Length is never overwritten, even if wrong"
+    );
+  });
+
+  await t.test("relative vs absolute URLs, baseUrl option", async () => {
+    const relative = await tagRequest({ baseUrl: "https://api.example.com" })`GET /search?q=1 HTTP/1.1`;
+    assert.equal(relative.url, "https://api.example.com/search?q=1");
+
+    const absolute = await tagRequest()`DELETE https://api.example.com/users/1 HTTP/1.1`;
+    assert.equal(absolute.url, "https://api.example.com/users/1");
+    assert.equal(absolute.method, "DELETE");
+  });
+});
+
+await test("tagResponse", async (t) => {
+  await t.test("basic response", async () => {
+    const response = await tagResponse`HTTP/1.1 201 Created
+Content-Type: application/json
+Location: http://example.com/users/123
+
+{"id":123}`;
+    assert.equal(response.status, 201);
+    assert.equal(response.statusText, "Created");
+    assert.equal(response.headers.get("location"), "http://example.com/users/123");
+    assert.deepEqual(await response.json(), { id: 123 });
+  });
+
+  await t.test("missing status line throws", async () => {
+    await assert.rejects(
+      () => tagResponse`Content-Type: text/plain
+
+oops`,
+      TypeError
+    );
+  });
+
+  await t.test("repeated Set-Cookie accumulates, not last-wins", async () => {
+    const response = await tagResponse`HTTP/1.1 200 OK
+Set-Cookie: a=1
+Set-Cookie: b=2
+Content-Type: text/plain
+
+hello`;
+    const cookies = response.headers.getSetCookie
+      ? response.headers.getSetCookie()
+      : [...response.headers.entries()]
+          .filter(([k]) => k === "set-cookie")
+          .map(([, v]) => v);
+    assert.deepEqual(cookies, ["a=1", "b=2"]);
+  });
+
+  await t.test("204 has a null body", async () => {
+    const response = await tagResponse`HTTP/1.1 204 No Content
+`;
+    assert.equal(response.status, 204);
+    assert.equal(await response.text(), "");
+  });
+
+  await t.test("binary body passthrough (Blob)", async () => {
+    const response = await tagResponse`HTTP/1.1 200 OK
+
+${new Blob(["hello blob"], { type: "text/plain" })}`;
+    assert.equal(response.headers.get("content-type"), "text/plain");
+    assert.equal(await response.text(), "hello blob");
+  });
+
+  await t.test("Content-Length auto-filled only when absent", async () => {
+    const auto = await tagResponse`HTTP/1.1 200 OK
+
+hello`;
+    assert.equal(auto.headers.get("content-length"), "5");
+  });
+});

package/test/types/fixture.ts

@@ -33,11 +33,14 @@ import {
   createRoute,
   createRequest,
   createResponse,
+  tagRequest,
+  tagResponse,
   deconstruct,
   cook,
   HTTPExpression,
 } from "@johnhenry/letterpress";
 import { createFSRouter } from "@johnhenry/letterpress/fs";
+import { createRewriter } from "@johnhenry/letterpress/rewrite";
 
 // createRouter: a Router is a Route (request, context?) => Response, plus
 // an `.endpoint` tagged-template extension that registers routes.
@@ -100,6 +103,24 @@ ok`;
 }
 void checkResponse;
 
+// tagRequest: (defaults?) => tagged-template => Promise<Request>
+async function checkTagRequest() {
+  const request = await tagRequest({ host: "example.com" })`GET /path HTTP/1.1
+Accept: application/json`;
+  return request instanceof Request;
+}
+void checkTagRequest;
+
+// tagResponse: itself a tagged-template function => Promise<Response>
+async function checkTagResponse() {
+  const response = await tagResponse`HTTP/1.1 200 OK
+Content-Type: text/plain
+
+ok`;
+  return response instanceof Response;
+}
+void checkTagResponse;
+
 // deconstruct: tagged-template => { strings, substitutions, raw }
 const deconstructed = deconstruct`GET /${"foo"}`;
 const deconstructedStrings: string[] = deconstructed.strings;
@@ -136,3 +157,36 @@ async function checkFsRouter() {
   return response === null || response instanceof Response;
 }
 void checkFsRouter;
+
+// createRewriter: only reachable via the "/rewrite" subpath (not the main
+// barrel), mirroring createFSRouter's "/fs" subpath precedent. Ported from
+// leroute -- see rewrite.mjs's top-of-file comment and CHANGELOG.md.
+const rewriter = createRewriter([
+  {
+    match: { path: /^\/old\/(.*)/ },
+    action: { rewritePath: "/new/$1", setHeader: { "x-rewritten": "true" } },
+  },
+]);
+const rewrittenRequest: Request = rewriter.rewriteRequest(
+  new Request("http://localhost/old/stuff")
+);
+void rewrittenRequest;
+const rewrittenResponse: Response = rewriter.rewriteResponse(
+  new Response("ok"),
+  new Request("http://localhost/old/stuff")
+);
+void rewrittenResponse;
+rewriter.addRule({ match: { path: "/teapot" }, action: { setStatus: 418 } });
+rewriter.removeRule(0);
+const ruleSnapshots = rewriter.getRules();
+const firstRuleIndex: number = ruleSnapshots[0]?.index ?? -1;
+void firstRuleIndex;
+const wrapped = rewriter.middleware(async (request: Request) => {
+  void request;
+  return new Response("ok");
+});
+async function checkRewriterMiddleware() {
+  const response = await wrapped(new Request("http://localhost/old/stuff"), {});
+  return response instanceof Response;
+}
+void checkRewriterMiddleware;

package/tsconfig.json

@@ -15,6 +15,7 @@
     "include": [
         "types.d.ts",
         "fs.d.ts",
+        "rewrite.d.ts",
         "test/types/**/*.ts"
     ]
 }

package/types.d.ts

@@ -19,12 +19,18 @@ export type RouterEndpointResponder = {
   (handler: Route): Router;
 };
 
+// A handler mountable under a Router prefix: a plain (Request) => Response
+// function, or an object exposing one as `.fetch` (so a Router can mount
+// another Router).
+export type Mountable = Route | { fetch: Route };
+
 // Extension for the Router to add endpoints
 export type RouterExtension = {
   endpoint: (
     template: TemplateStringsArray,
     ...substitutions: any[]
   ) => RouterEndpointResponder;
+  mount: (prefix: string, subHandler: Mountable) => Router;
 };
 
 // Combines Route and RouterExtension
@@ -124,6 +130,42 @@ export type CreateResponse = (
   ...substitutions: any[]
 ) => Response | Promise<Response>;
 
+// Configuration/sugar for tagRequest(). Unlike CreateRequestInit, these
+// fields only ever fill in what raw HTTP text can't express -- method,
+// URL, status, and body always come from the parsed template itself, not
+// from defaults. `host` is sugar for headers.host; providing both throws.
+export type TagRequestDefaults = {
+  headers?: HeadersInit | Headers;
+  host?: string;
+  baseUrl?: string;
+  redirect?: RequestRedirect;
+  credentials?: RequestCredentials;
+  mode?: RequestMode;
+  referrer?: string;
+  referrerPolicy?: ReferrerPolicy;
+  signal?: AbortSignal;
+};
+
+// Tagged-template function returned by tagRequest(): a strict, from-scratch
+// parser of raw HTTP-request text (see README's "which one do I want?"
+// note comparing this to createRequest). Substitutions are spliced in
+// verbatim -- never re-scanned for "\n"/":" -- and a binary-typed
+// substitution (Blob/Uint8Array/ArrayBuffer/ReadableStream/FormData/
+// URLSearchParams) must be the sole content of the body.
+export type TagRequestTag = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => Promise<Request>;
+
+export type TagRequest = (defaults?: TagRequestDefaults) => TagRequestTag;
+
+// tagResponse is itself the tagged-template function (uncurried, like
+// createResponse) -- there is no defaults-currying form in this version.
+export type TagResponse = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => Promise<Response>;
+
 // Result of deconstruct(): the raw pieces of a tagged template call.
 export type DeconstructResult = {
   strings: string[];
@@ -180,6 +222,8 @@ export declare const createRouter: CreateRouter;
 export declare const createRoute: CreateRoute;
 export declare const createRequest: CreateRequest;
 export declare const createResponse: CreateResponse;
+export declare const tagRequest: TagRequest;
+export declare const tagResponse: TagResponse;
 export declare const deconstruct: Deconstruct;
 export declare const cook: Cook;
 export declare const HTTPExpression: HTTPExpressionFn;