@plurnk/plurnk-schemes-http 1.3.11 → 1.4.0

package/.env.defaults

@@ -1,9 +1,9 @@
 # @plurnk/plurnk-schemes-http — .env.defaults (operator config + defaults floor).
 #
 # Every knob this package reads, family-namespaced PLURNK_SCHEMES_HTTP_*. This
-# file IS the operator documentation, and the daemon assembles every installed
-# member's .env.defaults into one operative floor at boot — set-if-unset under
-# the operator's env (service SPEC §operator-config-env-defaults, schemes#31).
+# file is the canonical value registry; {§http-config} owns policy. The daemon
+# assembles every installed member's .env.defaults into one operative floor at
+# boot, set-if-unset under the operator's env {§operator-config-env-defaults}.
 # UNCOMMENTED keys are real defaults the floor sets. COMMENTED keys are modes
 # whose ABSENCE is meaningful (unset = the documented behavior) — the floor
 # must not set them. Standalone (no daemon), the required numerics fail hard
@@ -21,8 +21,8 @@ PLURNK_SCHEMES_HTTP_SALVAGE_MIN_BODY_CHARS=200
 PLURNK_SCHEMES_HTTP_IDLE_TIMEOUT=900000
 
 # ── Defaults (floor-set; override to change) ────────────────────────────────
-# Playwright BrowserType method. "launch" uses the compatible bundled Chromium
-# unless CHANNEL or EXECUTABLE_PATH selects another local browser. "connect"
+# Playwright BrowserType method. "launch" uses an operator-provisioned compatible
+# Chromium unless CHANNEL or EXECUTABLE_PATH selects another local browser. "connect"
 # uses a Playwright protocol endpoint; "connectOverCDP" attaches to a running
 # Chromium browser; "disabled" explicitly removes rendered HTML retrieval.
 PLURNK_SCHEMES_HTTP_PLAYWRIGHT_METHOD=launch
@@ -44,13 +44,16 @@ PLURNK_SCHEMES_HTTP_MOBILE=1
 # 0 opts into revalidation on every read via ETag/304.
 # Required read: unset crashes, naming the var.
 PLURNK_SCHEMES_HTTP_TTL_MS=300000
-# Max HTTP redirect hops the SSRF-guarded fetch follows (WebFetcher). Each hop is
-# re-guarded — a public URL redirecting into private space is refused. 0 follows
-# none (strictest). Required read: unset crashes, naming the var.
+# Max HTTP redirect hops automatic WebFetcher acquisition follows. Every hop is
+# checked; 0 follows none. Required read: unset crashes, naming the var.
 PLURNK_SCHEMES_HTTP_REDIRECTS=5
 # Maximum buffered characters in one incomplete SSE line/event. Exceeding this
 # bound terminates the remote stream instead of allowing unbounded memory growth.
 PLURNK_SCHEMES_HTTP_SSE_MAX_BUFFER_CHARS=1048576
+# Maximum characters retained from a caught fetch, render, or transport
+# diagnostic in a model-facing Problem detail. Complete errors remain in daemon
+# diagnostics.
+PLURNK_SCHEMES_HTTP_ERROR_DETAIL_LIMIT=512
 
 # ── Optional modes (absence IS the mode — never floor-set) ──────────────────
 # Required by connect/connectOverCDP: the Playwright or CDP endpoint.
@@ -63,7 +66,6 @@ PLURNK_SCHEMES_HTTP_SSE_MAX_BUFFER_CHARS=1048576
 # Chromium JS heap cap in MB (--max-old-space-size). Unset → chromium default.
 # PLURNK_SCHEMES_HTTP_CHROMIUM_HEAP_MB=2048
 
-# Native Playwright installation controls remain authoritative and pass through
-# unchanged. These examples are intentionally unset.
+# Native Playwright browser-location controls remain authoritative. This example
+# is intentionally unset; the package never supplies its own path.
 # PLAYWRIGHT_BROWSERS_PATH=/var/cache/ms-playwright
-# PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1

package/README.md

@@ -1,41 +1,88 @@
 # plurnk-schemes-http
 
