bazis 0.96.1

package/core/http/Results/normalize.ts

@@ -0,0 +1,93 @@
+import type { HttpContext } from "../HttpContext/HttpContext";
+import { HttpResult } from "./HttpResult";
+
+/** Per-action response defaults coming from decorators. */
+export interface ResponseDefaults {
+  /** `@HttpCode(...)` value. */
+  httpCode?: number;
+  /** `@Produces(...)` value. */
+  produces?: string;
+}
+
+type ResponseBody = ConstructorParameters<typeof Response>[0];
+
+function isBinaryBody(body: unknown): body is Blob | Uint8Array | ArrayBuffer | ReadableStream {
+  return (
+    body instanceof Blob || body instanceof Uint8Array || body instanceof ArrayBuffer || body instanceof ReadableStream
+  );
+}
+
+/**
+ * Turns whatever an action returned into a `Response` with automatic
+ * Content-Type negotiation:
+ *
+ * - `Response` — returned as-is (full manual control);
+ * - `HttpResult` — status/headers/body from the helper;
+ * - `string` — text/plain (unless `@Produces` says otherwise);
+ * - `Blob`/bytes/stream — binary passthrough;
+ * - any other object/array/number/boolean — JSON;
+ * - `undefined`/`null` — empty body, 204 (or `@HttpCode`).
+ *
+ * Status priority: result helper > `@HttpCode` > `ctx.res.status(...)` > default.
+ * Headers from `ctx.res.header(...)` are merged into every non-raw response.
+ */
+export function normalizeResult(result: unknown, ctx: HttpContext, defaults: ResponseDefaults): Response {
+  if (result instanceof Response) {
+    return result;
+  }
+
+  const builderStatus = ctx.res.statusOverride;
+  const builderHeaders = ctx.res.headers;
+
+  let status: number;
+  let body: unknown;
+  let contentType: string | undefined = defaults.produces;
+  let extraHeaders: readonly [string, string][] | undefined;
+
+  if (result instanceof HttpResult) {
+    status = result.status;
+    body = result.body;
+    contentType = result.contentType ?? defaults.produces;
+    extraHeaders = result.headers;
+  } else {
+    body = result;
+    status = defaults.httpCode ?? builderStatus ?? (result === undefined || result === null ? 204 : 200);
+  }
+
+  const headers = new Headers();
+  if (extraHeaders) {
+    for (const [name, value] of extraHeaders) {
+      headers.append(name, value);
+    }
+  }
+  for (const [name, value] of builderHeaders) {
+    headers.append(name, value);
+  }
+
+  let payload: ResponseBody = null;
+  if (body === undefined || body === null) {
+    payload = null;
+  } else if (typeof body === "string") {
+    payload = body;
+    if (!headers.has("content-type")) {
+      headers.set("content-type", contentType ?? "text/plain; charset=utf-8");
+    }
+  } else if (isBinaryBody(body)) {
+    payload = body as ResponseBody;
+    if (contentType) {
+      headers.set("content-type", contentType);
+    }
+  } else {
+    payload = JSON.stringify(body);
+    if (!headers.has("content-type")) {
+      headers.set("content-type", contentType ?? "application/json; charset=utf-8");
+    }
+  }
+
+  // 204/304 must not carry a body.
+  if (status === 204 || status === 304) {
+    payload = null;
+  }
+
+  return new Response(payload, { status, headers });
+}

package/core/http/Results/results.ts

