@robodev-ai/tenant-host 0.0.0-stage → 0.1.0

package/src/request.ts

@@ -0,0 +1,132 @@
+/**
+ * The request a tenant host serves, after the server has read and parsed the body. Each host
+ * builds one with its own body rules and limits (hosted Starbase and `robodev dev` both on
+ * `Bun.serve`); `fromFetchRequest` is the plain Fetch version.
+ */
+export type TenantHeaders = Record<string, string | string[] | undefined>;
+
+export type TenantRequest = {
+  method: string;
+  /** Path and query as received, e.g. `/api/notes?limit=5`. */
+  url: string;
+  /** Decoded path without a trailing slash (`/` for the root). */
+  pathname: string;
+  /** The raw query string including `?`, or "". */
+  search: string;
+  /** Repeated keys become arrays, like Fastify's default query parser. */
+  query: Record<string, string | string[]>;
+  headers: TenantHeaders;
+  /** `Host` as the client sent it (may include a port). */
+  host: string;
+  /** Parsed by content type: JSON, a form as an object, or the bytes for binary and multipart. */
+  body: unknown;
+  /** The untouched request bytes, for `rawBody` handlers and multipart parsing. */
+  rawBody?: Buffer;
+  ip: string;
+  protocol: string;
+  /** The server's request id, for logs. */
+  id: string;
+};
+
+/** A malformed request body. Hosts answer it with `status` and `{ error: code, message }`. */
+export class TenantRequestError extends Error {
+  constructor(
+    readonly statusCode: number,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    // Malformed escapes: classify on the raw path; the route decides whether that is a 400.
+    return value;
+  }
+}
+
+/** `/a/b/?x` becomes `/a/b`. Backslashes count as slashes, like the hosted project host. */
+export function tenantPathname(url: string): string {
+  const raw = safeDecode(url.split("?")[0] ?? "/").replace(/\\/g, "/");
+  return raw.replace(/\/$/, "") || "/";
+}
+
+export function parseQuery(search: string): Record<string, string | string[]> {
+  const query: Record<string, string | string[]> = {};
+  for (const [key, value] of new URLSearchParams(search)) {
+    const existing = query[key];
+    if (existing === undefined) query[key] = value;
+    else if (Array.isArray(existing)) existing.push(value);
+    else query[key] = [existing, value];
+  }
+  return query;
+}
+
+function mediaType(headers: TenantHeaders): string {
+  const raw = headers["content-type"];
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  return (value ?? "").split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+
+/**
+ * The body as the hosts have always parsed it: JSON (empty is `{}`), urlencoded forms as a flat
+ * object, and binary or multipart as the bytes. Any other type keeps the bytes too.
+ */
+export function parseTenantBody(raw: Buffer, headers: TenantHeaders): unknown {
+  const type = mediaType(headers);
+  if (type === "application/json") {
+    const text = raw.toString("utf8");
+    if (!text) return {};
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new TenantRequestError(400, "invalid_json", "Request body is not valid JSON");
+    }
+  }
+  if (type === "application/x-www-form-urlencoded") {
+    return Object.fromEntries(new URLSearchParams(raw.toString("utf8")).entries());
+  }
+  return raw.length > 0 ? raw : undefined;
+}
+
+function headerRecord(headers: Headers): TenantHeaders {
+  const out: TenantHeaders = {};
+  for (const [name, value] of headers) out[name] = value;
+  const cookies = headers.getSetCookie?.() ?? [];
+  if (cookies.length > 1) out["set-cookie"] = cookies;
+  return out;
+}
+
+/** Reads a Fetch `Request` into a `TenantRequest`. The body is read once, here. */
+export async function fromFetchRequest(
+  request: Request,
+  info: { ip: string; id: string },
+): Promise<TenantRequest> {
+  const url = new URL(request.url);
+  const headers = headerRecord(request.headers);
+  const hasBody = request.method !== "GET" && request.method !== "HEAD" && request.body !== null;
+  const rawBody = hasBody ? Buffer.from(await request.arrayBuffer()) : undefined;
+  return {
+    method: request.method.toUpperCase(),
+    url: `${url.pathname}${url.search}`,
+    pathname: tenantPathname(url.pathname),
+    search: url.search,
+    query: parseQuery(url.search),
+    headers,
+    host: String(headers.host ?? url.host),
+    body: rawBody && rawBody.length > 0 ? parseTenantBody(rawBody, headers) : undefined,
+    rawBody,
+    ip: info.ip,
+    protocol: url.protocol.replace(/:$/, ""),
+    id: info.id,
+  };
+}
+
+/** The first value of a header, or undefined. */
+export function headerValue(headers: TenantHeaders, name: string): string | undefined {
+  const value = headers[name];
+  return Array.isArray(value) ? value[0] : value;
+}

