@procedures/peer 0.52.2 → 0.53.1

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @procedures/peer
 
+## 0.53.1
+
+### Patch Changes
+
+- Updated dependencies [84f0c78]
+- Updated dependencies [abf290c]
+  - @procedures/client@0.53.1
+
+## 0.53.0
+
+### Patch Changes
+
+- 0da2c6d: `staticFace()` serves the built files of a page on the listener of a procedures host, next to the procedure faces. Each path stays in the root, also through a symbolic link. A route of the page gets the fallback file when the request accepts `text/html`.
+  
+  Each response has a strict frame policy by default (`DEFAULT_STATIC_HEADERS`), the headers of the options, `nosniff` and an `ETag`. A hidden path (`.env`, `.git`) gets 404, except `.well-known`. A missing root gives 404 until a build makes it. `contentTypeOf()` gives the content type of a file from its extension.
+- The packages use the new versions of their dependencies of the owner: `@mark1russell7/service` `^0.8.3`, `@mark1russell7/coeval` `^0.26.1` and `@mark1russell7/docker-sqlite` `^0.3.0`. The range of `@mark1russell7/collections` stays `^0.5.0`: its version 0.7.0 and later remove names that `@procedures/collections` exports.
+- 556d0a8: The packages use `@mark1russell7/service` `^0.8.2` in place of `^0.6.0`. Version 0.7.0 adds the refusal cause `capacity`, and version 0.8.0 refuses a listen backlog of 0. Version 0.8.2 adds the call context of OpenTelemetry. The types `Clock` and `Cancel` of `@mark1russell7/service/clock` do not change: their home is `@mark1russell7/algebra/clock`, and the entry gives them again.
+  
+  A refusal of a call limit with the cause `capacity` gives `RATE_LIMITED` that is not retryable and has no `retry-after`. A take of one unit does not get this cause, because each policy holds 1 unit or more.
+- Updated dependencies [bc98f77]
+- Updated dependencies [11d9084]
+- Updated dependencies [d28ccb5]
+- Updated dependencies [735cfcf]
+- Updated dependencies
+- Updated dependencies [556d0a8]
+  - @procedures/client@0.53.0
+
+## 0.52.5
+
+### Patch Changes
+
+- Updated dependencies [25a5f44]
+  - @procedures/client@0.52.5
+
+## 0.52.4
+
+### Patch Changes
+
+- @procedures/client@0.52.4
+
+## 0.52.3
+
+### Patch Changes
+
+- Updated dependencies [db1bcaa]
+  - @procedures/client@0.52.3
+
 ## 0.52.2
 
 ### Patch Changes

package/README.md

@@ -108,6 +108,7 @@ This package depends on:
 - `zod` - Schema validation
 - `zod-to-json-schema` - JSON schema generation
 - `@mark1russell7/service` - The runner: the contracts of the parts, and `httpTransport` of `./http`
+- `@mark1russell7/files` - The containment check of the paths of `staticFace()`
 
 ## Usage
 
@@ -193,6 +194,36 @@ const host = createProcedureHost({
 - **`expose`** (a list of patterns, a tool surface or a function): the procedures that the callers of the face reach, as `hostPolicy({ expose })`. The server meets it with the expose rule of the host, for the call and for each nested call. A call outside it gets `NOT_FOUND`, and a nested call of a data-driven procedure outside it gets `NOT_EXPOSED`. The rule applies to each procedure, also to `host.health`, `host.info`, `host.metrics` and `events.subscribe`.
 - A face without these options serves the same calls as before. The option objects of `faces.http` and `faces.ws` take them too.
 
+### The built files of a page
+
+`staticFace()` serves the files of a folder, for example the `dist` folder of a Vite build. Thus an app with a page needs only the one listener of its host.
+
+```typescript
+import { createProcedureHost, staticFace, LOCAL_LISTENER_KNOBS } from "@procedures/peer";
+
+const host = createProcedureHost({
+  registry,
+  faces: {
+    http: true,
+    ws: true,
+    page: staticFace({ root: "dist", headers: { "Content-Security-Policy": "default-src 'self'; frame-ancestors 'self'" } }),
+  },
+  listen: [{ port: 3000, knobs: LOCAL_LISTENER_KNOBS }],
+});
+```
+
+- Put the face last. The first face that takes a request serves it, so the procedure faces keep their paths.
+- The face takes each `GET` and `HEAD` request under its `basePath` (default `/`). The face adds a `/` at the start of a base path that has none.
+- Each path stays in `root`. A path that leaves it, also through a symbolic link, gets 404.
+- A path with a segment that starts with `.` gets 404, so the `.env` or `.git` of a root stay hidden. Only `.well-known` is served.
+- A missing root gives 404. The next request reads the root again, so the files of a later build are served.
+- A folder gives its `index.html`. A path with no file and no extension is a route of the page. A request that accepts `text/html` gets the `fallback` file (default `index.html`). Another request, for example a probe, gets 404. With `fallback: false`, each route gets 404.
+- A route with a dot in its last segment, for example `/u/john.doe`, has an extension. It gets 404, not the fallback.
+- By default, only a page of the same origin can show the files in a frame: `DEFAULT_STATIC_HEADERS` has `Content-Security-Policy: frame-ancestors 'self'` and `X-Frame-Options: SAMEORIGIN`.
+- A header of `headers` replaces the default header of the same name, in any case. A policy of your own replaces the default policy, so put a `frame-ancestors` rule in it.
+- Each response also has `X-Content-Type-Options: nosniff`. A file has an `ETag`, and the same tag in `If-None-Match` gets 304.
+- The request tracking of the host tracks each request, so the drain of a stop waits for it.
+
 ### Creating a Server Peer
 
 `createPeer()` is for a process that has no service of its own: a test, or a host that a procedure starts (`server.create`). The peer builds a host with `createProcedureHost()`, declares its parts in a service of its own, and starts `run()` of `@mark1russell7/service` on a process port that installs no signal handler and never ends the process. `stop()` asks that lifecycle for its shutdown. A process that has a service of its own uses `createProcedureHost()` and `host.declare(svc)` in place of a peer.