@jsenv/server 17.6.6 → 17.6.8

package/docs/https.md

@@ -0,0 +1,77 @@
+# HTTPS
+
+```js
+import { startServer } from "@jsenv/server";
+
+const server = await startServer();
+server.origin.startsWith("http://"); // true
+```
+
+```js
+import { readFileSync } from "node:fs";
+import { startServer } from "@jsenv/server";
+
+const server = await startServer({
+  https: {
+    certificate: readFileSync(new URL("./server.crt", import.meta.url), "utf8"),
+    privateKey: readFileSync(new URL("./server.key", import.meta.url), "utf8"),
+  },
+});
+server.origin.startsWith("https://"); // true
+```
+
+Without certificate files, [@jsenv/https-local](https://github.com/jsenv/core/tree/main/packages/tooling/https-local) generates one for localhost, signed by an authority it can install on the machine:
+
+```js
+import { requestCertificate } from "@jsenv/https-local";
+import { startServer } from "@jsenv/server";
+
+const { certificate, privateKey } = requestCertificate();
+await startServer({ https: { certificate, privateKey } });
+```
+
+## Http requests on an https server
+
+By default an https server also accepts http on the same port and redirects it (301) to the https origin. `redirectHttpToHttps: false` refuses http instead. To serve both:
+
+```js
+await startServer({
+  https: { certificate, privateKey },
+  allowHttpRequestOnHttps: true,
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: (request) => {
+        return new Response(
+          request.origin.startsWith("http:")
+            ? `Welcome http user`
+            : `Welcome https user`,
+        );
+      },
+    },
+  ],
+});
+```
+
+## http2
+
+```js
+await startServer({
+  https: { certificate, privateKey },
+  http2: true,
+});
+```
+
+Http2 needs https (browsers do not speak it in clear). Http/1.1 clients are still accepted, unless `http1Allowed: false`.
+
+**When it is worth it.** A browser opens at most 6 http/1.1 connections per origin, http2 multiplexes everything on one. Measured with Chromium loading a page of 300 ES modules served by this package:
+
+| network                               | http/1.1 | http2  |
+| ------------------------------------- | -------- | ------ |
+| localhost                             | 80 ms    | 83 ms  |
+| 5 ms of latency (a phone on the wifi) | 369 ms   | 131 ms |
+| 20 ms of latency                      | 1300 ms  | 135 ms |
+
+Nothing to gain on the machine itself; a lot as soon as there is latency, so serving other devices (`acceptAnyIp`) is the case for it. The price is a certificate the device trusts.
+
+**What is lost.** Http2 has no reason phrase (RFC 9113): the `statusText` of a response only reaches the server logs and the body of 4xx/5xx responses, browser devtools show the status code alone. Http/1.1 stays the default for that reason: during development the status line is where the server explains a 404 or a 403 at a glance.

package/docs/lifecycle.md

@@ -0,0 +1,52 @@
+# Lifecycle
+
+```js
+import { startServer } from "@jsenv/server";
+
+const server = await startServer({ port: 3000 });
+server.origin; // "http://localhost:3000"
+server.origins; // { local: "http://localhost:3000", localip: "http://127.0.0.1:3000" }
+server.port; // 3000
+server.getStatus(); // "opened"
+```
+
+`startServer` resolves once the server listens. With `port: 0` (the default) the OS picks a free port, `server.port` tells which one; `portHint` asks for a port and takes the next free one when it is busy. `hostname` ("localhost" by default) can be an ip. `acceptAnyIp: true` listens on every interface so that other machines reach the server, at `server.origins.externalip`.
+
+## Stopping
+
+```js
+await server.stop();
+server.getStatus(); // "stopped"
+```
+
+`stop` answers every request still running with 503, then closes every connection, and resolves once everything is closed. A response already being written is cut short: its status is already sent. It takes a reason, anything, which `stoppedPromise` resolves with:
+
+```js
+import { startServer, STOP_REASON_PROCESS_SIGINT } from "@jsenv/server";
+
+const server = await startServer();
+server.stoppedPromise.then((reason) => {
+  if (reason === STOP_REASON_PROCESS_SIGINT) {
+    console.log("stopped by ctrl+c");
+  }
+});
+```
+
+The server stops by itself on SIGINT (`stopOnSIGINT`, off inside a cluster worker where the primary process is in charge) and on SIGHUP, SIGTERM, beforeExit, exit (`stopOnExit`); the reasons are the `STOP_REASON_PROCESS_*` exports. `stopOnInternalError` stops it when a route throws. The `signal` option cancels the start itself.
+
+## Keeping the process alive
+
+A listening server keeps the process alive. `keepProcessAlive: false` lets the process exit when nothing else runs — tests want that: the server stops on its own once the test is done.
+
+## Running something as long as the server runs
+
+```js
+server.addEffect(() => {
+  const interval = setInterval(doSomething, 1000);
+  return () => {
+    clearInterval(interval);
+  };
+});
+```
+
+The callback runs right away, the function it returns runs when the server stops. Plugins have `serverListening` and `serverStopped` hooks for the same purpose (see [plugins](./plugins.md)).

package/docs/plugins.md

@@ -0,0 +1,53 @@
+# Plugins
+
+A server plugin is an object with a `name` and some of the hooks below. Plugins run in the order they are given, after the built-in ones. An array of plugins is flattened, so a function can return several plugins, or none (`serverPluginCORS` returns `[]` when CORS stays disabled).
+
+```js
+await startServer({
+  plugins: [
+    {
+      name: "my_plugin",
+      routes: [{ endpoint: "GET /health", fetch: () => new Response("ok") }],
+      injectResponseProperties: () => {
+        return { headers: { "x-powered-by": "jsenv" } };
+      },
+    },
+  ],
+});
+```
+
+## Hooks
+
+In the order they run for a request:
+
+| hook                         | signature                                                                       | role                                                                                                                                                       |
+| ---------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `serverListening`            | `({ port })`                                                                    | once, when the server listens                                                                                                                              |
+| `redirectRequest`            | `(request) => { resource } \| { pathname } \| { ...requestProperties } \| null` | replace the request seen by the routes; `request.original` keeps the first one                                                                             |
+| `augmentRouteFetchSecondArg` | `async (request, helpers) => { ...moreHelpers } \| null`                        | add helpers for the routes                                                                                                                                 |
+| `grantPermissions`           | `async (request) => ["permission", …] \| null`                                  | called lazily, at most once per request, only when a route declares permissions                                                                            |
+| `routes`                     | an array of route descriptors                                                   | appended after the routes given to `startServer`                                                                                                           |
+| `handleError`                | `async (error, { request }) => response \| null`                                | answer a route that threw; the first response wins ([handling errors](./handling_errors.md))                                                               |
+| `injectResponseProperties`   | `(request, response) => responseToCompose \| null`                              | compose something into every response — headers mostly, see `composeTwoResponses`                                                                          |
+| `inspectResponse`            | `(request, { response, warn })`                                                 | look at the final response, after every injection, before it is sent (`response` is `{ status, statusText, headers, body }`); `warn` logs for that request |
+| `serverStopped`              | `({ reason })`                                                                  | once, when the server stopped                                                                                                                              |
+
+`redirectRequest` and `injectResponseProperties` are synchronous; `augmentRouteFetchSecondArg`, `grantPermissions` and `handleError` may return a promise.
+
+Lifecycle properties: `init()` runs before the server starts (returning `false` disables the plugin, returning a function registers it as `destroy`), `destroy()` runs when the server stops, `effect({ otherPlugins })` runs after every `init` (returning nothing disables the plugin).
+
+## Built-in plugins
+
+Always on:
+
+- response cookies — `helpers.responseCookies.set(name, value, options)` and `.delete(name)`,
+- default body for 4xx/5xx — a response without body for such a status gets one from its `statusText`/`statusMessage`,
+- route inspector — `GET /.internal/route_inspector` and `GET /.internal/routes.json`.
+
+With `canExposeSensitiveData` (development only, see [security](./security.md)):
+
+- open file — `GET /.internal/open_file/*` opens a file of the machine in the editor,
+- internal client files — `GET /@jsenv/server/*` serves this package's client files,
+- autoreload on restart — `GET /.internal/alive.websocket` and `GET /.internal/alive.eventsource` close when the server stops, so a client reloads.
+
+Exported, to add yourself: `serverPluginCORS`, `serverPluginErrorHandler`, `serverPluginRequestAliases`, `serverPluginResponseAcceptanceCheck`. Their options are in their JSDoc.

package/docs/security.md

@@ -0,0 +1,32 @@
+# Security
+
+What the server takes care of, and what it leaves to the code around it.
+
+## What it does
+
+- A malformed header (`forwarded`, `cookie`, `referer`, `accept`…) never takes the server down: a request that cannot be read is answered 500 and logged.
+- **The `host` header is checked.** A request whose host is not one of the names the server is reached at (localhost, `hostname`, the machine name and ips, `allowedHosts`) is answered 403. Without this a page served by another site reads the responses once its DNS name is rebound to this machine — the request comes from the developer's own browser, so listening on localhost is no protection. A custom name (an `/etc/hosts` entry, a tunnel) goes in `hostname` or `allowedHosts`; `allowedHosts: true` disables the check.
+- **Request bodies are bounded.** `request.json()`, `text()`, `buffer()` and `queryString()` answer 413 past `requestBodyMaxSize` (1 MiB by default), from the `content-length` when there is one, else while reading; the rest of the body is drained for a few seconds so that the client gets the 413, then the connection is cut. A route accepting more passes its own `{ maxSize }`. `request.body` (the observable) is never limited: who streams it takes the responsibility. `formData()` is bounded by formidable (200 MB per file, 20 MB of fields).
+- What a response echoes from the request (the url in a 404 message, a file path in a status text) is escaped in the html error pages, and status texts are reduced to what a status line accepts.
+- `createFileSystemFetch` refuses to leave its directory (403).
+- A route declaring permissions hides every route that declares none: forgetting `permissionsRequired` cannot expose a route ([handling requests](./handling_requests.md)).
+- Once one route has permissions, the route inspector only lists what the requester may see.
+
+## `canExposeSensitiveData`
+
+This option lets the server hand out what belongs to the machine it runs on. It is meant for the developer's machine, never for a server others can reach. It unlocks:
+
+- file paths in status texts (a 404 from `createFileSystemFetch` says which path);
+- the declaration source of every route in the route inspector, where every route is listed whatever its permissions;
+- `GET /.internal/open_file/*`, which opens any file of the machine in the editor;
+- `GET /@jsenv/server/*`, which serves this package's own files;
+- `/.internal/alive.websocket` and `/.internal/alive.eventsource`, telling clients when the server restarts.
+
+`sendErrorDetails` of `serverPluginErrorHandler` is of the same kind: a stack reveals file paths and code.
+
+## What it leaves to you
+
+- **Forwarded headers are trusted as-is.** `request.ipForwarded`, `protoForwarded` and `hostForwarded` are what the `forwarded` / `x-forwarded-*` headers say; any client can send them. Read them only behind a proxy you control, `request.ip` is the socket address.
+- **Uploaded files are not cleaned up.** `formData()` writes them to the temp directory and leaves them there.
+- **A route that throws with no error handler exits the process.** Always run with `serverPluginErrorHandler` (or a `handleError` plugin), see [handling errors](./handling_errors.md).
+- **No rate limiting, no authentication.** `grantPermissions` is where a session or a token becomes permissions; what it checks is up to you.

package/docs/server_sent_events.md

@@ -0,0 +1,64 @@
+# Server-Sent Events
+
+`ServerEvents` keeps track of the connected clients and broadcasts events to them. A client connects with an `EventSource` (`accept: text/event-stream`) or with a `WebSocket`: `serverEvents.fetch` handles both.
+
+_server.js_
+
+```js
+import { ServerEvents, startServer } from "@jsenv/server";
+
+const serverEvents = new ServerEvents();
+
+setInterval(() => {
+  serverEvents.sendEventToAllClients({
+    type: "ping",
+    data: JSON.stringify({ ts: Date.now() }),
+  });
+}, 1000);
+
+await startServer({
+  port: 3456,
+  routes: [
+    {
+      endpoint: "GET /events",
+      fetch: serverEvents.fetch,
+    },
+  ],
+});
+```
+
+_client.js_
+
+```js
+const eventSource = new EventSource("http://localhost:3456/events");
+eventSource.addEventListener("ping", (event) => {
+  console.log("ping from server", event.lastEventId, JSON.parse(event.data));
+});
+```
+
+![Screencast of server sent events execution in a terminal](./screenshots/sse-screencast.gif)
+
+An event is `{ type, data, id, retry }`; `data` is sent as is (stringify objects yourself) and must hold no line break: the event stream is line based, a line break ends the event. `JSON.stringify` without indentation is safe. Every event gets an incrementing `id` and is kept (`historyLength`, 1000 by default): a client reconnecting with a `last-event-id` header, or a `?last-event-id=` search param, receives what it missed. A comment is sent every `keepaliveDuration` (30s) so that proxies keep the connection open.
+
+A websocket client receives each event as one message, the whole event as json: `JSON.parse(message.data)` gives `{ type, data, id }`.
+
+Past `maxClientAllowed` (100) a new client is refused with 503, or the oldest one is disconnected with `actionOnClientLimitReached: "kick-oldest"`. `close()` disconnects everyone and answers 204 until `open()`. `getClientCount()` and `getAllEventSince(id)` tell where things stand.
+
+## Producing events only when someone listens
+
+`LazyServerEvents` runs a producer when the first client connects and its cleanup when the last one leaves — a file watcher, a database subscription, a timer. Only `fetch` is exposed: events can only come from the producer.
+
+```js
+import { LazyServerEvents } from "@jsenv/server";
+
+const ticks = new LazyServerEvents(({ sendEvent }) => {
+  const interval = setInterval(() => {
+    sendEvent({ type: "tick", data: new Date().toISOString() });
+  }, 1000);
+  return () => {
+    clearInterval(interval);
+  };
+});
+
+// route: { endpoint: "GET /ticks", fetch: ticks.fetch }
+```

package/docs/server_timing.md

@@ -0,0 +1,70 @@
+# Server timing
+
+`serverTiming: true` sends a `server-timing` response header telling what the server spent its time on. Devtools show it next to the TTFB of each request.
+
+_Chrome devtools, TTFB:_
+
+![screenshot of chrome devtools TTFB](./screenshots/devtools_TTFB.png)
+
+_Chrome devtools, server timing:_
+
+![screenshot of chrome devtools server timing](./screenshots/devtools_server_timing.png)
+
+```js
+import { startServer } from "@jsenv/server";
+
+await startServer({
+  serverTiming: true,
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: async (request, { timing }) => {
+        const waitTiming = timing("waiting 50ms");
+        await new Promise((resolve) => {
+          setTimeout(resolve, 50);
+        });
+        waitTiming.end();
+        return new Response("Hello");
+      },
+    },
+  ],
+});
+```
+
+```console
+server-timing: a;desc="time to start responding";dur=51.2, b;desc="routing";dur=0.1, c;desc="waiting 50ms";dur=50.7
+```
+
+The header holds:
+
+- `time to start responding`, from the request to the response headers;
+- the routing of each group of routes (`routing`, or `<plugin>.routing` for the routes a plugin brought);
+- what the route measured with `helpers.timing(name)`; `createFileSystemFetch` measures its stat and etag;
+- the `timing` property a plain response object hands back: `{ "db query": 12.3, "served from cache": null }` — a `null` duration is a marker, something to say with nothing to measure.
+
+Entries are named `a`, `b`, `c`… because devtools sort them alphabetically; the `desc` carries the name.
+
+`serverTiming: { minDuration: 0.5 }` drops the entries that took less than that many milliseconds: a request crosses every route, and a wall of sub-millisecond `routing` entries buries the measures worth reading. `time to start responding` and the markers always stay.
+
+## Measuring without telling everyone
+
+The header describes what the server does internally; an api usually wants it for itself, a bench or a probe, and for nobody else. Give a function instead of `true` and it is asked once per request, on what the client sent:
+
+```js
+const PERF_TIMING_TOKEN = process.env.PERF_TIMING_TOKEN;
+const isPerfTimingClient = (request) =>
+  request.headers["x-perf-timing"] === PERF_TIMING_TOKEN;
+
+await startServer({
+  serverTiming: isPerfTimingClient,
+  plugins: [
+    serverPluginCORS({
+      accessControlAllowedOrigins: ["https://app.example.com"],
+      // without it a page cannot read the timings of a cross-origin response
+      timingAllowOrigin: isPerfTimingClient,
+    }),
+  ],
+});
+```
+
+`{ enabled: isPerfTimingClient, minDuration: 1 }` says the same thing with a `minDuration`. When the predicate says no nothing is measured for that request and no header is composed; routes still call `helpers.timing(name)` unconditionally, it costs them nothing.

package/docs/serving_files.md

@@ -0,0 +1,64 @@
+# Serving files
+
+```js
+import { createFileSystemFetch, startServer } from "@jsenv/server";
+
+await startServer({
+  routes: [
+    {
+      endpoint: "GET /assets/*",
+      fetch: createFileSystemFetch(import.meta.resolve("./assets/")),
+    },
+    {
+      endpoint: "GET *",
+      fetch: createFileSystemFetch(import.meta.resolve("./public/"), {
+        mainFileRelativeUrl: "./index.html",
+      }),
+    },
+  ],
+});
+```
+
+The part of the url captured by `*` (the whole resource when the endpoint has none) is resolved inside the directory. A url leaving the directory (`..`) is answered 403. Any method other than GET and HEAD is declined: the next route is tried. The `content-type` comes from the file extension.
+
+The options are in the JSDoc of `createFileSystemFetch`; what follows is how they combine.
+
+## Client cache
+
+By default every request gets 200 with the content. Two ways to unlock 304:
+
+- `etagEnabled` — an `etag` computed from the content, remembered per file until its stats change (`etagMemory`, `etagMemoryMaxSize`); a matching `if-none-match` gets 304. Robust.
+- `mtimeEnabled` — a `last-modified` header from the filesystem date, second precision; a recent enough `if-modified-since` gets 304. Relies on filesystem dates being meaningful.
+
+When both are set, etag wins.
+
+`cacheControl` becomes the `cache-control` header. By default a versioned url (`isVersioned`: the url has a `v` search param) is `private,max-age=2592000,immutable` and anything else `private,max-age=0,must-revalidate`. It can be a function of the request:
+
+```js
+createFileSystemFetch(import.meta.resolve("./"), {
+  etagEnabled: true,
+  cacheControl: (request) =>
+    request.resource === "/"
+      ? `private,max-age=0,must-revalidate`
+      : `private,max-age=3600,immutable`,
+});
+```
+
+`"no-store"` disables etag and mtime, they would be pointless.
+
+## Compression
+
+`compressionEnabled` compresses textual files bigger than `compressionSizeThreshold` (1024 bytes) with brotli, gzip or deflate, whichever `accept-encoding` prefers. The compression happens for every request (brotli at quality 4 to keep it cheap) and the response has no `content-length`: for production, compress the files once at build time instead.
+
+## Directories
+
+A url pointing to a directory gets 403, unless:
+
+- `canReadDirectory: true` — the listing is sent, as json or as an html page of links (see `fetchDirectory`),
+- `mainFileRelativeUrl` — that file is sent for the root of the served directory, and for any extension-less url that does not exist (client side routing needs the same page for `/users/42`). A subdirectory still gets 403.
+
+`ENOENTFallback: () => fileUrl` serves another file when the requested one does not exist.
+
+## What a 404 says
+
+The status text is `ENOENT: File not found`; the file path is added only when the server runs with `canExposeSensitiveData` (see [security](./security.md)). Same for the other filesystem errors (EACCES → 403, EBUSY → 503 with `retry-after`, …).

package/docs/websocket.md

@@ -0,0 +1,64 @@
+# WebSocket
+
+A route accepts a websocket by returning a `WebSocketResponse`:
+
+_server.js_
+
+```js
+import {
+  createFileSystemFetch,
+  startServer,
+  WebSocketResponse,
+} from "@jsenv/server";
+
+await startServer({
+  port: 3000,
+  routes: [
+    {
+      endpoint: "GET /chat.websocket",
+      fetch: () => {
+        return new WebSocketResponse((websocket) => {
+          websocket.send("Hello world");
+          websocket.on("message", (data) => {
+            websocket.send(data);
+          });
+          return () => {
+            // the client is gone
+          };
+        });
+      },
+    },
+    {
+      endpoint: "GET *",
+      fetch: createFileSystemFetch(import.meta.resolve("./")),
+    },
+  ],
+});
+```
+
+_client.html_
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Title</title>
+    <link rel="icon" href="data:," />
+  </head>
+
+  <body>
+    <script>
+      const websocket = new WebSocket("ws://localhost:3000/chat.websocket");
+      websocket.onmessage = (message) => {
+        document.body.appendChild(document.createTextNode(message.data));
+      };
+    </script>
+  </body>
+</html>
+```
+
+A route is a websocket route when its endpoint ends with `.websocket` or its `headers` pattern has `upgrade: "websocket"`; a plain request to it is answered 426. The handler receives the [ws](https://github.com/websockets/ws/blob/master/doc/ws.md) socket once the upgrade is done; if it returns a function, that function runs when the socket closes.
+
+A websocket route can still refuse the upgrade by returning a regular response (a 401 for instance). A 101 response that is not a `WebSocketResponse` is an error, and so is a `WebSocketResponse` returned to a request that did not ask for an upgrade.
+
+`server.webSocketOrigin` is the `ws://` (or `wss://`) origin of the server. To broadcast to many clients, see [server sent events](./server_sent_events.md): `ServerEvents` accepts websocket clients too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/server",
-  "version": "17.6.6",
+  "version": "17.6.8",
   "type": "module",
   "description": "A modern Node.js HTTP server with declarative routing, content negotiation, and WebSocket support",
   "repository": {
@@ -28,6 +28,7 @@
   },
   "files": [
     "/dist/",
+    "/docs/",
     "/index.js",
     "/src/"
   ],
@@ -54,10 +55,10 @@
     "@jsenv/url-pattern": "../../tooling/url-pattern",
     "@jsenv/urls": "../../tooling/urls",
     "@jsenv/utils": "../../tooling/utils",
-    "eventsource": "5.1.1",
+    "eventsource": "5.1.2",
     "formidable": "3.5.4",
     "playwright": "1.63.0",
-    "undici": "8.10.2",
+    "undici": "8.11.2",
     "ws": "8.21.3"
   },
   "publishConfig": {

package/src/interfacing_with_node/from_node_request.js

@@ -20,6 +20,10 @@ import {
 } from "../internal/colorize_response_status.js";
 import { headersFromObject } from "../internal/headers_from_object.js";
 import { parseSingleHeaderWithAttributes } from "../internal/multiple_header.js";
+import {
+  readRequestTarget,
+  resourceToUrlObject,
+} from "../internal/request_target.js";
 import { observableFromNodeStream } from "./observable_from_node_stream.js";
 
 export const fromNodeRequest = (
@@ -66,8 +70,13 @@ export const fromNodeRequest = (
   nodeRequest.pause();
   const body = observableFromNodeStream(nodeRequest);
 
+  // an absolute-form target names the origin the request is for; the host
+  // header is ignored in that case (RFC 9112 section 3.3)
+  const requestTarget = readRequestTarget(nodeRequest.url);
   let requestOrigin;
-  if (nodeRequest.upgrade) {
+  if (requestTarget.origin) {
+    requestOrigin = requestTarget.origin;
+  } else if (nodeRequest.upgrade) {
     requestOrigin = serverOrigin;
   } else if (nodeRequest.authority) {
     requestOrigin = nodeRequest.connection.encrypted
@@ -200,7 +209,7 @@ export const fromNodeRequest = (
     http2: Boolean(nodeRequest.stream),
     origin: requestOrigin,
     ...getPropertiesFromResource({
-      resource: nodeRequest.url,
+      resource: requestTarget.resource,
       baseUrl: requestOrigin,
     }),
     method: nodeRequest.method,
@@ -440,13 +449,12 @@ export const applyRedirectionToRequest = (
   };
 };
 const getPropertiesFromResource = ({ resource, baseUrl }) => {
-  const urlObject = new URL(resource, baseUrl);
-  let pathname = urlObject.pathname;
+  const urlObject = resourceToUrlObject(resource, baseUrl);
 
   return {
     url: String(urlObject),
     searchParams: urlObject.searchParams,
-    pathname,
+    pathname: urlObject.pathname,
     resource,
   };
 };

package/src/internal/request_target.js

@@ -0,0 +1,55 @@
+/*
+ * A request target is the text between the method and the http version on the
+ * request line (RFC 9112 section 3.2), or the ":path" pseudo header in http2.
+ * It is a path, not a url reference, and the two must never be confused:
+ * "//wp-includes/x" is an origin-form target whose first path segment is
+ * empty, but `new URL("//wp-includes/x", origin)` reads it as a
+ * protocol-relative reference and turns "wp-includes" into the host. So the
+ * path is assigned onto the origin instead, and what a client sends can never
+ * replace that origin.
+ *
+ * The one form that legitimately names an origin is absolute-form
+ * ("GET http://host/path", sent by proxies and open-proxy scanners); it is
+ * read as such so the origin it names goes through the allowedHosts check
+ * like any other host, instead of reaching the routes unchecked.
+ */
+
+const ABSOLUTE_FORM_REGEX = /^[a-z][a-z0-9+\-.]*:\/\//i;
+
+/**
+ * @param {string} target the raw request target
+ * @returns {{ origin: string|null, host: string|null, resource: string }|null}
+ *   null when the target cannot be read; the server answers 400
+ */
+export const readRequestTarget = (target) => {
+  if (!ABSOLUTE_FORM_REGEX.test(target)) {
+    // origin-form ("/path?query"), asterisk-form ("*") or authority-form
+    return { origin: null, host: null, resource: target };
+  }
+  if (!URL.canParse(target)) {
+    return null;
+  }
+  const urlObject = new URL(target);
+  if (urlObject.protocol !== "http:" && urlObject.protocol !== "https:") {
+    return null;
+  }
+  return {
+    origin: urlObject.origin,
+    host: urlObject.host,
+    resource: `${urlObject.pathname}${urlObject.search}`,
+  };
+};
+
+// the search of baseUrl is dropped: the resource carries its own
+export const resourceToUrlObject = (resource, baseUrl) => {
+  const urlObject = new URL(baseUrl);
+  const searchSeparatorIndex = resource.indexOf("?");
+  if (searchSeparatorIndex === -1) {
+    urlObject.pathname = resource;
+    urlObject.search = "";
+  } else {
+    urlObject.pathname = resource.slice(0, searchSeparatorIndex);
+    urlObject.search = resource.slice(searchSeparatorIndex);
+  }
+  return urlObject;
+};