@velarscript/node 0.12.0 → 0.13.0

package/dist/serve-runtime.js

@@ -1,3 +1,4 @@
+import { ROUTE_SHAPE_FROM_SEGMENTS_SOURCE } from "./route-shape.js";
 // Application-facing velar/serve contract. HTTP sockets, request streams,
 // backpressure and static-file effects live in the shared isolated Node host;
 // this Realm owns only Velar values, handlers and strict JSON/type boundaries.
@@ -6,7 +7,7 @@ import { __velarNodeHostInvoke, __velarNodeHostOn } from "velar/node-host-v1";
 import { normalizeError as __velarServeNormalizeError } from "velar/compiler-runtime-errors-v1";
 import { __velarValidateDenseList as __velarServeValidateDenseList } from "velar/compiler-runtime-collection-lowering-v1";
 import { Bytes as __velarServeBytesType } from "velar/binary";
-import { writeBytes as __velarServeWriteBytes } from "velar/fs";
+import { canonical as __velarServeFsCanonical, info as __velarServeFsInfo, writeBytes as __velarServeWriteBytes } from "velar/fs";
 import { Cancellation as __velarServeCancellation } from "velar/task";
 
 const __velarServeArray = globalThis.Array;
@@ -114,6 +115,7 @@ const __velarServeDefaultShutdownGrace = 30_000;
 const __velarServeFileMarker = Symbol("velar.serve.file-response");
 const __velarServeAppMarker = Symbol("velar.serve.app");
 const __velarServeRouteMarker = Symbol("velar.serve.route");
+const __velarServeNotFoundMarker = Symbol("velar.serve.not-found");
 const __velarServeInputMarker = Symbol("velar.serve.input");
 const __velarServeProviderMarker = Symbol("velar.serve.provider");
 const __velarServeUploadMarker = Symbol("velar.serve.upload");
@@ -185,9 +187,8 @@ function __velarServeIsSafeInteger(value) {
 }
 
 function __velarServeReserveOutbound(bytes) {
-  if (!__velarServeIsSafeInteger(bytes) || bytes < 0 || __velarServeOutboundBytes + bytes > __velarServeMaxOutboundBytes) {
-    throw new __velarServeRangeError("ServeResponse aggregate outbound byte budget is exhausted");
-  }
+  if (!__velarServeIsSafeInteger(bytes) || bytes < 0) throw new __velarServeRangeError("ServeResponse outbound byte reservation must be a non-negative integer");
+  if (__velarServeOutboundBytes + bytes > __velarServeMaxOutboundBytes) throw new __velarServeOutboundBudgetError();
   __velarServeOutboundBytes += bytes;
 }
 
@@ -429,6 +430,19 @@ export class HttpError extends __velarServeError {
   }
 }
 
