@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/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @plinthjs/http
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Plinth's HTTP layer. `Request` and
|
|
4
4
|
`Response` value objects, an async middleware pipeline, a `Router` (parameters, constraints, groups,
|
|
5
5
|
named routes, resource routes, model binding, signed URLs, fallback), an HTTP exception hierarchy
|
|
6
6
|
with its `ExceptionHandler`, the `HttpKernel` that drives the request lifecycle over the
|
|
@@ -19,7 +19,7 @@ import { gracefulShutdown, HttpKernel, Response, Router, serve } from '@plinthjs
|
|
|
19
19
|
|
|
20
20
|
const router = new Router()
|
|
21
21
|
|
|
22
|
-
router.get('/', () => 'Hello
|
|
22
|
+
router.get('/', () => 'Hello Plinth') // strings and objects are coerced to responses
|
|
23
23
|
router.get('/users/{id}', (req) => Response.json({ id: req.param('id') })).whereNumber('id')
|
|
24
24
|
router.get('/posts/{page?}', (req) => Response.json({ page: req.param('page', '1') }))
|
|
25
25
|
|
|
@@ -77,7 +77,7 @@ req.boolean('published') // also integer(), float(), string(), enum()
|
|
|
77
77
|
req.has('tags') && req.filled('title')
|
|
78
78
|
req.header('accept')
|
|
79
79
|
req.bearerToken()
|
|
80
|
-
req.cookie('
|
|
80
|
+
req.cookie('plinth_session')
|
|
81
81
|
req.file('avatar') // UploadedFile (multipart bodies are parsed)
|
|
82
82
|
req.wantsJson()
|
|
83
83
|
req.withAttribute('user', user).attribute('user') // immutable, returns a new Request
|
|
@@ -99,7 +99,7 @@ Response.back('/')
|
|
|
99
99
|
Response.file('/srv/report.pdf')
|
|
100
100
|
Response.download('/srv/report.pdf', 'report.pdf')
|
|
101
101
|
Response.streamJson(rowsAsyncIterable)
|
|
102
|
-
Response.make('ok').cookie('seen', '1', { httpOnly: true }).withHeaders({ 'X-App': '
|
|
102
|
+
Response.make('ok').cookie('seen', '1', { httpOnly: true }).withHeaders({ 'X-App': 'plinth' })
|
|
103
103
|
|
|
104
104
|
Response.macro('created', () => Response.json({ created: true }, 201))
|
|
105
105
|
Response.callMacro('created')
|
package/dist/index.cjs
CHANGED
|
@@ -111,7 +111,7 @@ var Response = class _Response {
|
|
|
111
111
|
* matches the `Content-Length` set by {@link Response.file}/{@link Response.download}.
|
|
112
112
|
*/
|
|
113
113
|
bodyEncoding = "utf8";
|
|
114
|
-
/** Flash intent queued by {@link Response.with}; drained by the session layer
|
|
114
|
+
/** Flash intent queued by {@link Response.with}; drained by the session layer. */
|
|
115
115
|
flashData = {};
|
|
116
116
|
/** The streaming body source, when this is a streamed response (see {@link Response.stream}). */
|
|
117
117
|
streamSource;
|
|
@@ -195,7 +195,7 @@ var Response = class _Response {
|
|
|
195
195
|
/**
|
|
196
196
|
* Build a streamed response: `source` (an iterable, async iterable, or a generator/factory
|
|
197
197
|
* returning one) is consumed chunk by chunk as the response is flushed, each chunk written to the
|
|
198
|
-
* client as it yields
|
|
198
|
+
* client as it yields - the `response()->stream()` equivalent. No `Content-Length` is set, so
|
|
199
199
|
* Node serves it with chunked transfer encoding. The kernel/server adapter flushes streamed
|
|
200
200
|
* responses via {@link Response.writeStreamTo}.
|
|
201
201
|
*/
|
|
@@ -218,7 +218,7 @@ var Response = class _Response {
|
|
|
218
218
|
});
|
|
219
219
|
}
|
|
220
220
|
/**
|
|
221
|
-
* Build a streamed JSON response
|
|
221
|
+
* Build a streamed JSON response - the `response()->streamJson()` equivalent. An iterable (or
|
|
222
222
|
* async iterable) of rows is streamed as one JSON array, each row serialized as it yields; an
|
|
223
223
|
* object is emitted key by key with iterable values streamed as arrays and plain values encoded
|
|
224
224
|
* in place. Useful for serializing large result sets without buffering them.
|
|
@@ -234,7 +234,7 @@ var Response = class _Response {
|
|
|
234
234
|
}
|
|
235
235
|
// --- Macros (the `Response::macro` extension point) -----------------------
|
|
236
236
|
/**
|
|
237
|
-
* Register a reusable response builder under `name`. The
|
|
237
|
+
* Register a reusable response builder under `name`. The `Response::macro()` equivalent -
|
|
238
238
|
* application code installs a named factory once and invokes it via {@link Response.callMacro}
|
|
239
239
|
* (`Response.callMacro('caps', text)`). Re-registering a name overwrites the previous macro.
|
|
240
240
|
*/
|
|
@@ -251,8 +251,7 @@ var Response = class _Response {
|
|
|
251
251
|
}
|
|
252
252
|
/**
|
|
253
253
|
* Invoke a previously {@link Response.macro registered} macro by name, forwarding `args` and
|
|
254
|
-
* returning the {@link Response} it builds. Throws when no macro is registered under `name
|
|
255
|
-
* `BadMethodCallException` Laravel raises for an unknown macro). Typed pragmatically: callers cast
|
|
254
|
+
* returning the {@link Response} it builds. Throws when no macro is registered under `name`. Typed pragmatically: callers cast
|
|
256
255
|
* `args` to the macro's expected parameters.
|
|
257
256
|
*/
|
|
258
257
|
static callMacro(name, ...args) {
|
|
@@ -369,7 +368,7 @@ var Response = class _Response {
|
|
|
369
368
|
/**
|
|
370
369
|
* Flush this response to a Node {@link ServerResponse}: status, headers, cookies, then body.
|
|
371
370
|
* Streamed responses ({@link Response.stream}) must be flushed with the async
|
|
372
|
-
* {@link Response.writeStreamTo} instead
|
|
371
|
+
* {@link Response.writeStreamTo} instead - calling `writeTo` on one throws so a stream is never
|
|
373
372
|
* silently dropped.
|
|
374
373
|
*/
|
|
375
374
|
writeTo(res) {
|
|
@@ -405,7 +404,7 @@ var Response = class _Response {
|
|
|
405
404
|
};
|
|
406
405
|
|
|
407
406
|
// src/exceptions.ts
|
|
408
|
-
var EXCEPTION_HANDLER = /* @__PURE__ */ Symbol("
|
|
407
|
+
var EXCEPTION_HANDLER = /* @__PURE__ */ Symbol("plinth.exceptionHandler");
|
|
409
408
|
var HttpException = class extends Error {
|
|
410
409
|
constructor(status, message = "", headers = {}) {
|
|
411
410
|
super(message);
|
|
@@ -456,7 +455,7 @@ var ExceptionHandler = class {
|
|
|
456
455
|
renderCallbacks = [];
|
|
457
456
|
/**
|
|
458
457
|
* Error constructors whose instances are not reported. Seeded with {@link HttpException} (an
|
|
459
|
-
* `instanceof` check, so every subclass
|
|
458
|
+
* `instanceof` check, so every subclass - 404/405/… - is covered too), following the usual small
|
|
460
459
|
* internal don't-report list. Extend with {@link ExceptionHandler.ignore} / shrink with
|
|
461
460
|
* {@link ExceptionHandler.stopIgnoring}.
|
|
462
461
|
*/
|
|
@@ -471,7 +470,7 @@ var ExceptionHandler = class {
|
|
|
471
470
|
/** Per-constructor log levels consulted by {@link ExceptionHandler.levelFor}. */
|
|
472
471
|
levels = [];
|
|
473
472
|
/**
|
|
474
|
-
* Input keys never flashed back to the session on a validation redirect
|
|
473
|
+
* Input keys never flashed back to the session on a validation redirect - the conventional
|
|
475
474
|
* `$dontFlash` list, seeded with its defaults. `@plinthjs/http` itself has no redirect/flash path,
|
|
476
475
|
* so the list is stored here and exposed via {@link ExceptionHandler.getDontFlash} for the
|
|
477
476
|
* session/validation layer to consume when it re-flashes old input.
|
|
@@ -490,9 +489,9 @@ var ExceptionHandler = class {
|
|
|
490
489
|
// --- Exception mapping / levels / dontFlash --------------------------------
|
|
491
490
|
/**
|
|
492
491
|
* Map one exception type to another: whenever an instance of `from` reaches the handler, it is
|
|
493
|
-
* first converted via `to` and the *result* is reported and rendered instead. The
|
|
492
|
+
* first converted via `to` and the *result* is reported and rendered instead. The conventional
|
|
494
493
|
* `$exceptions->map(From::class, fn ($e) => new To(..., $e))` equivalent. Mappings are checked in
|
|
495
|
-
* registration order; the first `instanceof` match applies (once
|
|
494
|
+
* registration order; the first `instanceof` match applies (once - the mapped error is not
|
|
496
495
|
* re-mapped). Chains.
|
|
497
496
|
*/
|
|
498
497
|
map(from, to) {
|
|
@@ -507,8 +506,7 @@ var ExceptionHandler = class {
|
|
|
507
506
|
return error;
|
|
508
507
|
}
|
|
509
508
|
/**
|
|
510
|
-
* Set the log level instances of `ctor` are reported at
|
|
511
|
-
* `$exceptions->level(Type::class, LogLevel::WARNING)` equivalent. The level is surfaced as the
|
|
509
|
+
* Set the log level instances of `ctor` are reported at. The level is surfaced as the
|
|
512
510
|
* `level` key of the context passed to the {@link ReportSink}. Chains.
|
|
513
511
|
*/
|
|
514
512
|
level(ctor, logLevel) {
|
|
@@ -523,8 +521,8 @@ var ExceptionHandler = class {
|
|
|
523
521
|
return "error";
|
|
524
522
|
}
|
|
525
523
|
/**
|
|
526
|
-
* Replace the list of input keys that must never be flashed back on a validation redirect
|
|
527
|
-
*
|
|
524
|
+
* Replace the list of input keys that must never be flashed back on a validation redirect - the
|
|
525
|
+
* `$exceptions->dontFlash([...])` equivalent. Defaults to `current_password`, `password`,
|
|
528
526
|
* and `password_confirmation`. There is no redirect/flash path inside `@plinthjs/http`, so the list
|
|
529
527
|
* is exposed via {@link ExceptionHandler.getDontFlash} for the session/validation layer that
|
|
530
528
|
* re-flashes old input. Chains.
|
|
@@ -537,7 +535,7 @@ var ExceptionHandler = class {
|
|
|
537
535
|
getDontFlash() {
|
|
538
536
|
return [...this.dontFlashKeys];
|
|
539
537
|
}
|
|
540
|
-
// --- Reporting
|
|
538
|
+
// --- Reporting -----------------
|
|
541
539
|
/**
|
|
542
540
|
* Register a reportable callback. Runs in order during {@link ExceptionHandler.report}; returning
|
|
543
541
|
* `false` from a callback stops all further reporting of that error. Chains.
|
|
@@ -547,18 +545,17 @@ var ExceptionHandler = class {
|
|
|
547
545
|
return this;
|
|
548
546
|
}
|
|
549
547
|
/**
|
|
550
|
-
* Add error constructors to the don't-report list
|
|
551
|
-
* equivalent). Matching is by `instanceof`, so a base class also suppresses its subclasses. Chains.
|
|
548
|
+
* Add error constructors to the don't-report list. Matching is by `instanceof`, so a base class also suppresses its subclasses. Chains.
|
|
552
549
|
*/
|
|
553
550
|
ignore(...classes) {
|
|
554
551
|
this.ignored.push(...classes);
|
|
555
552
|
return this;
|
|
556
553
|
}
|
|
557
|
-
/** Alias of {@link ExceptionHandler.ignore}
|
|
554
|
+
/** Alias of {@link ExceptionHandler.ignore} - the `$dontReport` spelling. */
|
|
558
555
|
dontReport(...classes) {
|
|
559
556
|
return this.ignore(...classes);
|
|
560
557
|
}
|
|
561
|
-
/** Remove error constructors from the don't-report list.
|
|
558
|
+
/** Remove error constructors from the don't-report list. */
|
|
562
559
|
stopIgnoring(...classes) {
|
|
563
560
|
const drop = new Set(classes);
|
|
564
561
|
for (let i = this.ignored.length - 1; i >= 0; i--) {
|
|
@@ -573,7 +570,7 @@ var ExceptionHandler = class {
|
|
|
573
570
|
}
|
|
574
571
|
return true;
|
|
575
572
|
}
|
|
576
|
-
/** Replace the terminal report sink (the logger seam).
|
|
573
|
+
/** Replace the terminal report sink (the logger seam). */
|
|
577
574
|
reportUsing(sink) {
|
|
578
575
|
this.reportSink = sink;
|
|
579
576
|
return this;
|
|
@@ -585,16 +582,16 @@ var ExceptionHandler = class {
|
|
|
585
582
|
}
|
|
586
583
|
/**
|
|
587
584
|
* A hook for additional report context, merged into every report. Override in a subclass to attach
|
|
588
|
-
* request-scoped data (user id, etc.).
|
|
585
|
+
* request-scoped data (user id, etc.).
|
|
589
586
|
*/
|
|
590
587
|
context() {
|
|
591
588
|
return {};
|
|
592
589
|
}
|
|
593
590
|
/**
|
|
594
591
|
* Report `error`: if {@link ExceptionHandler.shouldReport} and not a duplicate (when
|
|
595
|
-
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order
|
|
596
|
-
* `false` return stops the chain (the default sink is skipped)
|
|
597
|
-
* terminal sink.
|
|
592
|
+
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order - a
|
|
593
|
+
* `false` return stops the chain (the default sink is skipped) - otherwise fall through to the
|
|
594
|
+
* terminal sink.
|
|
598
595
|
*/
|
|
599
596
|
report(error) {
|
|
600
597
|
const mapped = this.mapException(error);
|
|
@@ -741,8 +738,7 @@ var HttpKernel = class _HttpKernel {
|
|
|
741
738
|
return this.exceptionHandler;
|
|
742
739
|
}
|
|
743
740
|
/**
|
|
744
|
-
* Report `error
|
|
745
|
-
* also isolates reporting from rendering), then render it to a {@link Response}. Used at both
|
|
741
|
+
* Report `error`, then render it to a {@link Response}. Used at both
|
|
746
742
|
* pipeline catch sites so every thrown error is both reported and rendered.
|
|
747
743
|
*/
|
|
748
744
|
reportThenRender(req, error) {
|
|
@@ -791,7 +787,7 @@ var HttpKernel = class _HttpKernel {
|
|
|
791
787
|
* The composed pipeline for `route` (its resolved middleware stack ending in the route action).
|
|
792
788
|
* Cached per route so alias/group resolution and closure composition happen once, not per
|
|
793
789
|
* request. A cached entry is reused only while the route's reference list is unchanged
|
|
794
|
-
* ({@link sameReferences}
|
|
790
|
+
* ({@link sameReferences} - `route.middleware(...)` can append after registration), and stacks
|
|
795
791
|
* containing `string` references are never cached: their alias/group registrations live in
|
|
796
792
|
* mutable router registries and must be re-resolved each dispatch.
|
|
797
793
|
*/
|
|
@@ -978,11 +974,11 @@ var UploadedFile = class {
|
|
|
978
974
|
this.content = init.content;
|
|
979
975
|
this.size = init.content.byteLength;
|
|
980
976
|
}
|
|
981
|
-
/** The raw uploaded bytes. The `get()` content accessor
|
|
977
|
+
/** The raw uploaded bytes. The `get()` content accessor. */
|
|
982
978
|
get() {
|
|
983
979
|
return this.content;
|
|
984
980
|
}
|
|
985
|
-
/** The raw uploaded bytes
|
|
981
|
+
/** The raw uploaded bytes - an alias for {@link UploadedFile.get} reading more naturally as bytes. */
|
|
986
982
|
buffer() {
|
|
987
983
|
return this.content;
|
|
988
984
|
}
|
|
@@ -1006,8 +1002,8 @@ var UploadedFile = class {
|
|
|
1006
1002
|
return this.size;
|
|
1007
1003
|
}
|
|
1008
1004
|
/**
|
|
1009
|
-
* Whether the upload is valid
|
|
1010
|
-
*
|
|
1005
|
+
* Whether the upload is valid - here, simply that it carries a non-empty filename. Mirrors the
|
|
1006
|
+
* `$file->isValid()` predicate at this layer (no PHP upload-error codes exist in Node).
|
|
1011
1007
|
*/
|
|
1012
1008
|
isValid() {
|
|
1013
1009
|
return this.clientOriginalName.length > 0;
|
|
@@ -1029,7 +1025,7 @@ var UploadedFile = class {
|
|
|
1029
1025
|
}
|
|
1030
1026
|
/**
|
|
1031
1027
|
* Write the upload to the exact file path `destination`, creating its parent directory as needed,
|
|
1032
|
-
* and return `destination`. The `$file->move()` equivalent
|
|
1028
|
+
* and return `destination`. The `$file->move()` equivalent - the documented filesystem seam.
|
|
1033
1029
|
*/
|
|
1034
1030
|
move(destination) {
|
|
1035
1031
|
fs.mkdirSync(path2__default.default.dirname(destination), { recursive: true });
|
|
@@ -1037,8 +1033,8 @@ var UploadedFile = class {
|
|
|
1037
1033
|
return destination;
|
|
1038
1034
|
}
|
|
1039
1035
|
/**
|
|
1040
|
-
* A unique storage filename preserving the original extension
|
|
1041
|
-
*
|
|
1036
|
+
* A unique storage filename preserving the original extension - a timestamp/random base, the way
|
|
1037
|
+
* the conventional `hashName()` produces a collision-resistant name. Used by {@link UploadedFile.store}.
|
|
1042
1038
|
*/
|
|
1043
1039
|
hashName() {
|
|
1044
1040
|
const extension = this.getClientOriginalExtension();
|
|
@@ -1129,7 +1125,7 @@ var Request = class _Request {
|
|
|
1129
1125
|
/** Memoized pathname; a {@link isPlainPath plain} target resolves by slicing, sparing `new URL`. */
|
|
1130
1126
|
_pathname;
|
|
1131
1127
|
_host;
|
|
1132
|
-
/** The host as received (port included, if any)
|
|
1128
|
+
/** The host as received (port included, if any) - backs {@link Request.httpHost}. */
|
|
1133
1129
|
_httpHost;
|
|
1134
1130
|
/** The matched route's name, attached by the kernel after a successful match (for `routeIs`). */
|
|
1135
1131
|
_routeName;
|
|
@@ -1170,7 +1166,7 @@ var Request = class _Request {
|
|
|
1170
1166
|
}
|
|
1171
1167
|
/**
|
|
1172
1168
|
* Build a {@link Request} from a live Node {@link IncomingMessage}, draining and parsing the body.
|
|
1173
|
-
* The
|
|
1169
|
+
* The body is buffered
|
|
1174
1170
|
* up to {@link FromNodeOptions.maxBodyBytes} (default 1 MiB); anything larger rejects with a
|
|
1175
1171
|
* {@link PayloadTooLargeHttpException} without buffering past the cap.
|
|
1176
1172
|
*/
|
|
@@ -1337,9 +1333,9 @@ var Request = class _Request {
|
|
|
1337
1333
|
return this._httpHost;
|
|
1338
1334
|
}
|
|
1339
1335
|
/**
|
|
1340
|
-
* The scheme plus host (e.g. `https://acme.myapp.com:8080`)
|
|
1336
|
+
* The scheme plus host (e.g. `https://acme.myapp.com:8080`) - the `$request->schemeAndHttpHost()`
|
|
1341
1337
|
* equivalent. The scheme is read from the first `X-Forwarded-Proto` hop, defaulting to `http`
|
|
1342
|
-
* (
|
|
1338
|
+
* (Plinth's adapter sits on plain `node:http`; a TLS-terminating proxy sets the header).
|
|
1343
1339
|
* `undefined` when no host is known.
|
|
1344
1340
|
*/
|
|
1345
1341
|
schemeAndHttpHost() {
|
|
@@ -1356,15 +1352,15 @@ var Request = class _Request {
|
|
|
1356
1352
|
return "http";
|
|
1357
1353
|
}
|
|
1358
1354
|
/**
|
|
1359
|
-
* Whether the request arrived over HTTPS
|
|
1360
|
-
* `X-Forwarded-Proto` hop (
|
|
1355
|
+
* Whether the request arrived over HTTPS - the `$request->isSecure()` equivalent. Reads the first
|
|
1356
|
+
* `X-Forwarded-Proto` hop (Plinth sits on plain `node:http` behind a TLS-terminating proxy), so it
|
|
1361
1357
|
* is the trust-proxy signal a `secure` cookie or HSTS header should gate on.
|
|
1362
1358
|
*/
|
|
1363
1359
|
isSecure() {
|
|
1364
1360
|
return this.scheme() === "https";
|
|
1365
1361
|
}
|
|
1366
1362
|
/**
|
|
1367
|
-
* The full URL including the query string
|
|
1363
|
+
* The full URL including the query string - `scheme://host/path?query` when the host is known,
|
|
1368
1364
|
* otherwise just `/path?query` (matching {@link Request.url} for host-less synthetic requests).
|
|
1369
1365
|
* The `$request->fullUrl()` equivalent.
|
|
1370
1366
|
*/
|
|
@@ -1398,7 +1394,7 @@ var Request = class _Request {
|
|
|
1398
1394
|
}
|
|
1399
1395
|
// --- Path / route matching (the `is()` family, `*` wildcards) --------------
|
|
1400
1396
|
/**
|
|
1401
|
-
* Whether the request path matches any of the wildcard `patterns`
|
|
1397
|
+
* Whether the request path matches any of the wildcard `patterns` - `*` matches any run of
|
|
1402
1398
|
* characters. Patterns are matched against the path **without** its leading slash (so
|
|
1403
1399
|
* `req.is('admin/*')` matches `/admin/users`), mirroring `$request->is()`.
|
|
1404
1400
|
*/
|
|
@@ -1489,7 +1485,7 @@ var Request = class _Request {
|
|
|
1489
1485
|
return Object.keys(this.all());
|
|
1490
1486
|
}
|
|
1491
1487
|
/**
|
|
1492
|
-
* Read an input value coerced to a boolean
|
|
1488
|
+
* Read an input value coerced to a boolean - `true`/`1`/`'1'`/`'true'`/`'on'`/`'yes'` (strings
|
|
1493
1489
|
* case-insensitive) are `true`, anything else `false`. When the key is absent, `def` (default
|
|
1494
1490
|
* `false`) is returned. The `$request->boolean()` equivalent.
|
|
1495
1491
|
*/
|
|
@@ -1521,7 +1517,7 @@ var Request = class _Request {
|
|
|
1521
1517
|
}
|
|
1522
1518
|
/**
|
|
1523
1519
|
* Read an input value coerced to a primitive string. When the key is absent, `def` (default `''`)
|
|
1524
|
-
* is returned. The
|
|
1520
|
+
* is returned. The `$request->string()` equivalent - note this returns a primitive
|
|
1525
1521
|
* `string` rather than a `Stringable`; wrap it with `@plinthjs/support`'s `Str.of()` for fluent
|
|
1526
1522
|
* helpers if needed.
|
|
1527
1523
|
*/
|
|
@@ -1532,7 +1528,7 @@ var Request = class _Request {
|
|
|
1532
1528
|
}
|
|
1533
1529
|
/**
|
|
1534
1530
|
* Read an input value if (and only if) it is one of `values`, else `undefined`. Generic over the
|
|
1535
|
-
* union of allowed values. The
|
|
1531
|
+
* union of allowed values. The `$request->enum()` equivalent (returning the value, not a
|
|
1536
1532
|
* native enum case). Comparison is by strict equality against the supplied members.
|
|
1537
1533
|
*/
|
|
1538
1534
|
enum(key, values) {
|
|
@@ -1746,7 +1742,7 @@ var Request = class _Request {
|
|
|
1746
1742
|
// --- Route parameters ----------------------------------------------------
|
|
1747
1743
|
/**
|
|
1748
1744
|
* A structural copy carrying route parameters and attributes forward (kept immutable). Every
|
|
1749
|
-
* parsed artifact
|
|
1745
|
+
* parsed artifact - headers, URL memos, body buffer, parsed/multipart memos - is immutable once
|
|
1750
1746
|
* built, so clones share it by reference; only the per-clone bags (route params, attributes,
|
|
1751
1747
|
* bound models, merged input) are copied.
|
|
1752
1748
|
*/
|
|
@@ -1790,7 +1786,7 @@ var Request = class _Request {
|
|
|
1790
1786
|
return clone;
|
|
1791
1787
|
}
|
|
1792
1788
|
/**
|
|
1793
|
-
* Return a copy of this request with an arbitrary attribute attached
|
|
1789
|
+
* Return a copy of this request with an arbitrary attribute attached - the `$request->attributes`
|
|
1794
1790
|
* bag equivalent. Middleware use this to hand request-scoped values (the session, the
|
|
1795
1791
|
* authenticated user, …) to downstream handlers without mutating the original.
|
|
1796
1792
|
*/
|
|
@@ -1805,7 +1801,7 @@ var Request = class _Request {
|
|
|
1805
1801
|
return this._attributes.get(key);
|
|
1806
1802
|
}
|
|
1807
1803
|
/**
|
|
1808
|
-
* Return a copy of this request with `name` set to `value` (case-insensitive)
|
|
1804
|
+
* Return a copy of this request with `name` set to `value` (case-insensitive) - e.g. a `forceJson`
|
|
1809
1805
|
* middleware setting `Accept: application/json`. The header map is copied (clones normally share it
|
|
1810
1806
|
* by reference), so the original request is untouched.
|
|
1811
1807
|
*/
|
|
@@ -1827,7 +1823,7 @@ var Request = class _Request {
|
|
|
1827
1823
|
}
|
|
1828
1824
|
/**
|
|
1829
1825
|
* The route value for `key`: the resolved bound model when route-model binding applied, otherwise
|
|
1830
|
-
* the raw route parameter
|
|
1826
|
+
* the raw route parameter. `undefined` when neither exists.
|
|
1831
1827
|
*/
|
|
1832
1828
|
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- caller-supplied cast for the resolved bound model
|
|
1833
1829
|
route(key) {
|
|
@@ -2021,9 +2017,7 @@ var Route = class {
|
|
|
2021
2017
|
return this.domainPattern;
|
|
2022
2018
|
}
|
|
2023
2019
|
/**
|
|
2024
|
-
* Match a request `host` against this route's domain. Returns the extracted domain params (
|
|
2025
|
-
* empty object when the route has no domain — a domain-less route matches any host, mirroring
|
|
2026
|
-
* Laravel), or `undefined` when the route has a domain that the host does not satisfy (including
|
|
2020
|
+
* 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
|
|
2027
2021
|
* when the route requires a domain but no host was supplied).
|
|
2028
2022
|
*/
|
|
2029
2023
|
matchDomain(host) {
|
|
@@ -2051,23 +2045,23 @@ var Route = class {
|
|
|
2051
2045
|
}
|
|
2052
2046
|
return this;
|
|
2053
2047
|
}
|
|
2054
|
-
/** Constrain `param` to digits only.
|
|
2048
|
+
/** Constrain `param` to digits only. Chains. */
|
|
2055
2049
|
whereNumber(param) {
|
|
2056
2050
|
return this.where(param, WHERE_PATTERNS.number);
|
|
2057
2051
|
}
|
|
2058
|
-
/** Constrain `param` to ASCII letters only.
|
|
2052
|
+
/** Constrain `param` to ASCII letters only. Chains. */
|
|
2059
2053
|
whereAlpha(param) {
|
|
2060
2054
|
return this.where(param, WHERE_PATTERNS.alpha);
|
|
2061
2055
|
}
|
|
2062
|
-
/** Constrain `param` to letters and digits.
|
|
2056
|
+
/** Constrain `param` to letters and digits. Chains. */
|
|
2063
2057
|
whereAlphaNumeric(param) {
|
|
2064
2058
|
return this.where(param, WHERE_PATTERNS.alphanumeric);
|
|
2065
2059
|
}
|
|
2066
|
-
/** Constrain `param` to a UUID shape.
|
|
2060
|
+
/** Constrain `param` to a UUID shape. Chains. */
|
|
2067
2061
|
whereUuid(param) {
|
|
2068
2062
|
return this.where(param, WHERE_PATTERNS.uuid);
|
|
2069
2063
|
}
|
|
2070
|
-
/** Constrain `param` to a ULID shape.
|
|
2064
|
+
/** Constrain `param` to a ULID shape. Chains. */
|
|
2071
2065
|
whereUlid(param) {
|
|
2072
2066
|
return this.where(param, WHERE_PATTERNS.ulid);
|
|
2073
2067
|
}
|
|
@@ -2086,7 +2080,7 @@ var Route = class {
|
|
|
2086
2080
|
return this;
|
|
2087
2081
|
}
|
|
2088
2082
|
/**
|
|
2089
|
-
* The middleware stack for this route (a copy), as registered
|
|
2083
|
+
* The middleware stack for this route (a copy), as registered - so `string` alias/group names are
|
|
2090
2084
|
* returned verbatim. The {@link Router} resolves these to concrete entries via
|
|
2091
2085
|
* {@link Router.resolveMiddleware} when dispatching a matched route.
|
|
2092
2086
|
*/
|
|
@@ -2275,7 +2269,7 @@ var SingletonRegistration = class {
|
|
|
2275
2269
|
register;
|
|
2276
2270
|
isDestroyable = false;
|
|
2277
2271
|
builtRoutes;
|
|
2278
|
-
/** Also register `DELETE name` → `destroy`.
|
|
2272
|
+
/** Also register `DELETE name` → `destroy`. Chains. */
|
|
2279
2273
|
destroyable(value) {
|
|
2280
2274
|
this.isDestroyable = value ?? true;
|
|
2281
2275
|
return this;
|
|
@@ -2358,15 +2352,15 @@ var Router = class _Router {
|
|
|
2358
2352
|
}
|
|
2359
2353
|
// --- Convenience routes (the `Route::view` / `Route::redirect` family) -----
|
|
2360
2354
|
/**
|
|
2361
|
-
* Install the renderer {@link Router.view} routes defer to
|
|
2362
|
-
* plugs its template engine into.
|
|
2355
|
+
* Install the renderer {@link Router.view} routes defer to - the seam an app (or a view package)
|
|
2356
|
+
* plugs its template engine into. Chains.
|
|
2363
2357
|
*/
|
|
2364
2358
|
renderViewsUsing(renderer) {
|
|
2365
2359
|
this.viewRenderer = renderer;
|
|
2366
2360
|
return this;
|
|
2367
2361
|
}
|
|
2368
2362
|
/**
|
|
2369
|
-
* Register a `GET` route that renders `view` with `data
|
|
2363
|
+
* Register a `GET` route that renders `view` with `data`.
|
|
2370
2364
|
* `@plinthjs/http` ships no template engine, so rendering is deferred to the {@link ViewRenderer}
|
|
2371
2365
|
* configured via {@link Router.renderViewsUsing} (or the `viewRenderer` construction option);
|
|
2372
2366
|
* dispatching the route without one throws a clear error. The renderer's string becomes an HTML
|
|
@@ -2384,19 +2378,19 @@ var Router = class _Router {
|
|
|
2384
2378
|
}
|
|
2385
2379
|
/**
|
|
2386
2380
|
* Register a route answering every verb with a redirect to `destination` (default `302`). The
|
|
2387
|
-
*
|
|
2381
|
+
* `Route::redirect()` equivalent.
|
|
2388
2382
|
*/
|
|
2389
2383
|
redirect(uri, destination, status = 302) {
|
|
2390
2384
|
return this.any(uri, () => Response.redirect(destination, status));
|
|
2391
2385
|
}
|
|
2392
|
-
/** Register a `301` redirect route.
|
|
2386
|
+
/** Register a `301` redirect route. */
|
|
2393
2387
|
permanentRedirect(uri, destination) {
|
|
2394
2388
|
return this.redirect(uri, destination, 301);
|
|
2395
2389
|
}
|
|
2396
2390
|
// --- Resource routes (the `Route::resource` family) -----------------------
|
|
2397
2391
|
/**
|
|
2398
2392
|
* Register the seven canonical RESTful routes for `controller` under `name`, mapping each verb+URI
|
|
2399
|
-
* to a controller method
|
|
2393
|
+
* to a controller method:
|
|
2400
2394
|
*
|
|
2401
2395
|
* - `GET name` → `index` (`name.index`)
|
|
2402
2396
|
* - `GET name/create` → `create` (`name.create`)
|
|
@@ -2419,7 +2413,7 @@ var Router = class _Router {
|
|
|
2419
2413
|
}
|
|
2420
2414
|
/**
|
|
2421
2415
|
* Like {@link Router.resource} but for APIs: registers the same routes minus `create` and `edit`
|
|
2422
|
-
* (the HTML form-presenting endpoints).
|
|
2416
|
+
* (the HTML form-presenting endpoints).
|
|
2423
2417
|
*/
|
|
2424
2418
|
apiResource(name, controller, options) {
|
|
2425
2419
|
return this.registerResource(name, controller, true, options);
|
|
@@ -2440,10 +2434,9 @@ var Router = class _Router {
|
|
|
2440
2434
|
return registration;
|
|
2441
2435
|
}
|
|
2442
2436
|
/**
|
|
2443
|
-
* Register a singleton resource
|
|
2437
|
+
* Register a singleton resource - routes for a resource with exactly one instance (a profile, a
|
|
2444
2438
|
* settings page), mapping `GET name` → `show`, `GET name/edit` → `edit`, and `PUT|PATCH name` →
|
|
2445
|
-
* `update` (no `{param}` segment, no `index`/`create`/`store`).
|
|
2446
|
-
* equivalent. Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
2439
|
+
* `update` (no `{param}` segment, no `index`/`create`/`store`). Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
2447
2440
|
* Registration is deferred exactly like {@link Router.resource}.
|
|
2448
2441
|
*/
|
|
2449
2442
|
singleton(name, controller) {
|
|
@@ -2451,8 +2444,7 @@ var Router = class _Router {
|
|
|
2451
2444
|
}
|
|
2452
2445
|
/**
|
|
2453
2446
|
* Like {@link Router.singleton} but for APIs: omits the HTML `edit` route, registering only
|
|
2454
|
-
* `show` and `update` (plus `destroy` after `.destroyable()`).
|
|
2455
|
-
* `Route::apiSingleton()` equivalent.
|
|
2447
|
+
* `show` and `update` (plus `destroy` after `.destroyable()`).
|
|
2456
2448
|
*/
|
|
2457
2449
|
apiSingleton(name, controller) {
|
|
2458
2450
|
return this.registerSingleton(name, controller, true);
|
|
@@ -2526,9 +2518,9 @@ var Router = class _Router {
|
|
|
2526
2518
|
}
|
|
2527
2519
|
// --- Middleware groups + aliases (the `$middlewareGroups` / `$middlewareAliases` family) ------
|
|
2528
2520
|
/**
|
|
2529
|
-
* Register a named middleware *group*
|
|
2521
|
+
* Register a named middleware *group* - a list of references (concrete entries and/or other
|
|
2530
2522
|
* alias/group names) that expand in place wherever the group name is used on a route or group. The
|
|
2531
|
-
*
|
|
2523
|
+
* `Route::middlewareGroup('web', [...])` equivalent. Re-registering a name replaces it.
|
|
2532
2524
|
* Names are resolved (recursively) at match time by {@link Router.resolveMiddleware}.
|
|
2533
2525
|
*/
|
|
2534
2526
|
middlewareGroup(name, entries) {
|
|
@@ -2536,8 +2528,8 @@ var Router = class _Router {
|
|
|
2536
2528
|
return this;
|
|
2537
2529
|
}
|
|
2538
2530
|
/**
|
|
2539
|
-
* Register a middleware *alias*
|
|
2540
|
-
*
|
|
2531
|
+
* Register a middleware *alias* - a short `string` name for a single concrete {@link MiddlewareEntry}.
|
|
2532
|
+
*
|
|
2541
2533
|
* Re-registering a name replaces it.
|
|
2542
2534
|
*/
|
|
2543
2535
|
aliasMiddleware(name, entry) {
|
|
@@ -2559,7 +2551,7 @@ var Router = class _Router {
|
|
|
2559
2551
|
/**
|
|
2560
2552
|
* Resolve a middleware reference list to concrete {@link MiddlewareEntry entries}, expanding
|
|
2561
2553
|
* `string` names: a name resolves first as an **alias** (→ its single entry), else as a **group**
|
|
2562
|
-
* (→ its references, expanded recursively). An unknown name **throws
|
|
2554
|
+
* (→ its references, expanded recursively). An unknown name **throws**, which
|
|
2563
2555
|
* raises when a route references a middleware that is neither an alias nor a group. Cyclic group
|
|
2564
2556
|
* references (a group that, directly or transitively, contains itself) also throw rather than
|
|
2565
2557
|
* recursing without bound. Function/class entries pass through unchanged and in order.
|
|
@@ -2574,7 +2566,7 @@ var Router = class _Router {
|
|
|
2574
2566
|
* Recursive worker for {@link Router.resolveMiddleware}. `groupPath` is the stack of group names
|
|
2575
2567
|
* currently being expanded; revisiting a name already on the path is a cycle (a group that
|
|
2576
2568
|
* directly or transitively contains itself) and throws. The same group may still appear in
|
|
2577
|
-
* sibling branches
|
|
2569
|
+
* sibling branches - only re-entrancy along a single path is rejected.
|
|
2578
2570
|
*/
|
|
2579
2571
|
expandMiddleware(references, groupPath) {
|
|
2580
2572
|
const resolved = [];
|
|
@@ -2614,8 +2606,8 @@ var Router = class _Router {
|
|
|
2614
2606
|
* Serialize the registered routes to a plain, JSON-serializable {@link RouteCache} snapshot
|
|
2615
2607
|
* (methods, path, name, domain, middleware names, and the `[controller, method]` action).
|
|
2616
2608
|
*
|
|
2617
|
-
* Closures cannot be serialized. Mirroring
|
|
2618
|
-
* "Unable to prepare route … for serialization. Uses Closure."
|
|
2609
|
+
* Closures cannot be serialized. Mirroring the conventional `route:cache` - which aborts with
|
|
2610
|
+
* "Unable to prepare route … for serialization. Uses Closure." - this **throws** when any route
|
|
2619
2611
|
* uses a closure handler, rather than silently dropping it, so a cache is always complete or
|
|
2620
2612
|
* absent. Rehydrate with {@link Router.loadCache} or {@link Router.fromCache}.
|
|
2621
2613
|
*/
|
|
@@ -2824,7 +2816,7 @@ var Router = class _Router {
|
|
|
2824
2816
|
return this.signingKey;
|
|
2825
2817
|
}
|
|
2826
2818
|
/**
|
|
2827
|
-
* Build a signed URL for the named route. The
|
|
2819
|
+
* Build a signed URL for the named route. The `URL::signedRoute()` equivalent: the route
|
|
2828
2820
|
* URL is generated as usual, an optional `expires` (a {@link Date} or unix-seconds number) is
|
|
2829
2821
|
* appended, and an HMAC `signature` over the canonical URL is added last. Verify it later with
|
|
2830
2822
|
* {@link Router.hasValidSignature}.
|
|
@@ -2840,7 +2832,7 @@ var Router = class _Router {
|
|
|
2840
2832
|
return `${pathname}?${search.toString()}`;
|
|
2841
2833
|
}
|
|
2842
2834
|
/**
|
|
2843
|
-
* Build a signed URL that expires after `expiresIn` seconds from now. The
|
|
2835
|
+
* Build a signed URL that expires after `expiresIn` seconds from now. The conventional
|
|
2844
2836
|
* `URL::temporarySignedRoute()` equivalent (with the expiry expressed in seconds rather than a
|
|
2845
2837
|
* `DateTime`/minutes).
|
|
2846
2838
|
*/
|
|
@@ -2873,8 +2865,7 @@ var Router = class _Router {
|
|
|
2873
2865
|
return this.validateSignature(req.url()) === "valid";
|
|
2874
2866
|
}
|
|
2875
2867
|
/**
|
|
2876
|
-
* A middleware that aborts unsigned/invalid/expired requests with a `403
|
|
2877
|
-
* `signed` / `ValidateSignature` middleware). On a valid signature it passes control inward.
|
|
2868
|
+
* A middleware that aborts unsigned/invalid/expired requests with a `403`. On a valid signature it passes control inward.
|
|
2878
2869
|
*/
|
|
2879
2870
|
signedMiddleware() {
|
|
2880
2871
|
return (req, next) => {
|
|
@@ -3045,7 +3036,7 @@ function throttle(options) {
|
|
|
3045
3036
|
const decaySeconds = options.decaySeconds ?? 60;
|
|
3046
3037
|
const keyFor = options.key ?? ((req) => `${req.ip() ?? "unknown"}|${req.method()}|${req.path()}`);
|
|
3047
3038
|
return async (req, next) => {
|
|
3048
|
-
const key = `
|
|
3039
|
+
const key = `plinth-throttle:${keyFor(req)}`;
|
|
3049
3040
|
if (options.limiter.tooManyAttempts(key, max)) {
|
|
3050
3041
|
const retryAfter = options.limiter.availableIn(key);
|
|
3051
3042
|
return Response.json({ message: "Too Many Attempts." }, 429).withHeaders({
|