@@ -0,0 +1,70 @@
+import { HttpResult } from "./HttpResult";
+
+/** 200 OK. Body optional: object -> JSON, string -> text. */
+export function Ok(body?: unknown): HttpResult {
+  return new HttpResult(200, body);
+}
+
+/** 201 Created with optional Location header. */
+export function Created(location?: string, body?: unknown): HttpResult {
+  return new HttpResult(201, body, location ? [["location", location]] : undefined);
+}
+
+/** 202 Accepted. */
+export function Accepted(body?: unknown): HttpResult {
+  return new HttpResult(202, body);
+}
+
+/** 204 No Content. */
+export function NoContent(): HttpResult {
+  return new HttpResult(204);
+}
+
+/** 400 Bad Request. */
+export function BadRequest(body?: unknown): HttpResult {
+  return new HttpResult(400, body ?? { error: "Bad Request" });
+}
+
+/** 401 Unauthorized. */
+export function Unauthorized(body?: unknown): HttpResult {
+  return new HttpResult(401, body ?? { error: "Unauthorized" });
+}
+
+/** 403 Forbidden. */
+export function Forbidden(body?: unknown): HttpResult {
+  return new HttpResult(403, body ?? { error: "Forbidden" });
+}
+
+/** 404 Not Found. */
+export function NotFound(body?: unknown): HttpResult {
+  return new HttpResult(404, body ?? { error: "Not Found" });
+}
+
+/** 409 Conflict. */
+export function Conflict(body?: unknown): HttpResult {
+  return new HttpResult(409, body ?? { error: "Conflict" });
+}
+
+/** 500 Internal Server Error. */
+export function InternalServerError(body?: unknown): HttpResult {
+  return new HttpResult(500, body ?? { error: "Internal Server Error" });
+}
+
+/** Redirect: 302 by default, 301 when `permanent`. */
+export function Redirect(location: string, permanent = false): HttpResult {
+  return new HttpResult(permanent ? 301 : 302, undefined, [["location", location]]);
+}
+
+/** Arbitrary status with a JSON body. */
+export function StatusCode(status: number, body?: unknown): HttpResult {
+  return new HttpResult(status, body);
+}
+
+/**
+ * File response backed by `Bun.file` (zero-copy streaming) or an explicit
+ * Blob/bytes. Content-Type is inferred by Bun for files on disk.
+ */
+export function File(pathOrBlob: string | Blob | Uint8Array, contentType?: string): HttpResult {
+  const body = typeof pathOrBlob === "string" ? Bun.file(pathOrBlob) : pathOrBlob;
+  return new HttpResult(200, body, undefined, contentType);
+}

package/core/http/Routing/Router.ts