+// Exhausting the aggregate outbound budget is a temporary load condition, not a
+// server fault: 503 with retry-after is what a load balancer and a client both
+// know how to act on, and 500 is what neither can. Most reserves happen while a
+// response is already on its way out, past the HttpError catch in
+// __velarServeHandleRequest, so both send paths recognize this one error by
+// identity and answer it themselves. The shed answer reserves nothing: it is a
+// fixed, tiny payload, and reserving for it would fail by construction.
+class __velarServeOutboundBudgetError extends HttpError {
+  constructor() {
+    super(503, {error: "outbound_budget_exhausted"}, new __velarServeMap([["retry-after", "1"]]));
+  }
+}
+
 function __velarServeIsFileResponse(value) {
   if (!value || typeof value !== "object") return false;
   const descriptor = __velarServeOwnDescriptor(value, __velarServeFileMarker);
@@ -581,7 +595,7 @@ export const ServeApp = __velarServeTypeObject(
   value => __velarServeIsApp(value),
   "ServeApp values are declared with 'server name:' or built by velar/serve composition functions",
   null,
-  __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{createApp: __velarCreateServeApp, createRoute: __velarCreateServeRoute, testClient: __velarServeTestClient, nativeApp: __velarServeNativeApp}]),
+  __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{createApp: __velarCreateServeApp, createRoute: __velarCreateServeRoute, createNotFound: __velarCreateServeNotFound, testClient: __velarServeTestClient, nativeApp: __velarServeNativeApp}]),
 );
 export const Server = __velarServeTypeObject(value => {
   try {
@@ -599,6 +613,74 @@ function __velarServeIsUpload(value) {
 
 export const Upload = __velarServeTypeObject(__velarServeIsUpload, "Upload values are created from multipart route inputs");
 
+// Upload.save takes its containment root as a required argument and refuses any
+// target that resolves outside it. The host operations bag __velarServeNativeFile
+// uses for static files is not reachable from this Realm, so containment is
+// composed from velar/fs instead of a new host operation: fail-closed textual
+// rules on the caller's path, then a canonical check of the directory that will
+// hold the file so a symbolic link cannot lead out of the root. That is the
+// smaller of the two shapes and adds no trust boundary. This is complementary to
+// the basename reduction in __velarServeUploadBasename, which bounds only what a
+// client can put into Upload.filename.
+function __velarServeUploadSegments(path) {
+  if (typeof path !== "string" || path.length === 0) throw new __velarServeTypeError("Upload.save path must be a non-empty path relative to its root");
+  if (path.length > __velarServeMaxPathCodeUnits || __velarServeCall(__velarServeStringIncludes, path, ["\0"])) {
+    throw new __velarServeRangeError("Upload.save path is outside the supported bounds");
+  }
+  // The root's separator is a host detail this Realm cannot consult, so both
+  // separators are refused, exactly as __velarServeNativeEscapes refuses both.
+  // Only '..' and an absolute path genuinely leave the root; a backslash, an
+  // empty segment and a '.' are refused because this Realm will not normalize a
+  // path on the caller's behalf, so each refusal says which of the two it is
+  // rather than naming an escape that did not happen.
+  if (__velarServeCall(__velarServeStringIncludes, path, ["\\"])) throw new __velarServeError("Upload.save path cannot contain a backslash: it is a path separator on some hosts");
+  if (__velarServeCall(__velarServeStringStartsWith, path, ["/"])) throw new __velarServeError("Upload.save path escapes its root: it is absolute");
+  const segments = __velarServeCall(__velarServeStringSplit, path, ["/"]);
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = segments[index];
+    if (segment === "..") throw new __velarServeError("Upload.save path escapes its root: it has a '..' segment");
+    if (segment === "") throw new __velarServeError("Upload.save path must be normalized: it has an empty segment");
+    if (segment === ".") throw new __velarServeError("Upload.save path must be normalized: it has a '.' segment");
+  }
+  return segments;
+}
+
+function __velarServeUploadContains(root, target) {
+  if (target === root) return true;
+  if (target.length <= root.length || __velarServeCall(__velarServeStringSlice, target, [0, root.length]) !== root) return false;
+  const boundary = __velarServeCall(__velarServeStringSlice, target, [root.length, root.length + 1]);
+  return boundary === "/" || boundary === "\\";
+}
+
+async function __velarServeUploadTarget(path, root) {
+  const segments = __velarServeUploadSegments(path);
+  if (typeof root !== "string" || root.length === 0) throw new __velarServeTypeError("Upload.save root must be a non-empty directory path");
+  // Resolution failures arrive from the host as an errno naming an absolute path
+  // the caller never wrote, so both are answered in the caller's own terms: the
+  // root it named, or the relative directory it asked for.
+  let base;
+  try { base = await __velarServeFsCanonical(root); }
+  catch { throw new __velarServeError("Upload.save root does not resolve to an existing directory"); }
+  let directory = base;
+  let relative = "";
+  for (let index = 0; index + 1 < segments.length; index += 1) {
+    directory += "/" + segments[index];
+    relative += relative === "" ? segments[index] : "/" + segments[index];
+  }
+  if (directory !== base) {
+    try { directory = await __velarServeFsCanonical(directory); }
+    catch { throw new __velarServeError("Upload.save path names a directory that does not exist under the root: " + relative); }
+    if (!__velarServeUploadContains(base, directory)) throw new __velarServeError("Upload.save path escapes its root through a symbolic link");
+  }
+  const target = directory + "/" + segments[segments.length - 1];
+  // A write follows a symbolic link at the target itself, so the last segment is
+  // canonicalized by kind rather than by path: refusing the link is fail-closed
+  // and needs no second containment test.
+  const existing = await __velarServeFsInfo(target);
+  if (existing !== null && existing.kind === "symlink") throw new __velarServeError("Upload.save refuses to write through a symbolic link");
+  return target;
+}
+
 function __velarServeUploadValue(name, filename, contentType, data, states) {
   if (!__velarServeBytesType.is(data)) throw new __velarServeTypeError("Upload data must be Bytes");
   const state = {data};
@@ -619,7 +701,11 @@ function __velarServeUploadValue(name, filename, contentType, data, states) {
       catch { throw new __velarServeTypeError("Upload is not valid UTF-8 text"); }
     },
     bytes: async () => __velarServeBytesType.parse(current()),
-    save: async path => { await __velarServeWriteBytes(path, current()); return null; },
+    save: async (path, root) => {
+      const value = current();
+      await __velarServeWriteBytes(await __velarServeUploadTarget(path, root), value);
+      return null;
+    },
   }]);
 }
 
@@ -897,6 +983,12 @@ function __velarServeIsRoute(value) {
   return descriptor?.enumerable === true && "value" in descriptor && descriptor.value === true;
 }
 
