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

package/NOTICE

@@ -7,3 +7,10 @@ This product includes software developed by the Oriel project
 Oriel is licensed under the Apache License, Version 2.0 (see LICENSE).
 The Oriel name and logo are not covered by that license; see TRADEMARKS.md
 (https://github.com/orieljs/framework/blob/main/TRADEMARKS.md).
+
+@orieljs/support (and @orieljs/framework, which bundles it) includes transliteration data from
+voku/portable-ascii (https://github.com/voku/portable-ascii), Copyright (C) 2019 Lars Moelleken, MIT License.
+
+@orieljs/notifications (and @orieljs/framework, which bundles it) includes the HTML and CSS of
+Laravel's default notification mail (laravel/framework, https://github.com/laravel/framework),
+Copyright (c) Taylor Otwell, MIT License.

package/README.md

@@ -0,0 +1,33 @@
+# @orieljs/http
+
+The HTTP layer of Oriel: the request, responses and redirects, the middleware kernel, the error handler and its error pages, and the server for Node and Bun. It is Oriel's counterpart of Laravel's HTTP layer. Http is part of `@orieljs/framework`, which every Oriel app already installs, and is re-exported from it. In an app, import it from `@orieljs/framework`; `@orieljs/http` is also published on its own.
+
+```bash
+npm install @orieljs/framework
+```
+
+```ts title="app/Http/Controllers/SearchController.ts"
+import { request, response } from '@orieljs/framework'
+import { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class SearchController extends Controller {
+  async index() {
+    const term = request().input('q', '')
+    const posts = await Post.whereLike('title', `%${term}%`).latest().get()
+    return response().json({ term, posts }, 200, { 'Cache-Control': 'no-store' })
+  }
+}
+```
+
+`request()` is the current `IncomingRequest`, with `input()`, `string()`, `boolean()`, `integer()`, `only()`, `file()` and `header()`; `await request().user()` is the signed-in user, or `undefined` for a guest. `response()`, `redirect()` and `back()` build responses, and `abort()`, `abortIf()` and `abortUnless()` stop a request with an HTTP error. `await serve(app)` runs the app on Node or Bun.
+
+Documentation: https://orieljs.vercel.app/docs/requests
+
+Status: early alpha. APIs will change.
+
+## License
+
+Oriel is open-source software licensed under the Apache License 2.0 (Apache-2.0; see `LICENSE` and `NOTICE`). The Oriel name and logo are trademarks; see `TRADEMARKS.md`.
+
+Website: https://orieljs.vercel.app

package/TRADEMARKS.md

@@ -0,0 +1,33 @@
+# Oriel trademark policy
+
+The Oriel code is open source under the Apache License 2.0. The **Oriel name and logo** are not: the license covers
+the code only (section 6 of the license says so), and the name and logo stay with the project. This page explains
+what you can and can't do with them. The goal is simple: people should always be able to tell what is the real Oriel
+and what isn't.
+
+## You can, without asking
+
+- Use, change, ship and sell the code, as the license allows.
+- Say that your app or package is "built with Oriel", "for Oriel" or "compatible with Oriel".
+- Name a package `oriel-<something>` or `<something>-for-oriel` when it works with Oriel, as long as it is clear that
+  it is not official (for example, don't publish it under the `@orieljs` npm scope).
+- Use the name and logo to write about Oriel, teach it, or link to it, in articles, talks, videos and courses.
+- Use the unmodified logo to point to the project, as it is (no recolouring, cropping or
+  distortion).
+
+## You can't, without written permission
+
+- Call a fork, a modified copy or a competing product "Oriel", or anything likely to be confused with it.
+- Use the name or logo as the name, logo or domain of your own product, company or service.
+- Suggest that the Oriel project made, endorses or supports your work when it doesn't.
+- Sell merchandise with the name or logo.
+
+## Forks
+
+Forks are welcome. Please give yours a different name and logo, keep the `LICENSE` and `NOTICE` files, and say that
+it is based on Oriel.
+
+## Questions
+
+Open an issue at https://github.com/orieljs/framework or email meeeet.dev@gmail.com. If you're unsure whether a use
+is fine, ask; the answer is usually yes.

package/dist/index.d.ts

@@ -1,7 +1,14 @@
-import { HttpRequest, CookieJar, Session, Container, RedirectResponse, HeadersInit, Redirector, UploadedFile, Rules, OrielError, ResponseFactory, BodyInit, UrlGenerator, HttpKernel, Application, MiddlewareClass, Middleware, Next, MiddlewareConfigurator, Router, ConfigRepository, ExceptionHandler, ExceptionsConfigurator, ConsoleKernel, Route } from '@orieljs/contracts';
+import { HttpRequest, CookieJar, Session, Container, RedirectResponse, HeadersInit, MessageBag, Redirector, UploadedFile, Rules, InferValidatedType, OrielError, RouteName, RouteArguments, ResponseFactory, BodyInit, UrlGenerator, HttpKernel, Application, MiddlewareClass, Middleware, Next, MiddlewareConfigurator, Router, ConfigRepository, ExceptionHandler, ExceptionsConfigurator, ConsoleKernel, Route } from '@orieljs/contracts';
+import { FileType, Stringable, ServiceProvider } from '@orieljs/support';
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { ServiceProvider } from '@orieljs/support';
+import { SpawnOptions, ChildProcess } from 'node:child_process';
 
+/**
+ * Whether a JSON text nests objects and arrays deeper than `maxDepth`, found by scanning (no parsing, no recursion):
+ * brackets inside strings don't count. The kernel answers 400 for such bodies (http.max_json_depth) before the
+ * recursive input handling (sanitizing, TrimStrings, validation) could overflow the stack.
+ */
+declare function exceedsJsonDepth(text: string, maxDepth: number): boolean;
 /** Reads a request body into memory, refusing more than `limit` bytes (413), like PHP's post_max_size. */
 declare function readBody(raw: Request, limit: number | null): Promise<Uint8Array>;
 
@@ -12,9 +19,7 @@ declare function currentRequest(): HttpRequest | undefined;
 declare function optionalSession(): Session | undefined;
 declare function optionalCookieJar(): CookieJar | undefined;
 
-type ErrorsInput = Record<string, string | string[]> | {
-    toObject(): Record<string, string[]>;
-};
+type ErrorsInput = Record<string, string | string[]> | MessageBag;
 /**
  * Laravel's RedirectResponse. with()/withErrors()/withInput() flash to the request's Session immediately, like
  * Laravel; without a bound Session (an API-only app) they are skipped silently.
@@ -46,7 +51,10 @@ declare class HttpRedirector implements Redirector {
     /** Pulls url.intended from the session (put there by guest()), else goes to `fallback`. */
     intended(fallback?: string, status?: number): HttpRedirectResponse;
     away(url: string, status?: number): HttpRedirectResponse;
-    /** 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: string, status?: number): HttpRedirectResponse;
     setIntendedUrl(url: string): void;
     refresh(status?: number): HttpRedirectResponse;
@@ -58,13 +66,26 @@ declare function clientAddress(request: Request): string | undefined;
 /** An uploaded file from a multipart body. store()/storeAs() go through the FilesystemManager. */
 declare class FormUploadedFile implements UploadedFile {
     private readonly file;
+    private readonly detected?;
     readonly clientName: string;
     readonly mimeType: string;
     readonly size: number;
+    /**
+     * Reads the leading bytes first, so extension(), hashName() and store() name the file by its content. The request
+     * builds its uploads this way.
+     */
+    static fromFile(file: Blob & {
+        readonly name?: string;
+    }): Promise<FormUploadedFile>;
     constructor(file: Blob & {
         readonly name?: string;
-    });
-    /** Guessed from the MIME type, falling back to the client's extension (Laravel's extension()). */
+    }, detected?: FileType.DetectedType | undefined);
+    /**
+     * 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(): string;
     clientExtension(): string;
     /** A random 40-character name with the guessed extension. */
@@ -81,6 +102,8 @@ interface IncomingRequestOptions {
     trustedProxies?: readonly string[];
     /** Largest request body in bytes before a 413 (config http.max_body_size); null is unlimited. Default 8 MB. */
     maxBodySize?: number | null;
+    /** Deepest nesting of objects and arrays in a JSON body before a 400 (config http.max_json_depth); null is unlimited. Default 512. */
+    maxJsonDepth?: number | null;
 }
 /** Exact match, IPv4 CIDR ('10.0.0.0/8') or '*'. */
 declare function ipMatches(ip: string, patterns: readonly string[]): boolean;
@@ -136,7 +159,10 @@ declare class IncomingRequest implements HttpRequest {
     hasAny(...keys: Array<string | string[]>): boolean;
     missing(...keys: Array<string | string[]>): boolean;
     filled(key: string): boolean;
-    string(key: string, defaultValue?: string): string;
+    /** Laravel's string(): the input as a Stringable (the default when it is missing or null): request().string('q').trim(). */
+    string(key: string, defaultValue?: string): Stringable;
+    /** Laravel's str(): string() under its short name. */
+    str(key: string, defaultValue?: string): Stringable;
     /** PHP's FILTER_VALIDATE_BOOLEAN: '1', 'true', 'on', 'yes' (any case) and true are true. */
     boolean(key: string, defaultValue?: boolean): boolean;
     /** PHP's intval: leading digits, else 0. */
@@ -155,10 +181,17 @@ declare class IncomingRequest implements HttpRequest {
     /** One route parameter (after model binding), or all of them. */
     route<T = unknown>(key?: string): T;
     session(): Session;
-    user<T = unknown>(guard?: string): T | undefined;
+    /**
+     * 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.
+     */
+    user<T = unknown>(guard?: string): Promise<T | undefined>;
     setUserResolver(resolver: (guard?: string) => unknown): void;
-    /** Validates all() through the ValidationFactory; throws its Validation error on failure. */
-    validate<T = Record<string, unknown>>(rules: Rules, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<T>;
+    /**
+     * 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<const R extends Rules>(rules: R, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<InferValidatedType<R>>;
 }
 
 /** Helpers for request input: PHP-style bracket keys, safe cloning (no prototype pollution) and blank checks. */
@@ -209,22 +242,32 @@ declare class HttpServerError extends Error implements OrielError {
     readonly name = "HttpServerError";
 }
 
-/** request() → the current HttpRequest; request('key', default) → its input. */
-declare function request(): HttpRequest;
+/**
+ * request() → the current request (Laravel's Illuminate\Http\Request: the HttpRequest contract plus its extras, such
+ * as string()); request('key', default) → its input.
+ */
+declare function request(): IncomingRequest;
 declare function request<T = unknown>(key: string, defaultValue?: T): T;
 /** response() → the ResponseFactory; response(content, status, headers) → a Response. */
 declare function response(): ResponseFactory;
 declare function response(content: BodyInit | null, status?: number, headers?: HeadersInit): Response;
+/** The Redirector with its route() typed by the generated route names and their parameters. */
+type TypedRedirector = Omit<Redirector, 'route'> & {
+    route<N extends RouteName>(name: N, ...args: RouteArguments<N, [status?: number]>): RedirectResponse;
+};
 /** redirect() → the Redirector; redirect('/path', status) → a RedirectResponse. */
-declare function redirect(): Redirector;
+declare function redirect(): TypedRedirector;
 declare function redirect(to: string, status?: number): RedirectResponse;
 /** Redirect to the previous URL (same argument order as Redirector.back()). */
 declare function back(fallback?: string, status?: number): RedirectResponse;
 /** url() → the UrlGenerator; url('/path', query, absolute) → a URL. */
 declare function url(): UrlGenerator;
 declare function url(path: string, query?: Record<string, unknown>, absolute?: boolean): string;
-/** The URL of a named route. */
-declare function route(name: string, parameters?: unknown, absolute?: boolean): string;
+/**
+ * The URL of a named route: route('posts.show', post), route('posts.show', { post, page: 2 }). Once `oriel
+ * route:types` has run, the name and the route's parameters are checked.
+ */
+declare function route<N extends RouteName>(name: N, ...args: RouteArguments<N>): string;
 /** abort(404), abort(403, 'Nope', headers), or abort(response) to send a ready response. */
 declare function abort(status: number | Response, message?: string, headers?: Record<string, string>): never;
 declare function abortIf(condition: unknown, status: number | Response, message?: string, headers?: Record<string, string>): void;
@@ -312,6 +355,7 @@ declare function applyMiddlewareCallbacks(app: Application, kernel: Kernel): voi
 type ReportCallback = (error: unknown) => void | boolean | Promise<void | boolean>;
 type RenderCallback = (error: unknown, request: unknown) => Response | undefined | Promise<Response | undefined>;
 type ErrorClass = abstract new (...args: never[]) => Error;
+type JsonWhenCallback = (request: HttpRequest, error: unknown) => boolean;
 /** HTTP status for an error (spec §7). */
 declare function statusFor(error: unknown): number;
 /** "The title field is required. (and 2 more errors)" (Laravel's ValidationException::summarize). */
@@ -326,6 +370,10 @@ declare class ErrorHandler implements ExceptionHandler {
     reportUsing(callback: ReportCallback): void;
     renderUsing(callback: RenderCallback): void;
     ignore(...classes: ErrorClass[]): void;
+    /** Laravel's shouldRenderJsonWhen(): the callback decides JSON or HTML instead of the Accept header. */
+    shouldRenderJsonWhen(callback: JsonWhenCallback): void;
+    /** Laravel's shouldReturnJson(): the shouldRenderJsonWhen() callback when set, else request.expectsJson(). */
+    protected shouldReturnJson(request: HttpRequest, error: unknown): boolean;
     shouldReport(error: unknown): boolean;
     /** Report callbacks first (returning false stops the default log), then LogManager.error(), else console.error. Once per error. */
     report(error: unknown): Promise<void>;
@@ -339,11 +387,16 @@ declare class ExceptionsConfiguration implements ExceptionsConfigurator {
     report(callback: ReportCallback): this;
     render(callback: RenderCallback): this;
     dontReport(...classes: ErrorClass[]): this;
+    /** shouldRenderJsonWhen((request) => request.is('api/*')): JSON errors for those requests, whatever they accept. */
+    shouldRenderJsonWhen(callback: (request: HttpRequest, error: unknown) => boolean): this;
 }
 /** Runs the withExceptions() callbacks against a handler (the provider does this when the handler is built). */
 declare function applyExceptionCallbacks(app: Application, handler: ErrorHandler): void;
 
-/** Laravel's wording for the status (its error pages say "Server Error" and "Page Expired"). */
+/**
+ * The text an error page shows for a status: Laravel's own wording where it has a view ("Server Error", "Page
+ * Expired"), else Symfony's `Response::$statusTexts`, which Laravel shows for the others.
+ */
 declare function statusText(status: number): string;
 declare function escapeHtml(value: string): string;
 /** Laravel's minimal error page: "404 | Not Found". */
@@ -373,12 +426,16 @@ interface ServeOptions {
     runtime?: Runtime;
     /** Called once listening. Default: prints "Server running on [url]." */
     onListen?: (server: RunningServer) => void;
+    /** Serve existing files from this directory before the app (Laravel's server.php). Default: app.publicPath(); false turns it off. */
+    publicPath?: string | false;
 }
 interface ResolvedServeOptions {
     readonly port: number;
     readonly hostname: string;
     readonly signals: boolean;
     readonly shutdownTimeout: number;
+    /** Where public files are served from, or undefined when turned off. */
+    readonly publicPath?: string;
 }
 interface RunningServer {
     readonly runtime: Runtime;
@@ -421,6 +478,35 @@ declare function detectRuntime(): Runtime;
 /** Boots the app and serves it with node:http or Bun.serve (public/index.ts: `await serve(app)`). */
 declare function serve(app: Application, options?: ServeOptions): Promise<RunningServer>;
 
+/**
+ * Laravel's server.php for `artisan serve`: a GET or HEAD for a file that exists under public/ is answered
+ * with that file, so the built Vite assets (public/build) and other public files work without a web server.
+ * Anything else (directories, missing files, other methods) returns undefined and goes to the application.
+ */
+declare function servePublicFile(publicPath: string, request: Request): Promise<Response | undefined>;
+
+interface FileWatcher {
+    close(): void;
+}
+
+/** node:child_process's spawn(), replaceable in tests. */
+type SpawnServer = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+interface WatchedServerOptions {
+    /** The server's command line: the runtime, its flags, the CLI script, then `serve --host=… --port=…`. */
+    command: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Starts watching: calls back with the changed files (relative to the base path) once they settle. */
+    watch(onChange: (files: string[]) => void): FileWatcher;
+    info(message: string): void;
+    error(message: string): void;
+    /** How long a server may take to stop before it is killed, in ms. Default 15000 (serve gives requests 10 s). */
+    stopTimeout?: number;
+    /** The signals that stop it. Default SIGINT, SIGTERM and SIGHUP. */
+    signals?: readonly NodeJS.Signals[];
+    spawn?: SpawnServer;
+}
+
 interface RouteListRow {
     /** 'GET|HEAD' */
     readonly method: string;
@@ -460,6 +546,8 @@ interface HttpCommandOptions {
     serve?: (app: Application, options: ServeOptions) => Promise<RunningServer>;
     /** The terminal width for route:list. Default: process.stdout.columns, else 120. */
     terminalWidth?: () => number;
+    /** Replaces `serve --watch`'s restarting server (tests). Resolves the command's exit code. */
+    watch?: (options: WatchedServerOptions) => Promise<number>;
 }
 /** Registers `serve`, `route:list` and `install:api` as closure commands (PC1). */
 declare function registerHttpCommands(kernel: ConsoleKernel, app: Application, options?: HttpCommandOptions): void;
@@ -477,4 +565,4 @@ declare class HttpServiceProvider extends ServiceProvider {
     boot(): void;
 }
 
-export { API_ROUTES_STUB, ConvertEmptyStringsToNull, type ErrorClass, ErrorHandler, ExceptionsConfiguration, FormUploadedFile, type HttpCommandOptions, HttpException, HttpRedirectResponse, HttpRedirector, HttpResponseException, HttpResponseFactory, HttpServerError, HttpServiceProvider, IncomingRequest, type IncomingRequestOptions, Kernel, MiddlewareConfiguration, type RenderCallback, type ReportCallback, type ResolvedServeOptions, type RouteListFilters, type RouteListRow, type RunningServer, type Runtime, type ServeOptions, type StackFrame, TrimStrings, abort, abortIf, abortUnless, addApiRouting, applyExceptionCallbacks, applyMiddlewareCallbacks, back, bunRuntime, clientAddress, contentDisposition, currentRequest, debugPage, detectRuntime, escapeHtml, extensionFromMime, filterRouteList, formatRouteList, fromEntries, ipMatches, isBlank, mergeRecursive, mimeFromExtension, minimalPage, normalizeLists, optionalCookieJar, optionalSession, parseBracketKey, readBody, redirect, registerHttpCommands, request, requestScope, response, route, routeListRows, sanitize, serve, serveBun, serveNode, setClientAddress, stackFrames, statusFor, statusText, summarizeValidation, toWebRequest, transformLeaves, url, writeResponse };
+export { API_ROUTES_STUB, ConvertEmptyStringsToNull, type ErrorClass, ErrorHandler, ExceptionsConfiguration, FormUploadedFile, type HttpCommandOptions, HttpException, HttpRedirectResponse, HttpRedirector, HttpResponseException, HttpResponseFactory, HttpServerError, HttpServiceProvider, IncomingRequest, type IncomingRequestOptions, type JsonWhenCallback, Kernel, MiddlewareConfiguration, type RenderCallback, type ReportCallback, type ResolvedServeOptions, type RouteListFilters, type RouteListRow, type RunningServer, type Runtime, type ServeOptions, type StackFrame, TrimStrings, type TypedRedirector, abort, abortIf, abortUnless, addApiRouting, applyExceptionCallbacks, applyMiddlewareCallbacks, back, bunRuntime, clientAddress, contentDisposition, currentRequest, debugPage, detectRuntime, escapeHtml, exceedsJsonDepth, extensionFromMime, filterRouteList, formatRouteList, fromEntries, ipMatches, isBlank, mergeRecursive, mimeFromExtension, minimalPage, normalizeLists, optionalCookieJar, optionalSession, parseBracketKey, readBody, redirect, registerHttpCommands, request, requestScope, response, route, routeListRows, sanitize, serve, serveBun, serveNode, servePublicFile, setClientAddress, stackFrames, statusFor, statusText, summarizeValidation, toWebRequest, transformLeaves, url, writeResponse };