package/src/resolve.ts

@@ -0,0 +1,107 @@
+import {
+  ENTERPRISE_SPEC_PATH,
+  isProjectMcpRequest,
+  isProjectOAuthRequestPath,
+  isReservedAuthPath,
+  isReservedRobodevPath,
+  isReservedStoragePath,
+  isReservedStorageUploadPath,
+  matchProjectRoute,
+} from "@robodev-ai/runtime";
+import type { TenantHeaders } from "./request.js";
+
+export type ResourceKind =
+  | "reserved"
+  | "mcp"
+  | "oauth"
+  | "api"
+  | "swagger"
+  | "scalar"
+  | "asset"
+  | "static"
+  | "spa"
+  | "not_found";
+
+/** Which reserved endpoint a `reserved` resource is. */
+export type ReservedKind = "auth" | "storage" | "ready" | "openapi" | "enterprise_spec" | "other";
+
+export type ResolveResult = {
+  kind: ResourceKind;
+  rel?: string;
+  reserved?: ReservedKind;
+};
+
+export type FrontendKind = "none" | "static" | "react" | (string & {});
+
+export type ResolveRuntime = {
+  routes: { method: string; path: string }[];
+  frontendKind: FrontendKind;
+  webHas: (relPath: string) => boolean;
+};
+
+/** Apple and Google fetch these by exact path; the SPA's HTML must never answer them. */
+export function isWellKnownLookupPath(path: string): boolean {
+  return path.startsWith("/.well-known/") || path === "/apple-app-site-association";
+}
+
+/**
+ * What a project path serves, in priority order: Robodev's reserved endpoints, the MCP endpoint
+ * and its OAuth server, docs, hashed assets, the project's routes, then web files and the SPA.
+ */
+export function resolveProjectResource(
+  pathname: string,
+  method: string,
+  runtime: ResolveRuntime,
+  headers: TenantHeaders = {},
+): ResolveResult {
+  const verb = method.toLowerCase();
+  const path = pathname.replace(/\/$/, "") || "/";
+
+  if (isReservedAuthPath(path)) return { kind: "reserved", reserved: "auth" };
+  if (isReservedStoragePath(path) || isReservedStorageUploadPath(path)) {
+    return { kind: "reserved", reserved: "storage" };
+  }
+  if (path === "/_robodev/ready") return { kind: "reserved", reserved: "ready" };
+  if (path === "/openapi.json") return { kind: "reserved", reserved: "openapi" };
+  if (path === ENTERPRISE_SPEC_PATH) return { kind: "reserved", reserved: "enterprise_spec" };
+  // The project's MCP endpoint and its OAuth server win over routes and static files. A
+  // browser opening `/mcp` as a page falls through, so a tenant SPA route there still loads.
+  if (isProjectMcpRequest(path, method, headers)) return { kind: "mcp" };
+  if (isProjectOAuthRequestPath(path)) return { kind: "oauth" };
+  if (path === "/_robodev/docs" || path === "/_robodev/swagger") {
+    return { kind: "swagger" };
+  }
+  if (path === "/_robodev/scalar") {
+    return { kind: "scalar" };
+  }
+  if (path === "/docs" || path === "/swagger") {
+    if (runtime.frontendKind === "none") return { kind: "swagger" };
+  }
+  if (path === "/scalar") {
+    if (runtime.frontendKind === "none") return { kind: "scalar" };
+  }
+  if (path === "/_robodev/assets" || path.startsWith("/_robodev/assets/")) {
+    const rel = path === "/_robodev/assets" ? "" : path.slice("/_robodev/assets/".length);
+    return { kind: "asset", rel };
+  }
+  if (isReservedRobodevPath(path)) {
+    return { kind: "reserved", reserved: "other" };
+  }
+
+  const matched = matchProjectRoute(path, verb, runtime.routes);
+  if (matched) return { kind: "api" };
+
+  const staticRel = path === "/" ? "index.html" : path.slice(1);
+  if (runtime.webHas(staticRel)) return { kind: "static", rel: staticRel };
+  if (isWellKnownLookupPath(path)) return { kind: "not_found" };
+
+  if (
+    runtime.frontendKind !== "none" &&
+    (verb === "get" || verb === "head") &&
+    runtime.webHas("index.html")
+  ) {
+    return { kind: "spa", rel: "index.html" };
+  }
+
+  return { kind: "not_found" };
+}

