@orieljs/routing 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/index.js

@@ -1,15 +1,12 @@
 // BaseRouter.ts
 import {
   CurrentRoute as CurrentRoute2,
+  InertiaFactory,
   UrlGenerator,
   ViewFactory
 } from "@orieljs/contracts";
 import { currentContainer as currentContainer2 } from "@orieljs/container";
 
-// dispatch.ts
-import { CurrentRoute } from "@orieljs/contracts";
-import { currentContainer } from "@orieljs/container";
-
 // bindings.ts
 import { RouteModelResolver } from "@orieljs/contracts";
 import { BindingResolutionError } from "@orieljs/container";
@@ -69,6 +66,24 @@ var RoutingError = class extends Error {
   status = 500;
   name = "RoutingError";
 };
+var InvalidUrlSignatureError = class extends Error {
+  kind = "Http";
+  status = 403;
+  name = "InvalidUrlSignatureError";
+  constructor() {
+    super("Invalid signature.");
+  }
+};
+var ThrottleRequestsError = class extends Error {
+  constructor(headers = {}) {
+    super("Too Many Attempts.");
+    this.headers = headers;
+  }
+  headers;
+  kind = "Http";
+  status = 429;
+  name = "ThrottleRequestsError";
+};
 
 // middleware.ts
 import {
@@ -237,6 +252,10 @@ async function substituteBindings(router, route, values, container) {
   return bound;
 }
 
+// dispatch.ts
+import { CurrentRoute } from "@orieljs/contracts";
+import { currentContainer } from "@orieljs/container";
+
 // RouteDefinition.ts
 var PARAMETER = /\{(\w+)(?::(\w+))?(\?)?\}/g;
 var WHOLE_OPTIONAL = /^\{(\w+)(?::\w+)?\?\}$/;
@@ -327,6 +346,7 @@ var RouteDefinition = class {
     this.#name = (this.#name ?? "") + name;
     return this;
   }
+  /** middleware('auth', 'verified') or middleware(['auth', 'verified']). */
   middleware(...middleware) {
     this.#middleware.push(...middleware.flat());
     return this;
@@ -341,6 +361,32 @@ var RouteDefinition = class {
     this.#compiled = void 0;
     return this;
   }
+  /** Laravel's whereAlpha(): ASCII letters only. One parameter name or several. */
+  whereAlpha(parameters) {
+    return this.#assign(parameters, "[a-zA-Z]+");
+  }
+  /** Laravel's whereAlphaNumeric(): ASCII letters and digits. */
+  whereAlphaNumeric(parameters) {
+    return this.#assign(parameters, "[a-zA-Z0-9]+");
+  }
+  /** Laravel's whereNumber(): digits only. */
+  whereNumber(parameters) {
+    return this.#assign(parameters, "[0-9]+");
+  }
+  /** Laravel's whereUlid(): 26 Crockford base-32 characters, the first at most 7. */
+  whereUlid(parameters) {
+    return this.#assign(parameters, "[0-7][0-9a-hjkmnp-tv-zA-HJKMNP-TV-Z]{25}");
+  }
+  /** Laravel's whereUuid(): five groups of hex digits (8-4-4-4-12), any version. */
+  whereUuid(parameters) {
+    return this.#assign(parameters, "[\\da-fA-F]{8}-[\\da-fA-F]{4}-[\\da-fA-F]{4}-[\\da-fA-F]{4}-[\\da-fA-F]{12}");
+  }
+  /** Laravel's whereIn(): one of the values. Unlike Laravel, each value is matched literally (`c++` is not a pattern). */
+  whereIn(parameters, values) {
+    const first = typeof parameters === "string" ? parameters : parameters[0];
+    if (values.length === 0 && first !== void 0) throw new Error(`Routing requirement for "${first}" cannot be empty.`);
+    return this.#assign(parameters, values.map((value) => escapeRegex(String(value))).join("|"));
+  }
   gatherMiddleware() {
     return [...this.#middleware];
   }
@@ -371,6 +417,10 @@ var RouteDefinition = class {
     if (this.uri === "/") return [];
     return this.uri.split("/").map((segment) => WHOLE_OPTIONAL.test(segment) ? 2 : segment.includes("{") ? 1 : 0);
   }
+  #assign(parameters, pattern) {
+    const names = typeof parameters === "string" ? [parameters] : parameters;
+    return this.where(Object.fromEntries(names.map((name) => [name, pattern])));
+  }
   #regex(patterns, version) {
     if (this.#compiled !== void 0 && this.#compiled.version === version) return this.#compiled.regex;
     const wheres = { ...patterns, ...this.#wheres };
@@ -643,6 +693,23 @@ var BaseRouter = class {
     holder.route = this.addRoute(["GET", "HEAD"], uri, action);
     return holder.route;
   }
+  /**
+   * Route.inertia('/about', 'About', props): GET/HEAD; renders the page through the InertiaFactory (resolved when
+   * the route runs, so Routing needs no Inertia import). Route parameters are merged into the props.
+   */
+  inertia(uri, component, props = {}) {
+    const holder = {};
+    const action = (...values) => {
+      const parameters = Object.fromEntries(holder.route.parameters.map((parameter, index) => [parameter.name, values[index]]));
+      const container = currentContainer2() ?? this.container;
+      if (container === void 0 || !container.bound(InertiaFactory)) {
+        throw new RoutingError(`Cannot render Inertia page [${component}]: no InertiaFactory is bound.`);
+      }
+      return container.make(InertiaFactory).render(component, { ...props, ...parameters });
+    };
+    holder.route = this.addRoute(["GET", "HEAD"], uri, action);
+    return holder.route;
+  }
   resource(name, controller, options = {}) {
     this.#registerResource(name, controller, options, false);
   }
@@ -713,6 +780,14 @@ var BaseRouter = class {
   getModel(parameter) {
     return this.#models.get(parameter);
   }
+  /**
+   * Binds a matched route's raw parameter values as a request to it would: Route.bind() callbacks, Route.model(),
+   * then implicit binding through the RouteModelResolver of `container`. A missing model throws
+   * RouteModelNotFoundError (404). Live uses it to check a page route's `can:` middleware again on each update.
+   */
+  substituteBindings(route, values, container) {
+    return substituteBindings(this, route, values, container);
+  }
   aliasMiddleware(name, middleware) {
     this.#aliases[name] = middleware;
     return this;
@@ -777,7 +852,8 @@ var BaseRouter = class {
 };
 
 // BaseUrlGenerator.ts
-import { ConfigRepository, HttpRequest, Session } from "@orieljs/contracts";
+import { createHmac, timingSafeEqual } from "crypto";
+import { ConfigRepository, Encrypter, HttpRequest, Session } from "@orieljs/contracts";
 import { currentContainer as currentContainer3 } from "@orieljs/container";
 var VALID_URL = /^(#|\/\/|https?:\/\/|(mailto|tel|sms):)/i;
 var isPlainObject = (value) => {
@@ -805,6 +881,17 @@ function routeKey(value, field) {
   if (field !== void 0) return typeof model.getAttribute === "function" ? model.getAttribute(field) : model[field];
   return typeof model.getRouteKey === "function" ? model.getRouteKey() : value;
 }
+function sign(url, key) {
+  return createHmac("sha256", key).update(url).digest("hex");
+}
+function safeEquals(expected, given) {
+  const a = Buffer.from(expected);
+  const b = Buffer.from(given);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function availableAt(expiration) {
+  return expiration instanceof Date ? Math.floor(expiration.getTime() / 1e3) : Math.floor(Date.now() / 1e3) + expiration;
+}
 var BaseUrlGenerator = class {
   constructor(router, container) {
     this.router = router;
@@ -892,6 +979,69 @@ var BaseUrlGenerator = class {
   hasRoute(name) {
     return this.router.getByName(name) !== void 0;
   }
+  /**
+   * Laravel's URL::signedRoute(): the route URL with its parameters sorted by name, then a `signature` query (the
+   * HMAC-SHA256 of that URL, keyed by APP_KEY). `expiration` (a Date, or seconds from now) adds `expires`.
+   * `absolute: false` signs the path only (checked by `signed:relative`).
+   */
+  signedRoute(name, parameters, expiration, absolute = true) {
+    const named = this.#namedParameters(name, parameters);
+    for (const reserved of ["signature", "expires"]) {
+      if (Object.hasOwn(named, reserved)) {
+        throw new RoutingError(`"${reserved}" is a reserved parameter when generating signed routes. Please rename your route parameter.`);
+      }
+    }
+    if (expiration !== void 0) named.expires = availableAt(expiration);
+    const sorted = Object.fromEntries(Object.keys(named).sort().map((key) => [key, named[key]]));
+    const signature = sign(this.route(name, sorted, absolute), this.#signingKeys()[0]);
+    return this.route(name, { ...sorted, signature }, absolute);
+  }
+  /** Laravel's URL::temporarySignedRoute(): a signed URL that expires at `expiration` (a Date, or seconds from now). */
+  temporarySignedRoute(name, expiration, parameters, absolute = true) {
+    return this.signedRoute(name, parameters, expiration, absolute);
+  }
+  /** The request URL carries a correct signature (current or previous APP_KEY) that hasn't expired. */
+  hasValidSignature(request, absolute = true) {
+    return this.hasCorrectSignature(request, absolute) && this.signatureHasNotExpired(request);
+  }
+  /** The signature matches the URL without its `signature` query, in a constant-time comparison. */
+  hasCorrectSignature(request, absolute = true) {
+    const full = new URL(request.fullUrl());
+    const path = request.path();
+    const url = absolute ? request.url() : path === "/" ? "/" : `/${path}`;
+    const query = full.search.slice(1).split("&").filter((pair) => pair !== "" && pair.split("=")[0] !== "signature").join("&");
+    const original = query === "" ? url : `${url}?${query}`;
+    const given = full.searchParams.get("signature") ?? "";
+    return this.#signingKeys().some((key) => safeEquals(sign(original, key), given));
+  }
+  /** No `expires` query, or one that is still in the future. */
+  signatureHasNotExpired(request) {
+    const expires = new URL(request.fullUrl()).searchParams.get("expires");
+    if (expires === null || expires === "") return true;
+    const at = Number(expires);
+    return Number.isFinite(at) && Math.floor(Date.now() / 1e3) <= at;
+  }
+  /** Named parameters: an object as is, positional values (a list or one value) by the route's parameter names. */
+  #namedParameters(name, parameters) {
+    if (isPlainObject(parameters)) return { ...parameters };
+    const route = this.router.getByName(name);
+    if (route === void 0) throw new RouteNotDefinedError(name);
+    const values = parameters === void 0 || parameters === null ? [] : Array.isArray(parameters) ? parameters : [parameters];
+    const named = {};
+    route.parameters.forEach((parameter, index) => {
+      if (index < values.length) named[parameter.name] = values[index];
+    });
+    return named;
+  }
+  /** The Encrypter's key, then its previous keys (config app.previous_keys), so rotated keys still verify. */
+  #signingKeys() {
+    const scope = this.#scope();
+    if (scope === void 0 || !scope.bound(Encrypter)) {
+      throw new RoutingError("Signed URLs need the Encrypter: set APP_KEY (oriel key:generate).");
+    }
+    const encrypter = scope.make(Encrypter);
+    return typeof encrypter.getAllKeys === "function" ? encrypter.getAllKeys() : [encrypter.getKey()];
+  }
   #join(path, absolute) {
     const trimmed = path.replace(/^\/+|\/+$/g, "");
     if (!absolute) return `/${trimmed}`;
@@ -916,6 +1066,51 @@ import { Router } from "@orieljs/contracts";
 import { facade } from "@orieljs/support";
 var Route = facade(Router);
 
+// health.ts
+import { ConfigRepository as ConfigRepository2, EventDispatcher, ExceptionHandler as ExceptionHandler2 } from "@orieljs/contracts";
+var DiagnosingHealth = class {
+};
+var escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+var STYLE = ':root{color-scheme:dark}*{box-sizing:border-box;margin:0}html{background:#05050b}body{min-height:100vh;display:grid;place-items:center;padding:20px;background:#1a1a1a;color:#fff;font:400 16px/1.7 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif}main{display:flex;align-items:center;gap:20px;width:100%;max-width:640px;padding:20px 32px;border-radius:18px;background:#212121}.dot{flex:none;width:12px;height:12px;border-radius:50%;background:#74ec5a}.dot.down{background:#ff3543}h1{font-size:21px;line-height:1.4;font-weight:600}p{color:#a3a3a3}.time{color:#ba94ff}';
+function healthResponse(page = {}) {
+  const healthy = page.healthy ?? true;
+  const time = page.milliseconds === void 0 ? "" : ` Response rendered in <span class="time">${Math.round(page.milliseconds)} ms</span>.`;
+  const html2 = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(page.appName ?? "Oriel")}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+<span class="${healthy ? "dot" : "dot down"}" aria-hidden="true"></span>
+<div>
+<h1>Application ${healthy ? "up" : "experiencing problems"}</h1>
+<p>HTTP request received.${time}</p>
+</div>
+</main>
+</body>
+</html>
+`;
+  return new Response(html2, { status: healthy ? 200 : 500, headers: { "content-type": "text/html; charset=utf-8" } });
+}
+async function diagnoseHealth(app) {
+  const started = performance.now();
+  const config = app.bound(ConfigRepository2) ? app.make(ConfigRepository2) : void 0;
+  let healthy = true;
+  try {
+    if (app.bound(EventDispatcher)) await app.make(EventDispatcher).dispatch(new DiagnosingHealth());
+  } catch (error) {
+    if (config?.get("app.debug", false) === true) throw error;
+    if (app.bound(ExceptionHandler2)) await app.make(ExceptionHandler2).report(error);
+    healthy = false;
+  }
+  const appName = String(config?.get("app.name", "Oriel") ?? "Oriel");
+  return healthResponse({ healthy, appName, milliseconds: performance.now() - started });
+}
+
 // routeFiles.ts
 import { pathToFileURL } from "url";
 var generation = 0;
@@ -927,18 +1122,137 @@ async function loadRoutesFrom(app, router, file) {
   ));
   if (typeof module.default === "function") await app.run(() => module.default(router));
 }
-function healthResponse() {
-  const html2 = '<!DOCTYPE html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n<title>Application up</title>\n</head>\n<body><h1>Application up</h1></body>\n</html>';
-  return new Response(html2, { status: 200, headers: { "content-type": "text/html; charset=utf-8" } });
-}
 
 // RoutingServiceProvider.ts
-import { Router as Router2, RoutingPaths, UrlGenerator as UrlGenerator2 } from "@orieljs/contracts";
+import { Router as Router2, RoutingPaths, UrlGenerator as UrlGenerator3 } from "@orieljs/contracts";
 import { ServiceProvider } from "@orieljs/support";
+
+// ThrottleRequests.ts
+import { createHash } from "crypto";
+import { RateLimiter } from "@orieljs/contracts";
+import { inject } from "@orieljs/container";
+var sha1 = (value) => createHash("sha1").update(value).digest("hex");
+function withHeaders(response, headers) {
+  try {
+    for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
+    return response;
+  } catch {
+    const copy = new Headers(response.headers);
+    for (const [name, value] of Object.entries(headers)) copy.set(name, value);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers: copy });
+  }
+}
+var ThrottleRequests = class {
+  async handle(request, next, maxAttempts = "60", decayMinutes = "1", prefix = "") {
+    const max = Number(maxAttempts);
+    const decay = Number(decayMinutes);
+    if (maxAttempts.trim() === "" || !Number.isInteger(max) || max < 0 || decayMinutes.trim() === "" || !Number.isFinite(decay) || decay <= 0) {
+      throw new RoutingError(
+        `Invalid throttle parameters "${maxAttempts},${decayMinutes}": use throttle:<maxAttempts>,<decayMinutes>[,<prefix>] (named rate limiters are not supported).`
+      );
+    }
+    const limiter = inject(RateLimiter);
+    const key = prefix + await this.resolveRequestSignature(request);
+    if (await limiter.tooManyAttempts(key, max)) {
+      const retryAfter = await limiter.availableIn(key);
+      throw new ThrottleRequestsError({
+        "X-RateLimit-Limit": String(max),
+        "X-RateLimit-Remaining": "0",
+        "Retry-After": String(retryAfter),
+        "X-RateLimit-Reset": String(Math.floor(Date.now() / 1e3) + retryAfter)
+      });
+    }
+    await limiter.hit(key, Math.round(decay * 60));
+    const response = await next(request);
+    return withHeaders(response, {
+      "X-RateLimit-Limit": String(max),
+      "X-RateLimit-Remaining": String(await limiter.remaining(key, max))
+    });
+  }
+  /** The signed-in user's identifier, else the client IP, hashed (Laravel's resolveRequestSignature()). */
+  async resolveRequestSignature(request) {
+    const user = await request.user();
+    if (user !== void 0 && user !== null && typeof user.getAuthIdentifier === "function") {
+      return sha1(String(user.getAuthIdentifier()));
+    }
+    return sha1(`|${request.ip() ?? ""}`);
+  }
+};
+
+// SetCacheHeaders.ts
+import { createHash as createHash2 } from "crypto";
+var DIRECTIVES = /* @__PURE__ */ new Set([
+  "public",
+  "private",
+  "no_cache",
+  "no_store",
+  "no_transform",
+  "must_revalidate",
+  "proxy_revalidate",
+  "immutable",
+  "max_age",
+  "s_maxage",
+  "stale_while_revalidate",
+  "stale_if_error"
+]);
+var SetCacheHeaders = class {
+  async handle(request, next, ...parameters) {
+    const response = await next(request);
+    const method = request.method();
+    if (method !== "GET" && method !== "HEAD") return response;
+    if (response.headers.has("set-cookie") || /\bno-store\b/i.test(response.headers.get("cache-control") ?? "")) return response;
+    const options = parameters.join(",").split(";").map((option) => option.trim()).filter((option) => option !== "");
+    const headers = new Headers(response.headers);
+    const directives = [];
+    let etag = false;
+    for (const option of options) {
+      const [name = "", value] = option.split("=", 2);
+      if (name === "etag") {
+        etag = true;
+        continue;
+      }
+      if (!DIRECTIVES.has(name)) throw new Error(`cache.headers: unknown option "${name}".`);
+      const directive = name.replace(/_/g, "-");
+      directives.push(value === void 0 ? directive : `${directive}=${value}`);
+    }
+    if (directives.length > 0) headers.set("cache-control", directives.join(", "));
+    if (!etag) return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+    const body = new Uint8Array(await response.arrayBuffer());
+    const tag = `"${createHash2("md5").update(body).digest("hex")}"`;
+    headers.set("etag", tag);
+    if (matches(request.header("if-none-match"), tag)) {
+      const notModified = new Headers({ etag: tag });
+      const cacheControl = headers.get("cache-control");
+      if (cacheControl !== null) notModified.set("cache-control", cacheControl);
+      return new Response(null, { status: 304, headers: notModified });
+    }
+    return new Response(body, { status: response.status, statusText: response.statusText, headers });
+  }
+};
+function matches(header, tag) {
+  if (header === void 0) return false;
+  return header.split(",").some((candidate) => {
+    const value = candidate.trim();
+    return value === "*" || value === tag || value === `W/${tag}`;
+  });
+}
+
+// ValidateSignature.ts
+import { UrlGenerator as UrlGenerator2 } from "@orieljs/contracts";
+import { inject as inject2 } from "@orieljs/container";
+var ValidateSignature = class {
+  async handle(request, next, ...parameters) {
+    const absolute = parameters[0] !== "relative";
+    if (inject2(UrlGenerator2).hasValidSignature(request, absolute)) return next(request);
+    throw new InvalidUrlSignatureError();
+  }
+};
+
+// RoutingServiceProvider.ts
 var RoutingServiceProvider = class extends ServiceProvider {
   register() {
     this.app.singleton(Router2, () => new BaseRouter(this.app));
-    this.app.singleton(UrlGenerator2, () => {
+    this.app.singleton(UrlGenerator3, () => {
       const router = this.app.make(Router2);
       if (!(router instanceof BaseRouter)) {
         throw new RoutingError("The UrlGenerator needs the BaseRouter: the bound Router was replaced by another implementation.");
@@ -952,21 +1266,28 @@ var RoutingServiceProvider = class extends ServiceProvider {
    * when the route files run.
    */
   boot() {
+    this.app.make(Router2).aliasMiddleware("signed", ValidateSignature).aliasMiddleware("throttle", ThrottleRequests).aliasMiddleware("cache.headers", SetCacheHeaders);
     this.app.booted(async () => {
       if (!this.app.bound(RoutingPaths)) return;
       const { web, api, health, apiPrefix } = this.app.make(RoutingPaths);
       const router = this.app.make(Router2);
-      if (health !== void 0) router.get(health, () => healthResponse());
-      if (web !== void 0) await router.middleware("web").group(() => loadRoutesFrom(this.app, router, web));
-      if (api !== void 0) await router.prefix(apiPrefix).middleware("api").group(() => loadRoutesFrom(this.app, router, api));
+      if (health !== void 0) router.get(health, () => diagnoseHealth(this.app));
+      if (web !== void 0) await router.middleware("web").group(() => this.#load(router, web));
+      if (api !== void 0) await router.prefix(apiPrefix).middleware("api").group(() => this.#load(router, api));
     });
   }
+  /** One file or several, in order: each is imported afresh for this application (a nested import is not). */
+  async #load(router, files) {
+    for (const file of [files].flat()) await loadRoutesFrom(this.app, router, file);
+  }
 };
 export {
   BaseRouter,
   BaseUrlGenerator,
   ControllerMethodNotFoundError,
+  DiagnosingHealth,
   GroupRegistrar,
+  InvalidUrlSignatureError,
   MethodNotAllowedHttpError,
   MiddlewareNotFoundError,
   NotFoundHttpError,
@@ -976,7 +1297,11 @@ export {
   RouteNotDefinedError,
   RoutingError,
   RoutingServiceProvider,
+  SetCacheHeaders,
+  ThrottleRequests,
+  ThrottleRequestsError,
   UrlGenerationError,
+  ValidateSignature,
   buildQuery,
   compareRoutes,
   dispatchRoute,