+function __velarServeIsNotFound(value) {
+  if (!value || typeof value !== "object") return false;
+  const descriptor = __velarServeOwnDescriptor(value, __velarServeNotFoundMarker);
+  return descriptor?.enumerable === true && "value" in descriptor && descriptor.value === true;
+}
+
 function __velarServeIsApp(value) {
   if (!value || typeof value !== "object") return false;
   const descriptor = __velarServeOwnDescriptor(value, __velarServeAppMarker);
@@ -922,12 +1014,13 @@ function __velarServeRoutePath(path, name = "Route path") {
   return path;
 }
 
+// D90 R19(c): the shape rule is written once, in route-shape.ts, and this
+// module interpolates that one definition. The shared core touches only
+// indexed access and .length, so it stays sound inside this hardened Realm;
+// the split it never performs itself happens here with the captured split.
+const __velarServeRouteShapeFromSegments = ${ROUTE_SHAPE_FROM_SEGMENTS_SOURCE};
 function __velarServeRouteShape(path) {
-  const segments = __velarServeCall(__velarServeStringSplit, path, ["/"]);
-  for (let index = 1; index < segments.length; index += 1) {
-    if (__velarServeCall(__velarServeStringStartsWith, segments[index], ["{"]) && __velarServeCall(__velarServeStringEndsWith, segments[index], ["}"])) segments[index] = "{}";
-  }
-  return __velarServeCall(__velarServeArrayJoin, segments, ["/"]);
+  return __velarServeRouteShapeFromSegments(__velarServeCall(__velarServeStringSplit, path, ["/"]));
 }
 
 function __velarCreateServeRoute(method, path, parameters, handler, metadata = {}) {
@@ -1032,6 +1125,21 @@ function __velarCreateServeRoute(method, path, parameters, handler, metadata = {
   }]);
 }
 
+function __velarCreateServeNotFound(handler, middleware = []) {
+  if (typeof handler !== "function") throw new __velarServeTypeError("@notFound handler is invalid");
+  if (!__velarServeIsArray(middleware) || middleware.length > 64) throw new __velarServeRangeError("@notFound cannot have more than 64 middleware functions");
+  const checkedMiddleware = [];
+  for (let index = 0; index < middleware.length; index += 1) {
+    if (typeof middleware[index] !== "function") throw new __velarServeTypeError("@notFound middleware entries must be functions");
+    checkedMiddleware[checkedMiddleware.length] = middleware[index];
+  }
+  return __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{
+    [__velarServeNotFoundMarker]: true,
+    handler,
+    middleware: __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [checkedMiddleware]),
+  }]);
+}
+
 function __velarServeDocumentationText(value, name, maximum) {
   if (value == null) return null;
   if (typeof value !== "string" || value.length === 0 || value.length > maximum || /[\0]/u.test(value)) {
@@ -1118,7 +1226,7 @@ function __velarServeBodyLimit(value) {
   return value;
 }
 
-function __velarServeAppValue(name, routes, lifecycles = []) {
+function __velarServeAppValue(name, routes, lifecycles = [], notFound = null) {
   const router = __velarServeRouter(routes);
   return __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{
     [__velarServeAppMarker]: true,
@@ -1126,34 +1234,54 @@ function __velarServeAppValue(name, routes, lifecycles = []) {
     routes: __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [routes]),
     router,
     lifecycles: __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [lifecycles]),
+    notFound,
   }]);
 }
 
 function __velarCreateServeApp(name, items) {
   if (typeof name !== "string" || name.length === 0 || name.length > 256) throw new __velarServeTypeError("ServeApp name must be bounded text");
-  if (!__velarServeIsArray(items) || items.length > __velarServeMaxRoutes) throw new __velarServeTypeError("ServeApp items cannot exceed 4096 entries");
+  if (!__velarServeIsArray(items) || items.length > __velarServeMaxRoutes + 1) throw new __velarServeTypeError("ServeApp items cannot exceed 4096 routes and one fallback");
   const routes = [];
   const lifecycles = [];
+  let notFound = null;
+  // D90 R19(b): assembly is the moment the final table exists, so the final
+  // table is judged here — a conflict names both routes and both origins,
+  // because the statically invisible half of a collision is exactly the one
+  // the author cannot see in his own file.
   const shapes = new __velarServeMap();
-  const append = route => {
+  const describeRoute = entry => "'" + entry.route.method + " " + entry.route.path + "'"
+    + (entry.source === null ? " declared by this server" : " composed in from '" + entry.source + "'");
+  const append = (route, source) => {
     if (routes.length >= __velarServeMaxRoutes) throw new __velarServeRangeError("ServeApp cannot contain more than 4096 routes after composition");
     const key = route.method + " " + __velarServeRouteShape(route.path);
-    if (__velarServeCall(__velarServeMapHas, shapes, [key])) throw new __velarServeTypeError("ServeApp contains conflicting route '" + key + "'");
-    __velarServeCall(__velarServeMapSet, shapes, [key, true]);
+    const previous = __velarServeCall(__velarServeMapGet, shapes, [key]);
+    if (previous !== undefined) {
+      throw new __velarServeTypeError("ServeApp '" + name + "' contains conflicting routes: " + describeRoute({route, source})
+        + " and " + describeRoute(previous) + " both answer '" + key + "' — narrow or remove one");
+    }
+    __velarServeCall(__velarServeMapSet, shapes, [key, {route, source}]);
     routes[routes.length] = route;
   };
   for (let index = 0; index < items.length; index += 1) {
     const item = items[index];
-    if (__velarServeIsRoute(item)) append(item);
+    if (__velarServeIsRoute(item)) append(item, null);
+    else if (__velarServeIsNotFound(item)) {
+      if (notFound !== null) throw new __velarServeTypeError("ServeApp contains more than one @notFound fallback");
+      notFound = item;
+    }
     else if (__velarServeIsApp(item)) {
-      for (let route = 0; route < item.routes.length; route += 1) append(item.routes[route]);
+      for (let route = 0; route < item.routes.length; route += 1) append(item.routes[route], item.name);
       for (let hook = 0; hook < item.lifecycles.length; hook += 1) {
         if (lifecycles.length >= __velarServeMaxLifecycles) throw new __velarServeRangeError("ServeApp cannot contain more than 4096 lifecycle pairs after composition");
         lifecycles[lifecycles.length] = item.lifecycles[hook];
       }
+      if (item.notFound !== null) {
+        if (notFound !== null) throw new __velarServeTypeError("ServeApp contains more than one @notFound fallback");
+        notFound = item.notFound;
+      }
     } else throw new __velarServeTypeError("A server composition entry must be a ServeApp");
   }
-  return __velarServeAppValue(name, routes, lifecycles);
+  return __velarServeAppValue(name, routes, lifecycles, notFound);
 }
 
 export function prefix(path, app) {
@@ -1163,6 +1291,7 @@ export function prefix(path, app) {
     throw new __velarServeTypeError("prefix path must contain only literal path segments");
   }
   if (path === "/") return app;
+  if (app.notFound !== null) throw new __velarServeTypeError("prefix cannot scope @notFound; compose the fallback on the final server instead");
   const routes = [];
   for (let index = 0; index < app.routes.length; index += 1) {
     const route = app.routes[index];
@@ -1175,7 +1304,7 @@ export function prefix(path, app) {
     );
   }
   const output = __velarCreateServeApp(app.name, routes);
-  return __velarServeAppValue(output.name, output.routes, app.lifecycles);
+  return __velarServeAppValue(output.name, output.routes, app.lifecycles, null);
 }
 
 export function staticFiles(path, root, fallback = null) {
@@ -1208,8 +1337,18 @@ export function use(app, middleware) {
       {...__velarServeRouteMetadata(route), middleware: entries},
     );
   }
-  const output = __velarCreateServeApp(app.name, routes);
-  return __velarServeAppValue(output.name, output.routes, app.lifecycles);
+  let notFound = app.notFound;
+  if (notFound !== null) {
+    const entries = [];
+    for (let item = 0; item < notFound.middleware.length; item += 1) entries[entries.length] = notFound.middleware[item];
+    for (let item = 0; item < additions.length; item += 1) entries[entries.length] = additions[item];
+    notFound = __velarCreateServeNotFound(notFound.handler, entries);
+  }
+  const items = [];
+  for (let index = 0; index < routes.length; index += 1) items[items.length] = routes[index];
+  if (notFound !== null) items[items.length] = notFound;
+  const output = __velarCreateServeApp(app.name, items);
+  return __velarServeAppValue(output.name, output.routes, app.lifecycles, output.notFound);
 }
 
 export function bodyLimit(app, maxBytes) {
@@ -1227,7 +1366,7 @@ export function bodyLimit(app, maxBytes) {
     );
   }
   const output = __velarCreateServeApp(app.name, routes);
