@orieljs/http 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/index.js

@@ -28,6 +28,21 @@ var HttpServerError = class extends Error {
 };
 
 // body.ts
+function exceedsJsonDepth(text, maxDepth) {
+  let depth = 0;
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (inString) {
+      if (code === 92) i++;
+      else if (code === 34) inString = false;
+    } else if (code === 34) inString = true;
+    else if (code === 123 || code === 91) {
+      if (++depth > maxDepth) return true;
+    } else if (code === 125 || code === 93) depth--;
+  }
+  return false;
+}
 async function readBody(raw, limit) {
   if (raw.body === null) return new Uint8Array(0);
   const declared = Number(raw.headers.get("content-length") ?? NaN);
@@ -146,6 +161,15 @@ var HttpRedirectResponse = class {
 // HttpRedirector.ts
 import { UrlGenerator } from "@orieljs/contracts";
 import { inject } from "@orieljs/container";
+function pathOf(url2) {
+  let parsed;
+  try {
+    parsed = new URL(url2, "http://localhost");
+  } catch {
+    return "/";
+  }
+  return `${parsed.pathname.replace(/^\/+/, "/")}${parsed.search}${parsed.hash}`;
+}
 var HttpRedirector = class {
   to(path, status = 302, headers) {
     return new HttpRedirectResponse(inject(UrlGenerator).to(path), status, headers);
@@ -164,13 +188,16 @@ var HttpRedirector = class {
   away(url2, status = 302) {
     return new HttpRedirectResponse(url2, status);
   }
-  /** Remembers where a guest was going (a GET page, else the previous URL), then redirects to `path`. */
+  /**
+   * Remembers where a guest was going (a GET page, else the previous URL), then redirects to `path`. Only the path
+   * is stored, so intended() goes back on whichever host serves the app, and never to another site's Referer.
+   */
   guest(path, status = 302) {
     const session = optionalSession();
     const request2 = currentRequest();
     if (session !== void 0) {
       const intended = request2 !== void 0 && request2.method() === "GET" && !request2.expectsJson() ? request2.fullUrl() : inject(UrlGenerator).previous();
-      session.put("url.intended", intended);
+      session.put("url.intended", pathOf(intended));
     }
     return this.to(path, status);
   }
@@ -195,7 +222,7 @@ function clientAddress(request2) {
 // FormUploadedFile.ts
 import { FilesystemManager } from "@orieljs/contracts";
 import { inject as inject2 } from "@orieljs/container";
-import { Str } from "@orieljs/support";
+import { FileType, Str } from "@orieljs/support";
 
 // mime.ts
 var TYPES = {
@@ -210,13 +237,16 @@ var TYPES = {
   ico: "image/vnd.microsoft.icon",
   jpg: "image/jpeg",
   js: "text/javascript",
+  map: "application/json",
   json: "application/json",
   md: "text/markdown",
   mp3: "audio/mpeg",
   mp4: "video/mp4",
+  otf: "font/otf",
   pdf: "application/pdf",
   png: "image/png",
   svg: "image/svg+xml",
+  ttf: "font/ttf",
   txt: "text/plain",
   wasm: "application/wasm",
   webm: "video/webm",
@@ -239,20 +269,60 @@ function extensionFromMime(type) {
 }
 
 // FormUploadedFile.ts
-var FormUploadedFile = class {
-  constructor(file) {
+var NEVER_CLAIMED = /* @__PURE__ */ new Set([
+  ...FileType.BINARY_AND_MARKUP_TYPES.flatMap(({ extensions }) => extensions),
+  "jpe",
+  "svgz",
+  "xhtml",
+  "xht",
+  "shtml",
+  "xsl",
+  "xslt",
+  "mht",
+  "mhtml",
+  "js",
+  "mjs",
+  "rss",
+  "atom",
+  "rdf",
+  "mathml",
+  "mml",
+  "xul"
+]);
+var PLAIN_EXTENSION = /^[a-z0-9]+$/;
+var FormUploadedFile = class _FormUploadedFile {
+  constructor(file, detected) {
     this.file = file;
+    this.detected = detected;
     this.clientName = file.name ?? "";
     this.mimeType = file.type === "" ? "application/octet-stream" : file.type;
     this.size = file.size;
   }
   file;
+  detected;
   clientName;
   mimeType;
   size;
-  /** Guessed from the MIME type, falling back to the client's extension (Laravel's extension()). */
+  /**
+   * Reads the leading bytes first, so extension(), hashName() and store() name the file by its content. The request
+   * builds its uploads this way.
+   */
+  static async fromFile(file) {
+    return new _FormUploadedFile(file, FileType.detectFileType(new Uint8Array(await file.slice(0, FileType.SNIFF_BYTES).arrayBuffer())));
+  }
+  /**
+   * Laravel's extension(): the type the bytes show (guessExtension()), when they were read and match a known format.
+   * Text and bytes no format matches keep the client's claim (its MIME type, else its file name) when it is a plain
+   * extension, unless it names a format the bytes would have shown or one a browser renders or runs: otherwise 'txt'
+   * for text, '' for the rest. Unread (built directly), the client's claim when it is a plain extension, else ''.
+   */
   extension() {
-    return extensionFromMime(this.mimeType) ?? this.clientExtension();
+    const claimed = extensionFromMime(this.mimeType) ?? this.clientExtension();
+    const detected = this.detected;
+    if (detected === void 0) return PLAIN_EXTENSION.test(claimed) ? claimed : "";
+    if (detected !== FileType.TEXT && detected.extensions.length > 0) return detected.extensions[0];
+    if (PLAIN_EXTENSION.test(claimed) && !NEVER_CLAIMED.has(claimed)) return claimed;
+    return detected === FileType.TEXT ? "txt" : "";
   }
   clientExtension() {
     const dot = this.clientName.lastIndexOf(".");
@@ -282,6 +352,7 @@ var FormUploadedFile = class {
 
 // IncomingRequest.ts
 import {
+  AuthFactory,
   CurrentRoute,
   Session as Session2,
   ValidationFactory
@@ -404,6 +475,7 @@ var IncomingRequest = class {
     this.#url = new URL(raw.url);
     this.#trustedProxies = options.trustedProxies ?? [];
     this.#maxBodySize = options.maxBodySize === void 0 ? 8 * 1024 * 1024 : options.maxBodySize;
+    this.#maxJsonDepth = options.maxJsonDepth === void 0 ? 512 : options.maxJsonDepth;
     this.#query = fromEntries(this.#url.searchParams.entries());
     this.#method = raw.method.toUpperCase();
   }
@@ -411,6 +483,7 @@ var IncomingRequest = class {
   #url;
   #trustedProxies;
   #maxBodySize;
+  #maxJsonDepth;
   #query;
   #body = {};
   #files = {};
@@ -432,6 +505,9 @@ var IncomingRequest = class {
       const isMultipart = type.startsWith("multipart/form-data");
       if (isJson || isUrlencoded || isMultipart) {
         const bytes = await readBody(this.raw, this.#maxBodySize);
+        if (isJson && this.#maxJsonDepth !== null && exceedsJsonDepth(new TextDecoder().decode(bytes), this.#maxJsonDepth)) {
+          throw new HttpException(400, "The request body is nested too deeply.");
+        }
         try {
           if (isJson) {
             this.#content = new TextDecoder().decode(bytes);
@@ -440,7 +516,7 @@ var IncomingRequest = class {
             this.#content = new TextDecoder().decode(bytes);
             this.#body = fromEntries(new URLSearchParams(this.#content).entries());
           } else {
-            this.#parseForm(await new Response(bytes, { headers: { "content-type": this.raw.headers.get("content-type") ?? "" } }).formData());
+            await this.#parseForm(await new Response(bytes, { headers: { "content-type": this.raw.headers.get("content-type") ?? "" } }).formData());
           }
         } catch {
         }
@@ -465,12 +541,12 @@ var IncomingRequest = class {
     if (Array.isArray(parsed)) return sanitize({ ...parsed });
     return isPlainObject(parsed) ? sanitize(parsed) : {};
   }
-  #parseForm(form) {
+  async #parseForm(form) {
     const fields = [];
     const files = [];
     for (const [name, value] of form.entries()) {
       if (typeof value === "string") fields.push([name, value]);
-      else if (!((value.name ?? "") === "" && value.size === 0)) files.push([name, new FormUploadedFile(value)]);
+      else if (!((value.name ?? "") === "" && value.size === 0)) files.push([name, await FormUploadedFile.fromFile(value)]);
     }
     this.#body = fromEntries(fields);
     this.#files = fromEntries(files);
@@ -610,9 +686,14 @@ var IncomingRequest = class {
   filled(key) {
     return !isBlank(Arr.get(this.all(), key));
   }
+  /** Laravel's string(): the input as a Stringable (the default when it is missing or null): request().string('q').trim(). */
   string(key, defaultValue = "") {
     const value = this.input(key);
-    return value === void 0 || value === null ? defaultValue : String(value);
+    return Str2.of(value === void 0 || value === null ? defaultValue : value);
+  }
+  /** Laravel's str(): string() under its short name. */
+  str(key, defaultValue = "") {
+    return this.string(key, defaultValue);
   }
   /** PHP's FILTER_VALIDATE_BOOLEAN: '1', 'true', 'on', 'yes' (any case) and true are true. */
   boolean(key, defaultValue = false) {
@@ -688,13 +769,23 @@ var IncomingRequest = class {
   session() {
     return inject3(Session2);
   }
-  user(guard) {
-    return this.#userResolver?.(guard);
+  /**
+   * The signed-in user, through the resolver Auth sets, else the current scope's guard (the default, or `guard`).
+   * The guard keeps the user it found, so it is looked up once per request. Undefined for a guest or without auth.
+   */
+  async user(guard) {
+    if (this.#userResolver !== void 0) return await this.#userResolver(guard);
+    const container = currentContainer2();
+    if (container === void 0 || !container.bound(AuthFactory)) return void 0;
+    return await container.make(AuthFactory).guard(guard).user();
   }
   setUserResolver(resolver) {
     this.#userResolver = resolver;
   }
-  /** Validates all() through the ValidationFactory; throws its Validation error on failure. */
+  /**
+   * Validates all() through the ValidationFactory; throws its Validation error on failure. The data is typed from the
+   * rules: `validate({ title: 'required|string' })` is `{ title: string }`.
+   */
   validate(rules, messages, attributes) {
     return inject3(ValidationFactory).make(this.all(), rules, messages, attributes).validated();
   }
@@ -738,7 +829,8 @@ function url(path, query, absolute) {
   const generator = inject4(UrlGenerator2);
   return path === void 0 ? generator : generator.to(path, query, absolute);
 }
-function route(name, parameters, absolute) {
+function route(name, ...args) {
+  const [parameters, absolute] = args;
   return inject4(UrlGenerator2).route(name, parameters, absolute);
 }
 function abort(status, message = "", headers = {}) {
@@ -878,7 +970,11 @@ var Kernel = class {
     let request2;
     let response2;
     try {
-      request2 = new IncomingRequest(raw, { trustedProxies: this.#trustedProxies(), maxBodySize: this.#maxBodySize() });
+      request2 = new IncomingRequest(raw, {
+        trustedProxies: this.#trustedProxies(),
+        maxBodySize: this.#maxBodySize(),
+        maxJsonDepth: this.#maxJsonDepth()
+      });
       scope.instance(HttpRequest3, request2);
       const state = { scope, request: request2, middleware: [] };
       this.#requests.set(raw, state);
@@ -990,6 +1086,16 @@ var Kernel = class {
       `Invalid http.max_body_size ${JSON.stringify(value) ?? String(value)}: use a number of bytes (0 or more), or null for no limit.`
     );
   }
+  /** config('http.max_json_depth'): how deep a JSON body may nest, or null for no limit. */
+  #maxJsonDepth() {
+    if (!this.app.bound(ConfigRepository)) return 512;
+    const value = this.app.make(ConfigRepository).get("http.max_json_depth", 512);
+    if (value === null) return null;
+    if (typeof value === "number" && Number.isInteger(value) && value >= 1) return value;
+    throw new HttpServerError(
+      `Invalid http.max_json_depth ${JSON.stringify(value) ?? String(value)}: use a whole number (1 or more), or null for no limit.`
+    );
+  }
   /** config('http.trusted_proxies'): an array, or a comma-separated string such as '*' or '10.0.0.0/8,::1'. */
   #trustedProxies() {
     if (!this.app.bound(ConfigRepository)) return [];
@@ -1089,18 +1195,41 @@ var STATUS_TEXTS = {
   403: "Forbidden",
   404: "Not Found",
   405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
   408: "Request Timeout",
   409: "Conflict",
   410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
   413: "Content Too Large",
+  414: "URI Too Long",
   415: "Unsupported Media Type",
+  416: "Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a teapot",
   419: "Page Expired",
+  421: "Misdirected Request",
   422: "Unprocessable Content",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
   429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
   500: "Server Error",
+  501: "Not Implemented",
   502: "Bad Gateway",
   503: "Service Unavailable",
-  504: "Gateway Timeout"
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required"
 };
 function statusText(status) {
   return STATUS_TEXTS[status] ?? (status >= 500 ? "Server Error" : "Error");
@@ -1217,6 +1346,7 @@ var ErrorHandler = class {
   #renderCallbacks = [];
   #dontReport = [];
   #reported = /* @__PURE__ */ new WeakSet();
+  #jsonWhen;
   reportUsing(callback) {
     this.#reportCallbacks.push(callback);
   }
@@ -1226,6 +1356,14 @@ var ErrorHandler = class {
   ignore(...classes) {
     this.#dontReport.push(...classes);
   }
+  /** Laravel's shouldRenderJsonWhen(): the callback decides JSON or HTML instead of the Accept header. */
+  shouldRenderJsonWhen(callback) {
+    this.#jsonWhen = callback;
+  }
+  /** Laravel's shouldReturnJson(): the shouldRenderJsonWhen() callback when set, else request.expectsJson(). */
+  shouldReturnJson(request2, error) {
+    return this.#jsonWhen !== void 0 ? this.#jsonWhen(request2, error) : request2.expectsJson();
+  }
   shouldReport(error) {
     const kind = kindOf(error);
     if (kind !== void 0 && NOT_REPORTED.has(kind)) return false;
@@ -1264,11 +1402,10 @@ var ErrorHandler = class {
     let response2;
     if (kind === "Validation") response2 = await this.#renderValidation(http, error);
     else if (kind === "Authentication") response2 = await this.#renderAuthentication(http, error);
-    else if (http.expectsJson()) response2 = this.#renderJson(error);
+    else if (this.shouldReturnJson(http, error)) response2 = this.#renderJson(error);
     else response2 = await this.#renderHtml(http, error);
     const headers = error?.headers;
-    if (headers !== void 0) for (const [name, value] of Object.entries(headers)) response2.headers.set(name, value);
-    return response2;
+    return headers === void 0 ? response2 : withHeaders(response2, headers);
   }
   /** An error with its own render(request) or toResponse(request) (Laravel's renderable exceptions / Responsable). */
   async #renderCustom(request2, error) {
@@ -1282,7 +1419,7 @@ var ErrorHandler = class {
     return void 0;
   }
   async #renderValidation(request2, error) {
-    if (request2.expectsJson()) {
+    if (this.shouldReturnJson(request2, error)) {
       return this.#json({ message: summarizeValidation(error.errors), errors: error.errors }, statusFor(error));
     }
     const input = { ...request2.input() };
@@ -1297,7 +1434,7 @@ var ErrorHandler = class {
     return response2;
   }
   async #renderAuthentication(request2, error) {
-    if (request2.expectsJson()) return this.#json({ message: error.message || "Unauthenticated." }, 401);
+    if (this.shouldReturnJson(request2, error)) return this.#json({ message: error.message || "Unauthenticated." }, 401);
     const target = error.redirectTo ?? this.#guestRedirect(request2);
     const container = this.#container();
     if (!container.bound(Redirector2)) return this.#redirect(target);
@@ -1388,6 +1525,11 @@ var ErrorHandler = class {
     return currentContainer4() ?? this.app;
   }
 };
+function withHeaders(response2, extra) {
+  const headers = new Headers(response2.headers);
+  for (const [name, value] of Object.entries(extra)) headers.set(name, value);
+  return new Response(response2.body, { status: response2.status, statusText: response2.statusText, headers });
+}
 
 // ExceptionsConfiguration.ts
 import { ExceptionCallbacks } from "@orieljs/contracts";
@@ -1408,6 +1550,11 @@ var ExceptionsConfiguration = class {
     this.handler.ignore(...classes);
     return this;
   }
+  /** shouldRenderJsonWhen((request) => request.is('api/*')): JSON errors for those requests, whatever they accept. */
+  shouldRenderJsonWhen(callback) {
+    this.handler.shouldRenderJsonWhen(callback);
+    return this;
+  }
 };
 function applyExceptionCallbacks(app, handler) {
   if (!app.bound(ExceptionCallbacks)) return;
@@ -1417,6 +1564,41 @@ function applyExceptionCallbacks(app, handler) {
 
 // server/types.ts
 import { HttpKernel } from "@orieljs/contracts";
+
+// server/static.ts
+import { createReadStream as createReadStream2 } from "fs";
+import { stat as stat2 } from "fs/promises";
+import { Readable as Readable2 } from "stream";
+import { relative, resolve, sep } from "path";
+var HIDDEN_SEGMENT = /^\.|\.(ts|tsx|mts|cts)$|[. ]$/i;
+async function servePublicFile(publicPath, request2) {
+  if (request2.method !== "GET" && request2.method !== "HEAD") return void 0;
+  let pathname;
+  try {
+    pathname = decodeURIComponent(new URL(request2.url).pathname);
+  } catch {
+    return void 0;
+  }
+  if (pathname === "/" || pathname.includes("\0")) return void 0;
+  const root = resolve(publicPath);
+  const file = resolve(root, `.${pathname}`);
+  if (!file.startsWith(root + sep)) return void 0;
+  if (relative(root, file).split(/[\\/]/).some((segment) => HIDDEN_SEGMENT.test(segment))) return void 0;
+  const info = await stat2(file).catch(() => void 0);
+  if (info === void 0 || !info.isFile()) return void 0;
+  const type = mimeFromExtension(file);
+  const headers = new Headers({
+    "content-type": type.startsWith("text/") || type === "application/json" ? `${type}; charset=utf-8` : type,
+    "content-length": String(info.size),
+    "last-modified": info.mtime.toUTCString()
+  });
+  if (pathname.startsWith("/build/assets/")) headers.set("cache-control", "public, max-age=31536000, immutable");
+  if (request2.method === "HEAD") return new Response(null, { status: 200, headers });
+  const body = Readable2.toWeb(createReadStream2(file));
+  return new Response(body, { status: 200, headers });
+}
+
+// server/types.ts
 async function terminateRequest(app, request2, response2) {
   try {
     if (app.bound(HttpKernel)) await app.make(HttpKernel).terminate?.(request2, response2);
@@ -1424,17 +1606,21 @@ async function terminateRequest(app, request2, response2) {
     console.error(error);
   }
 }
-async function handleSafely(app, request2) {
+async function handleSafely(app, request2, publicPath) {
   try {
+    if (publicPath !== void 0) {
+      const file = await servePublicFile(publicPath, request2);
+      if (file !== void 0) return file;
+    }
     return await app.handle(request2);
   } catch (error) {
     console.error(error);
     return plainServerError();
   }
 }
-function exitOnSignals(close, closed) {
+function exitOnSignals(close, closed, app) {
   const onSignal = () => {
-    void close().then(() => process.exit(0));
+    void close().then(() => app.shutdown()).then(() => process.exit(0));
   };
   process.once("SIGINT", onSignal);
   process.once("SIGTERM", onSignal);
@@ -1453,13 +1639,13 @@ async function serveBun(app, options) {
   const bun = bunRuntime();
   if (bun === void 0) throw new HttpServerError("Bun.serve is not available: the process is not running on Bun.");
   let markClosed = () => void 0;
-  const closed = new Promise((resolve) => markClosed = resolve);
+  const closed = new Promise((resolve2) => markClosed = resolve2);
   const server = bun.serve({
     port: options.port,
     hostname: options.hostname,
     async fetch(request2, current) {
       setClientAddress(request2, current.requestIP(request2)?.address);
-      const response2 = await handleSafely(app, request2);
+      const response2 = await handleSafely(app, request2, options.publicPath);
       setTimeout(() => void terminateRequest(app, request2, response2), 0);
       return response2;
     },
@@ -1471,14 +1657,14 @@ async function serveBun(app, options) {
   let closing;
   const close = () => closing ??= (async () => {
     let timer;
-    const forced = new Promise((resolve) => {
-      timer = setTimeout(() => void Promise.resolve(server.stop(true)).then(resolve), options.shutdownTimeout);
+    const forced = new Promise((resolve2) => {
+      timer = setTimeout(() => void Promise.resolve(server.stop(true)).then(resolve2), options.shutdownTimeout);
     });
     await Promise.race([Promise.resolve(server.stop(false)), forced]);
     clearTimeout(timer);
     markClosed();
   })();
-  if (options.signals) exitOnSignals(close, closed);
+  if (options.signals) exitOnSignals(close, closed, app);
   return {
     runtime: "bun",
     hostname: options.hostname,
@@ -1491,7 +1677,7 @@ async function serveBun(app, options) {
 
 // server/node.ts
 import { createServer } from "http";
-import { Readable as Readable2 } from "stream";
+import { Readable as Readable3 } from "stream";
 import { pipeline } from "stream/promises";
 function requestBody(req) {
   let finished = false;
@@ -1573,7 +1759,7 @@ async function writeResponse(res, response2) {
     res.end();
     return;
   }
-  await pipeline(Readable2.fromWeb(response2.body), res);
+  await pipeline(Readable3.fromWeb(response2.body), res);
 }
 async function serveNode(app, options) {
   const fallbackHost = `${displayHost(options.hostname)}:${options.port}`;
@@ -1588,7 +1774,7 @@ async function serveNode(app, options) {
         return;
       }
       setClientAddress(request2, req.socket.remoteAddress);
-      const response2 = await handleSafely(app, request2);
+      const response2 = await handleSafely(app, request2, options.publicPath);
       try {
         await writeResponse(res, response2);
       } catch {
@@ -1597,18 +1783,18 @@ async function serveNode(app, options) {
       await terminateRequest(app, request2, response2);
     })();
   });
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     server.once("error", reject);
     server.listen(options.port, options.hostname, () => {
       server.off("error", reject);
-      resolve();
+      resolve2();
     });
   });
   const address = server.address();
-  const closed = new Promise((resolve) => server.once("close", () => resolve()));
+  const closed = new Promise((resolve2) => server.once("close", () => resolve2()));
   let closing;
   const close = () => closing ??= (async () => {
-    const done = new Promise((resolve) => server.close(() => resolve()));
+    const done = new Promise((resolve2) => server.close(() => resolve2()));
     server.closeIdleConnections();
     const idle = setInterval(() => server.closeIdleConnections(), 50);
     const force = setTimeout(() => server.closeAllConnections(), options.shutdownTimeout);
@@ -1616,7 +1802,7 @@ async function serveNode(app, options) {
     clearInterval(idle);
     clearTimeout(force);
   })();
-  if (options.signals) exitOnSignals(close, closed);
+  if (options.signals) exitOnSignals(close, closed, app);
   return {
     runtime: "node",
     hostname: options.hostname,
@@ -1636,7 +1822,8 @@ async function serve(app, options = {}) {
     port: options.port ?? Number(process.env.PORT ?? process.env.SERVER_PORT ?? 8e3),
     hostname: options.hostname ?? "127.0.0.1",
     signals: options.signals ?? true,
-    shutdownTimeout: options.shutdownTimeout ?? 1e4
+    shutdownTimeout: options.shutdownTimeout ?? 1e4,
+    ...options.publicPath !== false && { publicPath: options.publicPath ?? app.publicPath() }
   };
   await app.boot();
   const runtime = options.runtime ?? detectRuntime();
@@ -1647,12 +1834,255 @@ async function serve(app, options = {}) {
 }
 
 // commands.ts
-import { existsSync } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { mkdir, readFile as readFile2, writeFile } from "fs/promises";
 import { dirname } from "path";
 import {
   Router as Router3
 } from "@orieljs/contracts";
+
+// watch/environment.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import * as util from "util";
+var launchEnvironment = Object.freeze({ ...process.env });
+var BUN_ENV_FILES = [
+  ".env",
+  ".env.development",
+  ".env.production",
+  ".env.test",
+  ".env.local",
+  ".env.development.local",
+  ".env.production.local",
+  ".env.test.local"
+];
+var expand = (value, env) => value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => env[braced ?? bare] ?? "");
+function serverEnvironment(options = {}) {
+  const launched = options.launched ?? launchEnvironment;
+  const env = { ...launched };
+  if (!(options.bun ?? process.versions.bun !== void 0)) return env;
+  const parseEnv2 = "parseEnv" in options ? options.parseEnv : util.parseEnv;
+  if (typeof parseEnv2 !== "function") return env;
+  const cwd = options.cwd ?? process.cwd();
+  for (const name of BUN_ENV_FILES) {
+    const file = join(cwd, name);
+    if (!existsSync(file)) continue;
+    let values;
+    try {
+      values = parseEnv2(readFileSync(file, "utf8"));
+    } catch {
+      continue;
+    }
+    for (const [key, raw] of Object.entries(values)) {
+      const value = launched[key];
+      if (raw !== void 0 && value !== void 0 && (value === raw || value === expand(raw, launched))) delete env[key];
+    }
+  }
+  return env;
+}
+
+// watch/files.ts
+import { existsSync as existsSync2, statSync, watch as watchPath } from "fs";
+import { join as join2 } from "path";
+var WATCHED_FOLDERS = ["app", "bootstrap", "config", "lang", "resources/lang", "resources/views", "routes"];
+var WATCHED_ROOT_FILES = ["package.json", "tsconfig.json"];
+var IGNORED_FOLDERS = ["bootstrap/ssr", "bootstrap/cache"];
+var CODE_FILE = /\.(?:[cm]?[jt]sx?|json)$/;
+var DECLARATION_FILE = /\.d\.[cm]?ts$/;
+var EDITOR_FILE = /(?:\.sw[a-px]|~|___jb_(?:tmp|old)___)$/;
+var isEnvironmentFile = (name) => (name === ".env" || name.startsWith(".env.")) && name !== ".env.example" && !EDITOR_FILE.test(name);
+function isWatchedPath(path) {
+  const segments = path.split("/");
+  if (segments.length === 1) return isEnvironmentFile(path) || WATCHED_ROOT_FILES.includes(path);
+  if (!WATCHED_FOLDERS.some((folder) => path.startsWith(`${folder}/`))) return false;
+  if (IGNORED_FOLDERS.some((folder) => path === folder || path.startsWith(`${folder}/`))) return false;
+  if (segments.some((segment) => segment.startsWith(".") || segment === "node_modules")) return false;
+  const name = segments.at(-1);
+  if (DECLARATION_FILE.test(name)) return false;
+  return CODE_FILE.test(name) || !name.includes(".");
+}
+var toSlashes = (file) => file.split("\\").join("/");
+function watchFiles(basePath, onChange, options = {}) {
+  const watch = options.watch ?? ((path, watchOptions, listener) => watchPath(path, watchOptions, listener));
+  const debounce = options.debounce ?? 200;
+  const onError = options.onError ?? (() => {
+  });
+  const changed = /* @__PURE__ */ new Set();
+  let timer;
+  const settle = options.settle ?? 1e3;
+  const startedAt = Date.now();
+  const reportedLate = (path) => {
+    if (Date.now() - startedAt >= settle) return false;
+    try {
+      const modified = statSync(join2(basePath, path), { throwIfNoEntry: false })?.mtimeMs;
+      return modified === void 0 || modified < startedAt + 1;
+    } catch {
+      return false;
+    }
+  };
+  const record = (path) => {
+    if (!isWatchedPath(path) || reportedLate(path)) return;
+    changed.add(path);
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      const files = [...changed];
+      changed.clear();
+      onChange(files);
+    }, debounce);
+  };
+  const handles = [];
+  const start = (folder, recursive, toPath) => {
+    try {
+      const handle = watch(folder === "." ? basePath : join2(basePath, folder), { recursive }, (_event, file) => {
+        const path = toPath(file);
+        if (path !== void 0) record(path);
+      });
+      handle.on("error", (error) => onError(folder, error));
+      handles.push(handle);
+    } catch (error) {
+      onError(folder, error);
+    }
+  };
+  start(".", false, (file) => file === null ? void 0 : toSlashes(file));
+  for (const folder of WATCHED_FOLDERS) {
+    if (existsSync2(join2(basePath, folder))) start(folder, true, (file) => `${folder}/${file === null ? "" : toSlashes(file)}`);
+  }
+  return {
+    close() {
+      clearTimeout(timer);
+      changed.clear();
+      for (const handle of handles) handle.close();
+    }
+  };
+}
+
+// watch/port.ts
+import { createServer as createServer2 } from "net";
+function claimPort(hostname, port) {
+  return new Promise((resolve2, reject) => {
+    const server = createServer2();
+    server.once("error", reject);
+    try {
+      server.listen({ port, host: hostname, exclusive: true }, () => {
+        const { port: claimed } = server.address();
+        server.close(() => resolve2(claimed));
+      });
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+var REASONS = {
+  EADDRINUSE: "Address already in use",
+  EACCES: "Permission denied",
+  EADDRNOTAVAIL: "Can't assign requested address"
+};
+function listenFailure(hostname, port, error) {
+  const { code, message } = error;
+  return `Failed to listen on ${displayHost(hostname)}:${port} (reason: ${code !== void 0 && REASONS[code] || message})`;
+}
+
+// watch/WatchedServer.ts
+import { spawn as spawnProcess } from "child_process";
+var WatchedServer = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  running;
+  restarting = false;
+  stopping = false;
+  finish = () => {
+  };
+  /** Starts the server and keeps it current until stopped. Resolves 0 once the last server has exited. */
+  run() {
+    const done = new Promise((resolve2) => this.finish = resolve2);
+    const stopListening = this.listenForSignals();
+    const watcher = this.options.watch((files) => void this.changed(files));
+    this.start();
+    return done.finally(() => {
+      watcher.close();
+      stopListening();
+    });
+  }
+  /** Stops the server and ends run(); called again, kills the server at once. */
+  stop() {
+    if (this.stopping) {
+      this.running?.child.kill("SIGKILL");
+      return;
+    }
+    this.stopping = true;
+    void this.stopServer().then(() => this.finish(0));
+  }
+  async changed(files) {
+    if (this.stopping || this.restarting || files.length === 0) return;
+    this.restarting = true;
+    try {
+      this.options.info(
+        files.some(isEnvironmentFile) ? "Environment modified. Restarting server..." : `Application change detected in [${files[0]}]. Restarting server...`
+      );
+      await this.stopServer();
+      if (!this.stopping) this.start();
+    } finally {
+      this.restarting = false;
+    }
+  }
+  start() {
+    const [command, ...args] = this.options.command;
+    const child = (this.options.spawn ?? spawnProcess)(command, args, {
+      cwd: this.options.cwd,
+      env: this.options.env,
+      stdio: ["ignore", "inherit", "inherit"]
+    });
+    const running = { child, stopping: false, killed: false, exited: Promise.resolve() };
+    running.exited = new Promise((resolve2) => {
+      let settled = false;
+      const settle = (report) => {
+        if (settled) return;
+        settled = true;
+        if (this.running === running) this.running = void 0;
+        if (!running.stopping && !this.stopping) this.options.error(`${report}. Waiting for changes before restarting...`);
+        resolve2();
+      };
+      child.once("exit", (code, signal) => settle(signal !== null ? `The server stopped (signal ${signal})` : `The server stopped (exit code ${code})`));
+      child.once("error", (error) => {
+        if (child.pid === void 0) settle(`The server could not start (${error.message})`);
+      });
+    });
+    this.running = running;
+  }
+  /** Sends SIGTERM once and waits for the exit, killing the server after stopTimeout. */
+  async stopServer() {
+    const running = this.running;
+    if (running === void 0) return;
+    if (!running.stopping) {
+      running.stopping = true;
+      running.child.kill("SIGTERM");
+    }
+    const timeout = this.options.stopTimeout ?? 15e3;
+    const timer = setTimeout(() => {
+      if (running.killed) return;
+      running.killed = true;
+      this.options.error(`The server did not stop within ${timeout / 1e3} seconds and was killed.`);
+      running.child.kill("SIGKILL");
+    }, timeout);
+    try {
+      await running.exited;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  listenForSignals() {
+    const signals = this.options.signals ?? ["SIGINT", "SIGTERM", "SIGHUP"];
+    const handler = () => this.stop();
+    for (const signal of signals) process.on(signal, handler);
+    return () => {
+      for (const signal of signals) process.off(signal, handler);
+    };
+  }
+};
+
+// commands.ts
 function io(command) {
   return {
     option: (name) => {
@@ -1726,11 +2156,36 @@ ${web[1]}api: 'routes/api.ts',`);
 ${create[0]}`);
   return void 0;
 }
+async function serveWatching(app, out, port, run) {
+  const hostname = out.option("host") ?? "127.0.0.1";
+  const requested = port !== void 0 ? Number(port) : Number(process.env.PORT ?? process.env.SERVER_PORT ?? 8e3);
+  let claimed;
+  try {
+    claimed = await claimPort(hostname, requested);
+  } catch (error) {
+    out.error(listenFailure(hostname, requested, error));
+    return 1;
+  }
+  const script = process.argv[1];
+  if (script === void 0) {
+    out.error("serve --watch can't tell which script started this process, so it can't start the server.");
+    return 1;
+  }
+  return run({
+    command: [process.execPath, ...process.execArgv, script, "serve", `--host=${hostname}`, `--port=${claimed}`],
+    cwd: process.cwd(),
+    env: serverEnvironment(),
+    watch: (onChange) => watchFiles(app.basePath(), onChange, { onError: (folder, error) => out.warn(`Unable to watch [${folder}] for changes: ${error.message}`) }),
+    info: (message) => out.info(message),
+    error: (message) => out.error(message)
+  });
+}
 function registerHttpCommands(kernel, app, options = {}) {
   const serveApp = options.serve ?? serve;
   const terminalWidth = options.terminalWidth ?? (() => process.stdout.columns ?? 120);
+  const runWatching = options.watch ?? ((watchOptions) => new WatchedServer(watchOptions).run());
   kernel.command(
-    "serve {--host=127.0.0.1 : The host address to serve the application on} {--port= : The port to serve the application on}",
+    "serve {--host=127.0.0.1 : The host address to serve the application on} {--port= : The port to serve the application on} {--watch : Automatically restart the server when the application is modified}",
     async function() {
       const out = io(this);
       const port = out.option("port");
@@ -1738,6 +2193,7 @@ function registerHttpCommands(kernel, app, options = {}) {
         out.error("The --port option must be a number.");
         return 1;
       }
+      if (out.flag("watch")) return serveWatching(app, out, port, runWatching);
       const server = await serveApp(app, {
         hostname: out.option("host") ?? "127.0.0.1",
         ...port !== void 0 && { port: Number(port) },
@@ -1785,7 +2241,7 @@ function registerHttpCommands(kernel, app, options = {}) {
   kernel.command("install:api {--force : Overwrite any existing API routes file}", async function() {
     const out = io(this);
     const routesFile = app.basePath("routes/api.ts");
-    if (existsSync(routesFile) && !out.flag("force")) {
+    if (existsSync3(routesFile) && !out.flag("force")) {
       out.error("API routes file already exists.");
     } else {
       await mkdir(dirname(routesFile), { recursive: true });
@@ -1793,7 +2249,7 @@ function registerHttpCommands(kernel, app, options = {}) {
       out.info("Published API routes file.");
     }
     const bootstrapFile = app.bootstrapPath("app.ts");
-    const source = existsSync(bootstrapFile) ? await readFile2(bootstrapFile, "utf8") : void 0;
+    const source = existsSync3(bootstrapFile) ? await readFile2(bootstrapFile, "utf8") : void 0;
     const updated = source === void 0 ? void 0 : addApiRouting(source);
     if (updated === void 0) {
       out.warn(
@@ -1802,7 +2258,7 @@ function registerHttpCommands(kernel, app, options = {}) {
     } else if (updated !== source) {
       await writeFile(bootstrapFile, updated);
     }
-    out.info("API scaffolding installed. Run [oriel migrate] to create the personal access tokens table.");
+    out.info("API scaffolding installed.");
     return 0;
   }).purpose("Create an API routes file and prepare the application for API authentication");
 }
@@ -1816,6 +2272,7 @@ var HttpServiceProvider = class extends ServiceProvider {
       {
         trusted_proxies: [],
         max_body_size: 8 * 1024 * 1024,
+        max_json_depth: 512,
         csrf_except: [],
         redirect_guests_to: void 0,
         redirect_users_to: void 0
@@ -1870,6 +2327,7 @@ export {
   debugPage,
   detectRuntime,
   escapeHtml,
+  exceedsJsonDepth,
   extensionFromMime,
   filterRouteList,
   formatRouteList,
@@ -1895,6 +2353,7 @@ export {
   serve,
   serveBun,
   serveNode,
+  servePublicFile,
   setClientAddress,
   stackFrames,
   statusFor,