package/src/response.ts

@@ -0,0 +1,175 @@
+import { Readable } from "node:stream";
+
+/**
+ * Responses whose body is a stream (storage objects, files off Bun). Every other response is
+ * small and sent as one buffer.
+ */
+const streamed = new WeakSet<Response>();
+
+export function isStreamedResponse(response: Response): boolean {
+  return streamed.has(response);
+}
+
+/**
+ * The body each buffered response was built from. A server adapter sends these bytes as they
+ * are instead of reading the body stream back, which on Node (undici) costs more than the
+ * request itself. The body stream stays readable for anyone else.
+ */
+const builtBodies = new WeakMap<Response, string | Uint8Array>();
+
+export function builtBodyOf(response: Response): string | Uint8Array | undefined {
+  return response.bodyUsed ? undefined : builtBodies.get(response);
+}
+
+type Body = string | Buffer | Uint8Array | null;
+
+function isNodeReadable(value: unknown): value is Readable {
+  return value instanceof Readable;
+}
+
+/**
+ * How a value goes on the wire, matching Fastify's `reply.send`: strings as text, bytes as
+ * bytes, streams piped, `undefined` as no body, anything else as JSON.
+ */
+export function encodeBody(value: unknown): {
+  body: Body | ReadableStream<Uint8Array>;
+  defaultType: string | null;
+} {
+  if (value === undefined) return { body: null, defaultType: null };
+  if (typeof value === "string") return { body: value, defaultType: "text/plain; charset=utf-8" };
+  if (value instanceof Uint8Array) return { body: value, defaultType: "application/octet-stream" };
+  if (value instanceof ReadableStream) {
+    return { body: value as ReadableStream<Uint8Array>, defaultType: "application/octet-stream" };
+  }
+  if (isNodeReadable(value)) {
+    return {
+      body: Readable.toWeb(value) as unknown as ReadableStream<Uint8Array>,
+      defaultType: "application/octet-stream",
+    };
+  }
+  return { body: JSON.stringify(value), defaultType: "application/json; charset=utf-8" };
+}
+
+/** Builds a `Response`, recording whether its body streams. */
+export function makeResponse(
+  status: number,
+  headers: Headers,
+  value: unknown,
+  method = "GET",
+): Response {
+  const { body, defaultType } = encodeBody(value);
+  if (defaultType && !headers.has("content-type")) headers.set("content-type", defaultType);
+  const noBody = status === 204 || status === 304 || method === "HEAD";
+  if (status === 204) {
+    // A 204 has no content, so it names no type or length (RFC 9110 §8.6).
+    headers.delete("content-type");
+    headers.delete("content-length");
+  }
+  if (body instanceof ReadableStream) {
+    if (noBody) {
+      void body.cancel().catch(() => {});
+      return new Response(null, { status, headers });
+    }
+    const response = new Response(body, { status, headers });
+    streamed.add(response);
+    return response;
+  }
+  if (body !== null && !headers.has("content-length")) {
+    const length = typeof body === "string" ? Buffer.byteLength(body) : body.byteLength;
+    headers.set("content-length", String(length));
+  }
+  const response = new Response(noBody ? null : (body as BodyInit | null), { status, headers });
+  if (!noBody && body !== null) builtBodies.set(response, body);
+  return response;
+}
+
+/** A JSON response. */
+export function json(body: unknown, status = 200, headers?: Record<string, string>): Response {
+  return makeResponse(status, new Headers(headers), body ?? null);
+}
+
+/**
+ * A reply builder with the slice of Fastify's `reply` API the tenant handlers use, so a
+ * handler reads the same as it did on Fastify and returns a `Response` instead of writing one.
+ */
+export class TenantReply {
+  statusCode = 200;
+  readonly headers = new Headers();
+  private result: Response | null = null;
+
+  constructor(private readonly method = "GET") {}
+
+  code(status: number): this {
+    this.statusCode = status;
+    return this;
+  }
+
+  status(status: number): this {
+    return this.code(status);
+  }
+
+  /** `Set-Cookie` accumulates, like Fastify; any other header is replaced. */
+  header(name: string, value: string | number | string[]): this {
+    const values = Array.isArray(value) ? value : [String(value)];
+    if (name.toLowerCase() === "set-cookie") {
+      for (const item of values) this.headers.append(name, item);
+    } else {
+      this.headers.set(name, values.join(", "));
+    }
+    return this;
+  }
+
+  type(contentType: string): this {
+    return this.header("content-type", contentType);
+  }
+
+  getHeader(name: string): string | null {
+    return this.headers.get(name);
+  }
+
+  get sent(): boolean {
+    return this.result !== null;
+  }
+
+  send(value?: unknown): this {
+    if (this.result) throw new Error("TenantReply already sent");
+    this.result = makeResponse(this.statusCode, this.headers, value, this.method);
+    return this;
+  }
+
+  /** Fastify's rule: an explicit code wins, then a non-200 code set earlier, then 302. */
+  redirect(location: string, code?: number): this {
+    const status = code ?? (this.statusCode === 200 ? 302 : this.statusCode);
+    this.code(status).header("location", location);
+    return this.send();
+  }
+
+  /** The finished response. A handler that never sent answers 204, like an empty Fastify reply. */
+  response(): Response {
+    return (
+      this.result ??
+      makeResponse(this.statusCode === 200 ? 204 : this.statusCode, this.headers, undefined)
+    );
+  }
+}
+
+/** A runtime-shaped answer (`{ status, headers, body }`) as a `Response`. */
+export function runtimeResponse(input: {
+  status: number;
+  headers?: Record<string, string>;
+  body?: unknown;
+}): Response {
+  return makeResponse(input.status, new Headers(input.headers), input.body);
+}
+
+/** A handler's encoded result (status, headers, content type, payload) as a `Response`. */
+export function encodedResponse(encoded: {
+  status: number;
+  headers: Record<string, string>;
+  contentType: string;
+  payload: unknown;
+}): Response {
+  const headers = new Headers(encoded.headers);
+  headers.set("content-type", encoded.contentType);
+  return makeResponse(encoded.status, headers, encoded.payload);
+}

