@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.js
CHANGED
|
@@ -105,7 +105,7 @@ var Response = class _Response {
|
|
|
105
105
|
* matches the `Content-Length` set by {@link Response.file}/{@link Response.download}.
|
|
106
106
|
*/
|
|
107
107
|
bodyEncoding = "utf8";
|
|
108
|
-
/** Flash intent queued by {@link Response.with}; drained by the session layer
|
|
108
|
+
/** Flash intent queued by {@link Response.with}; drained by the session layer. */
|
|
109
109
|
flashData = {};
|
|
110
110
|
/** The streaming body source, when this is a streamed response (see {@link Response.stream}). */
|
|
111
111
|
streamSource;
|
|
@@ -189,7 +189,7 @@ var Response = class _Response {
|
|
|
189
189
|
/**
|
|
190
190
|
* Build a streamed response: `source` (an iterable, async iterable, or a generator/factory
|
|
191
191
|
* returning one) is consumed chunk by chunk as the response is flushed, each chunk written to the
|
|
192
|
-
* client as it yields
|
|
192
|
+
* client as it yields - the `response()->stream()` equivalent. No `Content-Length` is set, so
|
|
193
193
|
* Node serves it with chunked transfer encoding. The kernel/server adapter flushes streamed
|
|
194
194
|
* responses via {@link Response.writeStreamTo}.
|
|
195
195
|
*/
|
|
@@ -212,7 +212,7 @@ var Response = class _Response {
|
|
|
212
212
|
});
|
|
213
213
|
}
|
|
214
214
|
/**
|
|
215
|
-
* Build a streamed JSON response
|
|
215
|
+
* Build a streamed JSON response - the `response()->streamJson()` equivalent. An iterable (or
|
|
216
216
|
* async iterable) of rows is streamed as one JSON array, each row serialized as it yields; an
|
|
217
217
|
* object is emitted key by key with iterable values streamed as arrays and plain values encoded
|
|
218
218
|
* in place. Useful for serializing large result sets without buffering them.
|
|
@@ -228,7 +228,7 @@ var Response = class _Response {
|
|
|
228
228
|
}
|
|
229
229
|
// --- Macros (the `Response::macro` extension point) -----------------------
|
|
230
230
|
/**
|
|
231
|
-
* Register a reusable response builder under `name`. The
|
|
231
|
+
* Register a reusable response builder under `name`. The `Response::macro()` equivalent -
|
|
232
232
|
* application code installs a named factory once and invokes it via {@link Response.callMacro}
|
|
233
233
|
* (`Response.callMacro('caps', text)`). Re-registering a name overwrites the previous macro.
|
|
234
234
|
*/
|
|
@@ -245,8 +245,7 @@ var Response = class _Response {
|
|
|
245
245
|
}
|
|
246
246
|
/**
|
|
247
247
|
* Invoke a previously {@link Response.macro registered} macro by name, forwarding `args` and
|
|
248
|
-
* returning the {@link Response} it builds. Throws when no macro is registered under `name
|
|
249
|
-
* `BadMethodCallException` Laravel raises for an unknown macro). Typed pragmatically: callers cast
|
|
248
|
+
* returning the {@link Response} it builds. Throws when no macro is registered under `name`. Typed pragmatically: callers cast
|
|
250
249
|
* `args` to the macro's expected parameters.
|
|
251
250
|
*/
|
|
252
251
|
static callMacro(name, ...args) {
|
|
@@ -363,7 +362,7 @@ var Response = class _Response {
|
|
|
363
362
|
/**
|
|
364
363
|
* Flush this response to a Node {@link ServerResponse}: status, headers, cookies, then body.
|
|
365
364
|
* Streamed responses ({@link Response.stream}) must be flushed with the async
|
|
366
|
-
* {@link Response.writeStreamTo} instead
|
|
365
|
+
* {@link Response.writeStreamTo} instead - calling `writeTo` on one throws so a stream is never
|
|
367
366
|
* silently dropped.
|
|
368
367
|
*/
|
|
369
368
|
writeTo(res) {
|
|
@@ -399,7 +398,7 @@ var Response = class _Response {
|
|
|
399
398
|
};
|
|
400
399
|
|
|
401
400
|
// src/exceptions.ts
|
|
402
|
-
var EXCEPTION_HANDLER = /* @__PURE__ */ Symbol("
|
|
401
|
+
var EXCEPTION_HANDLER = /* @__PURE__ */ Symbol("plinth.exceptionHandler");
|
|
403
402
|
var HttpException = class extends Error {
|
|
404
403
|
constructor(status, message = "", headers = {}) {
|
|
405
404
|
super(message);
|
|
@@ -450,7 +449,7 @@ var ExceptionHandler = class {
|
|
|
450
449
|
renderCallbacks = [];
|
|
451
450
|
/**
|
|
452
451
|
* Error constructors whose instances are not reported. Seeded with {@link HttpException} (an
|
|
453
|
-
* `instanceof` check, so every subclass
|
|
452
|
+
* `instanceof` check, so every subclass - 404/405/… - is covered too), following the usual small
|
|
454
453
|
* internal don't-report list. Extend with {@link ExceptionHandler.ignore} / shrink with
|
|
455
454
|
* {@link ExceptionHandler.stopIgnoring}.
|
|
456
455
|
*/
|
|
@@ -465,7 +464,7 @@ var ExceptionHandler = class {
|
|
|
465
464
|
/** Per-constructor log levels consulted by {@link ExceptionHandler.levelFor}. */
|
|
466
465
|
levels = [];
|
|
467
466
|
/**
|
|
468
|
-
* Input keys never flashed back to the session on a validation redirect
|
|
467
|
+
* Input keys never flashed back to the session on a validation redirect - the conventional
|
|
469
468
|
* `$dontFlash` list, seeded with its defaults. `@plinthjs/http` itself has no redirect/flash path,
|
|
470
469
|
* so the list is stored here and exposed via {@link ExceptionHandler.getDontFlash} for the
|
|
471
470
|
* session/validation layer to consume when it re-flashes old input.
|
|
@@ -484,9 +483,9 @@ var ExceptionHandler = class {
|
|
|
484
483
|
// --- Exception mapping / levels / dontFlash --------------------------------
|
|
485
484
|
/**
|
|
486
485
|
* Map one exception type to another: whenever an instance of `from` reaches the handler, it is
|
|
487
|
-
* first converted via `to` and the *result* is reported and rendered instead. The
|
|
486
|
+
* first converted via `to` and the *result* is reported and rendered instead. The conventional
|
|
488
487
|
* `$exceptions->map(From::class, fn ($e) => new To(..., $e))` equivalent. Mappings are checked in
|
|
489
|
-
* registration order; the first `instanceof` match applies (once
|
|
488
|
+
* registration order; the first `instanceof` match applies (once - the mapped error is not
|
|
490
489
|
* re-mapped). Chains.
|
|
491
490
|
*/
|
|
492
491
|
map(from, to) {
|
|
@@ -501,8 +500,7 @@ var ExceptionHandler = class {
|
|
|
501
500
|
return error;
|
|
502
501
|
}
|
|
503
502
|
/**
|
|
504
|
-
* Set the log level instances of `ctor` are reported at
|
|
505
|
-
* `$exceptions->level(Type::class, LogLevel::WARNING)` equivalent. The level is surfaced as the
|
|
503
|
+
* Set the log level instances of `ctor` are reported at. The level is surfaced as the
|
|
506
504
|
* `level` key of the context passed to the {@link ReportSink}. Chains.
|
|
507
505
|
*/
|
|
508
506
|
level(ctor, logLevel) {
|
|
@@ -517,8 +515,8 @@ var ExceptionHandler = class {
|
|
|
517
515
|
return "error";
|
|
518
516
|
}
|
|
519
517
|
/**
|
|
520
|
-
* Replace the list of input keys that must never be flashed back on a validation redirect
|
|
521
|
-
*
|
|
518
|
+
* Replace the list of input keys that must never be flashed back on a validation redirect - the
|
|
519
|
+
* `$exceptions->dontFlash([...])` equivalent. Defaults to `current_password`, `password`,
|
|
522
520
|
* and `password_confirmation`. There is no redirect/flash path inside `@plinthjs/http`, so the list
|
|
523
521
|
* is exposed via {@link ExceptionHandler.getDontFlash} for the session/validation layer that
|
|
524
522
|
* re-flashes old input. Chains.
|
|
@@ -531,7 +529,7 @@ var ExceptionHandler = class {
|
|
|
531
529
|
getDontFlash() {
|
|
532
530
|
return [...this.dontFlashKeys];
|
|
533
531
|
}
|
|
534
|
-
// --- Reporting
|
|
532
|
+
// --- Reporting -----------------
|
|
535
533
|
/**
|
|
536
534
|
* Register a reportable callback. Runs in order during {@link ExceptionHandler.report}; returning
|
|
537
535
|
* `false` from a callback stops all further reporting of that error. Chains.
|
|
@@ -541,18 +539,17 @@ var ExceptionHandler = class {
|
|
|
541
539
|
return this;
|
|
542
540
|
}
|
|
543
541
|
/**
|
|
544
|
-
* Add error constructors to the don't-report list
|
|
545
|
-
* equivalent). Matching is by `instanceof`, so a base class also suppresses its subclasses. Chains.
|
|
542
|
+
* Add error constructors to the don't-report list. Matching is by `instanceof`, so a base class also suppresses its subclasses. Chains.
|
|
546
543
|
*/
|
|
547
544
|
ignore(...classes) {
|
|
548
545
|
this.ignored.push(...classes);
|
|
549
546
|
return this;
|
|
550
547
|
}
|
|
551
|
-
/** Alias of {@link ExceptionHandler.ignore}
|
|
548
|
+
/** Alias of {@link ExceptionHandler.ignore} - the `$dontReport` spelling. */
|
|
552
549
|
dontReport(...classes) {
|
|
553
550
|
return this.ignore(...classes);
|
|
554
551
|
}
|
|
555
|
-
/** Remove error constructors from the don't-report list.
|
|
552
|
+
/** Remove error constructors from the don't-report list. */
|
|
556
553
|
stopIgnoring(...classes) {
|
|
557
554
|
const drop = new Set(classes);
|
|
558
555
|
for (let i = this.ignored.length - 1; i >= 0; i--) {
|
|
@@ -567,7 +564,7 @@ var ExceptionHandler = class {
|
|
|
567
564
|
}
|
|
568
565
|
return true;
|
|
569
566
|
}
|
|
570
|
-
/** Replace the terminal report sink (the logger seam).
|
|
567
|
+
/** Replace the terminal report sink (the logger seam). */
|
|
571
568
|
reportUsing(sink) {
|
|
572
569
|
this.reportSink = sink;
|
|
573
570
|
return this;
|
|
@@ -579,16 +576,16 @@ var ExceptionHandler = class {
|
|
|
579
576
|
}
|
|
580
577
|
/**
|
|
581
578
|
* A hook for additional report context, merged into every report. Override in a subclass to attach
|
|
582
|
-
* request-scoped data (user id, etc.).
|
|
579
|
+
* request-scoped data (user id, etc.).
|
|
583
580
|
*/
|
|
584
581
|
context() {
|
|
585
582
|
return {};
|
|
586
583
|
}
|
|
587
584
|
/**
|
|
588
585
|
* Report `error`: if {@link ExceptionHandler.shouldReport} and not a duplicate (when
|
|
589
|
-
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order
|
|
590
|
-
* `false` return stops the chain (the default sink is skipped)
|
|
591
|
-
* terminal sink.
|
|
586
|
+
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order - a
|
|
587
|
+
* `false` return stops the chain (the default sink is skipped) - otherwise fall through to the
|
|
588
|
+
* terminal sink.
|
|
592
589
|
*/
|
|
593
590
|
report(error) {
|
|
594
591
|
const mapped = this.mapException(error);
|
|
@@ -735,8 +732,7 @@ var HttpKernel = class _HttpKernel {
|
|
|
735
732
|
return this.exceptionHandler;
|
|
736
733
|
}
|
|
737
734
|
/**
|
|
738
|
-
* Report `error
|
|
739
|
-
* also isolates reporting from rendering), then render it to a {@link Response}. Used at both
|
|
735
|
+
* Report `error`, then render it to a {@link Response}. Used at both
|
|
740
736
|
* pipeline catch sites so every thrown error is both reported and rendered.
|
|
741
737
|
*/
|
|
742
738
|
reportThenRender(req, error) {
|
|
@@ -785,7 +781,7 @@ var HttpKernel = class _HttpKernel {
|
|
|
785
781
|
* The composed pipeline for `route` (its resolved middleware stack ending in the route action).
|
|
786
782
|
* Cached per route so alias/group resolution and closure composition happen once, not per
|
|
787
783
|
* request. A cached entry is reused only while the route's reference list is unchanged
|
|
788
|
-
* ({@link sameReferences}
|
|
784
|
+
* ({@link sameReferences} - `route.middleware(...)` can append after registration), and stacks
|
|
789
785
|
* containing `string` references are never cached: their alias/group registrations live in
|
|
790
786
|
* mutable router registries and must be re-resolved each dispatch.
|
|
791
787
|
*/
|
|
@@ -972,11 +968,11 @@ var UploadedFile = class {
|
|
|
972
968
|
this.content = init.content;
|
|
973
969
|
this.size = init.content.byteLength;
|
|
974
970
|
}
|
|
975
|
-
/** The raw uploaded bytes. The `get()` content accessor
|
|
971
|
+
/** The raw uploaded bytes. The `get()` content accessor. */
|
|
976
972
|
get() {
|
|
977
973
|
return this.content;
|
|
978
974
|
}
|
|
979
|
-
/** The raw uploaded bytes
|
|
975
|
+
/** The raw uploaded bytes - an alias for {@link UploadedFile.get} reading more naturally as bytes. */
|
|
980
976
|
buffer() {
|
|
981
977
|
return this.content;
|
|
982
978
|
}
|
|
@@ -1000,8 +996,8 @@ var UploadedFile = class {
|
|
|
1000
996
|
return this.size;
|
|
1001
997
|
}
|
|
1002
998
|
/**
|
|
1003
|
-
* Whether the upload is valid
|
|
1004
|
-
*
|
|
999
|
+
* Whether the upload is valid - here, simply that it carries a non-empty filename. Mirrors the
|
|
1000
|
+
* `$file->isValid()` predicate at this layer (no PHP upload-error codes exist in Node).
|
|
1005
1001
|
*/
|
|
1006
1002
|
isValid() {
|
|
1007
1003
|
return this.clientOriginalName.length > 0;
|
|
@@ -1023,7 +1019,7 @@ var UploadedFile = class {
|
|
|
1023
1019
|
}
|
|
1024
1020
|
/**
|
|
1025
1021
|
* Write the upload to the exact file path `destination`, creating its parent directory as needed,
|
|
1026
|
-
* and return `destination`. The `$file->move()` equivalent
|
|
1022
|
+
* and return `destination`. The `$file->move()` equivalent - the documented filesystem seam.
|
|
1027
1023
|
*/
|
|
1028
1024
|
move(destination) {
|
|
1029
1025
|
mkdirSync(path2.dirname(destination), { recursive: true });
|
|
@@ -1031,8 +1027,8 @@ var UploadedFile = class {
|
|
|
1031
1027
|
return destination;
|
|
1032
1028
|
}
|
|
1033
1029
|
/**
|
|
1034
|
-
* A unique storage filename preserving the original extension
|
|
1035
|
-
*
|
|
1030
|
+
* A unique storage filename preserving the original extension - a timestamp/random base, the way
|
|
1031
|
+
* the conventional `hashName()` produces a collision-resistant name. Used by {@link UploadedFile.store}.
|
|
1036
1032
|
*/
|
|
1037
1033
|
hashName() {
|
|
1038
1034
|
const extension = this.getClientOriginalExtension();
|
|
@@ -1123,7 +1119,7 @@ var Request = class _Request {
|
|
|
1123
1119
|
/** Memoized pathname; a {@link isPlainPath plain} target resolves by slicing, sparing `new URL`. */
|
|
1124
1120
|
_pathname;
|
|
1125
1121
|
_host;
|
|
1126
|
-
/** The host as received (port included, if any)
|
|
1122
|
+
/** The host as received (port included, if any) - backs {@link Request.httpHost}. */
|
|
1127
1123
|
_httpHost;
|
|
1128
1124
|
/** The matched route's name, attached by the kernel after a successful match (for `routeIs`). */
|
|
1129
1125
|
_routeName;
|
|
@@ -1164,7 +1160,7 @@ var Request = class _Request {
|
|
|
1164
1160
|
}
|
|
1165
1161
|
/**
|
|
1166
1162
|
* Build a {@link Request} from a live Node {@link IncomingMessage}, draining and parsing the body.
|
|
1167
|
-
* The
|
|
1163
|
+
* The body is buffered
|
|
1168
1164
|
* up to {@link FromNodeOptions.maxBodyBytes} (default 1 MiB); anything larger rejects with a
|
|
1169
1165
|
* {@link PayloadTooLargeHttpException} without buffering past the cap.
|
|
1170
1166
|
*/
|
|
@@ -1331,9 +1327,9 @@ var Request = class _Request {
|
|
|
1331
1327
|
return this._httpHost;
|
|
1332
1328
|
}
|
|
1333
1329
|
/**
|
|
1334
|
-
* The scheme plus host (e.g. `https://acme.myapp.com:8080`)
|
|
1330
|
+
* The scheme plus host (e.g. `https://acme.myapp.com:8080`) - the `$request->schemeAndHttpHost()`
|
|
1335
1331
|
* equivalent. The scheme is read from the first `X-Forwarded-Proto` hop, defaulting to `http`
|
|
1336
|
-
* (
|
|
1332
|
+
* (Plinth's adapter sits on plain `node:http`; a TLS-terminating proxy sets the header).
|
|
1337
1333
|
* `undefined` when no host is known.
|
|
1338
1334
|
*/
|
|
1339
1335
|
schemeAndHttpHost() {
|
|
@@ -1350,15 +1346,15 @@ var Request = class _Request {
|
|
|
1350
1346
|
return "http";
|
|
1351
1347
|
}
|
|
1352
1348
|
/**
|
|
1353
|
-
* Whether the request arrived over HTTPS
|
|
1354
|
-
* `X-Forwarded-Proto` hop (
|
|
1349
|
+
* Whether the request arrived over HTTPS - the `$request->isSecure()` equivalent. Reads the first
|
|
1350
|
+
* `X-Forwarded-Proto` hop (Plinth sits on plain `node:http` behind a TLS-terminating proxy), so it
|
|
1355
1351
|
* is the trust-proxy signal a `secure` cookie or HSTS header should gate on.
|
|
1356
1352
|
*/
|
|
1357
1353
|
isSecure() {
|
|
1358
1354
|
return this.scheme() === "https";
|
|
1359
1355
|
}
|
|
1360
1356
|
/**
|
|
1361
|
-
* The full URL including the query string
|
|
1357
|
+
* The full URL including the query string - `scheme://host/path?query` when the host is known,
|
|
1362
1358
|
* otherwise just `/path?query` (matching {@link Request.url} for host-less synthetic requests).
|
|
1363
1359
|
* The `$request->fullUrl()` equivalent.
|
|
1364
1360
|
*/
|
|
@@ -1392,7 +1388,7 @@ var Request = class _Request {
|
|
|
1392
1388
|
}
|
|
1393
1389
|
// --- Path / route matching (the `is()` family, `*` wildcards) --------------
|
|
1394
1390
|
/**
|
|
1395
|
-
* Whether the request path matches any of the wildcard `patterns`
|
|
1391
|
+
* Whether the request path matches any of the wildcard `patterns` - `*` matches any run of
|
|
1396
1392
|
* characters. Patterns are matched against the path **without** its leading slash (so
|
|
1397
1393
|
* `req.is('admin/*')` matches `/admin/users`), mirroring `$request->is()`.
|
|
1398
1394
|
*/
|
|
@@ -1483,7 +1479,7 @@ var Request = class _Request {
|
|
|
1483
1479
|
return Object.keys(this.all());
|
|
1484
1480
|
}
|
|
1485
1481
|
/**
|
|
1486
|
-
* Read an input value coerced to a boolean
|
|
1482
|
+
* Read an input value coerced to a boolean - `true`/`1`/`'1'`/`'true'`/`'on'`/`'yes'` (strings
|
|
1487
1483
|
* case-insensitive) are `true`, anything else `false`. When the key is absent, `def` (default
|
|
1488
1484
|
* `false`) is returned. The `$request->boolean()` equivalent.
|
|
1489
1485
|
*/
|
|
@@ -1515,7 +1511,7 @@ var Request = class _Request {
|
|
|
1515
1511
|
}
|
|
1516
1512
|
/**
|
|
1517
1513
|
* Read an input value coerced to a primitive string. When the key is absent, `def` (default `''`)
|
|
1518
|
-
* is returned. The
|
|
1514
|
+
* is returned. The `$request->string()` equivalent - note this returns a primitive
|
|
1519
1515
|
* `string` rather than a `Stringable`; wrap it with `@plinthjs/support`'s `Str.of()` for fluent
|
|
1520
1516
|
* helpers if needed.
|
|
1521
1517
|
*/
|
|
@@ -1526,7 +1522,7 @@ var Request = class _Request {
|
|
|
1526
1522
|
}
|
|
1527
1523
|
/**
|
|
1528
1524
|
* Read an input value if (and only if) it is one of `values`, else `undefined`. Generic over the
|
|
1529
|
-
* union of allowed values. The
|
|
1525
|
+
* union of allowed values. The `$request->enum()` equivalent (returning the value, not a
|
|
1530
1526
|
* native enum case). Comparison is by strict equality against the supplied members.
|
|
1531
1527
|
*/
|
|
1532
1528
|
enum(key, values) {
|
|
@@ -1740,7 +1736,7 @@ var Request = class _Request {
|
|
|
1740
1736
|
// --- Route parameters ----------------------------------------------------
|
|
1741
1737
|
/**
|
|
1742
1738
|
* A structural copy carrying route parameters and attributes forward (kept immutable). Every
|
|
1743
|
-
* parsed artifact
|
|
1739
|
+
* parsed artifact - headers, URL memos, body buffer, parsed/multipart memos - is immutable once
|
|
1744
1740
|
* built, so clones share it by reference; only the per-clone bags (route params, attributes,
|
|
1745
1741
|
* bound models, merged input) are copied.
|
|
1746
1742
|
*/
|
|
@@ -1784,7 +1780,7 @@ var Request = class _Request {
|
|
|
1784
1780
|
return clone;
|
|
1785
1781
|
}
|
|
1786
1782
|
/**
|
|
1787
|
-
* Return a copy of this request with an arbitrary attribute attached
|
|
1783
|
+
* Return a copy of this request with an arbitrary attribute attached - the `$request->attributes`
|
|
1788
1784
|
* bag equivalent. Middleware use this to hand request-scoped values (the session, the
|
|
1789
1785
|
* authenticated user, …) to downstream handlers without mutating the original.
|
|
1790
1786
|
*/
|
|
@@ -1799,7 +1795,7 @@ var Request = class _Request {
|
|
|
1799
1795
|
return this._attributes.get(key);
|
|
1800
1796
|
}
|
|
1801
1797
|
/**
|
|
1802
|
-
* Return a copy of this request with `name` set to `value` (case-insensitive)
|
|
1798
|
+
* Return a copy of this request with `name` set to `value` (case-insensitive) - e.g. a `forceJson`
|
|
1803
1799
|
* middleware setting `Accept: application/json`. The header map is copied (clones normally share it
|
|
1804
1800
|
* by reference), so the original request is untouched.
|
|
1805
1801
|
*/
|
|
@@ -1821,7 +1817,7 @@ var Request = class _Request {
|
|
|
1821
1817
|
}
|
|
1822
1818
|
/**
|
|
1823
1819
|
* The route value for `key`: the resolved bound model when route-model binding applied, otherwise
|
|
1824
|
-
* the raw route parameter
|
|
1820
|
+
* the raw route parameter. `undefined` when neither exists.
|
|
1825
1821
|
*/
|
|
1826
1822
|
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- caller-supplied cast for the resolved bound model
|
|
1827
1823
|
route(key) {
|
|
@@ -2015,9 +2011,7 @@ var Route = class {
|
|
|
2015
2011
|
return this.domainPattern;
|
|
2016
2012
|
}
|
|
2017
2013
|
/**
|
|
2018
|
-
* Match a request `host` against this route's domain. Returns the extracted domain params (
|
|
2019
|
-
* empty object when the route has no domain — a domain-less route matches any host, mirroring
|
|
2020
|
-
* Laravel), or `undefined` when the route has a domain that the host does not satisfy (including
|
|
2014
|
+
* 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
|
|
2021
2015
|
* when the route requires a domain but no host was supplied).
|
|
2022
2016
|
*/
|
|
2023
2017
|
matchDomain(host) {
|
|
@@ -2045,23 +2039,23 @@ var Route = class {
|
|
|
2045
2039
|
}
|
|
2046
2040
|
return this;
|
|
2047
2041
|
}
|
|
2048
|
-
/** Constrain `param` to digits only.
|
|
2042
|
+
/** Constrain `param` to digits only. Chains. */
|
|
2049
2043
|
whereNumber(param) {
|
|
2050
2044
|
return this.where(param, WHERE_PATTERNS.number);
|
|
2051
2045
|
}
|
|
2052
|
-
/** Constrain `param` to ASCII letters only.
|
|
2046
|
+
/** Constrain `param` to ASCII letters only. Chains. */
|
|
2053
2047
|
whereAlpha(param) {
|
|
2054
2048
|
return this.where(param, WHERE_PATTERNS.alpha);
|
|
2055
2049
|
}
|
|
2056
|
-
/** Constrain `param` to letters and digits.
|
|
2050
|
+
/** Constrain `param` to letters and digits. Chains. */
|
|
2057
2051
|
whereAlphaNumeric(param) {
|
|
2058
2052
|
return this.where(param, WHERE_PATTERNS.alphanumeric);
|
|
2059
2053
|
}
|
|
2060
|
-
/** Constrain `param` to a UUID shape.
|
|
2054
|
+
/** Constrain `param` to a UUID shape. Chains. */
|
|
2061
2055
|
whereUuid(param) {
|
|
2062
2056
|
return this.where(param, WHERE_PATTERNS.uuid);
|
|
2063
2057
|
}
|
|
2064
|
-
/** Constrain `param` to a ULID shape.
|
|
2058
|
+
/** Constrain `param` to a ULID shape. Chains. */
|
|
2065
2059
|
whereUlid(param) {
|
|
2066
2060
|
return this.where(param, WHERE_PATTERNS.ulid);
|
|
2067
2061
|
}
|
|
@@ -2080,7 +2074,7 @@ var Route = class {
|
|
|
2080
2074
|
return this;
|
|
2081
2075
|
}
|
|
2082
2076
|
/**
|
|
2083
|
-
* The middleware stack for this route (a copy), as registered
|
|
2077
|
+
* The middleware stack for this route (a copy), as registered - so `string` alias/group names are
|
|
2084
2078
|
* returned verbatim. The {@link Router} resolves these to concrete entries via
|
|
2085
2079
|
* {@link Router.resolveMiddleware} when dispatching a matched route.
|
|
2086
2080
|
*/
|
|
@@ -2269,7 +2263,7 @@ var SingletonRegistration = class {
|
|
|
2269
2263
|
register;
|
|
2270
2264
|
isDestroyable = false;
|
|
2271
2265
|
builtRoutes;
|
|
2272
|
-
/** Also register `DELETE name` → `destroy`.
|
|
2266
|
+
/** Also register `DELETE name` → `destroy`. Chains. */
|
|
2273
2267
|
destroyable(value) {
|
|
2274
2268
|
this.isDestroyable = value ?? true;
|
|
2275
2269
|
return this;
|
|
@@ -2352,15 +2346,15 @@ var Router = class _Router {
|
|
|
2352
2346
|
}
|
|
2353
2347
|
// --- Convenience routes (the `Route::view` / `Route::redirect` family) -----
|
|
2354
2348
|
/**
|
|
2355
|
-
* Install the renderer {@link Router.view} routes defer to
|
|
2356
|
-
* plugs its template engine into.
|
|
2349
|
+
* Install the renderer {@link Router.view} routes defer to - the seam an app (or a view package)
|
|
2350
|
+
* plugs its template engine into. Chains.
|
|
2357
2351
|
*/
|
|
2358
2352
|
renderViewsUsing(renderer) {
|
|
2359
2353
|
this.viewRenderer = renderer;
|
|
2360
2354
|
return this;
|
|
2361
2355
|
}
|
|
2362
2356
|
/**
|
|
2363
|
-
* Register a `GET` route that renders `view` with `data
|
|
2357
|
+
* Register a `GET` route that renders `view` with `data`.
|
|
2364
2358
|
* `@plinthjs/http` ships no template engine, so rendering is deferred to the {@link ViewRenderer}
|
|
2365
2359
|
* configured via {@link Router.renderViewsUsing} (or the `viewRenderer` construction option);
|
|
2366
2360
|
* dispatching the route without one throws a clear error. The renderer's string becomes an HTML
|
|
@@ -2378,19 +2372,19 @@ var Router = class _Router {
|
|
|
2378
2372
|
}
|
|
2379
2373
|
/**
|
|
2380
2374
|
* Register a route answering every verb with a redirect to `destination` (default `302`). The
|
|
2381
|
-
*
|
|
2375
|
+
* `Route::redirect()` equivalent.
|
|
2382
2376
|
*/
|
|
2383
2377
|
redirect(uri, destination, status = 302) {
|
|
2384
2378
|
return this.any(uri, () => Response.redirect(destination, status));
|
|
2385
2379
|
}
|
|
2386
|
-
/** Register a `301` redirect route.
|
|
2380
|
+
/** Register a `301` redirect route. */
|
|
2387
2381
|
permanentRedirect(uri, destination) {
|
|
2388
2382
|
return this.redirect(uri, destination, 301);
|
|
2389
2383
|
}
|
|
2390
2384
|
// --- Resource routes (the `Route::resource` family) -----------------------
|
|
2391
2385
|
/**
|
|
2392
2386
|
* Register the seven canonical RESTful routes for `controller` under `name`, mapping each verb+URI
|
|
2393
|
-
* to a controller method
|
|
2387
|
+
* to a controller method:
|
|
2394
2388
|
*
|
|
2395
2389
|
* - `GET name` → `index` (`name.index`)
|
|
2396
2390
|
* - `GET name/create` → `create` (`name.create`)
|
|
@@ -2413,7 +2407,7 @@ var Router = class _Router {
|
|
|
2413
2407
|
}
|
|
2414
2408
|
/**
|
|
2415
2409
|
* Like {@link Router.resource} but for APIs: registers the same routes minus `create` and `edit`
|
|
2416
|
-
* (the HTML form-presenting endpoints).
|
|
2410
|
+
* (the HTML form-presenting endpoints).
|
|
2417
2411
|
*/
|
|
2418
2412
|
apiResource(name, controller, options) {
|
|
2419
2413
|
return this.registerResource(name, controller, true, options);
|
|
@@ -2434,10 +2428,9 @@ var Router = class _Router {
|
|
|
2434
2428
|
return registration;
|
|
2435
2429
|
}
|
|
2436
2430
|
/**
|
|
2437
|
-
* Register a singleton resource
|
|
2431
|
+
* Register a singleton resource - routes for a resource with exactly one instance (a profile, a
|
|
2438
2432
|
* settings page), mapping `GET name` → `show`, `GET name/edit` → `edit`, and `PUT|PATCH name` →
|
|
2439
|
-
* `update` (no `{param}` segment, no `index`/`create`/`store`).
|
|
2440
|
-
* equivalent. Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
2433
|
+
* `update` (no `{param}` segment, no `index`/`create`/`store`). Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
2441
2434
|
* Registration is deferred exactly like {@link Router.resource}.
|
|
2442
2435
|
*/
|
|
2443
2436
|
singleton(name, controller) {
|
|
@@ -2445,8 +2438,7 @@ var Router = class _Router {
|
|
|
2445
2438
|
}
|
|
2446
2439
|
/**
|
|
2447
2440
|
* Like {@link Router.singleton} but for APIs: omits the HTML `edit` route, registering only
|
|
2448
|
-
* `show` and `update` (plus `destroy` after `.destroyable()`).
|
|
2449
|
-
* `Route::apiSingleton()` equivalent.
|
|
2441
|
+
* `show` and `update` (plus `destroy` after `.destroyable()`).
|
|
2450
2442
|
*/
|
|
2451
2443
|
apiSingleton(name, controller) {
|
|
2452
2444
|
return this.registerSingleton(name, controller, true);
|
|
@@ -2520,9 +2512,9 @@ var Router = class _Router {
|
|
|
2520
2512
|
}
|
|
2521
2513
|
// --- Middleware groups + aliases (the `$middlewareGroups` / `$middlewareAliases` family) ------
|
|
2522
2514
|
/**
|
|
2523
|
-
* Register a named middleware *group*
|
|
2515
|
+
* Register a named middleware *group* - a list of references (concrete entries and/or other
|
|
2524
2516
|
* alias/group names) that expand in place wherever the group name is used on a route or group. The
|
|
2525
|
-
*
|
|
2517
|
+
* `Route::middlewareGroup('web', [...])` equivalent. Re-registering a name replaces it.
|
|
2526
2518
|
* Names are resolved (recursively) at match time by {@link Router.resolveMiddleware}.
|
|
2527
2519
|
*/
|
|
2528
2520
|
middlewareGroup(name, entries) {
|
|
@@ -2530,8 +2522,8 @@ var Router = class _Router {
|
|
|
2530
2522
|
return this;
|
|
2531
2523
|
}
|
|
2532
2524
|
/**
|
|
2533
|
-
* Register a middleware *alias*
|
|
2534
|
-
*
|
|
2525
|
+
* Register a middleware *alias* - a short `string` name for a single concrete {@link MiddlewareEntry}.
|
|
2526
|
+
*
|
|
2535
2527
|
* Re-registering a name replaces it.
|
|
2536
2528
|
*/
|
|
2537
2529
|
aliasMiddleware(name, entry) {
|
|
@@ -2553,7 +2545,7 @@ var Router = class _Router {
|
|
|
2553
2545
|
/**
|
|
2554
2546
|
* Resolve a middleware reference list to concrete {@link MiddlewareEntry entries}, expanding
|
|
2555
2547
|
* `string` names: a name resolves first as an **alias** (→ its single entry), else as a **group**
|
|
2556
|
-
* (→ its references, expanded recursively). An unknown name **throws
|
|
2548
|
+
* (→ its references, expanded recursively). An unknown name **throws**, which
|
|
2557
2549
|
* raises when a route references a middleware that is neither an alias nor a group. Cyclic group
|
|
2558
2550
|
* references (a group that, directly or transitively, contains itself) also throw rather than
|
|
2559
2551
|
* recursing without bound. Function/class entries pass through unchanged and in order.
|
|
@@ -2568,7 +2560,7 @@ var Router = class _Router {
|
|
|
2568
2560
|
* Recursive worker for {@link Router.resolveMiddleware}. `groupPath` is the stack of group names
|
|
2569
2561
|
* currently being expanded; revisiting a name already on the path is a cycle (a group that
|
|
2570
2562
|
* directly or transitively contains itself) and throws. The same group may still appear in
|
|
2571
|
-
* sibling branches
|
|
2563
|
+
* sibling branches - only re-entrancy along a single path is rejected.
|
|
2572
2564
|
*/
|
|
2573
2565
|
expandMiddleware(references, groupPath) {
|
|
2574
2566
|
const resolved = [];
|
|
@@ -2608,8 +2600,8 @@ var Router = class _Router {
|
|
|
2608
2600
|
* Serialize the registered routes to a plain, JSON-serializable {@link RouteCache} snapshot
|
|
2609
2601
|
* (methods, path, name, domain, middleware names, and the `[controller, method]` action).
|
|
2610
2602
|
*
|
|
2611
|
-
* Closures cannot be serialized. Mirroring
|
|
2612
|
-
* "Unable to prepare route … for serialization. Uses Closure."
|
|
2603
|
+
* Closures cannot be serialized. Mirroring the conventional `route:cache` - which aborts with
|
|
2604
|
+
* "Unable to prepare route … for serialization. Uses Closure." - this **throws** when any route
|
|
2613
2605
|
* uses a closure handler, rather than silently dropping it, so a cache is always complete or
|
|
2614
2606
|
* absent. Rehydrate with {@link Router.loadCache} or {@link Router.fromCache}.
|
|
2615
2607
|
*/
|
|
@@ -2818,7 +2810,7 @@ var Router = class _Router {
|
|
|
2818
2810
|
return this.signingKey;
|
|
2819
2811
|
}
|
|
2820
2812
|
/**
|
|
2821
|
-
* Build a signed URL for the named route. The
|
|
2813
|
+
* Build a signed URL for the named route. The `URL::signedRoute()` equivalent: the route
|
|
2822
2814
|
* URL is generated as usual, an optional `expires` (a {@link Date} or unix-seconds number) is
|
|
2823
2815
|
* appended, and an HMAC `signature` over the canonical URL is added last. Verify it later with
|
|
2824
2816
|
* {@link Router.hasValidSignature}.
|
|
@@ -2834,7 +2826,7 @@ var Router = class _Router {
|
|
|
2834
2826
|
return `${pathname}?${search.toString()}`;
|
|
2835
2827
|
}
|
|
2836
2828
|
/**
|
|
2837
|
-
* Build a signed URL that expires after `expiresIn` seconds from now. The
|
|
2829
|
+
* Build a signed URL that expires after `expiresIn` seconds from now. The conventional
|
|
2838
2830
|
* `URL::temporarySignedRoute()` equivalent (with the expiry expressed in seconds rather than a
|
|
2839
2831
|
* `DateTime`/minutes).
|
|
2840
2832
|
*/
|
|
@@ -2867,8 +2859,7 @@ var Router = class _Router {
|
|
|
2867
2859
|
return this.validateSignature(req.url()) === "valid";
|
|
2868
2860
|
}
|
|
2869
2861
|
/**
|
|
2870
|
-
* A middleware that aborts unsigned/invalid/expired requests with a `403
|
|
2871
|
-
* `signed` / `ValidateSignature` middleware). On a valid signature it passes control inward.
|
|
2862
|
+
* A middleware that aborts unsigned/invalid/expired requests with a `403`. On a valid signature it passes control inward.
|
|
2872
2863
|
*/
|
|
2873
2864
|
signedMiddleware() {
|
|
2874
2865
|
return (req, next) => {
|
|
@@ -3039,7 +3030,7 @@ function throttle(options) {
|
|
|
3039
3030
|
const decaySeconds = options.decaySeconds ?? 60;
|
|
3040
3031
|
const keyFor = options.key ?? ((req) => `${req.ip() ?? "unknown"}|${req.method()}|${req.path()}`);
|
|
3041
3032
|
return async (req, next) => {
|
|
3042
|
-
const key = `
|
|
3033
|
+
const key = `plinth-throttle:${keyFor(req)}`;
|
|
3043
3034
|
if (options.limiter.tooManyAttempts(key, max)) {
|
|
3044
3035
|
const retryAfter = options.limiter.availableIn(key);
|
|
3045
3036
|
return Response.json({ message: "Too Many Attempts." }, 429).withHeaders({
|