@@ -0,0 +1,201 @@
+import type { HttpMiddleware } from "../Middleware/types";
+import { HttpSetupError } from "../Errors/HttpError";
+import { INVALID } from "../Binding/convert";
+import type { SegmentConstraint, TemplateSegment } from "./template";
+
+/** A fully compiled route endpoint: its middleware chain runs the action. */
+export interface RouteAction {
+  /** Precompiled pipeline: [server-level, global, controller, route, terminal]. */
+  readonly chain: readonly HttpMiddleware[];
+  /** Declared API version (diagnostics). */
+  readonly version?: string;
+  /** Debug name: Controller.method. */
+  readonly name: string;
+  /** Action-specific body cap in bytes; undefined inherits the server cap. */
+  readonly maxBodyBytes?: number;
+}
+
+interface RouteEntry {
+  readonly action: RouteAction;
+  /** Names belong to the selected declaration, never to shared tree edges. */
+  readonly bindings: readonly { readonly name: string; readonly index: number }[];
+}
+
+/** method -> (versionKey -> entry); "" is unversioned, "*" matches any method. */
+type RouteLeaf = Map<string, Map<string, RouteEntry>>;
+
+interface ParamEdge {
+  readonly constraint?: SegmentConstraint;
+  readonly node: RouteNode;
+}
+
+class RouteNode {
+  statics?: Map<string, RouteNode>;
+  params?: ParamEdge[];
+  wildcard?: { leaf: RouteLeaf };
+  leaf?: RouteLeaf;
+}
+
+export type RouteParamsBag = Record<string, string | number | boolean>;
+
+export type MatchResult =
+  | { kind: "matched"; action: RouteAction; params: RouteParamsBag }
+  | { kind: "method-not-allowed"; allow: readonly string[] }
+  | { kind: "unsupported-version"; supported: readonly string[] }
+  | { kind: "not-found" };
+
+/**
+ * Radix-style route tree. Segments are matched with priority
+ * static > constrained param > param > wildcard, with backtracking, so the
+ * most specific route always wins regardless of registration order.
+ * Captures are indexed by path position and named only after method/version
+ * selection, so overlapping declarations cannot change each other's params.
+ */
+export class Router {
+  private readonly root = new RouteNode();
+
+  /** Registers a parsed template. Duplicate (path, method, version) -> startup error. */
+  register(segments: readonly TemplateSegment[], httpMethod: string, versionKey: string, action: RouteAction): void {
+    const entry: RouteEntry = {
+      action,
+      bindings: segments.flatMap((segment, index) => segment.kind === "static" ? [] : [{ name: segment.name, index }]),
+    };
+    let node = this.root;
+    for (let index = 0; index < segments.length; index += 1) {
+      const segment = segments[index]!;
+      if (segment.kind === "static") {
+        node.statics ??= new Map();
+        let child = node.statics.get(segment.value);
+        if (!child) {
+          child = new RouteNode();
+          node.statics.set(segment.value, child);
+        }
+        node = child;
+      } else if (segment.kind === "param") {
+        node.params ??= [];
+        let edge = node.params.find(
+          (candidate) => candidate.constraint?.name === segment.constraint?.name,
+        );
+        if (!edge) {
+          edge = { constraint: segment.constraint, node: new RouteNode() };
+          node.params.push(edge);
+          // Keep overlap resolution deterministic: constrained before plain,
+          // and integer before the broader number constraint.
+          node.params.sort((left, right) => constraintPriority(right.constraint) - constraintPriority(left.constraint));
+        }
+        node = edge.node;
+      } else {
+        node.wildcard ??= { leaf: new Map() };
+        this.addToLeaf(node.wildcard.leaf, httpMethod, versionKey, entry);
+        return;
+      }
+    }
+    node.leaf ??= new Map();
+    this.addToLeaf(node.leaf, httpMethod, versionKey, entry);
+  }
+
+  private addToLeaf(leaf: RouteLeaf, httpMethod: string, versionKey: string, entry: RouteEntry): void {
+    let versions = leaf.get(httpMethod);
+    if (!versions) {
+      versions = new Map();
+      leaf.set(httpMethod, versions);
+    }
+    if (versions.has(versionKey)) {
+      throw new HttpSetupError(
+        `Duplicate route: ${httpMethod} (version "${versionKey || "-"}") already mapped to ${versions.get(versionKey)!.action.name}, cannot map ${entry.action.name}.`,
+      );
+    }
+    versions.set(versionKey, entry);
+  }
+
+  /**
+   * @param requestedVersion Version resolved from the request (query/header
+   *   sources) or `undefined`. URL-source versions are part of the path.
+   */
+  match(httpMethod: string, segments: readonly string[], requestedVersion?: string): MatchResult {
+    const captures: (string | number | boolean)[] = [];
+    const leaf = this.descend(this.root, segments, 0, captures);
+    if (!leaf) {
+      return { kind: "not-found" };
+    }
+    // HEAD falls back to a GET handler (the server strips the body); explicit
+    // HEAD routes still win. "*" (@All) matches any method last.
+    const versions =
+      leaf.get(httpMethod) ?? (httpMethod === "HEAD" ? leaf.get("GET") : undefined) ?? leaf.get("*");
+    if (!versions) {
+      const allow = [...leaf.keys()].filter((method) => method !== "*");
+      if (allow.includes("GET") && !allow.includes("HEAD")) {
+        allow.push("HEAD");
+      }
+      return { kind: "method-not-allowed", allow };
+    }
+    const entry =
+      requestedVersion !== undefined ? (versions.get(requestedVersion) ?? versions.get("")) : versions.get("");
+    if (!entry) {
+      return { kind: "unsupported-version", supported: [...versions.keys()].filter((key) => key !== "") };
+    }
+    const params: RouteParamsBag = Object.create(null) as RouteParamsBag;
+    for (const { name, index } of entry.bindings) {
+      params[name] = captures[index]!;
+    }
+    return { kind: "matched", action: entry.action, params };
+  }
+
+  private descend(node: RouteNode, segments: readonly string[], index: number, captures: (string | number | boolean)[]): RouteLeaf | undefined {
+    if (index === segments.length) {
+      if (node.leaf) {
+        return node.leaf;
+      }
+      // A trailing wildcard also matches the empty rest ("files" -> "files/*path").
+      if (node.wildcard) {
+        captures[index] = "";
+        return node.wildcard.leaf;
+      }
+      return undefined;
+    }
+    const segment = segments[index]!;
+
+    const staticChild = node.statics?.get(segment);
+    if (staticChild) {
+      const leaf = this.descend(staticChild, segments, index + 1, captures);
+      if (leaf) {
+        return leaf;
+      }
+    }
+
+    if (node.params) {
+      for (const edge of node.params) {
+        const value = edge.constraint ? edge.constraint.convert(segment) : segment;
+        if (value === INVALID) {
+          continue;
+        }
+        captures[index] = value;
+        const leaf = this.descend(edge.node, segments, index + 1, captures);
+        if (leaf) {
+          return leaf;
+        }
+      }
+    }
+
+    if (node.wildcard) {
+      captures[index] = segments.slice(index).join("/");
+      return node.wildcard.leaf;
+    }
+    return undefined;
+  }
+}
+
+function constraintPriority(constraint: SegmentConstraint | undefined): number {
+  switch (constraint?.name) {
+    case "int":
+      return 30;
+    case "uuid":
+    case "bool":
+    case "alpha":
+      return 20;
+    case "number":
+      return 10;
+    default:
+      return 0;
+  }
+}

