stitchkit 0.45.0 → 0.47.0

package/dist/{index-w0mec79h.js → index-44xysy8r.js}

@@ -2,14 +2,12 @@ import {
   assertCorsConfig,
   corsHeaders,
   corsPreflightResponse
-} from "./index-6jypn22c.js";
-import {
-  isWithinDir
-} from "./index-x3fcszf8.js";
+} from "./index-r1qp4rve.js";
 import {
   AppError,
   __require,
   badRequest,
+  callRuntimeHandler,
   errorCode,
   extractIp,
   getClientInfo,
@@ -29,298 +27,433 @@ import {
   setRequestEndpoint,
   setRequestError,
   typedEntries,
-  validateDeclaredOutput
-} from "./index-yh0p5ddn.js";
+  validateDeclaredOutput,
+  zodIssues
+} from "./index-ee621cmy.js";
 
 // src/server/multipart.ts
-var DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
-async function readBodyCapped(req, maxBytes) {
-  const reader = req.body?.getReader();
-  if (!reader)
-    return new Uint8Array(0);
-  const chunks = [];
-  let total = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      total += value.length;
-      if (total > maxBytes) {
-        await reader.cancel();
-        badRequest(`Upload exceeds the ${Math.round(maxBytes / 1024 / 1024)} MB limit`);
+var DEFAULT_MAX_REQUEST_BYTES = 25 * 1024 * 1024;
+var DEFAULT_MAX_FIELD_BYTES = 1024 * 1024;
+var DEFAULT_MAX_HEADER_BYTES = 64 * 1024;
+var DEFAULT_MAX_PARTS = 1000;
+var CRLF = new Uint8Array([13, 10]);
+var HEADER_END = new Uint8Array([13, 10, 13, 10]);
+var decoder = new TextDecoder;
+var encoder = new TextEncoder;
+function indexOfBytes(haystack, needle) {
+  outer:
+    for (let index = 0;index <= haystack.length - needle.length; index += 1) {
+      for (let offset = 0;offset < needle.length; offset += 1) {
+        if (haystack[index + offset] !== needle[offset])
+          continue outer;
       }
-      chunks.push(value);
+      return index;
     }
-  } finally {
-    reader.releaseLock();
-  }
-  const buffer = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    buffer.set(chunk, offset);
-    offset += chunk.length;
+  return -1;
+}
+function startsWithBytes(value, prefix) {
+  if (value.length < prefix.length)
+    return false;
+  for (let index = 0;index < prefix.length; index += 1) {
+    if (value[index] !== prefix[index])
+      return false;
   }
-  return buffer;
+  return true;
 }
-async function parseMultipart(req, fileField, fieldsSchema, maxBytes = DEFAULT_MAX_UPLOAD_BYTES) {
-  const body = await readBodyCapped(req, maxBytes);
+function concatBytes(left, right) {
+  if (left.length === 0)
+    return right.slice();
+  if (right.length === 0)
+    return left.slice();
+  const joined = new Uint8Array(left.length + right.length);
+  joined.set(left);
+  joined.set(right, left.length);
+  return joined;
+}
+function parseBoundary(req) {
   const contentType = req.headers.get("content-type") ?? "";
-  const formData = await new Response(body, {
-    headers: { "content-type": contentType }
-  }).formData();
-  const file = formData.get(fileField);
-  if (!file || !(file instanceof File)) {
-    badRequest(`Missing file field: ${fileField}`);
+  if (!contentType.toLowerCase().startsWith("multipart/form-data")) {
+    badRequest("Request body must be multipart/form-data");
   }
-  const fields = {};
-  for (const [key, value] of formData.entries()) {
-    if (key === fileField)
-      continue;
-    if (isUnsafeKey(key))
-      continue;
-    if (typeof value === "string")
-      fields[key] = value;
-  }
-  return { file, fields: fieldsSchema ? fieldsSchema.parse(fields) : fields };
+  const match = /(?:^|;)\s*boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(contentType);
+  const boundary = match?.[1] ?? match?.[2];
+  if (!boundary || boundary.length > 200)
+    badRequest("Invalid multipart boundary");
+  return boundary;
 }
-
-// src/server/router.ts
-import { readFile, stat } from "node:fs/promises";
-import { resolve } from "node:path";
-
-// src/server/mime.ts
-import { extname } from "node:path";
-var MIME_BY_EXT = {
-  ".html": "text/html; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".mjs": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".avif": "image/avif",
-  ".ico": "image/x-icon",
-  ".woff2": "font/woff2",
-  ".txt": "text/plain; charset=utf-8",
-  ".wasm": "application/wasm",
-  ".mp4": "video/mp4",
-  ".webm": "video/webm",
-  ".mov": "video/quicktime",
-  ".ogv": "video/ogg",
-  ".mp3": "audio/mpeg",
-  ".m4a": "audio/mp4",
-  ".wav": "audio/wav",
-  ".flac": "audio/flac",
-  ".oga": "audio/ogg",
-  ".ogg": "audio/ogg",
-  ".pdf": "application/pdf",
-  ".zip": "application/zip"
-};
-function mimeForPath(path) {
-  return MIME_BY_EXT[extname(path).toLowerCase()] ?? "application/octet-stream";
-}
-
-// src/server/router.ts
-function joinPath(...parts) {
-  const joined = parts.filter(Boolean).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
-  return `/${joined}`;
+function parseDisposition(value) {
+  if (!value || !/^form-data(?:;|$)/i.test(value))
+    badRequest("Invalid multipart disposition");
+  const name = /(?:^|;)\s*name="([^"]*)"/i.exec(value)?.[1];
+  const filename = /(?:^|;)\s*filename="([^"]*)"/i.exec(value)?.[1];
+  if (!name || isUnsafeKey(name))
+    badRequest("Invalid multipart field name");
+  return filename === undefined ? { name } : { name, filename };
 }