package/src/web-media.test.ts

@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, before, test } from "node:test";
+import type { ResourceKind } from "./resolve.js";
+import { webFileHeaders, webFileResponse } from "./web.js";
+
+/** A Fetch server on a free loopback port, and requests against it in an inject-like shape. */
+function serve(handler: (request: Request) => Promise<Response>) {
+  const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: handler });
+  return {
+    async inject(input: { method: string; url: string; headers?: Record<string, string> }) {
+      const response = await fetch(new URL(input.url, server.url), {
+        method: input.method,
+        headers: input.headers,
+      });
+      const rawPayload = Buffer.from(await response.arrayBuffer());
+      return {
+        statusCode: response.status,
+        headers: Object.fromEntries(response.headers) as Record<string, string | undefined>,
+        rawPayload,
+        body: rawPayload.toString("utf8"),
+      };
+    },
+    close: () => server.stop(true),
+  };
+}
+
+/** `rel` from `root` as the tenant core serves it, or null when the file is absent. */
+async function serveFile(
+  root: string,
+  rel: string,
+  kind: ResourceKind,
+  request: Request,
+): Promise<Response | null> {
+  const sent = await webFileResponse(
+    root,
+    rel,
+    kind,
+    { method: request.method, range: request.headers.get("range") ?? undefined },
+    "frame-ancestors 'self'",
+  );
+  return sent?.response ?? null;
+}
+
+const notFound = () => Response.json({ error: "not_found" }, { status: 404 });
+
+let root = "";
+let server: ReturnType<typeof serve>;
+const svg = `<svg xmlns="http://www.w3.org/2000/svg">${"<path d='M0 0'/>".repeat(200_000)}</svg>`;
+const video = Buffer.from(Array.from({ length: 64 * 1024 }, (_, i) => i % 251));
+
+before(async () => {
+  root = await mkdtemp(join(tmpdir(), "rd-host-media-"));
+  await writeFile(join(root, "index.html"), "<html></html>");
+  await writeFile(join(root, "clip.mp4"), video);
+  await writeFile(join(root, "big.svg"), svg);
+  server = serve(async (request) => {
+    const rel = new URL(request.url).pathname.slice(1) || "index.html";
+    return (await serveFile(root, rel, "static", request)) ?? notFound();
+  });
+});
+
+after(async () => {
+  await server.close();
+  await rm(root, { recursive: true, force: true });
+});
+
+test("project host: media MIME types", () => {
+  const types: Record<string, string> = {
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mov: "video/quicktime",
+    pdf: "application/pdf",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+  };
+  for (const [ext, type] of Object.entries(types)) {
+    assert.equal(webFileHeaders(`media/a.${ext}`, "static").type, type, ext);
+  }
+});
+
+test("project host: full GET streams the file with Accept-Ranges and Content-Length", async () => {
+  const response = await server.inject({ method: "GET", url: "/clip.mp4" });
+  assert.equal(response.statusCode, 200);
+  assert.equal(response.headers["accept-ranges"], "bytes");
+  assert.equal(response.headers["content-length"], String(video.length));
+  assert.equal(response.headers["content-type"], "video/mp4");
+  assert.deepEqual(response.rawPayload, video);
+});
+
+test("project host: Range gives 206 with Content-Range; out of range is 416", async () => {
+  const part = await server.inject({
+    method: "GET",
+    url: "/clip.mp4",
+    headers: { range: "bytes=0-1023" },
+  });
+  assert.equal(part.statusCode, 206);
+  assert.equal(part.headers["content-range"], `bytes 0-1023/${video.length}`);
+  assert.equal(part.headers["content-length"], "1024");
+  assert.equal(part.headers["content-type"], "video/mp4");
+  assert.equal(part.headers["accept-ranges"], "bytes");
+  assert.deepEqual(part.rawPayload, video.subarray(0, 1024));
+
+  const open = await server.inject({
+    method: "GET",
+    url: "/clip.mp4",
+    headers: { range: "bytes=65000-" },
+  });
+  assert.equal(open.statusCode, 206);
+  assert.deepEqual(open.rawPayload, video.subarray(65000));
+
+  const bad = await server.inject({
+    method: "GET",
+    url: "/clip.mp4",
+    headers: { range: `bytes=${video.length}-` },
+  });
+  assert.equal(bad.statusCode, 416);
+  assert.equal(bad.headers["content-range"], `bytes */${video.length}`);
+});
+
+test("project host: HEAD sends headers only", async () => {
+  const head = await server.inject({ method: "HEAD", url: "/clip.mp4" });
+  assert.equal(head.statusCode, 200);
+  assert.equal(head.headers["content-length"], String(video.length));
+  assert.equal(head.rawPayload.length, 0);
+});
+
+test("project host: a 3MB SVG (materialized from a blob) is served as image/svg+xml", async () => {
+  const response = await server.inject({ method: "GET", url: "/big.svg" });
+  assert.equal(response.statusCode, 200);
+  assert.equal(response.headers["content-type"], "image/svg+xml");
+  assert.equal(response.headers["content-length"], String(Buffer.byteLength(svg)));
+  assert.equal(response.body, svg);
+});