package/core/http/Routing/RouterBuilder.ts

@@ -0,0 +1,184 @@
+import type { Class, Token } from "../../di";
+import { bindArguments } from "../Binding/ParameterBinder";
+import { resolveGeneratedBindings } from "../Binding/autoBindings";
+import { controllerMetaOf, type ActionMeta, type ControllerMeta } from "../Decorators/metadata";
+import { HttpSetupError } from "../Errors/HttpError";
+import type { HttpContext } from "../HttpContext/HttpContext";
+import type { ActionFilterHooks, HttpMiddleware } from "../Middleware/types";
+import { normalizeResult } from "../Results/normalize";
+import type { ApiVersioningOptions, RouteMiddlewareComposer } from "../options";
+import { createAuthorizeComposer } from "../Authorization/authorizeComposer";
+import { Router, type RouteAction } from "./Router";
+import { joinPaths, parseTemplate } from "./template";
+
+type ControllerInstance = Record<string | symbol, (...args: unknown[]) => unknown>;
+
+interface ActionPipeline {
+  /** Binding and ActionFilter.before: boundary checks that must also run on cache hits. */
+  readonly boundary: HttpMiddleware;
+  /** Controller/action execution and ActionFilter.after: skipped when middleware short-circuits. */
+  readonly terminal: HttpMiddleware;
+}
+
+/**
+ * Builds the radix router from controller metadata. Runs once at server
+ * startup: templates are parsed and the action boundary/terminal handlers are
+ * precompiled per route — request dispatch performs no metadata work at all.
+ */
+export class RouterBuilder {
+  private readonly authorizeComposer = createAuthorizeComposer();
+
+  constructor(
+    /** Middleware prepended to every route: [logger?, cors?, errorHandler, ...global]. */
+    private readonly serverChain: readonly HttpMiddleware[],
+    private readonly globalPrefix: string | undefined,
+    private readonly versioning: ApiVersioningOptions | undefined,
+    private readonly routeMiddlewareComposer?: RouteMiddlewareComposer,
+  ) {}
+
+  build(controllers: readonly Class<object>[]): Router {
+    const router = new Router();
+    for (const controllerClass of controllers) {
+      const meta = controllerMetaOf(controllerClass);
+      if (!meta?.isController) {
+        throw new HttpSetupError(
+          `Class "${controllerClass.name}" is not a controller. Add @Controller() and route decorators.`,
+        );
+      }
+      this.registerController(router, controllerClass, meta);
+    }
+    return router;
+  }
+
+  private registerController(router: Router, controllerClass: Class<object>, meta: ControllerMeta): void {
+    const useUrlVersioning = this.versioning === undefined || this.versioning.source === "url";
+    for (const [methodName, action] of meta.actions) {
+      if (action.routes.length === 0) {
+        continue;
+      }
+      if (action.maxBodyBytes !== undefined
+        && (!Number.isSafeInteger(action.maxBodyBytes) || action.maxBodyBytes <= 0)) {
+        throw new HttpSetupError("HTTP route maxBodyBytes metadata must be a positive safe integer.");
+      }
+      const version = action.version ?? meta.version;
+      const pipeline = this.createActionPipeline(controllerClass, methodName, meta, action);
+      const authorization = this.authorizeComposer(controllerClass, methodName, meta, action);
+      const composed = this.routeMiddlewareComposer?.(controllerClass, methodName, meta, action) ?? [];
+      // Authorization must precede controller middleware so unauthenticated
+      // requests cannot trigger controller-level work or side effects. Route
+      // and method policies plus ActionFilter.before form the public action
+      // boundary and therefore run before short-circuiting composers such as
+      // output cache. The controller and action still remain lazy on a hit.
+      const chain = [
+        ...this.serverChain,
+        ...authorization,
+        ...meta.middleware,
+        ...action.middleware,
+        pipeline.boundary,
+        ...composed,
+        pipeline.terminal,
+      ];
+      const routeAction: RouteAction = {
+        chain,
+        version,
+        name: `${controllerClass.name}.${String(methodName)}`,
+        maxBodyBytes: action.maxBodyBytes,
+      };
+      for (const declaration of action.routes) {
+        const versionSegment = useUrlVersioning && version !== undefined ? `v${version}` : undefined;
+        const fullPath = joinPaths(this.globalPrefix, versionSegment, meta.prefix, declaration.template);
+        const versionKey = useUrlVersioning ? "" : (version ?? "");
+        router.register(parseTemplate(fullPath), declaration.httpMethod, versionKey, routeAction);
+      }
+    }
+  }
+
+  /**
+   * Precompiles binding + ActionFilter.before as a boundary middleware and
+   * controller execution + ActionFilter.after as the terminal. This lets
+   * output cache short-circuit only the latter. Errors first get a chance at
+   * the controller's @Catch handlers, then bubble to the global error handler.
+   */
+  private createActionPipeline(
+    controllerClass: Class<object>,
+    methodName: string | symbol,
+    meta: ControllerMeta,
+    action: ActionMeta,
+  ): ActionPipeline {
+    const filters: readonly ActionFilterHooks[] = [...meta.filters, ...action.filters];
+    const catches = meta.catches;
+    const bindings = resolveGeneratedBindings(controllerClass, methodName);
+    const responseDefaults = { httpCode: action.httpCode, produces: action.produces };
+    const bindingDefaults = { consumes: action.consumes };
+    const token = controllerClass as unknown as Token<object>;
+    const boundArguments = new WeakMap<HttpContext, readonly unknown[]>();
+
+    const handleError = async (
+      error: unknown,
+      ctx: HttpContext,
+      resolvedController?: ControllerInstance,
+    ): Promise<boolean> => {
+      if (catches.length === 0) {
+        return false;
+      }
+      const controller = resolvedController ?? ctx.services.resolve(token) as ControllerInstance;
+      for (const handler of catches) {
+        if (handler.errorType !== undefined && !(error instanceof handler.errorType)) {
+          continue;
+        }
+        const handled: unknown = await controller[handler.methodName]!(error, ctx);
+        if (handled !== undefined) {
+          ctx.response = normalizeResult(handled, ctx, {});
+          return true;
+        }
+      }
+      return false;
+    };
+
+    const boundary: HttpMiddleware = async (ctx, next) => {
+      try {
+        const args = bindings ? await bindArguments(bindings, ctx, bindingDefaults) : [ctx];
+        for (const filter of filters) {
+          await filter.before?.(ctx);
+        }
+        boundArguments.set(ctx, args);
+      } catch (error) {
+        if (await handleError(error, ctx)) {
+          return;
+        }
+        throw error;
+      }
+
+      try {
+        await next();
+      } finally {
+        boundArguments.delete(ctx);
+      }
+    };
+
+    const terminal: HttpMiddleware = async (ctx: HttpContext) => {
+      const args = boundArguments.get(ctx);
+      if (args === undefined) {
+        throw new Error(`Action boundary was not executed for ${controllerClass.name}.${String(methodName)}`);
+      }
+      const controller = ctx.services.resolve(token) as ControllerInstance;
+      try {
+        let result: unknown = await controller[methodName]!(...args);
+        for (let index = filters.length - 1; index >= 0; index -= 1) {
+          const replaced = await filters[index]!.after?.(ctx, result);
+          if (replaced !== undefined) {
+            result = replaced;
+          }
+        }
+        ctx.response = normalizeResult(result, ctx, responseDefaults);
+      } catch (error) {
+        if (await handleError(error, ctx, controller)) {
+          return;
+        }
+        throw error;
+      }
+    };
+
+    return { boundary, terminal };
+  }
+}