-`http(s)://` URI scheme handler for the [plurnk](https://github.com/plurnk/plurnk-service) agent runtime. The **first greenfield `@plurnk/plurnk-schemes-*` sibling** — authored entirely against the DB-free capability contract ([`@plurnk/plurnk-schemes`](https://github.com/plurnk/plurnk-service/tree/main/plurnk-schemes) `SchemeCtx`), importing zero plurnk-service internals.
+HTTP(S) request/response and WebSocket scheme handlers for the
+[plurnk](https://github.com/plurnk/plurnk-service) agent runtime. The package is
+authored against the DB-free
+[`@plurnk/plurnk-schemes`](https://github.com/plurnk/plurnk-service/tree/main/plurnk-schemes)
+`SchemeCtx` contract.
 
-## What it does
+## HTTP operations
 
-Lets the model treat any web URL as an addressable, streamable resource:
+| Operation                         | Behavior                                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------- |
+| Unscoped `READ(http(s)://…)`      | Fetch or reuse/revalidate a GET representation, then stream the selected response channel |
+| Scoped `READ(http(s)://…)<scope>` | Apply the standard entry READ to an already-materialized response without refetching      |
+| `FIND(http(s)://…):matcher`       | Materialize an exact URL when required, then use the universal entry query and matcher    |
+| `SEND[200](http(s)://…):body:`    | POST the body and stream the response                                                     |
+| `EDIT(http(s)://…):body:`         | PUT a whole-resource replacement; line-scoped HTTP edits are invalid                      |
+| `KILL(http(s)://…)`               | DELETE the remote resource and stream the response                                        |
+| `SEND[499](http(s)://…)`          | Cancel the routed in-flight subscription                                                  |
+| `SEND[410](http(s)://…)`          | Delete the local stored response entry                                                    |
 
-| Op | Behavior |
-|---|---|
-| `READ(http(s)://host/path)` | Without `<scope>`, fetch/revalidate the URL and stream its readable body. With `<scope>`, read that range from the materialized response without refetching. |
-| `FIND(http(s)://host/path):matcher` | Materialize an exact URL when necessary, then query it through the standard entry FIND contract. Glob/regex scopes query already-materialized web entries. |
-| `SEND[200](http(s)://…)` | Request with a body (POST); response streams back the same way. |
-| `SEND[499](http(s)://…)` | Cancel an in-flight request (abort the fetch). |
-| `SEND[410](http(s)://…)` | Delete the cached response entry. |
+A path-pattern FIND surveys already-materialized web entries; it does not crawl
+or discover the remote web. Exact FIND and matcher READ share the standard
+catalog, matcher evidence, weighting, pagination, and status contract.
 
-Response status + headers land in the `header` channel; the body in `body` (the default).
+## HTTP channels
 
-## Channels
+| Channel  | Content                                                                 |
+| -------- | ----------------------------------------------------------------------- |
+| `body`   | Text, derived Unicode, typed binary marker, SSE data, or readable HTML  |
+| `header` | HTTP status line, headers, and package acquisition metadata             |
+| `html`   | Faithful HTML used to produce the readable body                         |
 
-- `body` — response payload (default channel).
-- `header` — `HTTP <status> <statusText>` line + response headers.
+A fragmentless operation publishes only `body`; auxiliary channels remain
+durable and can be addressed explicitly. Remote HTTP status is stored in
+`header`; the PLURNK operation result reports the streaming lifecycle.
+Binary responses use an installed bounded readable projection when available;
+only derived Unicode becomes durable. Otherwise direct operations preserve a
+typed empty marker and return `415`, while exact query preparation prunes the
+unreadable result from automatic search ingestion. Input above the common
+projection ceiling returns `413`.
 
 ## Design
 
-- **Streaming via the capability `subscriptions` lifecycle** (`open` → `notifyChunk` → `close`). `open()` returns the worker+teardown-composed `AbortSignal`; a `SubscriptionHandle` is registered so the engine routes `SEND[499]` cancellation to the in-flight `fetch`.
-- **Batteries-included rendering** — installation provisions Playwright's compatible Chromium and daemon boot verifies it. The shipped `.env.defaults` also exposes Playwright `launch`, `connect`, and `connectOverCDP`: launch may select an installed browser channel or executable, while connection methods target an operator-managed browser. Rendering may be explicitly disabled; incompatible choices fail instead of falling back silently.
-- **DB-free** — reaches the substrate only through `ctx` capabilities (`subscriptions`, `entries`), never a raw DB handle (plurnk-schemes SPEC §5). This is what the keystone capability ctx made possible.
+- WebFetcher checks automatic byte targets and redirects; direct HTTP,
+  Playwright, and WebSocket use their ordinary configured transports.
+- Direct GET HTML is rendered through Playwright, projected into `body`, and
+  retained faithfully in `html`.
+- GET representations carry method, acquisition-time, and single-variant cache
+  metadata; derived representations also carry projection identity. Explicit
+  request metadata, `Vary`, `no-store`, expired origin freshness, or a reader
+  change prevents unsafe reuse; the operator TTL remains an independent ceiling.
+- HTTP(S) and WS(S) entry identity retains protocol, authority, path, ordered
+  query, and explicit empty query; a fragment selects a channel.
+- Handler-owned browser and socket state follows the shared readiness, drain,
+  and aggregate-shutdown lifecycle.
+- All storage and streaming work uses `SchemeCtx` capabilities rather than a
+  raw database handle.
+
+The same package registers `wss` (with `ws` routing to it) for
+workspace-scoped full-duplex connections. See [`docs/wss.md`](docs/wss.md) for
+its operation surface and current transport limits.
 
 ## Install
 
-```
-npm i @plurnk/plurnk-schemes-http && plurnk start
+Requires Node.js 26 or newer.
+
+```sh
+npm i @plurnk/plurnk-schemes-http
+plurnk start
 ```
 
-Plugin discovery registers it at boot (`package.json#plurnk.kind === "scheme"`).
-No browser setup is required for the default installation.
+The Playwright client is included. Provision a compatible local browser
+separately, select an external Playwright/CDP endpoint, or disable rendering.
+The shipped `.env.defaults` is the canonical operator configuration registry.
 
-## Tests
+For local `launch`:
 
-`test:lint` (tsc) + `test:unit` (conformant `SchemeCtx` stub + mock `fetch`).
+```sh
+npx playwright install chromium
+```
+
+## Verify
+
+```sh
+npm test
+npm run test:intg
+```