-  return __velarServeAppValue(output.name, output.routes, app.lifecycles);
+  return __velarServeAppValue(output.name, output.routes, app.lifecycles, app.notFound);
 }
 
 export function lifecycle(app, startup = null, shutdown = null) {
@@ -1237,7 +1376,7 @@ export function lifecycle(app, startup = null, shutdown = null) {
   const lifecycles = [];
   for (let index = 0; index < app.lifecycles.length; index += 1) lifecycles[index] = app.lifecycles[index];
   lifecycles[lifecycles.length] = __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{startup, shutdown}]);
-  return __velarServeAppValue(app.name, app.routes, lifecycles);
+  return __velarServeAppValue(app.name, app.routes, lifecycles, app.notFound);
 }
 
 function __velarServeResponseWithHeaders(value, additions) {
@@ -1293,6 +1432,7 @@ function __velarServeCors(origins = ["*"], methods = ["GET", "POST", "PUT", "PAT
   methods = __velarServeStringList(methods, "middleware.cors methods");
   headers = __velarServeStringList(headers, "middleware.cors headers");
   if (typeof credentials !== "boolean" || !__velarServeIsSafeInteger(maxAge) || maxAge < 0 || maxAge > 86400) throw new __velarServeTypeError("middleware.cors options are invalid");
+  if (credentials && __velarServeCall(__velarServeArrayIncludes, origins, ["*"])) throw new __velarServeTypeError("middleware.cors cannot combine credentials with the '*' origin wildcard");
   return async (request, next) => {
     const origin = __velarServeCall(__velarServeMapHas, request.headers, ["origin"]) ? __velarServeCall(__velarServeMapGet, request.headers, ["origin"]) : null;
     const wildcard = __velarServeCall(__velarServeArrayIncludes, origins, ["*"]);
@@ -1423,18 +1563,26 @@ function __velarServeTimeout(milliseconds) {
     if (__velarServeActiveTimeouts >= __velarServeMaxActiveTimeouts) {
       return {status: 503, json: {error: "server_busy"}, headers: new __velarServeMap([["retry-after", "1"]])};
     }
-    __velarServeActiveTimeouts += 1;
     let timer = null;
-    let detached = false;
-    let pending;
-    try { pending = next(); }
-    catch (error) { __velarServeActiveTimeouts -= 1; throw error; }
+    const pending = next();
     const expired = new __velarServePromise(resolve => { timer = __velarServeCall(__velarServeSetTimeout, globalThis, [() => resolve(__velarServeMissing), milliseconds]); });
     try {
       const result = await __velarServeCall(__velarServePromiseRace, __velarServePromise, [__velarServeCall(__velarServeObjectFreeze, __velarServeObject, [[pending, expired]])]);
       if (result !== __velarServeMissing) return result;
-      detached = true;
       __velarServeCancellation.__velarCancel(request.cancellation, "Request timed out");
+      // The published bound counts unfinished timed-out continuations, and the
+      // background reservation at __velarServeRunBackground subtracts exactly
+      // this many slots from the process total. Admission alone cannot hold
+      // that count: a burst admitted while nothing was detached can expire
+      // together. When the detached budget is full the request has already been
+      // cancelled, so wait for it to unwind here instead of detaching work the
+      // process no longer accounts for.
+      if (__velarServeActiveTimeouts >= __velarServeMaxActiveTimeouts) {
+        try { await pending; }
+        catch (error) { __velarServeReportFailure(error); }
+        return {status: 504, json: {error: "request_timeout"}};
+      }
+      __velarServeActiveTimeouts += 1;
       __velarServeActiveBackgroundTasks += 1;
       const settlement = (async () => {
         try { await pending; }
@@ -1457,7 +1605,6 @@ function __velarServeTimeout(milliseconds) {
       };
     } finally {
       if (timer !== null) __velarServeCall(__velarServeClearTimeout, globalThis, [timer]);
-      if (!detached) __velarServeActiveTimeouts -= 1;
     }
   };
 }
@@ -1561,15 +1708,19 @@ function __velarServeDecodeScalar(raw, parameter) {
 function __velarServeCookieValue(request, name) {
   if (!__velarServeCall(__velarServeMapHas, request.headers, ["cookie"])) return __velarServeMissing;
   const pieces = __velarServeCall(__velarServeStringSplit, __velarServeCall(__velarServeMapGet, request.headers, ["cookie"]), [";"]);
+  let encoded = null;
+  let matches = 0;
   for (let index = 0; index < pieces.length; index += 1) {
     const piece = __velarServeCall(__velarServeStringTrim, pieces[index], []);
     const separator = __velarServeCall(__velarServeStringIndexOf, piece, ["="]);
     if (separator < 0 || __velarServeCall(__velarServeStringSlice, piece, [0, separator]) !== name) continue;
-    const encoded = __velarServeCall(__velarServeStringSlice, piece, [separator + 1]);
-    try { return __velarServeCall(__velarServeDecodeURIComponent, undefined, [encoded]); }
-    catch { throw new HttpError(400, {error: "invalid_cookie", parameter: name}); }
+    matches += 1;
+    if (matches > 1) throw new HttpError(400, {error: "duplicate_cookie", parameter: name});
+    encoded = __velarServeCall(__velarServeStringSlice, piece, [separator + 1]);
   }
-  return __velarServeMissing;
+  if (matches === 0) return __velarServeMissing;
+  try { return __velarServeCall(__velarServeDecodeURIComponent, undefined, [encoded]); }
+  catch { throw new HttpError(400, {error: "invalid_cookie", parameter: name}); }
 }
 
 function __velarServeNamedInputRaw(descriptor, parameterName, request) {
@@ -1770,6 +1921,17 @@ function __velarServeMultipartHeaders(text) {
   return output;
 }
 
+function __velarServeUploadBasename(filename) {
+  // A client may send a full path, including a Windows path with backslashes.
+  // An Upload name is one file name, never a path an application can compose
+  // into a directory it did not intend to write.
+  const slashed = __velarServeCall(__velarServeStringSplit, filename, ["/"]);
+  const separated = __velarServeCall(__velarServeStringSplit, slashed[slashed.length - 1], ["\\"]);
+  const base = separated[separated.length - 1];
+  if (base === "" || base === "." || base === ".." || __velarServeCall(__velarServeStringIncludes, base, ["\0"])) throw new HttpError(400, {error: "invalid_multipart"});
+  return base;
+}
+
 function __velarServeMultipart(data, boundary) {
   const opening = __velarServeBytePattern("--" + boundary);
   const separator = __velarServeBytePattern("\r\n\r\n");
@@ -1801,8 +1963,9 @@ function __velarServeMultipart(data, boundary) {
       __velarServeAddFormField(fields, name, __velarServeDecodeBytes(part));
     } else {
       if (filename.length > 1024 || __velarServeCall(__velarServeMapHas, files, [name])) throw new HttpError(400, {error: "invalid_multipart"});
+      const base = __velarServeUploadBasename(filename);
       const contentType = typeof headers["content-type"] === "string" ? headers["content-type"] : "application/octet-stream";
-      __velarServeCall(__velarServeMapSet, files, [name, __velarServeUploadValue(name, filename, contentType, part, uploadStates)]);
+      __velarServeCall(__velarServeMapSet, files, [name, __velarServeUploadValue(name, base, contentType, part, uploadStates)]);
     }
     parts += 1;
     if (parts > 128) throw new HttpError(413, {error: "too_many_form_parts"});
@@ -1981,12 +2144,26 @@ function __velarServeJsonContentType(headers) {
     || __velarServeCall(__velarServeStringStartsWith, value, ["application/"]) && __velarServeCall(__velarServeStringEndsWith, value, ["+json"]);
 }
 
+function __velarServeIsResponseAttempt(value) {
+  if (!value || typeof value !== "object" || __velarServeIsArray(value)) return false;
+  if (!__velarServeOwnDescriptor(value, "status")) return false;
+  return !!(__velarServeOwnDescriptor(value, "json") || __velarServeOwnDescriptor(value, "text") || __velarServeOwnDescriptor(value, "stream"));
+}
+
 function __velarServeAutomaticResponse(value) {
   if (__velarServeIsFileResponse(value)) return value;
+  if (__velarServeIsResponseAttempt(value)) return __velarServeResponse(value);
   try { return __velarServeResponse(value); }
   catch { return __velarServeResponse({status: 200, json: value}); }
 }
 
+function __velarServeNotFoundResponse(value) {
+  if (__velarServeIsFileResponse(value)) return value;
+  if (__velarServeIsResponseAttempt(value)) return __velarServeResponse(value);
+  try { return __velarServeResponse(value); }
+  catch { return __velarServeResponse({status: 404, json: value}); }
+}
+
 async function __velarServeHandleAppResponse(app, request, maxBodyBytes, context) {
   try {
     const actual = __velarServeCall(__velarServeStringSplit, request.path, ["/"]);
@@ -2014,6 +2191,13 @@ async function __velarServeHandleAppResponse(app, request, maxBodyBytes, context
         const methods = __velarServeAllowedMethods(allowed);
         return await __velarServeApplyMiddleware(pathOwner.route, request, async () => ({status: 405, json: {error: "method_not_allowed"}, headers: new __velarServeMap([["allow", __velarServeCall(__velarServeArrayJoin, methods, [", "])]])}));
       }
+      if (app.notFound !== null) {
+        return await __velarServeApplyMiddleware(
+          app.notFound,
+          request,
+          async () => __velarServeNotFoundResponse(await __velarServeCall(app.notFound.handler, undefined, [request])),
+        );
+      }
       return {status: 404, json: {error: "not_found"}};
     }
     let selected = candidates[0];
@@ -2025,6 +2209,7 @@ async function __velarServeHandleAppResponse(app, request, maxBodyBytes, context
     return await __velarServeApplyMiddleware(selected.route, request, invokeRoute);
   } catch (error) {
     if (error instanceof HttpError) return {status: error.status, json: error.body, headers: error.headers};
+    if (error instanceof RequestBodyTooLargeError) return {status: 413, json: {error: "request_too_large"}};
     throw error;
   }
 }
@@ -2462,7 +2647,7 @@ function __velarServeDocumentRoutes(app, documentation) {
     output[output.length] = __velarCreateServeRoute(route.method, route.path, route.parameters, route.handler, __velarServeRouteMetadata(route, __velarServeCall(__velarServeMapGet, configured, [key])));
   }
   if (__velarServeCall(__velarServeMapSize, seen, []) !== size) throw new __velarServeTypeError("docs routes contains a route that the application does not declare");
-  return __velarServeAppValue(app.name, output, app.lifecycles);
+  return __velarServeAppValue(app.name, output, app.lifecycles, app.notFound);
 }
 
 function __velarServeOpenApiPath(path) {
@@ -2556,6 +2741,16 @@ function __velarServeRequest(value) {
   }])};
 }
 
+// The budget error can also surface after a response has started, where the host
+// refuses a second terminal response; that attempt fails and the request falls
+// through to the opaque failure exactly as any other late error does.
+async function __velarServeShedOutbound(handle) {
+  try {
+    await __velarNodeHostInvoke("serve.respond", [handle, 503, [["retry-after", "1"]], "json", '{"error":"outbound_budget_exhausted"}', null, null, []]);
+    return true;
+  } catch { return false; }
+}
+
 async function __velarServeWriteResponse(handle, value) {
   let cleanup = null;
   let backgroundTasks = null;
@@ -2625,7 +2820,8 @@ function __velarServeNativeHeaders(request) {
   return output;
 }
 
-function __velarServeNativeRequest(request) {
+function __velarServeNativeRequest(request, maximum = __velarServeMaxBodyBytes) {
+  maximum = __velarServeBodyLimit(maximum);
   const method = request.method ?? "GET";
   if (typeof method !== "string" || !__velarServeCall(__velarServeRegExpTest, __velarServeMethodPattern, [method])) throw new __velarServeTypeError("Native HTTP method is invalid");
   const target = request.url ?? "/";
@@ -2642,7 +2838,7 @@ function __velarServeNativeRequest(request) {
       try {
         for await (const chunk of request) {
           const data = chunk instanceof __velarServeUint8Array ? chunk : __velarServeCall(__velarServeTextEncode, __velarServeUtf8Encoder, [__velarServeString(chunk)]);
-          if (total + data.byteLength > __velarServeMaxBodyBytes) { request.resume(); throw new RequestBodyTooLargeError(__velarServeMaxBodyBytes); }
+          if (total + data.byteLength > maximum) { request.resume(); throw new RequestBodyTooLargeError(maximum); }
           __velarServeReserveOutbound(data.byteLength);
           total += data.byteLength;
           reservedBodyBytes += data.byteLength;
@@ -2665,20 +2861,21 @@ function __velarServeNativeRequest(request) {
     })();
     return await bodyPromise;
   };
-  const bytes = async (maxBytes = __velarServeMaxBodyBytes) => {
+  const bytes = async (maxBytes = maximum) => {
     if (!__velarServeIsSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > __velarServeMaxBodyBytes) throw new __velarServeRangeError("Request body maxBytes must be an integer from 1 through 16777216");
     const data = await rawBody();
-    if (data.byteLength > maxBytes) throw new RequestBodyTooLargeError(maxBytes);
+    const effective = maxBytes > maximum ? maximum : maxBytes;
+    if (data.byteLength > effective) throw new RequestBodyTooLargeError(effective);
     return data;
   };
-  const body = async (maxBytes = __velarServeMaxBodyBytes) => {
+  const body = async (maxBytes = maximum) => {
     const data = await bytes(maxBytes);
     try { return __velarServeCall(__velarServeTextDecode, __velarServeUtf8Decoder, [data]); }
     catch { throw new __velarServeTypeError("Request body must be valid UTF-8 text"); }
   };
-  const json = async (maxBytes = __velarServeMaxBodyBytes) => __velarJsonParse(await body(maxBytes), "ServeRequest JSON text");
+  const json = async (maxBytes = maximum) => __velarJsonParse(await body(maxBytes), "ServeRequest JSON text");
   return {
-    request: __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{method, path, query: query.values, queryAll: query.all, headers: __velarServeNativeHeaders(request), cancellation, text: body, bytes, json, parse: async (Type, maxBytes = __velarServeMaxBodyBytes) => { Type = __velarRequireRuntimeType(Type, "ServeRequest.parse"); return Type.parse(await json(maxBytes)); }}]),
+    request: __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{method, path, query: query.values, queryAll: query.all, headers: __velarServeNativeHeaders(request), cancellation, text: body, bytes, json, parse: async (Type, maxBytes = maximum) => { Type = __velarRequireRuntimeType(Type, "ServeRequest.parse"); return Type.parse(await json(maxBytes)); }}]),
     cancellation,
     cleanup() { if (reservedBodyBytes > 0) { __velarServeReleaseOutbound(reservedBodyBytes); reservedBodyBytes = 0; } return null; },
   };
@@ -2693,14 +2890,49 @@ function __velarServeNativeSetHeaders(response, headers, cookies = []) {
   for (let index = 0; index < cookies.length; index += 1) allCookies[allCookies.length] = cookies[index];
   if (allCookies.length > 0) response.setHeader("Set-Cookie", allCookies);
 }
+// Every error branch of __velarServeHandleNative answers with a body of its own,
+// so it has to start from an empty header set: a content-length staged for the
+// response that failed makes the client wait for bytes that will never arrive,
+// and a Set-Cookie staged by a handler whose request was never served hands out
+// a session for nothing. The isolated-host transport gets this for free — it
+// sheds before the host ever sets a header — so this is the native transport
+// reaching the same state.
+function __velarServeNativeResetHeaders(response) {
+  const names = response.getHeaderNames();
+  for (let index = 0; index < names.length; index += 1) response.removeHeader(names[index]);
+}
+class __velarServeNativeNotFound extends __velarServeError {}
+function __velarServeNativeMissing(error) {
+  const code = error?.code;
+  return code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR";
+}
+// A relative path carries .. only as a whole segment, so a bare two-dot prefix
+// test also refuses an ordinary top-level file whose own name begins with two
+// dots — the same over-strict form the host worker's containment check carried.
+// The operations bag has no separator to consult and may come from a bridge
+// embedding, so both separators are refused: fail closed on Windows rather than
+// trust a default.
+function __velarServeNativeEscapes(path, operations) {
+  return path === ".." || path.startsWith("../") || path.startsWith("..\\") || operations.isAbsolute(path);
+}
 async function __velarServeNativeFile(value, operations) {
-  const root = await operations.realpath(operations.resolve(value.root));
+  let root;
+  // A static root that does not exist is the same miss as a file that does not
+  // exist: reporting it as a failure would answer 500 and write the absolute
+  // deployment path to stderr, which the host transport never does.
+  try { root = await operations.realpath(operations.resolve(value.root)); }
+  catch (error) { if (__velarServeNativeMissing(error)) throw new __velarServeNativeNotFound("fileResponse root does not name a directory"); throw error; }
   const load = async path => {
-    const target = await operations.realpath(operations.resolve(root, path.startsWith("/") ? "." + path : path));
+    let target;
+    try { target = await operations.realpath(operations.resolve(root, path.startsWith("/") ? "." + path : path)); }
+    catch (error) { if (__velarServeNativeMissing(error)) throw new __velarServeNativeNotFound("fileResponse path does not name a file"); throw error; }
     const relative = operations.relative(root, target);
-    if (relative.startsWith("..") || operations.isAbsolute(relative)) throw new __velarServeTypeError("fileResponse path escapes its root");
-    const info = await operations.stat(target);
-    if (!info.isFile() || info.size > 64 * 1024 * 1024) throw new __velarServeRangeError("fileResponse file exceeds 64 MiB");
+    if (__velarServeNativeEscapes(relative, operations)) throw new __velarServeNativeNotFound("fileResponse path escapes its root");
+    let info;
+    try { info = await operations.stat(target); }
+    catch (error) { if (__velarServeNativeMissing(error)) throw new __velarServeNativeNotFound("fileResponse path does not name a file"); throw error; }
+    if (!info.isFile()) throw new __velarServeNativeNotFound("fileResponse path does not name a file");
+    if (info.size > 64 * 1024 * 1024) throw new __velarServeRangeError("fileResponse file exceeds 64 MiB");
     return {target, info};
   };
   try { return await load(value.path); } catch (error) { if (value.fallback === null) throw error; return load(value.fallback); }
@@ -2770,13 +3002,13 @@ async function __velarServeNativeBody(response, value, checked, suppressBody, op
   if (!response.hasHeader("vary")) response.setHeader("vary", "Accept-Encoding");
   return __velarServeWithOutbound(compressed.byteLength, () => __velarServeNativeEnd(response, compressed));
 }
-async function __velarServeHandleNative(handler, request, response, operations) {
+async function __velarServeHandleNative(handler, request, response, operations, maxBodyBytes = __velarServeMaxBodyBytes) {
   let cleanup = null;
   let backgroundTasks = null;
   let incoming = null;
   let disconnected = null;
   try {
-    incoming = __velarServeNativeRequest(request);
+    incoming = __velarServeNativeRequest(request, maxBodyBytes);
     disconnected = () => { if (!response.writableFinished) __velarServeCancellation.__velarCancel(incoming.cancellation, "client_disconnect"); };
     request.once("aborted", disconnected);
     response.once("close", disconnected);
@@ -2791,7 +3023,34 @@ async function __velarServeHandleNative(handler, request, response, operations)
     let writing = false;
     const write = async chunk => { if (writing) throw new __velarServeError("ServeResponse allows only one active stream write"); writing = true; try { if (typeof chunk !== "string" || __velarUtf8ByteLength(chunk) > 1024 * 1024) throw new __velarServeTypeError("ServeResponse.stream chunks must be text of at most 1 MiB"); if (!suppressBody) await __velarServeWithOutbound(__velarUtf8ByteLength(chunk), () => __velarServeNativeWrite(response, chunk)); return null; } finally { writing = false; } };
     const result = await checked.stream(write); if (result !== null) throw new __velarServeTypeError("ServeResponse.stream producer must resolve to null"); if (writing) throw new __velarServeError("ServeResponse stream producer returned before its write completed"); await __velarServeNativeEnd(response); return null;
-  } catch (error) { __velarServeReportFailure(error); if (!response.headersSent) { response.statusCode = 500; response.setHeader("content-type", "text/plain; charset=utf-8"); response.end("Internal server error"); } else response.destroy(); return null; }
+  } catch (error) {
+    if (error instanceof RequestBodyTooLargeError && !response.headersSent) {
+      __velarServeNativeResetHeaders(response);
+      response.statusCode = 413;
+      response.setHeader("content-type", "application/json; charset=utf-8");
+      response.end(request.method === "HEAD" ? undefined : '{"error":"request_too_large"}');
+      return null;
+    }
+    if (error instanceof __velarServeNativeNotFound && !response.headersSent) {
+      __velarServeNativeResetHeaders(response);
+      response.statusCode = 404;
+      response.setHeader("content-type", "text/plain; charset=utf-8");
+      response.end(request.method === "HEAD" ? undefined : "Not found");
+      return null;
+    }
+    if (error instanceof __velarServeOutboundBudgetError && !response.headersSent) {
+      __velarServeNativeResetHeaders(response);
+      response.statusCode = 503;
+      response.setHeader("retry-after", "1");
+      response.setHeader("content-type", "application/json; charset=utf-8");
+      response.end(request.method === "HEAD" ? undefined : '{"error":"outbound_budget_exhausted"}');
+      return null;
+    }
+    __velarServeReportFailure(error);
+    if (!response.headersSent) { __velarServeNativeResetHeaders(response); response.statusCode = 500; response.setHeader("content-type", "text/plain; charset=utf-8"); response.end("Internal server error"); }
+    else response.destroy();
+    return null;
+  }
   finally {
     if (disconnected !== null) { request.off("aborted", disconnected); response.off("close", disconnected); }
     await __velarServeRunBackground(backgroundTasks);
@@ -3073,6 +3332,7 @@ async function __velarServeDispatch(event) {
   if (typeof handler !== "function") { __velarServeReportFailure(new __velarServeError("Node host requested an unknown server token")); await __velarNodeHostInvoke("serve.fail", [value.handle]); return; }
   try { await __velarServeWriteResponse(value.handle, await handler(value.request)); }
   catch (error) {
+    if (error instanceof __velarServeOutboundBudgetError && await __velarServeShedOutbound(value.handle)) return;
     __velarServeReportFailure(error);
     try { await __velarNodeHostInvoke("serve.fail", [value.handle]); }
     catch {}