package/core/http/Routing/template.ts

@@ -0,0 +1,112 @@
+import { HttpSetupError } from "../Errors/HttpError";
+import { INVALID, tryConvert } from "../Binding/convert";
+
+/** Route constraint: validates and converts a path segment. */
+export interface SegmentConstraint {
+  readonly name: string;
+  convert(segment: string): string | number | boolean | typeof INVALID;
+}
+
+const UUID_SEGMENT = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const CONSTRAINTS: Record<string, SegmentConstraint> = {
+  int: { name: "int", convert: (s) => tryConvert(s, "int") },
+  number: { name: "number", convert: (s) => tryConvert(s, "number") },
+  bool: { name: "bool", convert: (s) => tryConvert(s, "bool") },
+  uuid: { name: "uuid", convert: (s) => (UUID_SEGMENT.test(s) ? s : INVALID) },
+  alpha: { name: "alpha", convert: (s) => (/^[a-z]+$/i.test(s) ? s : INVALID) },
+};
+
+export type TemplateSegment =
+  | { readonly kind: "static"; readonly value: string }
+  | { readonly kind: "param"; readonly name: string; readonly constraint?: SegmentConstraint }
+  | { readonly kind: "wildcard"; readonly name: string };
+
+const PARAM_PATTERN = /^:([A-Za-z_][A-Za-z0-9_]*)(?:\(([a-z]+)\))?$/;
+const FORBIDDEN_PARAM_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+
+/** Joins path fragments into one normalized template ("a", "/b/" -> "a/b"). */
+export function joinPaths(...fragments: (string | undefined)[]): string {
+  const parts: string[] = [];
+  for (const fragment of fragments) {
+    if (!fragment) {
+      continue;
+    }
+    for (const piece of fragment.split("/")) {
+      if (piece !== "") {
+        parts.push(piece);
+      }
+    }
+  }
+  return parts.join("/");
+}
+
+/**
+ * Parses a route template into segments. Fails fast (at startup) on bad
+ * templates: unknown constraints, wildcard not in last position, parameter
+ * names that could pollute prototypes.
+ */
+export function parseTemplate(template: string): TemplateSegment[] {
+  const segments: TemplateSegment[] = [];
+  const rawSegments = template.split("/").filter((segment) => segment !== "");
+  for (let index = 0; index < rawSegments.length; index += 1) {
+    const raw = rawSegments[index]!;
+    if (raw.startsWith(":")) {
+      const match = PARAM_PATTERN.exec(raw);
+      if (!match) {
+        throw new HttpSetupError(`Invalid route parameter "${raw}" in template "${template}".`);
+      }
+      const name = match[1]!;
+      if (FORBIDDEN_PARAM_NAMES.has(name)) {
+        throw new HttpSetupError(`Forbidden route parameter name "${name}" in template "${template}".`);
+      }
+      let constraint: SegmentConstraint | undefined;
+      if (match[2] !== undefined) {
+        constraint = CONSTRAINTS[match[2]];
+        if (!constraint) {
+          throw new HttpSetupError(
+            `Unknown route constraint "(${match[2]})" in template "${template}". Known: ${Object.keys(CONSTRAINTS).join(", ")}.`,
+          );
+        }
+      }
+      segments.push({ kind: "param", name, constraint });
+    } else if (raw.startsWith("*")) {
+      if (index !== rawSegments.length - 1) {
+        throw new HttpSetupError(`Wildcard "*" must be the last segment in template "${template}".`);
+      }
+      const name = raw.length > 1 ? raw.slice(1) : "rest";
+      if (FORBIDDEN_PARAM_NAMES.has(name)) {
+        throw new HttpSetupError(`Forbidden wildcard name "${name}" in template "${template}".`);
+      }
+      segments.push({ kind: "wildcard", name });
+    } else {
+      segments.push({ kind: "static", value: raw });
+    }
+  }
+  return segments;
+}
+
+/**
+ * Splits and decodes a request path into segments.
+ * Returns `undefined` for malformed/unsafe paths (bad percent-encoding,
+ * `..` traversal attempts) — the server answers 400.
+ */
+export function parseRequestPath(pathname: string): string[] | undefined {
+  const segments: string[] = [];
+  for (const raw of pathname.split("/")) {
+    if (raw === "") {
+      continue;
+    }
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(raw);
+    } catch {
+      return undefined;
+    }
+    if (decoded === ".." || decoded === "." || decoded.includes("\0")) {
+      return undefined;
+    }
+    segments.push(decoded);
+  }
+  return segments;
+}