@plinthjs/http 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.md +4 -4
- package/dist/index.cjs +77 -86
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +133 -146
- package/dist/index.d.ts +133 -146
- package/dist/index.js +77 -86
- package/dist/index.js.map +1 -1
- package/package.json +8 -9
package/dist/index.d.cts
CHANGED
|
@@ -3,8 +3,7 @@ import { Collection } from '@plinthjs/support';
|
|
|
3
3
|
import { Newable, Container } from '@plinthjs/core';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
* `Controller`
|
|
7
|
-
* `Illuminate\Routing\Controller`). Controllers are plain classes resolved through the `@plinthjs/core`
|
|
6
|
+
* `Controller` - the optional convention base for `[Controller, method]` route actions. Controllers are plain classes resolved through the `@plinthjs/core`
|
|
8
7
|
* container, so extending this is not required; it gives a shared, stable base for app-wide
|
|
9
8
|
* controller helpers and a clear type. Route/group middleware is declared on the route, not here.
|
|
10
9
|
*/
|
|
@@ -24,12 +23,12 @@ type StreamChunk = string | Uint8Array;
|
|
|
24
23
|
/**
|
|
25
24
|
* The body source accepted by {@link Response.stream}: an iterable / async iterable of chunks, or a
|
|
26
25
|
* factory (e.g. a generator function) returning one. A factory is invoked lazily, once, when the
|
|
27
|
-
* response is flushed
|
|
26
|
+
* response is flushed.
|
|
28
27
|
*/
|
|
29
28
|
type StreamSource = Iterable<StreamChunk> | AsyncIterable<StreamChunk> | (() => Iterable<StreamChunk> | AsyncIterable<StreamChunk>);
|
|
30
29
|
/** A JSON streaming source: rows to stream as one array, or an object whose values may be iterables. */
|
|
31
30
|
type JsonStreamData = Iterable<unknown> | AsyncIterable<unknown> | Record<string, unknown>;
|
|
32
|
-
/** Options for {@link Response.cookie}
|
|
31
|
+
/** Options for {@link Response.cookie} - the common `Set-Cookie` attributes. */
|
|
33
32
|
interface CookieOptions {
|
|
34
33
|
/** `Max-Age` in seconds. */
|
|
35
34
|
maxAge?: number;
|
|
@@ -61,7 +60,7 @@ declare class Response {
|
|
|
61
60
|
* matches the `Content-Length` set by {@link Response.file}/{@link Response.download}.
|
|
62
61
|
*/
|
|
63
62
|
private bodyEncoding;
|
|
64
|
-
/** Flash intent queued by {@link Response.with}; drained by the session layer
|
|
63
|
+
/** Flash intent queued by {@link Response.with}; drained by the session layer. */
|
|
65
64
|
private flashData;
|
|
66
65
|
/** The streaming body source, when this is a streamed response (see {@link Response.stream}). */
|
|
67
66
|
private streamSource;
|
|
@@ -105,7 +104,7 @@ declare class Response {
|
|
|
105
104
|
/**
|
|
106
105
|
* Build a streamed response: `source` (an iterable, async iterable, or a generator/factory
|
|
107
106
|
* returning one) is consumed chunk by chunk as the response is flushed, each chunk written to the
|
|
108
|
-
* client as it yields
|
|
107
|
+
* client as it yields - the `response()->stream()` equivalent. No `Content-Length` is set, so
|
|
109
108
|
* Node serves it with chunked transfer encoding. The kernel/server adapter flushes streamed
|
|
110
109
|
* responses via {@link Response.writeStreamTo}.
|
|
111
110
|
*/
|
|
@@ -117,7 +116,7 @@ declare class Response {
|
|
|
117
116
|
*/
|
|
118
117
|
static streamDownload(source: StreamSource, filename: string, headers?: Record<string, string>): Response;
|
|
119
118
|
/**
|
|
120
|
-
* Build a streamed JSON response
|
|
119
|
+
* Build a streamed JSON response - the `response()->streamJson()` equivalent. An iterable (or
|
|
121
120
|
* async iterable) of rows is streamed as one JSON array, each row serialized as it yields; an
|
|
122
121
|
* object is emitted key by key with iterable values streamed as arrays and plain values encoded
|
|
123
122
|
* in place. Useful for serializing large result sets without buffering them.
|
|
@@ -126,7 +125,7 @@ declare class Response {
|
|
|
126
125
|
/** Whether this is a streamed response (flush it with {@link Response.writeStreamTo}). */
|
|
127
126
|
isStream(): boolean;
|
|
128
127
|
/**
|
|
129
|
-
* Register a reusable response builder under `name`. The
|
|
128
|
+
* Register a reusable response builder under `name`. The `Response::macro()` equivalent -
|
|
130
129
|
* application code installs a named factory once and invokes it via {@link Response.callMacro}
|
|
131
130
|
* (`Response.callMacro('caps', text)`). Re-registering a name overwrites the previous macro.
|
|
132
131
|
*/
|
|
@@ -137,8 +136,7 @@ declare class Response {
|
|
|
137
136
|
static mixin(macros: Record<string, ResponseMacro>): void;
|
|
138
137
|
/**
|
|
139
138
|
* Invoke a previously {@link Response.macro registered} macro by name, forwarding `args` and
|
|
140
|
-
* returning the {@link Response} it builds. Throws when no macro is registered under `name
|
|
141
|
-
* `BadMethodCallException` Laravel raises for an unknown macro). Typed pragmatically: callers cast
|
|
139
|
+
* returning the {@link Response} it builds. Throws when no macro is registered under `name`. Typed pragmatically: callers cast
|
|
142
140
|
* `args` to the macro's expected parameters.
|
|
143
141
|
*/
|
|
144
142
|
static callMacro(name: string, ...args: never[]): Response;
|
|
@@ -163,7 +161,7 @@ declare class Response {
|
|
|
163
161
|
/** Retarget this redirect at `fallback` (the previous-URL fallback when no referer is known). */
|
|
164
162
|
back(fallback?: string, status?: number): this;
|
|
165
163
|
/**
|
|
166
|
-
* Queue a flash value (or a whole bag) to survive to the next request. The
|
|
164
|
+
* Queue a flash value (or a whole bag) to survive to the next request. The conventional
|
|
167
165
|
* `redirect()->with('status', 'Saved!')` equivalent: a single `key`/`value` flashes that pair,
|
|
168
166
|
* while passing an object as the sole argument merges every entry. Returns `this` to chain.
|
|
169
167
|
*
|
|
@@ -195,7 +193,7 @@ declare class Response {
|
|
|
195
193
|
/**
|
|
196
194
|
* Flush this response to a Node {@link ServerResponse}: status, headers, cookies, then body.
|
|
197
195
|
* Streamed responses ({@link Response.stream}) must be flushed with the async
|
|
198
|
-
* {@link Response.writeStreamTo} instead
|
|
196
|
+
* {@link Response.writeStreamTo} instead - calling `writeTo` on one throws so a stream is never
|
|
199
197
|
* silently dropped.
|
|
200
198
|
*/
|
|
201
199
|
writeTo(res: ServerResponse): void;
|
|
@@ -227,9 +225,9 @@ declare class UploadedFile {
|
|
|
227
225
|
/** The uploaded bytes, held in memory. */
|
|
228
226
|
private readonly content;
|
|
229
227
|
constructor(init: UploadedFileInit);
|
|
230
|
-
/** The raw uploaded bytes. The `get()` content accessor
|
|
228
|
+
/** The raw uploaded bytes. The `get()` content accessor. */
|
|
231
229
|
get(): Buffer;
|
|
232
|
-
/** The raw uploaded bytes
|
|
230
|
+
/** The raw uploaded bytes - an alias for {@link UploadedFile.get} reading more naturally as bytes. */
|
|
233
231
|
buffer(): Buffer;
|
|
234
232
|
/** The client-supplied original filename. The `$file->getClientOriginalName()` equivalent. */
|
|
235
233
|
getClientOriginalName(): string;
|
|
@@ -243,8 +241,8 @@ declare class UploadedFile {
|
|
|
243
241
|
/** The size of the uploaded content in bytes. The `$file->getSize()` equivalent. */
|
|
244
242
|
getSize(): number;
|
|
245
243
|
/**
|
|
246
|
-
* Whether the upload is valid
|
|
247
|
-
*
|
|
244
|
+
* Whether the upload is valid - here, simply that it carries a non-empty filename. Mirrors the
|
|
245
|
+
* `$file->isValid()` predicate at this layer (no PHP upload-error codes exist in Node).
|
|
248
246
|
*/
|
|
249
247
|
isValid(): boolean;
|
|
250
248
|
/**
|
|
@@ -259,19 +257,19 @@ declare class UploadedFile {
|
|
|
259
257
|
storeAs(directory: string, name: string): string;
|
|
260
258
|
/**
|
|
261
259
|
* Write the upload to the exact file path `destination`, creating its parent directory as needed,
|
|
262
|
-
* and return `destination`. The `$file->move()` equivalent
|
|
260
|
+
* and return `destination`. The `$file->move()` equivalent - the documented filesystem seam.
|
|
263
261
|
*/
|
|
264
262
|
move(destination: string): string;
|
|
265
263
|
/**
|
|
266
|
-
* A unique storage filename preserving the original extension
|
|
267
|
-
*
|
|
264
|
+
* A unique storage filename preserving the original extension - a timestamp/random base, the way
|
|
265
|
+
* the conventional `hashName()` produces a collision-resistant name. Used by {@link UploadedFile.store}.
|
|
268
266
|
*/
|
|
269
267
|
hashName(): string;
|
|
270
268
|
}
|
|
271
269
|
|
|
272
270
|
/**
|
|
273
|
-
* `Request`
|
|
274
|
-
|
|
271
|
+
* `Request` - an immutable wrapper around an inbound HTTP request, the conventional
|
|
272
|
+
*. It normalizes the method, URL, headers, cookies, and a
|
|
275
273
|
* parsed body, and exposes the familiar accessor surface (`input`, `only`, `query`, `bearerToken`,
|
|
276
274
|
* `wantsJson`, …). Instances are immutable: {@link Request.withParams} returns a fresh copy with
|
|
277
275
|
* route parameters attached rather than mutating in place.
|
|
@@ -315,7 +313,7 @@ interface FromNodeOptions {
|
|
|
315
313
|
}
|
|
316
314
|
/**
|
|
317
315
|
* A `413 Payload Too Large`, thrown by {@link Request.fromNode} when an inbound body exceeds the
|
|
318
|
-
* configured cap
|
|
316
|
+
* configured cap - either declared up front by `Content-Length` or discovered while accumulating
|
|
319
317
|
* chunks. The server adapter answers it with a `413` and closes the connection (the unread
|
|
320
318
|
* remainder of the body would poison keep-alive reuse).
|
|
321
319
|
*/
|
|
@@ -331,7 +329,7 @@ declare class Request {
|
|
|
331
329
|
/** Memoized pathname; a {@link isPlainPath plain} target resolves by slicing, sparing `new URL`. */
|
|
332
330
|
private _pathname;
|
|
333
331
|
private _host;
|
|
334
|
-
/** The host as received (port included, if any)
|
|
332
|
+
/** The host as received (port included, if any) - backs {@link Request.httpHost}. */
|
|
335
333
|
private _httpHost;
|
|
336
334
|
/** The matched route's name, attached by the kernel after a successful match (for `routeIs`). */
|
|
337
335
|
private _routeName;
|
|
@@ -354,7 +352,7 @@ declare class Request {
|
|
|
354
352
|
constructor(init?: RequestInit);
|
|
355
353
|
/**
|
|
356
354
|
* Build a {@link Request} from a live Node {@link IncomingMessage}, draining and parsing the body.
|
|
357
|
-
* The
|
|
355
|
+
* The body is buffered
|
|
358
356
|
* up to {@link FromNodeOptions.maxBodyBytes} (default 1 MiB); anything larger rejects with a
|
|
359
357
|
* {@link PayloadTooLargeHttpException} without buffering past the cap.
|
|
360
358
|
*/
|
|
@@ -400,22 +398,22 @@ declare class Request {
|
|
|
400
398
|
*/
|
|
401
399
|
httpHost(): string | undefined;
|
|
402
400
|
/**
|
|
403
|
-
* The scheme plus host (e.g. `https://acme.myapp.com:8080`)
|
|
401
|
+
* The scheme plus host (e.g. `https://acme.myapp.com:8080`) - the `$request->schemeAndHttpHost()`
|
|
404
402
|
* equivalent. The scheme is read from the first `X-Forwarded-Proto` hop, defaulting to `http`
|
|
405
|
-
* (
|
|
403
|
+
* (Plinth's adapter sits on plain `node:http`; a TLS-terminating proxy sets the header).
|
|
406
404
|
* `undefined` when no host is known.
|
|
407
405
|
*/
|
|
408
406
|
schemeAndHttpHost(): string | undefined;
|
|
409
407
|
/** The request scheme: the first `X-Forwarded-Proto` hop, defaulting to `http`. */
|
|
410
408
|
private scheme;
|
|
411
409
|
/**
|
|
412
|
-
* Whether the request arrived over HTTPS
|
|
413
|
-
* `X-Forwarded-Proto` hop (
|
|
410
|
+
* Whether the request arrived over HTTPS - the `$request->isSecure()` equivalent. Reads the first
|
|
411
|
+
* `X-Forwarded-Proto` hop (Plinth sits on plain `node:http` behind a TLS-terminating proxy), so it
|
|
414
412
|
* is the trust-proxy signal a `secure` cookie or HSTS header should gate on.
|
|
415
413
|
*/
|
|
416
414
|
isSecure(): boolean;
|
|
417
415
|
/**
|
|
418
|
-
* The full URL including the query string
|
|
416
|
+
* The full URL including the query string - `scheme://host/path?query` when the host is known,
|
|
419
417
|
* otherwise just `/path?query` (matching {@link Request.url} for host-less synthetic requests).
|
|
420
418
|
* The `$request->fullUrl()` equivalent.
|
|
421
419
|
*/
|
|
@@ -433,7 +431,7 @@ declare class Request {
|
|
|
433
431
|
/** Reassemble the full URL from the current scheme/host/path plus an edited query bag. */
|
|
434
432
|
private rebuildFullUrl;
|
|
435
433
|
/**
|
|
436
|
-
* Whether the request path matches any of the wildcard `patterns`
|
|
434
|
+
* Whether the request path matches any of the wildcard `patterns` - `*` matches any run of
|
|
437
435
|
* characters. Patterns are matched against the path **without** its leading slash (so
|
|
438
436
|
* `req.is('admin/*')` matches `/admin/users`), mirroring `$request->is()`.
|
|
439
437
|
*/
|
|
@@ -478,7 +476,7 @@ declare class Request {
|
|
|
478
476
|
/** Every merged-input key. The `$request->keys()` equivalent. */
|
|
479
477
|
keys(): string[];
|
|
480
478
|
/**
|
|
481
|
-
* Read an input value coerced to a boolean
|
|
479
|
+
* Read an input value coerced to a boolean - `true`/`1`/`'1'`/`'true'`/`'on'`/`'yes'` (strings
|
|
482
480
|
* case-insensitive) are `true`, anything else `false`. When the key is absent, `def` (default
|
|
483
481
|
* `false`) is returned. The `$request->boolean()` equivalent.
|
|
484
482
|
*/
|
|
@@ -496,14 +494,14 @@ declare class Request {
|
|
|
496
494
|
float(key: string, def?: number): number;
|
|
497
495
|
/**
|
|
498
496
|
* Read an input value coerced to a primitive string. When the key is absent, `def` (default `''`)
|
|
499
|
-
* is returned. The
|
|
497
|
+
* is returned. The `$request->string()` equivalent - note this returns a primitive
|
|
500
498
|
* `string` rather than a `Stringable`; wrap it with `@plinthjs/support`'s `Str.of()` for fluent
|
|
501
499
|
* helpers if needed.
|
|
502
500
|
*/
|
|
503
501
|
string(key: string, def?: string): string;
|
|
504
502
|
/**
|
|
505
503
|
* Read an input value if (and only if) it is one of `values`, else `undefined`. Generic over the
|
|
506
|
-
* union of allowed values. The
|
|
504
|
+
* union of allowed values. The `$request->enum()` equivalent (returning the value, not a
|
|
507
505
|
* native enum case). Comparison is by strict equality against the supplied members.
|
|
508
506
|
*/
|
|
509
507
|
enum<T>(key: string, values: readonly T[]): T | undefined;
|
|
@@ -590,7 +588,7 @@ declare class Request {
|
|
|
590
588
|
allFiles(): Record<string, UploadedFile | UploadedFile[]>;
|
|
591
589
|
/**
|
|
592
590
|
* A structural copy carrying route parameters and attributes forward (kept immutable). Every
|
|
593
|
-
* parsed artifact
|
|
591
|
+
* parsed artifact - headers, URL memos, body buffer, parsed/multipart memos - is immutable once
|
|
594
592
|
* built, so clones share it by reference; only the per-clone bags (route params, attributes,
|
|
595
593
|
* bound models, merged input) are copied.
|
|
596
594
|
*/
|
|
@@ -607,7 +605,7 @@ declare class Request {
|
|
|
607
605
|
*/
|
|
608
606
|
withParams(params: Record<string, string>): Request;
|
|
609
607
|
/**
|
|
610
|
-
* Return a copy of this request with an arbitrary attribute attached
|
|
608
|
+
* Return a copy of this request with an arbitrary attribute attached - the `$request->attributes`
|
|
611
609
|
* bag equivalent. Middleware use this to hand request-scoped values (the session, the
|
|
612
610
|
* authenticated user, …) to downstream handlers without mutating the original.
|
|
613
611
|
*/
|
|
@@ -615,7 +613,7 @@ declare class Request {
|
|
|
615
613
|
/** Read a middleware-attached attribute, or `undefined` when absent. */
|
|
616
614
|
attribute<T = unknown>(key: string): T | undefined;
|
|
617
615
|
/**
|
|
618
|
-
* Return a copy of this request with `name` set to `value` (case-insensitive)
|
|
616
|
+
* Return a copy of this request with `name` set to `value` (case-insensitive) - e.g. a `forceJson`
|
|
619
617
|
* middleware setting `Accept: application/json`. The header map is copied (clones normally share it
|
|
620
618
|
* by reference), so the original request is untouched.
|
|
621
619
|
*/
|
|
@@ -628,7 +626,7 @@ declare class Request {
|
|
|
628
626
|
withBoundModels(models: Record<string, unknown>): Request;
|
|
629
627
|
/**
|
|
630
628
|
* The route value for `key`: the resolved bound model when route-model binding applied, otherwise
|
|
631
|
-
* the raw route parameter
|
|
629
|
+
* the raw route parameter. `undefined` when neither exists.
|
|
632
630
|
*/
|
|
633
631
|
route<T = unknown>(key: string): T | undefined;
|
|
634
632
|
/** Read a single route parameter, or `def` when absent. The `$request->route('id')` equivalent. */
|
|
@@ -638,7 +636,7 @@ declare class Request {
|
|
|
638
636
|
}
|
|
639
637
|
|
|
640
638
|
/**
|
|
641
|
-
* HTTP exceptions and the exception handler
|
|
639
|
+
* HTTP exceptions and the exception handler - the conventional
|
|
642
640
|
* `Symfony\Component\HttpKernel\Exception\HttpException` family plus
|
|
643
641
|
* `App\Exceptions\Handler`. {@link HttpException} carries a status code; {@link ExceptionHandler}
|
|
644
642
|
* renders any thrown error into a {@link Response}, negotiating JSON vs. HTML from the request.
|
|
@@ -646,28 +644,28 @@ declare class Request {
|
|
|
646
644
|
|
|
647
645
|
/**
|
|
648
646
|
* Container token for the application's {@link ExceptionHandler}. Bind a custom handler under this
|
|
649
|
-
* token
|
|
650
|
-
* uses it
|
|
647
|
+
* token and {@link HttpKernel} resolves and
|
|
648
|
+
* uses it - `app.singleton(EXCEPTION_HANDLER, () => new MyHandler())`. A symbol token (rather than
|
|
651
649
|
* the {@link ExceptionHandler} class itself) keeps the binding key decoupled, so an app may bind any
|
|
652
650
|
* handler shape without the class participating as a key.
|
|
653
651
|
*/
|
|
654
652
|
declare const EXCEPTION_HANDLER: symbol;
|
|
655
653
|
/**
|
|
656
654
|
* A reportable callback registered via {@link ExceptionHandler.reportable}. Returning `false` halts
|
|
657
|
-
* further reporting of that error (no later reportable callbacks and no default sink run)
|
|
658
|
-
*
|
|
655
|
+
* further reporting of that error (no later reportable callbacks and no default sink run) - the
|
|
656
|
+
* `reportable(fn)->stop()` / `return false` convention. Any other return (including
|
|
659
657
|
* returning nothing) lets reporting continue; the return is `unknown` so void callbacks fit too.
|
|
660
658
|
*/
|
|
661
659
|
type ReportableCallback = (error: unknown) => unknown;
|
|
662
660
|
/**
|
|
663
661
|
* A renderable callback registered via {@link ExceptionHandler.renderable}. Returning a
|
|
664
662
|
* {@link Response} makes {@link ExceptionHandler.render} use it; returning `undefined` falls through
|
|
665
|
-
* to the next renderable, then the default rendering.
|
|
663
|
+
* to the next renderable, then the default rendering.
|
|
666
664
|
*/
|
|
667
665
|
type RenderableCallback = (error: unknown, request?: Request) => Response | undefined;
|
|
668
|
-
/** The terminal report destination
|
|
666
|
+
/** The terminal report destination - where un-stopped errors are sent. The settable log seam. */
|
|
669
667
|
type ReportSink = (error: unknown, context: Record<string, unknown>) => void;
|
|
670
|
-
/** The log severities an exception may be reported at
|
|
668
|
+
/** The log severities an exception may be reported at - the PSR-3 / `level()` levels. */
|
|
671
669
|
type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
|
|
672
670
|
/** A base HTTP error carrying a status code. The `HttpException` equivalent. */
|
|
673
671
|
declare class HttpException extends Error {
|
|
@@ -688,7 +686,7 @@ declare class MethodNotAllowedHttpException extends HttpException {
|
|
|
688
686
|
constructor(allowed?: string[], message?: string);
|
|
689
687
|
}
|
|
690
688
|
/**
|
|
691
|
-
* `ExceptionHandler`
|
|
689
|
+
* `ExceptionHandler` - renders a thrown error to a {@link Response}, the `App\Exceptions\Handler`
|
|
692
690
|
* equivalent. JSON when the request {@link Request.wantsJson wants JSON}, otherwise an HTML page.
|
|
693
691
|
* The handler is deterministic: it derives status and message from the error, never the clock.
|
|
694
692
|
*/
|
|
@@ -700,7 +698,7 @@ declare class ExceptionHandler {
|
|
|
700
698
|
private readonly renderCallbacks;
|
|
701
699
|
/**
|
|
702
700
|
* Error constructors whose instances are not reported. Seeded with {@link HttpException} (an
|
|
703
|
-
* `instanceof` check, so every subclass
|
|
701
|
+
* `instanceof` check, so every subclass - 404/405/… - is covered too), following the usual small
|
|
704
702
|
* internal don't-report list. Extend with {@link ExceptionHandler.ignore} / shrink with
|
|
705
703
|
* {@link ExceptionHandler.stopIgnoring}.
|
|
706
704
|
*/
|
|
@@ -714,7 +712,7 @@ declare class ExceptionHandler {
|
|
|
714
712
|
/** Per-constructor log levels consulted by {@link ExceptionHandler.levelFor}. */
|
|
715
713
|
private readonly levels;
|
|
716
714
|
/**
|
|
717
|
-
* Input keys never flashed back to the session on a validation redirect
|
|
715
|
+
* Input keys never flashed back to the session on a validation redirect - the conventional
|
|
718
716
|
* `$dontFlash` list, seeded with its defaults. `@plinthjs/http` itself has no redirect/flash path,
|
|
719
717
|
* so the list is stored here and exposed via {@link ExceptionHandler.getDontFlash} for the
|
|
720
718
|
* session/validation layer to consume when it re-flashes old input.
|
|
@@ -734,25 +732,24 @@ declare class ExceptionHandler {
|
|
|
734
732
|
statusFor(error: unknown): number;
|
|
735
733
|
/**
|
|
736
734
|
* Map one exception type to another: whenever an instance of `from` reaches the handler, it is
|
|
737
|
-
* first converted via `to` and the *result* is reported and rendered instead. The
|
|
735
|
+
* first converted via `to` and the *result* is reported and rendered instead. The conventional
|
|
738
736
|
* `$exceptions->map(From::class, fn ($e) => new To(..., $e))` equivalent. Mappings are checked in
|
|
739
|
-
* registration order; the first `instanceof` match applies (once
|
|
737
|
+
* registration order; the first `instanceof` match applies (once - the mapped error is not
|
|
740
738
|
* re-mapped). Chains.
|
|
741
739
|
*/
|
|
742
740
|
map<T>(from: Newable<T>, to: (error: T) => unknown): this;
|
|
743
741
|
/** Apply the first matching {@link ExceptionHandler.map} mapping to `error`, if any. */
|
|
744
742
|
mapException(error: unknown): unknown;
|
|
745
743
|
/**
|
|
746
|
-
* Set the log level instances of `ctor` are reported at
|
|
747
|
-
* `$exceptions->level(Type::class, LogLevel::WARNING)` equivalent. The level is surfaced as the
|
|
744
|
+
* Set the log level instances of `ctor` are reported at. The level is surfaced as the
|
|
748
745
|
* `level` key of the context passed to the {@link ReportSink}. Chains.
|
|
749
746
|
*/
|
|
750
747
|
level(ctor: Newable, logLevel: LogLevel): this;
|
|
751
748
|
/** The log level `error` reports at: the first registered `instanceof` match, else `'error'`. */
|
|
752
749
|
levelFor(error: unknown): LogLevel;
|
|
753
750
|
/**
|
|
754
|
-
* Replace the list of input keys that must never be flashed back on a validation redirect
|
|
755
|
-
*
|
|
751
|
+
* Replace the list of input keys that must never be flashed back on a validation redirect - the
|
|
752
|
+
* `$exceptions->dontFlash([...])` equivalent. Defaults to `current_password`, `password`,
|
|
756
753
|
* and `password_confirmation`. There is no redirect/flash path inside `@plinthjs/http`, so the list
|
|
757
754
|
* is exposed via {@link ExceptionHandler.getDontFlash} for the session/validation layer that
|
|
758
755
|
* re-flashes old input. Chains.
|
|
@@ -766,30 +763,29 @@ declare class ExceptionHandler {
|
|
|
766
763
|
*/
|
|
767
764
|
reportable(callback: ReportableCallback): this;
|
|
768
765
|
/**
|
|
769
|
-
* Add error constructors to the don't-report list
|
|
770
|
-
* equivalent). Matching is by `instanceof`, so a base class also suppresses its subclasses. Chains.
|
|
766
|
+
* Add error constructors to the don't-report list. Matching is by `instanceof`, so a base class also suppresses its subclasses. Chains.
|
|
771
767
|
*/
|
|
772
768
|
ignore(...classes: Newable[]): this;
|
|
773
|
-
/** Alias of {@link ExceptionHandler.ignore}
|
|
769
|
+
/** Alias of {@link ExceptionHandler.ignore} - the `$dontReport` spelling. */
|
|
774
770
|
dontReport(...classes: Newable[]): this;
|
|
775
|
-
/** Remove error constructors from the don't-report list.
|
|
771
|
+
/** Remove error constructors from the don't-report list. */
|
|
776
772
|
stopIgnoring(...classes: Newable[]): this;
|
|
777
773
|
/** Whether `error` should be reported: `false` when it (or a superclass) is in the ignore list. */
|
|
778
774
|
shouldReport(error: unknown): boolean;
|
|
779
|
-
/** Replace the terminal report sink (the logger seam).
|
|
775
|
+
/** Replace the terminal report sink (the logger seam). */
|
|
780
776
|
reportUsing(sink: ReportSink): this;
|
|
781
777
|
/** De-duplicate reports: the same error instance is reported at most once. The `withoutDuplicates()` flag. */
|
|
782
778
|
withoutDuplicates(): this;
|
|
783
779
|
/**
|
|
784
780
|
* A hook for additional report context, merged into every report. Override in a subclass to attach
|
|
785
|
-
* request-scoped data (user id, etc.).
|
|
781
|
+
* request-scoped data (user id, etc.).
|
|
786
782
|
*/
|
|
787
783
|
context(): Record<string, unknown>;
|
|
788
784
|
/**
|
|
789
785
|
* Report `error`: if {@link ExceptionHandler.shouldReport} and not a duplicate (when
|
|
790
|
-
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order
|
|
791
|
-
* `false` return stops the chain (the default sink is skipped)
|
|
792
|
-
* terminal sink.
|
|
786
|
+
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order - a
|
|
787
|
+
* `false` return stops the chain (the default sink is skipped) - otherwise fall through to the
|
|
788
|
+
* terminal sink.
|
|
793
789
|
*/
|
|
794
790
|
report(error: unknown): void;
|
|
795
791
|
/** Register a renderable callback, tried first by {@link ExceptionHandler.render}. Chains. */
|
|
@@ -805,7 +801,7 @@ declare class ExceptionHandler {
|
|
|
805
801
|
}
|
|
806
802
|
|
|
807
803
|
/**
|
|
808
|
-
* Middleware
|
|
804
|
+
* Middleware - the conventional, API-driven HTTP middleware stack. A
|
|
809
805
|
* {@link Middleware} receives the {@link Request} and a `next` continuation, and either calls
|
|
810
806
|
* `next` (passing control inward) or returns a {@link Response} directly to short-circuit.
|
|
811
807
|
* {@link runMiddleware} composes a stack around a final handler; {@link isTerminable} /
|
|
@@ -816,8 +812,7 @@ declare class ExceptionHandler {
|
|
|
816
812
|
type Next = (req: Request) => Promise<Response>;
|
|
817
813
|
/**
|
|
818
814
|
* An HTTP middleware. Call `next(req)` to continue (optionally with a modified request), or return
|
|
819
|
-
* a {@link Response} without calling `next` to short-circuit the stack.
|
|
820
|
-
* `handle($request, Closure $next)` equivalent.
|
|
815
|
+
* a {@link Response} without calling `next` to short-circuit the stack.
|
|
821
816
|
*/
|
|
822
817
|
type Middleware = (req: Request, next: Next) => Promise<Response>;
|
|
823
818
|
/** A middleware that also wants a post-response `terminate()` callback (e.g. session save). */
|
|
@@ -840,7 +835,7 @@ type MiddlewareReference = MiddlewareEntry | string;
|
|
|
840
835
|
declare function isTerminable(entry: MiddlewareEntry): entry is TerminableMiddleware;
|
|
841
836
|
/**
|
|
842
837
|
* Compose `stack` around `destination`, running the middleware left-to-right (outermost first) and
|
|
843
|
-
* returning the resulting {@link Response}. Equivalent to passing the request through
|
|
838
|
+
* returning the resulting {@link Response}. Equivalent to passing the request through the conventional
|
|
844
839
|
* `Pipeline`. A middleware that returns without calling `next` short-circuits everything inward.
|
|
845
840
|
*/
|
|
846
841
|
declare function runMiddleware(req: Request, stack: MiddlewareEntry[], destination: Next): Promise<Response>;
|
|
@@ -851,15 +846,14 @@ declare function runMiddleware(req: Request, stack: MiddlewareEntry[], destinati
|
|
|
851
846
|
declare function terminateMiddleware(req: Request, res: Response, stack: readonly MiddlewareEntry[]): Promise<void>;
|
|
852
847
|
|
|
853
848
|
/**
|
|
854
|
-
* `Router`
|
|
849
|
+
* `Router` - registration and matching of HTTP routes, the conventional API
|
|
855
850
|
* equivalent. Routes carry a method set, a path pattern (`/users/{id}`, optional `{id?}`), an
|
|
856
851
|
* optional name, and per-route middleware. {@link Router.group} applies a shared prefix and
|
|
857
852
|
* middleware to everything registered inside it; {@link Router.match} resolves an inbound
|
|
858
853
|
* method+path to a {@link Route} (with extracted parameters), a 405 (method not allowed), or a 404.
|
|
859
854
|
*
|
|
860
855
|
* It also generates signed URLs ({@link Router.signedUrl}) and validates them
|
|
861
|
-
* ({@link Router.hasValidSignature}, {@link Router.signedMiddleware})
|
|
862
|
-
* `URL::signedRoute()` / `$request->hasValidSignature()` equivalent, built on an HMAC over a
|
|
856
|
+
* ({@link Router.hasValidSignature}, {@link Router.signedMiddleware}), built on an HMAC over a
|
|
863
857
|
* {@link Router.setSigningKey configured} secret.
|
|
864
858
|
*/
|
|
865
859
|
|
|
@@ -880,19 +874,18 @@ type RouteHandlerClosure = (req: Request) => RouteResult | Promise<RouteResult>;
|
|
|
880
874
|
/** A controller action: a class plus the method name to invoke, resolved via the container. */
|
|
881
875
|
type ControllerAction = readonly [controller: Newable, method: string];
|
|
882
876
|
/**
|
|
883
|
-
* A single-action ("invokable") controller reference
|
|
877
|
+
* A single-action ("invokable") controller reference - a controller class on its own, or a
|
|
884
878
|
* one-element `[Controller]` tuple. The kernel resolves the instance via the container and calls its
|
|
885
|
-
* `__invoke` method.
|
|
886
|
-
* equivalent.
|
|
879
|
+
* `__invoke` method.
|
|
887
880
|
*/
|
|
888
881
|
type InvokableAction = Newable | readonly [controller: Newable];
|
|
889
882
|
/**
|
|
890
883
|
* Either supported handler form: a closure, a `[Controller, method]` pair, or an
|
|
891
|
-
* {@link InvokableAction} (a controller class
|
|
884
|
+
* {@link InvokableAction} (a controller class - or `[Controller]` - whose `__invoke` is called).
|
|
892
885
|
*/
|
|
893
886
|
type RouteHandler = RouteHandlerClosure | ControllerAction | InvokableAction;
|
|
894
887
|
/**
|
|
895
|
-
* Resolves a route-bound parameter to a value (typically a model)
|
|
888
|
+
* Resolves a route-bound parameter to a value (typically a model) - the `Route::bind`
|
|
896
889
|
* resolver. May return synchronously or as a `Promise` (both covered by `unknown`); returning
|
|
897
890
|
* `null`/`undefined` makes the route a 404 (implicit-binding "not found").
|
|
898
891
|
*/
|
|
@@ -901,12 +894,12 @@ type BindingResolver = (value: string, req: Request) => unknown;
|
|
|
901
894
|
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
|
|
902
895
|
/**
|
|
903
896
|
* A route-parameter constraint: a regex pattern (string or `RegExp`) the parameter's value must
|
|
904
|
-
* fully match for the route to match.
|
|
897
|
+
* fully match for the route to match.
|
|
905
898
|
*/
|
|
906
899
|
type WherePattern = string | RegExp;
|
|
907
900
|
/**
|
|
908
|
-
* A renderer the {@link Router} defers {@link Router.view} routes to
|
|
909
|
-
* data bag, and the request, it produces the HTML string. The
|
|
901
|
+
* A renderer the {@link Router} defers {@link Router.view} routes to - given the view name, the
|
|
902
|
+
* data bag, and the request, it produces the HTML string. The usual view-factory seam: `@plinthjs/http`
|
|
910
903
|
* has no templating, so the app (or `@plinthjs/view`-style package) installs one via
|
|
911
904
|
* {@link Router.renderViewsUsing} or the `viewRenderer` {@link RouterOptions construction option}.
|
|
912
905
|
*/
|
|
@@ -915,7 +908,7 @@ type ViewRenderer = (view: string, data: Record<string, unknown>, req: Request)
|
|
|
915
908
|
interface RouteGroupOptions {
|
|
916
909
|
prefix?: string;
|
|
917
910
|
/**
|
|
918
|
-
* Parameter constraints applied to every route registered inside the group
|
|
911
|
+
* Parameter constraints applied to every route registered inside the group - the conventional
|
|
919
912
|
* `Route::group(['where' => [...]])` / group-level `pattern` equivalent. A route's own
|
|
920
913
|
* {@link Route.where} for the same parameter overrides the group's.
|
|
921
914
|
*/
|
|
@@ -923,12 +916,12 @@ interface RouteGroupOptions {
|
|
|
923
916
|
/**
|
|
924
917
|
* Shared middleware for every route in the group. Accepts concrete entries (function/class) and
|
|
925
918
|
* `string` names referencing a registered alias or middleware group; names are resolved when a
|
|
926
|
-
* matched route's stack is assembled.
|
|
919
|
+
* matched route's stack is assembled.
|
|
927
920
|
*/
|
|
928
921
|
middleware?: MiddlewareReference | MiddlewareReference[];
|
|
929
922
|
/**
|
|
930
923
|
* A host pattern (e.g. `{account}.myapp.com`) constraining every route in the group. When groups
|
|
931
|
-
* nest, the innermost `domain` wins.
|
|
924
|
+
* nest, the innermost `domain` wins.
|
|
932
925
|
*/
|
|
933
926
|
domain?: string;
|
|
934
927
|
}
|
|
@@ -944,7 +937,7 @@ type RouteMatch = {
|
|
|
944
937
|
readonly type: 'not-found';
|
|
945
938
|
};
|
|
946
939
|
/**
|
|
947
|
-
* A single route in a {@link RouteCache} snapshot
|
|
940
|
+
* A single route in a {@link RouteCache} snapshot - a plain, JSON-serializable description of a
|
|
948
941
|
* registered route. The handler is recorded as a `[controllerName, method]` pair (closures cannot
|
|
949
942
|
* be serialized; see {@link Router.toCache}), and middleware are recorded by name only.
|
|
950
943
|
*/
|
|
@@ -953,12 +946,12 @@ interface CachedRoute {
|
|
|
953
946
|
readonly path: string;
|
|
954
947
|
readonly name: string | undefined;
|
|
955
948
|
readonly domain: string | undefined;
|
|
956
|
-
/** Middleware names (function/class names)
|
|
949
|
+
/** Middleware names (function/class names) - recorded for inspection and optional rehydration. */
|
|
957
950
|
readonly middleware: readonly string[];
|
|
958
951
|
/** The controller class name and method invoked for this route. */
|
|
959
952
|
readonly action: readonly [controller: string, method: string];
|
|
960
953
|
}
|
|
961
|
-
/** A JSON-serializable snapshot of a {@link Router}'s routes
|
|
954
|
+
/** A JSON-serializable snapshot of a {@link Router}'s routes - the `route:cache` artifact. */
|
|
962
955
|
interface RouteCache {
|
|
963
956
|
readonly routes: readonly CachedRoute[];
|
|
964
957
|
}
|
|
@@ -977,7 +970,7 @@ interface LoadCacheOptions {
|
|
|
977
970
|
*/
|
|
978
971
|
middleware?: MiddlewareResolver;
|
|
979
972
|
}
|
|
980
|
-
/** Why a signature failed to validate, or `'valid'`
|
|
973
|
+
/** Why a signature failed to validate, or `'valid'` - surfaced by {@link Router.validateSignature}. */
|
|
981
974
|
type SignatureResult = 'valid' | 'missing' | 'invalid' | 'expired';
|
|
982
975
|
/** A single registered route. Builder methods ({@link Route.name}, {@link Route.middleware}) chain. */
|
|
983
976
|
declare class Route {
|
|
@@ -1008,29 +1001,27 @@ declare class Route {
|
|
|
1008
1001
|
/** This route's domain pattern, or `undefined` when it matches any host. */
|
|
1009
1002
|
getDomain(): string | undefined;
|
|
1010
1003
|
/**
|
|
1011
|
-
* Match a request `host` against this route's domain. Returns the extracted domain params (
|
|
1012
|
-
* empty object when the route has no domain — a domain-less route matches any host, mirroring
|
|
1013
|
-
* Laravel), or `undefined` when the route has a domain that the host does not satisfy (including
|
|
1004
|
+
* Match a request `host` against this route's domain. Returns the extracted domain params, or `undefined` when the route has a domain that the host does not satisfy (including
|
|
1014
1005
|
* when the route requires a domain but no host was supplied).
|
|
1015
1006
|
*/
|
|
1016
1007
|
matchDomain(host: string | undefined): Record<string, string> | undefined;
|
|
1017
1008
|
/**
|
|
1018
|
-
* Constrain route parameter(s) to a regex pattern
|
|
1009
|
+
* Constrain route parameter(s) to a regex pattern. Accepts a
|
|
1019
1010
|
* single `param`/`pattern` pair or a `{ param: pattern }` record; patterns are strings or
|
|
1020
1011
|
* `RegExp`s, anchored so the **whole** parameter value must match. A non-matching value makes this
|
|
1021
1012
|
* route not match at all, so the request falls through to later routes (or a 404). Chains.
|
|
1022
1013
|
*/
|
|
1023
1014
|
where(param: string, pattern: WherePattern): this;
|
|
1024
1015
|
where(patterns: Record<string, WherePattern>): this;
|
|
1025
|
-
/** Constrain `param` to digits only.
|
|
1016
|
+
/** Constrain `param` to digits only. Chains. */
|
|
1026
1017
|
whereNumber(param: string): this;
|
|
1027
|
-
/** Constrain `param` to ASCII letters only.
|
|
1018
|
+
/** Constrain `param` to ASCII letters only. Chains. */
|
|
1028
1019
|
whereAlpha(param: string): this;
|
|
1029
|
-
/** Constrain `param` to letters and digits.
|
|
1020
|
+
/** Constrain `param` to letters and digits. Chains. */
|
|
1030
1021
|
whereAlphaNumeric(param: string): this;
|
|
1031
|
-
/** Constrain `param` to a UUID shape.
|
|
1022
|
+
/** Constrain `param` to a UUID shape. Chains. */
|
|
1032
1023
|
whereUuid(param: string): this;
|
|
1033
|
-
/** Constrain `param` to a ULID shape.
|
|
1024
|
+
/** Constrain `param` to a ULID shape. Chains. */
|
|
1034
1025
|
whereUlid(param: string): this;
|
|
1035
1026
|
/** Constrain `param` to one of `values` (matched literally). The `->whereIn()` equivalent. Chains. */
|
|
1036
1027
|
whereIn(param: string, values: readonly string[]): this;
|
|
@@ -1041,7 +1032,7 @@ declare class Route {
|
|
|
1041
1032
|
*/
|
|
1042
1033
|
middleware(...entries: MiddlewareReference[]): this;
|
|
1043
1034
|
/**
|
|
1044
|
-
* The middleware stack for this route (a copy), as registered
|
|
1035
|
+
* The middleware stack for this route (a copy), as registered - so `string` alias/group names are
|
|
1045
1036
|
* returned verbatim. The {@link Router} resolves these to concrete entries via
|
|
1046
1037
|
* {@link Router.resolveMiddleware} when dispatching a matched route.
|
|
1047
1038
|
*/
|
|
@@ -1067,20 +1058,20 @@ type ResourceMethod = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update'
|
|
|
1067
1058
|
* may be further narrowed/renamed by chaining.
|
|
1068
1059
|
*/
|
|
1069
1060
|
interface ResourceOptions {
|
|
1070
|
-
/** Register only these resource methods (others are skipped).
|
|
1061
|
+
/** Register only these resource methods (others are skipped). */
|
|
1071
1062
|
only?: readonly ResourceMethod[];
|
|
1072
|
-
/** Register every resource method except these.
|
|
1063
|
+
/** Register every resource method except these. */
|
|
1073
1064
|
except?: readonly ResourceMethod[];
|
|
1074
|
-
/** Override the generated route name for specific methods.
|
|
1065
|
+
/** Override the generated route name for specific methods. */
|
|
1075
1066
|
names?: Partial<Record<ResourceMethod, string>>;
|
|
1076
1067
|
/**
|
|
1077
1068
|
* Override the URI parameter name(s). A single string renames the resource's one parameter; a map
|
|
1078
|
-
* renames per resource-name key (for nested resources).
|
|
1069
|
+
* renames per resource-name key (for nested resources).
|
|
1079
1070
|
*/
|
|
1080
1071
|
parameters?: string | Record<string, string>;
|
|
1081
1072
|
/**
|
|
1082
1073
|
* Scope nested-resource child URIs to only the trailing parameter (and prefix it with the resource
|
|
1083
|
-
* name) for `show`/`edit`/`update`/`destroy`.
|
|
1074
|
+
* name) for `show`/`edit`/`update`/`destroy`.
|
|
1084
1075
|
*/
|
|
1085
1076
|
shallow?: boolean;
|
|
1086
1077
|
}
|
|
@@ -1092,12 +1083,12 @@ interface ResourceContext {
|
|
|
1092
1083
|
readonly where: Record<string, WherePattern>;
|
|
1093
1084
|
}
|
|
1094
1085
|
/**
|
|
1095
|
-
* A pending resource-route registration
|
|
1096
|
-
* {@link Router.apiResource}, the
|
|
1086
|
+
* A pending resource-route registration - the builder returned by {@link Router.resource} /
|
|
1087
|
+
* {@link Router.apiResource}, the `PendingResourceRegistration` equivalent. Routes are not
|
|
1097
1088
|
* created when this is returned; instead the registration is **deferred** and finalized (built into
|
|
1098
1089
|
* real {@link Route}s) the first time the owning {@link Router} is matched, enumerated, has a named
|
|
1099
1090
|
* URL generated, or is cached. This lets `.only()` / `.except()` / `.names()` / `.parameters()` /
|
|
1100
|
-
* `.shallow()` be chained after the call and still take effect
|
|
1091
|
+
* `.shallow()` be chained after the call and still take effect - each just narrows/renames config,
|
|
1101
1092
|
* then returns `this`. The group prefix/middleware/domain in force when {@link Router.resource} was
|
|
1102
1093
|
* called are captured up-front, so deferred building still honors the enclosing group.
|
|
1103
1094
|
*
|
|
@@ -1139,11 +1130,11 @@ declare class ResourceRegistration {
|
|
|
1139
1130
|
*/
|
|
1140
1131
|
private buildRoute;
|
|
1141
1132
|
}
|
|
1142
|
-
/** The singleton-resource methods.
|
|
1133
|
+
/** The singleton-resource methods. */
|
|
1143
1134
|
type SingletonMethod = 'show' | 'edit' | 'update' | 'destroy';
|
|
1144
1135
|
/**
|
|
1145
|
-
* A pending singleton-resource registration
|
|
1146
|
-
* {@link Router.apiSingleton}, the
|
|
1136
|
+
* A pending singleton-resource registration - the builder returned by {@link Router.singleton} /
|
|
1137
|
+
* {@link Router.apiSingleton}, the `PendingSingletonResourceRegistration` equivalent. A
|
|
1147
1138
|
* singleton resource has exactly one instance per context (a profile, a thumbnail), so no `index`,
|
|
1148
1139
|
* `create`/`store`, or `{param}` segment is registered:
|
|
1149
1140
|
*
|
|
@@ -1165,7 +1156,7 @@ declare class SingletonRegistration {
|
|
|
1165
1156
|
private isDestroyable;
|
|
1166
1157
|
private builtRoutes;
|
|
1167
1158
|
constructor(resourceName: string, controller: Newable, api: boolean, context: ResourceContext, register: (route: Route) => void);
|
|
1168
|
-
/** Also register `DELETE name` → `destroy`.
|
|
1159
|
+
/** Also register `DELETE name` → `destroy`. Chains. */
|
|
1169
1160
|
destroyable(value?: boolean): this;
|
|
1170
1161
|
/** Build (once) and register every selected route, returning them. Idempotent. */
|
|
1171
1162
|
resolve(): Route[];
|
|
@@ -1201,12 +1192,12 @@ declare class Router {
|
|
|
1201
1192
|
/** Register a route for an explicit set of verbs. The `Route::match()` equivalent. */
|
|
1202
1193
|
on(methods: HttpMethod[], path: string, handler: RouteHandler): Route;
|
|
1203
1194
|
/**
|
|
1204
|
-
* Install the renderer {@link Router.view} routes defer to
|
|
1205
|
-
* plugs its template engine into.
|
|
1195
|
+
* Install the renderer {@link Router.view} routes defer to - the seam an app (or a view package)
|
|
1196
|
+
* plugs its template engine into. Chains.
|
|
1206
1197
|
*/
|
|
1207
1198
|
renderViewsUsing(renderer: ViewRenderer): this;
|
|
1208
1199
|
/**
|
|
1209
|
-
* Register a `GET` route that renders `view` with `data
|
|
1200
|
+
* Register a `GET` route that renders `view` with `data`.
|
|
1210
1201
|
* `@plinthjs/http` ships no template engine, so rendering is deferred to the {@link ViewRenderer}
|
|
1211
1202
|
* configured via {@link Router.renderViewsUsing} (or the `viewRenderer` construction option);
|
|
1212
1203
|
* dispatching the route without one throws a clear error. The renderer's string becomes an HTML
|
|
@@ -1215,14 +1206,14 @@ declare class Router {
|
|
|
1215
1206
|
view(uri: string, view: string, data?: Record<string, unknown>): Route;
|
|
1216
1207
|
/**
|
|
1217
1208
|
* Register a route answering every verb with a redirect to `destination` (default `302`). The
|
|
1218
|
-
*
|
|
1209
|
+
* `Route::redirect()` equivalent.
|
|
1219
1210
|
*/
|
|
1220
1211
|
redirect(uri: string, destination: string, status?: number): Route;
|
|
1221
|
-
/** Register a `301` redirect route.
|
|
1212
|
+
/** Register a `301` redirect route. */
|
|
1222
1213
|
permanentRedirect(uri: string, destination: string): Route;
|
|
1223
1214
|
/**
|
|
1224
1215
|
* Register the seven canonical RESTful routes for `controller` under `name`, mapping each verb+URI
|
|
1225
|
-
* to a controller method
|
|
1216
|
+
* to a controller method:
|
|
1226
1217
|
*
|
|
1227
1218
|
* - `GET name` → `index` (`name.index`)
|
|
1228
1219
|
* - `GET name/create` → `create` (`name.create`)
|
|
@@ -1243,23 +1234,21 @@ declare class Router {
|
|
|
1243
1234
|
resource(name: string, controller: Newable, options?: ResourceOptions): ResourceRegistration;
|
|
1244
1235
|
/**
|
|
1245
1236
|
* Like {@link Router.resource} but for APIs: registers the same routes minus `create` and `edit`
|
|
1246
|
-
* (the HTML form-presenting endpoints).
|
|
1237
|
+
* (the HTML form-presenting endpoints).
|
|
1247
1238
|
*/
|
|
1248
1239
|
apiResource(name: string, controller: Newable, options?: ResourceOptions): ResourceRegistration;
|
|
1249
1240
|
/** Shared builder for {@link Router.resource} / {@link Router.apiResource}. */
|
|
1250
1241
|
private registerResource;
|
|
1251
1242
|
/**
|
|
1252
|
-
* Register a singleton resource
|
|
1243
|
+
* Register a singleton resource - routes for a resource with exactly one instance (a profile, a
|
|
1253
1244
|
* settings page), mapping `GET name` → `show`, `GET name/edit` → `edit`, and `PUT|PATCH name` →
|
|
1254
|
-
* `update` (no `{param}` segment, no `index`/`create`/`store`).
|
|
1255
|
-
* equivalent. Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
1245
|
+
* `update` (no `{param}` segment, no `index`/`create`/`store`). Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
1256
1246
|
* Registration is deferred exactly like {@link Router.resource}.
|
|
1257
1247
|
*/
|
|
1258
1248
|
singleton(name: string, controller: Newable): SingletonRegistration;
|
|
1259
1249
|
/**
|
|
1260
1250
|
* Like {@link Router.singleton} but for APIs: omits the HTML `edit` route, registering only
|
|
1261
|
-
* `show` and `update` (plus `destroy` after `.destroyable()`).
|
|
1262
|
-
* `Route::apiSingleton()` equivalent.
|
|
1251
|
+
* `show` and `update` (plus `destroy` after `.destroyable()`).
|
|
1263
1252
|
*/
|
|
1264
1253
|
apiSingleton(name: string, controller: Newable): SingletonRegistration;
|
|
1265
1254
|
/** Shared builder for {@link Router.singleton} / {@link Router.apiSingleton}. */
|
|
@@ -1284,15 +1273,15 @@ declare class Router {
|
|
|
1284
1273
|
/** The binding resolver registered for `key`, if any. */
|
|
1285
1274
|
binding(key: string): BindingResolver | undefined;
|
|
1286
1275
|
/**
|
|
1287
|
-
* Register a named middleware *group*
|
|
1276
|
+
* Register a named middleware *group* - a list of references (concrete entries and/or other
|
|
1288
1277
|
* alias/group names) that expand in place wherever the group name is used on a route or group. The
|
|
1289
|
-
*
|
|
1278
|
+
* `Route::middlewareGroup('web', [...])` equivalent. Re-registering a name replaces it.
|
|
1290
1279
|
* Names are resolved (recursively) at match time by {@link Router.resolveMiddleware}.
|
|
1291
1280
|
*/
|
|
1292
1281
|
middlewareGroup(name: string, entries: MiddlewareReference[]): this;
|
|
1293
1282
|
/**
|
|
1294
|
-
* Register a middleware *alias*
|
|
1295
|
-
*
|
|
1283
|
+
* Register a middleware *alias* - a short `string` name for a single concrete {@link MiddlewareEntry}.
|
|
1284
|
+
*
|
|
1296
1285
|
* Re-registering a name replaces it.
|
|
1297
1286
|
*/
|
|
1298
1287
|
aliasMiddleware(name: string, entry: MiddlewareEntry): this;
|
|
@@ -1306,7 +1295,7 @@ declare class Router {
|
|
|
1306
1295
|
/**
|
|
1307
1296
|
* Resolve a middleware reference list to concrete {@link MiddlewareEntry entries}, expanding
|
|
1308
1297
|
* `string` names: a name resolves first as an **alias** (→ its single entry), else as a **group**
|
|
1309
|
-
* (→ its references, expanded recursively). An unknown name **throws
|
|
1298
|
+
* (→ its references, expanded recursively). An unknown name **throws**, which
|
|
1310
1299
|
* raises when a route references a middleware that is neither an alias nor a group. Cyclic group
|
|
1311
1300
|
* references (a group that, directly or transitively, contains itself) also throw rather than
|
|
1312
1301
|
* recursing without bound. Function/class entries pass through unchanged and in order.
|
|
@@ -1319,7 +1308,7 @@ declare class Router {
|
|
|
1319
1308
|
* Recursive worker for {@link Router.resolveMiddleware}. `groupPath` is the stack of group names
|
|
1320
1309
|
* currently being expanded; revisiting a name already on the path is a cycle (a group that
|
|
1321
1310
|
* directly or transitively contains itself) and throws. The same group may still appear in
|
|
1322
|
-
* sibling branches
|
|
1311
|
+
* sibling branches - only re-entrancy along a single path is rejected.
|
|
1323
1312
|
*/
|
|
1324
1313
|
private expandMiddleware;
|
|
1325
1314
|
/** Every registered route (a copy). Pending resource registrations are materialized first. */
|
|
@@ -1328,8 +1317,8 @@ declare class Router {
|
|
|
1328
1317
|
* Serialize the registered routes to a plain, JSON-serializable {@link RouteCache} snapshot
|
|
1329
1318
|
* (methods, path, name, domain, middleware names, and the `[controller, method]` action).
|
|
1330
1319
|
*
|
|
1331
|
-
* Closures cannot be serialized. Mirroring
|
|
1332
|
-
* "Unable to prepare route … for serialization. Uses Closure."
|
|
1320
|
+
* Closures cannot be serialized. Mirroring the conventional `route:cache` - which aborts with
|
|
1321
|
+
* "Unable to prepare route … for serialization. Uses Closure." - this **throws** when any route
|
|
1333
1322
|
* uses a closure handler, rather than silently dropping it, so a cache is always complete or
|
|
1334
1323
|
* absent. Rehydrate with {@link Router.loadCache} or {@link Router.fromCache}.
|
|
1335
1324
|
*/
|
|
@@ -1365,14 +1354,14 @@ declare class Router {
|
|
|
1365
1354
|
/** The configured signing key, asserting one is set (signing without a key is a programmer error). */
|
|
1366
1355
|
private requireKey;
|
|
1367
1356
|
/**
|
|
1368
|
-
* Build a signed URL for the named route. The
|
|
1357
|
+
* Build a signed URL for the named route. The `URL::signedRoute()` equivalent: the route
|
|
1369
1358
|
* URL is generated as usual, an optional `expires` (a {@link Date} or unix-seconds number) is
|
|
1370
1359
|
* appended, and an HMAC `signature` over the canonical URL is added last. Verify it later with
|
|
1371
1360
|
* {@link Router.hasValidSignature}.
|
|
1372
1361
|
*/
|
|
1373
1362
|
signedUrl(name: string, params?: Record<string, string | number>, expiresAt?: Date | number, query?: Record<string, string | number>): string;
|
|
1374
1363
|
/**
|
|
1375
|
-
* Build a signed URL that expires after `expiresIn` seconds from now. The
|
|
1364
|
+
* Build a signed URL that expires after `expiresIn` seconds from now. The conventional
|
|
1376
1365
|
* `URL::temporarySignedRoute()` equivalent (with the expiry expressed in seconds rather than a
|
|
1377
1366
|
* `DateTime`/minutes).
|
|
1378
1367
|
*/
|
|
@@ -1390,15 +1379,14 @@ declare class Router {
|
|
|
1390
1379
|
*/
|
|
1391
1380
|
hasValidSignature(req: Request): boolean;
|
|
1392
1381
|
/**
|
|
1393
|
-
* A middleware that aborts unsigned/invalid/expired requests with a `403
|
|
1394
|
-
* `signed` / `ValidateSignature` middleware). On a valid signature it passes control inward.
|
|
1382
|
+
* A middleware that aborts unsigned/invalid/expired requests with a `403`. On a valid signature it passes control inward.
|
|
1395
1383
|
*/
|
|
1396
1384
|
signedMiddleware(): Middleware;
|
|
1397
1385
|
private addRoute;
|
|
1398
1386
|
}
|
|
1399
1387
|
|
|
1400
1388
|
/**
|
|
1401
|
-
* `HttpKernel`
|
|
1389
|
+
* `HttpKernel` - the request lifecycle.
|
|
1402
1390
|
* {@link HttpKernel.handle} runs a request through the global middleware stack, matches it against
|
|
1403
1391
|
* the {@link Router}, runs any route middleware, invokes the handler (resolving controller classes
|
|
1404
1392
|
* through the `@plinthjs/core` container), and coerces the result to a {@link Response}.
|
|
@@ -1443,8 +1431,7 @@ declare class HttpKernel {
|
|
|
1443
1431
|
*/
|
|
1444
1432
|
getExceptionHandler(): ExceptionHandler;
|
|
1445
1433
|
/**
|
|
1446
|
-
* Report `error
|
|
1447
|
-
* also isolates reporting from rendering), then render it to a {@link Response}. Used at both
|
|
1434
|
+
* Report `error`, then render it to a {@link Response}. Used at both
|
|
1448
1435
|
* pipeline catch sites so every thrown error is both reported and rendered.
|
|
1449
1436
|
*/
|
|
1450
1437
|
private reportThenRender;
|
|
@@ -1454,7 +1441,7 @@ declare class HttpKernel {
|
|
|
1454
1441
|
* The composed pipeline for `route` (its resolved middleware stack ending in the route action).
|
|
1455
1442
|
* Cached per route so alias/group resolution and closure composition happen once, not per
|
|
1456
1443
|
* request. A cached entry is reused only while the route's reference list is unchanged
|
|
1457
|
-
* ({@link sameReferences}
|
|
1444
|
+
* ({@link sameReferences} - `route.middleware(...)` can append after registration), and stacks
|
|
1458
1445
|
* containing `string` references are never cached: their alias/group registrations live in
|
|
1459
1446
|
* mutable router registries and must be re-resolved each dispatch.
|
|
1460
1447
|
*/
|
|
@@ -1538,15 +1525,15 @@ interface GracefulShutdownOptions {
|
|
|
1538
1525
|
signals?: readonly NodeJS.Signals[];
|
|
1539
1526
|
/** Milliseconds to wait for in-flight requests before forcing exit. Default `10000`. */
|
|
1540
1527
|
timeout?: number;
|
|
1541
|
-
/** Run after the server stops accepting and before exit
|
|
1528
|
+
/** Run after the server stops accepting and before exit - close DB pools, flush logs, etc. */
|
|
1542
1529
|
onShutdown?: () => void | Promise<void>;
|
|
1543
1530
|
/** Exit hook (override in tests). Default `process.exit`. */
|
|
1544
1531
|
exit?: (code: number) => void;
|
|
1545
1532
|
}
|
|
1546
1533
|
/**
|
|
1547
|
-
* Drain and stop a server on a termination signal
|
|
1534
|
+
* Drain and stop a server on a termination signal - the production lifecycle Node needs (k8s/systemd
|
|
1548
1535
|
* send `SIGTERM` on a rolling deploy). Stops accepting new connections, lets in-flight requests
|
|
1549
|
-
* finish (up to `timeout`), runs `onShutdown` (close the DB, etc.), then exits 0
|
|
1536
|
+
* finish (up to `timeout`), runs `onShutdown` (close the DB, etc.), then exits 0 - or exits 1 if the
|
|
1550
1537
|
* drain times out. Returns an unsubscribe function that removes the signal handlers.
|
|
1551
1538
|
*/
|
|
1552
1539
|
declare function gracefulShutdown(server: Server, options?: GracefulShutdownOptions): () => void;
|
|
@@ -1568,7 +1555,7 @@ interface SecurityHeadersOptions {
|
|
|
1568
1555
|
referrerPolicy?: string | false;
|
|
1569
1556
|
}
|
|
1570
1557
|
/**
|
|
1571
|
-
* Attach baseline security response headers
|
|
1558
|
+
* Attach baseline security response headers - the helmet-style defaults a server-rendered app should
|
|
1572
1559
|
* always set: `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, and optionally HSTS.
|
|
1573
1560
|
* Existing headers are never overwritten, so a route can opt out per response.
|
|
1574
1561
|
*/
|
|
@@ -1589,11 +1576,11 @@ interface CorsOptions {
|
|
|
1589
1576
|
maxAge?: number;
|
|
1590
1577
|
}
|
|
1591
1578
|
/**
|
|
1592
|
-
* Cross-Origin Resource Sharing
|
|
1579
|
+
* Cross-Origin Resource Sharing - the `HandleCors` equivalent for API stacks. Answers preflight
|
|
1593
1580
|
* `OPTIONS` with the negotiated headers and stamps actual responses with `Access-Control-Allow-*`.
|
|
1594
1581
|
*/
|
|
1595
1582
|
declare function cors(options?: CorsOptions): Middleware;
|
|
1596
|
-
/** The rate-limiter surface {@link throttle} needs
|
|
1583
|
+
/** The rate-limiter surface {@link throttle} needs - `@plinthjs/rate-limiter`'s `RateLimiter` fits by shape. */
|
|
1597
1584
|
interface RateLimiterSeam {
|
|
1598
1585
|
/** Record one hit against `key`, expiring after `decaySeconds`; returns the new count. */
|
|
1599
1586
|
hit(key: string, decaySeconds?: number): number;
|
|
@@ -1614,26 +1601,26 @@ interface ThrottleOptions {
|
|
|
1614
1601
|
key?: (req: Request) => string;
|
|
1615
1602
|
}
|
|
1616
1603
|
/**
|
|
1617
|
-
* Rate-limit requests
|
|
1604
|
+
* Rate-limit requests - the `throttle:max,minutes` middleware. Over the limit, responds
|
|
1618
1605
|
* `429 Too Many Requests` with a `Retry-After` header; otherwise records a hit and continues. Key by
|
|
1619
1606
|
* ip+route by default; pass `key` to scope it (e.g. by login email).
|
|
1620
1607
|
*/
|
|
1621
1608
|
declare function throttle(options: ThrottleOptions): Middleware;
|
|
1622
1609
|
|
|
1623
1610
|
/**
|
|
1624
|
-
* @plinthjs/http
|
|
1611
|
+
* @plinthjs/http - the conventional API and its supporting layer (Tier 3).
|
|
1625
1612
|
*
|
|
1626
|
-
* The {@link Request} / {@link Response} value objects
|
|
1613
|
+
* The {@link Request} / {@link Response} value objects - including response macros
|
|
1627
1614
|
* ({@link Response.macro}), redirect helpers with flash intent ({@link Response.redirectTo} /
|
|
1628
1615
|
* {@link Response.with}), and file/download builders ({@link Response.file} /
|
|
1629
|
-
* {@link Response.download})
|
|
1616
|
+
* {@link Response.download}) - the async middleware pipeline ({@link Middleware} /
|
|
1630
1617
|
* {@link runMiddleware}, with {@link TerminableMiddleware} support), the HTTP exception hierarchy
|
|
1631
1618
|
* ({@link HttpException} and friends) and its {@link ExceptionHandler}, the {@link Router} (params,
|
|
1632
1619
|
* optional params, groups, named routes + URL generation, signed URLs via {@link Router.signedUrl},
|
|
1633
1620
|
* fallback), the {@link HttpKernel} that drives the request lifecycle over the `@plinthjs/core`
|
|
1634
1621
|
* container, and a {@link createServer}/{@link serve} adapter over Node's built-in `node:http`.
|
|
1635
1622
|
*/
|
|
1636
|
-
/** The
|
|
1623
|
+
/** The Plinth version this build of `http` ships with. */
|
|
1637
1624
|
declare const VERSION = "0.1.0";
|
|
1638
1625
|
|
|
1639
1626
|
export { type BindingResolver, type CachedRoute, Controller, type ControllerAction, type ControllerResolver, type CookieOptions, type CorsOptions, EXCEPTION_HANDLER, ExceptionHandler, type FlashBag, type FromNodeOptions, type GracefulShutdownOptions, HttpException, HttpKernel, type HttpKernelOptions, type HttpMethod, type InvokableAction, type JsonStreamData, type JsonValue, type LoadCacheOptions, type LogLevel, MethodNotAllowedHttpException, type Middleware, type MiddlewareEntry, type MiddlewareReference, type MiddlewareResolver, type MultipartField, type MultipartFilePart, type MultipartParseResult, type Next, NotFoundHttpException, PayloadTooLargeHttpException, type RateLimiterSeam, type RenderableCallback, type ReportSink, type ReportableCallback, Request, type RequestInit, type ResourceMethod, type ResourceOptions, ResourceRegistration, Response, type ResponseMacro, Route, type RouteCache, type RouteGroupOptions, type RouteHandler, type RouteHandlerClosure, type RouteMatch, type RouteResult, Router, type RouterOptions, type SecurityHeadersOptions, type ServerOptions, type SignatureResult, type SingletonMethod, SingletonRegistration, type StreamChunk, type StreamSource, type TerminableMiddleware, type ThrottleOptions, UploadedFile, type UploadedFileInit, VERSION, type ViewRenderer, type WherePattern, cors, createServer, gracefulShutdown, isTerminable, runMiddleware, securityHeaders, serve, terminateMiddleware, throttle };
|