-function matchSegments(patternSegments, requestSegments) {
-  const wildcardSegment = patternSegments.at(-1);
-  const wildcardName = wildcardSegment?.startsWith("*") ? wildcardSegment.slice(1) : null;
-  const prefixLength = wildcardName ? patternSegments.length - 1 : patternSegments.length;
-  if (wildcardName) {
-    if (requestSegments.length < prefixLength)
-      return null;
-  } else if (patternSegments.length !== requestSegments.length) {
-    return null;
+function parsePartHeaders(bytes) {
+  let text;
+  try {
+    text = decoder.decode(bytes);
+  } catch {
+    badRequest("Invalid multipart headers");
   }
-  const params = {};
-  for (const [i, pattern] of patternSegments.slice(0, prefixLength).entries()) {
-    const actual = requestSegments[i];
-    if (actual === undefined)
-      return null;
-    if (pattern.startsWith(":")) {
-      params[pattern.slice(1)] = decodeURIComponent(actual);
-    } else if (pattern !== actual) {
-      return null;
-    }
+  const headers = new Headers;
+  for (const line of text.split(`\r
+`)) {
+    const separator = line.indexOf(":");
+    if (separator <= 0)
+      badRequest("Invalid multipart header");
+    headers.append(line.slice(0, separator).trim(), line.slice(separator + 1).trim());
   }
-  if (wildcardName) {
-    params[wildcardName] = requestSegments.slice(prefixLength).map(decodeURIComponent).join("/");
+  const disposition = parseDisposition(headers.get("content-disposition") ?? undefined);
+  const rawContentType = headers.get("content-type");
+  const contentType = rawContentType?.split(";", 1)[0]?.trim().toLowerCase();
+  const rawSize = headers.get("content-length");
+  const declaredSize = rawSize === null ? undefined : Number(rawSize);
+  if (declaredSize !== undefined && (!Number.isSafeInteger(declaredSize) || declaredSize < 0)) {
+    badRequest("Invalid multipart part content-length");
   }
-  return params;
-}
-function segmentRank(segment) {
-  if (segment?.startsWith("*"))
-    return 2;
-  if (segment?.startsWith(":"))
-    return 1;
-  return 0;
+  return { ...disposition, contentType, declaredSize };
 }
-function buildRouteMap(groups) {
-  const map = new Map;
-  for (const { prefix, service, hooks } of groups) {
-    for (const [, method] of Object.entries(service.methods)) {
-      if (method.expose && !method.expose.includes("HTTP"))
-        continue;
-      const servicePath = joinPath("/", service.prefix, method.path === "/" ? "" : method.path);
-      const fullPath = prefix ? joinPath(prefix, servicePath) : servicePath;
-      const segments = fullPath.split("/").filter(Boolean);
-      const entries = map.get(method.method) ?? [];
-      entries.push({ method, pattern: fullPath, segments, groupHooks: hooks });
-      map.set(method.method, entries);
+
+class MultipartStreamReader {
+  #reader;
+  #delimiter;
+  #initialBoundary;
+  #maxRequestBytes;
+  #buffer = new Uint8Array;
+  #readBytes = 0;
+  #sourceDone = false;
+  #terminal = false;
+  #activePart = false;
+  constructor(req, boundary, maxRequestBytes) {
+    if (!req.body)
+      badRequest("Multipart request body is empty");
+    this.#reader = req.body.getReader();
+    this.#delimiter = encoder.encode(`\r
+--${boundary}`);
+    this.#initialBoundary = encoder.encode(`--${boundary}`);
+    this.#maxRequestBytes = maxRequestBytes;
+  }
+  async start() {
+    await this.#ensure(this.#initialBoundary.length + 2);
+    if (!startsWithBytes(this.#buffer, this.#initialBoundary)) {
+      badRequest("Malformed multipart body");
     }
+    this.#consume(this.#initialBoundary.length);
+    await this.#consumeBoundarySuffix();
   }
-  for (const [, entries] of map) {
-    entries.sort((a, b) => {
-      const len = Math.min(a.segments.length, b.segments.length);
-      for (let i = 0;i < len; i++) {
-        const rankDifference = segmentRank(a.segments[i]) - segmentRank(b.segments[i]);
-        if (rankDifference !== 0)
-          return rankDifference;
+  async nextPart() {
+    if (this.#activePart)
+      badRequest("Multipart part stream was not fully consumed");
+    if (this.#terminal)
+      return null;
+    const header = await this.#readUntil(HEADER_END, DEFAULT_MAX_HEADER_BYTES);
+    const parsed = parsePartHeaders(header);
+    this.#activePart = true;
+    let ended = false;
+    const stream = new ReadableStream({
+      pull: async (controller) => {
+        if (ended) {
+          controller.close();
+          return;
+        }
+        try {
+          const chunk = await this.#readPartChunk();
+          if (chunk.value.length > 0)
+            controller.enqueue(chunk.value);
+          if (chunk.end) {
+            ended = true;
+            controller.close();
+          }
+        } catch (error) {
+          controller.error(error);
+          this.cancel(error);
+        }
+      },
+      cancel: (reason) => {
+        this.cancel(reason);
       }
-      return a.segments.length - b.segments.length;
     });
+    return { ...parsed, stream, consumed: () => ended };
   }
-  return map;
-}
-function matchRoute(routeMap, httpMethod, pathname) {
-  const entries = routeMap.get(httpMethod);
-  if (!entries)
-    return null;
-  const requestSegments = pathname.split("/").filter(Boolean);
-  for (const entry of entries) {
-    const pathParams = matchSegments(entry.segments, requestSegments);
-    if (pathParams) {
-      return {
-        method: entry.method,
-        pathParams,
-        groupHooks: entry.groupHooks
-      };
-    }
+  cancel(reason) {
+    this.#reader.cancel(reason).catch(() => {});
   }
-  return null;
-}
-function allowedMethods(routeMap, pathname) {
-  const requestSegments = pathname.split("/").filter(Boolean);
-  const methods = [];
-  for (const [method, entries] of routeMap) {
-    for (const entry of entries) {
-      if (matchSegments(entry.segments, requestSegments)) {
-        methods.push(method);
-        break;
+  release() {
+    this.#reader.releaseLock();
+  }
+  async#readPartChunk() {
+    while (true) {
+      const boundaryIndex = indexOfBytes(this.#buffer, this.#delimiter);
+      if (boundaryIndex >= 0) {
+        const value = this.#buffer.slice(0, boundaryIndex);
+        this.#consume(boundaryIndex + this.#delimiter.length);
+        await this.#consumeBoundarySuffix();
+        this.#activePart = false;
+        return { value, end: true };
+      }
+      const retained = this.#delimiter.length - 1;
+      if (this.#buffer.length > retained) {
+        const emitLength = this.#buffer.length - retained;
+        const value = this.#buffer.slice(0, emitLength);
+        this.#consume(emitLength);
+        return { value, end: false };
       }
+      if (this.#sourceDone)
+        badRequest("Incomplete multipart body");
+      await this.#readMore();
     }
   }
-  return methods;
-}
-function validateRoutes(routeMap) {
-  for (const [method, entries] of routeMap) {
-    const seen = new Map;
-    for (const entry of entries) {
-      parseTrailingWildcard(entry.pattern);
-      const normalized = entry.segments.map((s) => s.startsWith(":") ? ":param" : s.startsWith("*") ? "*wildcard" : s).join("/");
-      const key = `${method} /${normalized}`;
-      const existing = seen.get(key);
-      if (existing) {
-        throw new Error(`Duplicate route: ${method} ${entry.pattern} conflicts with ${existing}`);
+  async#consumeBoundarySuffix() {
+    await this.#ensure(2);
+    if (this.#buffer[0] === 45 && this.#buffer[1] === 45) {
+      this.#consume(2);
+      this.#terminal = true;
+      if (startsWithBytes(this.#buffer, CRLF))
+        this.#consume(2);
+      return;
+    }
+    if (!startsWithBytes(this.#buffer, CRLF))
+      badRequest("Malformed multipart boundary");
+    this.#consume(2);
+  }
+  async#readUntil(marker, maxBytes) {
+    while (true) {
+      const index = indexOfBytes(this.#buffer, marker);
+      if (index >= 0) {
+        if (index > maxBytes)
+          badRequest("Multipart part headers are too large");
+        const value = this.#buffer.slice(0, index);
+        this.#consume(index + marker.length);
+        return value;
       }
-      seen.set(key, entry.pattern);
+      if (this.#buffer.length > maxBytes)
+        badRequest("Multipart part headers are too large");
+      if (this.#sourceDone)
+        badRequest("Incomplete multipart headers");
+      await this.#readMore();
     }
   }
-}
-function findShadowedRoutes(routeMap, rawRoutes) {
-  if (!rawRoutes || rawRoutes.length === 0)
-    return [];
-  const shadowed = [];
-  for (const [httpMethod, entries] of routeMap) {
-    for (const entry of entries) {
-      const probe = `/${entry.segments.map((segment) => {
-        if (segment.startsWith(":"))
-          return "__param__";
-        if (segment.startsWith("*"))
-          return "__wildcard__";
-        return segment;
-      }).join("/")}`;
-      const match = matchRawRoute(rawRoutes, httpMethod, probe);
-      if (!match)
-        continue;
-      shadowed.push({
-        pattern: `${httpMethod} ${entry.pattern}`,
-        endpoint: `${entry.method.serviceName}.${entry.method.key}`,
-        rawRoute: `${match.route.method} ${match.route.path}`,
-        scope: entry.method.scope
-      });
+  async#ensure(length) {
+    while (this.#buffer.length < length && !this.#sourceDone)
+      await this.#readMore();
+    if (this.#buffer.length < length)
+      badRequest("Incomplete multipart body");
+  }
+  async#readMore() {
+    const result = await this.#reader.read();
+    if (result.done) {
+      this.#sourceDone = true;
+      return;
     }
+    this.#readBytes += result.value.length;
+    if (this.#readBytes > this.#maxRequestBytes) {
+      this.cancel();
+      badRequest(`Multipart request exceeds ${this.#maxRequestBytes} bytes`);
+    }
+    this.#buffer = concatBytes(this.#buffer, result.value);
+  }
+  #consume(length) {
+    this.#buffer = this.#buffer.slice(length);
   }
-  return shadowed;
 }
-function matchRawRoute(rawRoutes, httpMethod, pathname) {
-  for (const route of rawRoutes) {
-    if (route.method !== "ALL" && route.method !== httpMethod)
-      continue;
-    if (parseTrailingWildcard(route.path)) {
-      const routeSegs = route.path.split("/").filter(Boolean);
-      const pathSegs = pathname.split("/").filter(Boolean);
-      const params = matchSegments(routeSegs, pathSegs);
-      if (params)
-        return { route, params };
-      continue;
+function matchesContentType(contentType, accepted) {
+  const normalized = contentType.toLowerCase();
+  return accepted.some((candidate) => {
+    const policy = candidate.toLowerCase();
+    return policy.endsWith("/*") ? normalized.startsWith(policy.slice(0, -1)) : normalized === policy;
+  });
+}
+function limitedStream(stream, maxBytes, label, signal) {
+  const reader = stream.getReader();
+  let total = 0;
+  const cancelReader = (reason) => {
+    reader.cancel(reason).catch(() => {});
+  };
+  return new ReadableStream({
+    async pull(controller) {
+      if (signal.aborted) {
+        cancelReader(signal.reason);
+        controller.error(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        return;
+      }
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          controller.close();
+          reader.releaseLock();
+          return;
+        }
+        total += result.value.length;
+        if (total > maxBytes) {
+          cancelReader();
+          badRequest(`${label} exceeds ${maxBytes} bytes`);
+        }
+        controller.enqueue(result.value);
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      cancelReader(reason);
     }
-    if (route.path.includes("/:")) {
-      const routeSegs = route.path.split("/").filter(Boolean);
-      const pathSegs = pathname.split("/").filter(Boolean);
-      const params = matchSegments(routeSegs, pathSegs);
-      if (params)
-        return { route, params };
-      continue;
+  });
+}
+async function collectFile(part, stream) {
+  const chunks = [];
+  const reader = stream.getReader();
+  while (true) {
+    const result = await reader.read();
+    if (result.done)
+      break;
+    chunks.push(Uint8Array.from(result.value).buffer);
+  }
+  return new File(chunks, part.filename ?? "upload", {
+    type: part.contentType ?? "application/octet-stream"
+  });
+}
+async function readText(stream, maxBytes) {
+  const chunks = [];
+  const reader = stream.getReader();
+  let total = 0;
+  while (true) {
+    const result = await reader.read();
+    if (result.done)
+      break;
+    total += result.value.length;
+    if (total > maxBytes) {
+      await reader.cancel();
+      badRequest(`Multipart text field exceeds ${maxBytes} bytes`);
     }
-    if (route.path === pathname)
-      return { route, params: {} };
+    chunks.push(result.value);
   }
-  return null;
+  const value = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    value.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return decoder.decode(value);
 }
-function validateRawRoutes(rawRoutes) {
-  for (const route of rawRoutes ?? [])
-    parseTrailingWildcard(route.path);
+function required(policy) {
+  return policy.required !== false;
 }
-function staticRoute(prefix, dir) {
-  const cleanPrefix = prefix.replace(/\/+$/, "");
-  const root = resolve(dir.replace(/\/+$/, ""));
-  return {
-    method: "GET",
-    path: `${cleanPrefix}/*filePath`,
-    handler: async (req) => {
-      const pathname = new URL(req.url).pathname;
-      let rel;
+async function parseMultipart(req, descriptor, fieldsSchema, receivers) {
+  const maxRequestBytes = descriptor.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES;
+  const contentLength = Number(req.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > maxRequestBytes) {
+    badRequest(`Multipart request exceeds ${maxRequestBytes} bytes`);
+  }
+  const boundary = parseBoundary(req);
+  const parser = new MultipartStreamReader(req, boundary, maxRequestBytes);
+  const fields = {};
+  const files = {};
+  const counts = new Map;
+  const cleanups = [];
+  let rolledBack = false;
+  const rollback = async () => {
+    if (rolledBack)
+      return;
+    rolledBack = true;
+    for (let index = cleanups.length - 1;index >= 0; index -= 1) {
       try {
-        rel = decodeURIComponent(pathname.slice(cleanPrefix.length)).replace(/^\/+/, "");
-      } catch {
-        return new Response("Bad request", { status: 400 });
+        await cleanups[index]?.();
+      } catch (error) {
+        console.error("[stitchkit] multipart receiver cleanup failed", error);
+      }
+    }
+  };
+  try {
+    await parser.start();
+    let partCount = 0;
+    while (true) {
+      const part = await parser.nextPart();
+      if (!part)
+        break;
+      partCount += 1;
+      if (partCount > DEFAULT_MAX_PARTS)
+        badRequest("Too many multipart parts");
+      const policy = descriptor.files[part.name];
+      const isFile = part.filename !== undefined || part.contentType !== undefined;
+      if (!isFile) {
+        if (policy)
+          badRequest(`Multipart file field "${part.name}" must contain a file`);
+        if (Object.hasOwn(fields, part.name)) {
+          badRequest(`Duplicate multipart text field: ${part.name}`);
+        }
+        fields[part.name] = await readText(part.stream, descriptor.maxFieldBytes ?? DEFAULT_MAX_FIELD_BYTES);
+        continue;
       }
-      const target = resolve(root, rel);
-      if (!isWithinDir(root, target)) {
-        return new Response("Forbidden", { status: 403 });
+      if (!policy)
+        badRequest(`Unexpected multipart file field: ${part.name}`);
+      const count = (counts.get(part.name) ?? 0) + 1;
+      counts.set(part.name, count);
+      const maxFiles = policy.multiple === true ? policy.maxFiles ?? DEFAULT_MAX_PARTS : 1;
+      if (count > maxFiles)
+        badRequest(`Too many files for multipart field: ${part.name}`);
+      const contentType = part.contentType ?? "";
+      if (policy.contentTypes && !matchesContentType(contentType, policy.contentTypes)) {
+        badRequest(`Unsupported content type for multipart field "${part.name}"`);
       }
-      const info = await stat(target).catch(() => null);
-      if (!info?.isFile()) {
-        return new Response("Not found", { status: 404 });
+      const maxFileBytes = policy.maxBytes ?? maxRequestBytes;
+      if (part.declaredSize !== undefined && part.declaredSize > maxFileBytes) {
+        badRequest(`Multipart field "${part.name}" exceeds ${maxFileBytes} bytes`);
       }
-      const body = await readFile(target);
-      return new Response(body, {
-        headers: {
-          "Content-Type": mimeForPath(target),
-          "X-Content-Type-Options": "nosniff"
+      const stream = limitedStream(part.stream, maxFileBytes, `Multipart field "${part.name}"`, req.signal);
+      let value;
+      if (descriptor.delivery === "stream") {
+        const receiver = receivers?.[part.name];
+        if (!receiver)
+          badRequest(`Missing multipart receiver for field: ${part.name}`);
+        const result = await receiver({
+          metadata: {
+            field: part.name,
+            filename: part.filename ?? "upload",
+            contentType: contentType || "application/octet-stream",
+            size: part.declaredSize
+          },
+          stream,
+          signal: req.signal
+        });
+        cleanups.push(result.cleanup);
+        if (!part.consumed()) {
+          await stream.cancel();
+          badRequest(`Multipart receiver for "${part.name}" did not consume its stream`);
         }
-      });
+        value = result.value;
+      } else {
+        value = await collectFile(part, stream);
+      }
+      if (policy.multiple === true) {
+        const existing = files[part.name];
+        if (Array.isArray(existing))
+          existing.push(value);
+        else
+          files[part.name] = [value];
+      } else {
+        files[part.name] = value;
+      }
     }
-  };
+    for (const [field, policy] of Object.entries(descriptor.files)) {
+      const count = counts.get(field) ?? 0;
+      if (required(policy) && count === 0)
+        badRequest(`Missing multipart file field: ${field}`);
+      if (policy.multiple === true && count === 0 && !required(policy))
+        files[field] = [];
+    }
+    return {
+      files,
+      fields: fieldsSchema ? fieldsSchema.parse(fields) : fields,
+      rollback
+    };
+  } catch (error) {
+    parser.cancel(error);
+    await rollback();
+    throw error;
+  } finally {
+    parser.release();
+  }
 }
 
 // src/server/request-body.ts
@@ -406,17 +539,19 @@ function buildBaseContext(req, url, pathParams, traceId, clientIp) {
     ...getClientInfo(req, clientIp)
   };
 }
-async function parseRequestInto(ctx, req, url, method, maxUploadBytes, maxJsonBodyBytes) {
+function parsePathParamsInto(ctx, method) {
   if (method.paramsSchema) {
     ctx.params = method.paramsSchema.parse(ctx.params);
   }
+}
+async function parseRequestPayloadInto(ctx, req, url, method, maxJsonBodyBytes) {
   if (method.multipart) {
-    const cap = method.maxUploadBytes ?? maxUploadBytes;
-    const multipart = await parseMultipart(req, method.multipart, method.inputSchema, cap);
+    const multipart = await parseMultipart(req, method.multipart, method.inputSchema, method.multipartReceivers);
     ctx.input = multipart.fields;
-    if (multipart.file)
-      ctx.file = multipart.file;
-  } else if (method.inputSchema) {
+    ctx.files = multipart.files;
+    return multipart;
+  }
+  if (method.inputSchema) {
     if (req.method === "GET") {
       ctx.input = method.inputSchema.parse(parseQueryParams(url));
     } else if (req.method === "DELETE") {
@@ -436,6 +571,7 @@ async function parseRequestInto(ctx, req, url, method, maxUploadBytes, maxJsonBo
       ctx.input = method.inputSchema.parse(parseJsonBody(req, text));
     }
   }
+  return;
 }
 function buildErrorContext(req, url, traceId, clientIp) {
   return {
@@ -662,6 +798,172 @@ function applyResponseMetadata(target, metadata, endpointIdentity) {
   }
 }
 
+// src/server/router.ts
+function joinPath(...parts) {
+  const joined = parts.filter(Boolean).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+  return `/${joined}`;
+}
+function matchSegments(patternSegments, requestSegments) {
+  const wildcardSegment = patternSegments.at(-1);
+  const wildcardName = wildcardSegment?.startsWith("*") ? wildcardSegment.slice(1) : null;
+  const prefixLength = wildcardName ? patternSegments.length - 1 : patternSegments.length;
+  if (wildcardName) {
+    if (requestSegments.length < prefixLength)
+      return null;
+  } else if (patternSegments.length !== requestSegments.length) {
+    return null;
+  }
+  const params = {};
+  for (const [i, pattern] of patternSegments.slice(0, prefixLength).entries()) {
+    const actual = requestSegments[i];
+    if (actual === undefined)
+      return null;
+    if (pattern.startsWith(":")) {
+      params[pattern.slice(1)] = decodeURIComponent(actual);
+    } else if (pattern !== actual) {
+      return null;
+    }
+  }
+  if (wildcardName) {
+    params[wildcardName] = requestSegments.slice(prefixLength).map(decodeURIComponent).join("/");
+  }
+  return params;
+}
+function segmentRank(segment) {
+  if (segment?.startsWith("*"))
+    return 2;
+  if (segment?.startsWith(":"))
+    return 1;
+  return 0;
+}
+function buildRouteMap(groups) {
+  const map = new Map;
+  for (const { prefix, service, hooks } of groups) {
+    for (const [, method] of Object.entries(service.methods)) {
+      if (method.expose && !method.expose.includes("HTTP"))
+        continue;
+      const servicePath = joinPath("/", service.prefix, method.path === "/" ? "" : method.path);
+      const fullPath = prefix ? joinPath(prefix, servicePath) : servicePath;
+      const segments = fullPath.split("/").filter(Boolean);
+      const entries = map.get(method.method) ?? [];
+      entries.push({ method, pattern: fullPath, segments, groupHooks: hooks });
+      map.set(method.method, entries);
+    }
+  }
+  for (const [, entries] of map) {
+    entries.sort((a, b) => {
+      const len = Math.min(a.segments.length, b.segments.length);
+      for (let i = 0;i < len; i++) {
+        const rankDifference = segmentRank(a.segments[i]) - segmentRank(b.segments[i]);
+        if (rankDifference !== 0)
+          return rankDifference;
+      }
+      return a.segments.length - b.segments.length;
+    });
+  }
+  return map;
+}
+function matchRoute(routeMap, httpMethod, pathname) {
+  const entries = routeMap.get(httpMethod);
+  if (!entries)
+    return null;
+  const requestSegments = pathname.split("/").filter(Boolean);
+  for (const entry of entries) {
+    const pathParams = matchSegments(entry.segments, requestSegments);
+    if (pathParams) {
+      return {
+        method: entry.method,
+        pathParams,
+        groupHooks: entry.groupHooks
+      };
+    }
+  }
+  return null;
+}
+function allowedMethods(routeMap, pathname) {
+  const requestSegments = pathname.split("/").filter(Boolean);
+  const methods = [];
+  for (const [method, entries] of routeMap) {
+    for (const entry of entries) {
+      if (matchSegments(entry.segments, requestSegments)) {
+        methods.push(method);
+        break;
+      }
+    }
+  }
+  return methods;
+}
+function validateRoutes(routeMap) {
+  for (const [method, entries] of routeMap) {
+    const seen = new Map;
+    for (const entry of entries) {
+      parseTrailingWildcard(entry.pattern);
+      const normalized = entry.segments.map((s) => s.startsWith(":") ? ":param" : s.startsWith("*") ? "*wildcard" : s).join("/");
+      const key = `${method} /${normalized}`;
+      const existing = seen.get(key);
+      if (existing) {
+        throw new Error(`Duplicate route: ${method} ${entry.pattern} conflicts with ${existing}`);
+      }
+      seen.set(key, entry.pattern);
+    }
+  }
+}
+function findShadowedRoutes(routeMap, rawRoutes) {
+  if (!rawRoutes || rawRoutes.length === 0)
+    return [];
+  const shadowed = [];
+  for (const [httpMethod, entries] of routeMap) {
+    for (const entry of entries) {
+      const probe = `/${entry.segments.map((segment) => {
+        if (segment.startsWith(":"))
+          return "__param__";
+        if (segment.startsWith("*"))
+          return "__wildcard__";
+        return segment;
+      }).join("/")}`;
+      const match = matchRawRoute(rawRoutes, httpMethod, probe);
+      if (!match)
+        continue;
+      shadowed.push({
+        pattern: `${httpMethod} ${entry.pattern}`,
+        endpoint: `${entry.method.serviceName}.${entry.method.key}`,
+        rawRoute: `${match.route.method} ${match.route.path}`,
+        scope: entry.method.scope
+      });
+    }
+  }
+  return shadowed;
+}
+function matchRawRoute(rawRoutes, httpMethod, pathname) {
+  for (const route of rawRoutes) {
+    if (route.method !== "ALL" && route.method !== httpMethod)
+      continue;
+    if (parseTrailingWildcard(route.path)) {
+      const routeSegs = route.path.split("/").filter(Boolean);
+      const pathSegs = pathname.split("/").filter(Boolean);
+      const params = matchSegments(routeSegs, pathSegs);
+      if (params)
+        return { route, params };
+      continue;
+    }
+    if (route.path.includes("/:")) {
+      const routeSegs = route.path.split("/").filter(Boolean);
+      const pathSegs = pathname.split("/").filter(Boolean);
+      const params = matchSegments(routeSegs, pathSegs);
+      if (params)
+        return { route, params };
+      continue;
+    }
+    if (route.path === pathname)
+      return { route, params: {} };
+  }
+  return null;
+}
+function validateRawRoutes(rawRoutes) {
+  for (const route of rawRoutes ?? [])
+    parseTrailingWildcard(route.path);
+}
+
 // src/server/create.ts
 var BODY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function createHandler(config) {
@@ -854,8 +1156,16 @@ function createHandler(config) {
     const { method, pathParams, groupHooks } = match;
     const ctx = buildBaseContext(req, url, pathParams, traceId, clientIp);
     setRequestEndpoint(method.serviceName, method.key);
+    let multipartLifecycle;
     try {
-      await parseRequestInto(ctx, req, url, method, config.maxUploadBytes, config.maxJsonBodyBytes);
+      parsePathParamsInto(ctx, method);
+      if (hooks?.authorize) {
+        await hooks.authorize(ctx, method);
+      }
+      if (groupHooks?.authorize) {
+        await groupHooks.authorize(ctx, method);
+      }
+      multipartLifecycle = await parseRequestPayloadInto(ctx, req, url, method, config.maxJsonBodyBytes);
       if (hooks?.beforeHandle) {
         await hooks.beforeHandle(ctx, method);
       }
@@ -914,6 +1224,7 @@ function createHandler(config) {
       complete(responseStatus);
       return body;
     } catch (err) {
+      await multipartLifecycle?.rollback();
       return respondError(err, ctx, method);
     }
   }
@@ -1012,12 +1323,42 @@ function json(data, status, cors, req) {
 }
 
 // src/server/implement.ts
+function isStreamingImplementation(value) {
+  return typeof value === "object" && value !== null && "kind" in value && value.kind === "stitchkit.multipart.stream";
+}
+function defineMultipartStream(endpoint, config) {
+  const receivers = {};
+  for (const [key, receiver] of typedEntries(config.files)) {
+    receivers[String(key)] = receiver;
+  }
+  const declared = Object.keys(endpoint.multipart.files);
+  const configured = Object.keys(receivers);
+  if (declared.length !== configured.length || declared.some((field) => !Object.hasOwn(receivers, field))) {
+    throw new Error("Streaming multipart receivers must exactly match declared file fields");
+  }
+  return {
+    kind: "stitchkit.multipart.stream",
+    receivers,
+    execute(ctx, files) {
+      return callRuntimeHandler(config.handler, { ...ctx, files });
+    }
+  };
+}
 var HTTP_ONLY = Object.freeze(["HTTP"]);
 function implement(contract, handlers) {
   const methods = {};
   const groupScope = contract.meta.scope ?? "public";
   for (const [key, endpoint] of typedEntries(contract.endpoints)) {
     const typedHandler = handlers[key];
+    const isStreaming = endpoint.multipart?.delivery === "stream";
+    if (!isStreaming && typeof typedHandler !== "function") {
+      throw new Error(`[stitchkit] implement: missing handler for "${contract.meta.prefix}.${String(key)}"`);
+    }
+    if (isStreaming && !isStreamingImplementation(typedHandler)) {
+      throw new Error(`[stitchkit] implement: streaming multipart endpoint "${contract.meta.prefix}.${String(key)}" must use defineMultipartStream()`);
+    }
+    const streamingHandler = isStreamingImplementation(typedHandler) ? typedHandler : undefined;
+    const regularHandler = typeof typedHandler === "function" ? typedHandler : undefined;
     methods[String(key)] = {
       method: endpoint.method,
       path: endpoint.path,
@@ -1031,7 +1372,7 @@ function implement(contract, handlers) {
       inputSchema: endpoint.input,
       outputSchema: endpoint.output,
       multipart: endpoint.multipart,
-      maxUploadBytes: endpoint.maxUploadBytes,
+      multipartReceivers: streamingHandler?.receivers,
       maxJsonBodyBytes: endpoint.maxJsonBodyBytes,
       idempotent: endpoint.idempotent,
       ui: "ui" in endpoint ? endpoint.ui : undefined,
@@ -1042,7 +1383,12 @@ function implement(contract, handlers) {
       rawBody: endpoint.rawBody,
       responseMeta: endpoint.responseMeta,
       contentType: "contentType" in endpoint ? endpoint.contentType : undefined,
-      handler: (ctx) => typedHandler(ctx)
+      handler: streamingHandler ? (ctx) => streamingHandler.execute(ctx, ctx.files ?? {}) : (ctx) => {
+        if (!regularHandler) {
+          throw new Error(`[stitchkit] implement: missing handler for "${contract.meta.prefix}.${String(key)}"`);
+        }
+        return callRuntimeHandler(regularHandler, ctx);
+      }
     };
   }
   return {
@@ -1056,9 +1402,25 @@ function createImplement() {
   return (contract, handlers) => implement(contract, handlers);
 }
 
-// src/realtime/socket.ts
+// src/realtime/rejection.ts
 import { z } from "zod";
-var AcknowledgementCallbackSchema = z.function();
+function realtimeContractViolation(options) {
+  const issues = options.cause instanceof z.ZodError ? zodIssues(options.cause) : undefined;
+  const reason = options.reason.replaceAll("-", " ");
+  const error = new AppError("REALTIME_CONTRACT_VIOLATION", `Realtime event "${options.event}" (${options.direction}, ${options.phase}): ${reason}`, 500, {
+    event: options.event,
+    direction: options.direction,
+    phase: options.phase,
+    reason: options.reason,
+    fault: options.fault,
+    ...issues !== undefined && { issues }
+  });
+  if (options.cause !== undefined)
+    error.cause = options.cause;
+  return { ...options, error };
+}
+
+// src/realtime/socket.ts
 function method(target, name) {
   const value = Reflect.get(target, name);
   if (typeof value !== "function") {
@@ -1077,15 +1439,26 @@ function splitWireArguments(definition, args) {
     acknowledgement: (...callbackArgs) => Reflect.apply(acknowledgement, undefined, callbackArgs)
   };
 }
-function eventDefinition(registry, event) {
+function eventDefinition(registry, event, direction) {
   const definition = registry[event];
-  if (!definition)
-    throw new Error(`Unknown realtime event "${event}"`);
+  if (!definition) {
+    throw realtimeContractViolation({
+      event,
+      direction,
+      phase: "arguments",
+      reason: "unknown-event",
+      fault: "local"
+    }).error;
+  }
   return definition;
 }
-function reportRejected(rejected, hook) {
+function reportRejected(rejected, hook, logger) {
   if (!hook) {
-    console.error(`[stitchkit] rejected realtime ${rejected.direction} event "${rejected.event}" (${rejected.phase})`, rejected.error);
+    if (logger) {
+      logger.warn(rejected.error.message, rejected.error.details);
+      return;
+    }
+    console.warn(`[stitchkit] rejected realtime ${rejected.direction} event "${rejected.event}" (${rejected.phase})`, rejected.error);
     return;
   }
   Promise.resolve(hook(rejected)).catch((error) => {
@@ -1099,36 +1472,35 @@ function createValidatedRealtimeSocket({
   inboundDirection,
   outboundDirection,
   onRejected,
+  logger,
   subscribe
 }) {
-  const onTarget = method(target, "on");
-  const offTarget = subscribe ? undefined : method(target, "off");
   const emitTarget = method(target, "emit");
   return {
     on: (event, handler) => {
-      const definition = eventDefinition(inbound, event);
+      const definition = eventDefinition(inbound, event, inboundDirection);
       const wrapped = (...wireArgs) => {
         const { values, acknowledgement } = splitWireArguments(definition, wireArgs);
         const parsed = definition.args.safeParse(values);
         if (!parsed.success) {
-          reportRejected({
+          reportRejected(realtimeContractViolation({
             event,
             direction: inboundDirection,
             phase: "arguments",
-            error: parsed.error
-          }, onRejected);
+            reason: "invalid-arguments",
+            fault: "peer",
+            cause: parsed.error
+          }), onRejected, logger);
           return;
         }
         if (definition.ack && !acknowledgement) {
-          const callback = AcknowledgementCallbackSchema.safeParse(undefined);
-          if (!callback.success) {
-            reportRejected({
-              event,
-              direction: inboundDirection,
-              phase: "acknowledgement",
-              error: callback.error
-            }, onRejected);
-          }
+          reportRejected(realtimeContractViolation({
+            event,
+            direction: inboundDirection,
+            phase: "acknowledgement",
+            reason: "missing-acknowledgement",
+            fault: "peer"
+          }), onRejected, logger);
           return;
         }
         const applicationArgs = [...parsed.data];
@@ -1137,12 +1509,14 @@ function createValidatedRealtimeSocket({
             const ack = definition.ack?.safeParse(value);
             if (!ack?.success) {
               if (ack) {
-                reportRejected({
+                reportRejected(realtimeContractViolation({
                   event,
                   direction: outboundDirection,
                   phase: "acknowledgement",
-                  error: ack.error
-                }, onRejected);
+                  reason: "invalid-acknowledgement-value",
+                  fault: "local",
+                  cause: ack.error
+                }), onRejected, logger);
               }
               return;
             }
@@ -1153,30 +1527,50 @@ function createValidatedRealtimeSocket({
       };
       if (subscribe)
         return subscribe(event, wrapped);
+      const onTarget = method(target, "on");
+      const offTarget = method(target, "off");
       onTarget(event, wrapped);
       return () => {
-        offTarget?.(event, wrapped);
+        offTarget(event, wrapped);
       };
     },
     emit: (event, ...args) => {
-      const definition = eventDefinition(outbound, event);
+      const definition = eventDefinition(outbound, event, outboundDirection);
       const { values, acknowledgement } = splitWireArguments(definition, args);
-      const parsed = definition.args.parse(values);
+      const parsed = definition.args.safeParse(values);
+      if (!parsed.success) {
+        throw realtimeContractViolation({
+          event,
+          direction: outboundDirection,
+          phase: "arguments",
+          reason: "invalid-arguments",
+          fault: "local",
+          cause: parsed.error
+        }).error;
+      }
       if (definition.ack && !acknowledgement) {
-        AcknowledgementCallbackSchema.parse(undefined);
+        throw realtimeContractViolation({
+          event,
+          direction: outboundDirection,
+          phase: "acknowledgement",
+          reason: "missing-acknowledgement",
+          fault: "local"
+        }).error;
       }
-      const wireArgs = [...parsed];
+      const wireArgs = [...parsed.data];
       if (definition.ack && acknowledgement) {
         wireArgs.push((value) => {
           const ack = definition.ack?.safeParse(value);
           if (!ack?.success) {
             if (ack) {
-              reportRejected({
+              reportRejected(realtimeContractViolation({
                 event,
                 direction: inboundDirection,
                 phase: "acknowledgement",
-                error: ack.error
-              }, onRejected);
+                reason: "invalid-acknowledgement-value",
+                fault: "peer",
+                cause: ack.error
+              }), onRejected, logger);
             }
             return;
           }
@@ -1196,7 +1590,8 @@ function bindRealtimeServer(contract, handle, options = {}) {
     outbound: contract.serverToClient,
     inboundDirection: "server-inbound",
     outboundDirection: "server-outbound",
-    onRejected: options.onRejected
+    onRejected: options.onRejected,
+    logger: options.logger
   });
   const broadcast = outbound(handle.io);
   return {
@@ -1208,7 +1603,8 @@ function bindRealtimeServer(contract, handle, options = {}) {
           outbound: contract.serverToClient,
           inboundDirection: "server-inbound",
           outboundDirection: "server-outbound",
-          onRejected: options.onRejected
+          onRejected: options.onRejected,
+          logger: options.logger
         });
         handler({
           raw,
@@ -1372,4 +1768,4 @@ function socketIoLane(websocket) {
   });
 }
 
-export { parseMultipart, mimeForPath, staticRoute, createHandler, implement, createImplement, bindRealtimeServer, webSocketLane, composeWebSocketHandlers, createSocketIOServer, socketIoLane };
+export { parseMultipart, createHandler, defineMultipartStream, implement, createImplement, bindRealtimeServer, webSocketLane, composeWebSocketHandlers, createSocketIOServer, socketIoLane };