create-acrylblends 0.4.0 → 0.4.1

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.
@@ -72,7 +72,29 @@ plugin that only mounted routes is different: its mount and the requests it is s
72
72
  Let the process configuration choose the address. Do not hard-code a development port in a reusable plugin: a plugin mounts routes and
73
73
  leaves the socket to whichever adapter the app runs with.
74
74
 
75
- ## Not yet supported
75
+ ## WebSocket upgrades
76
76
 
77
- WebSocket upgrades under the router are a later task. The adapter's own WebSocket support exists in `src/adapter/` with its tests but is
78
- not wired to the router yet.
77
+ A plugin takes WebSocket upgrades with `ctx.nodeServer.upgrades()` (or `ctx.routerHttp.upgrades()` on the Host's web server, with `ctx.routerHttp.mount(prefix, { upgrade: [paths] })` naming the exact paths). It returns the ported `upgradeWebSocket`; the route is an ordinary route with ordinary middleware in front of it:
78
+
79
+ ```ts
80
+ export function apply(ctx: Context) {
81
+ const upgrade = ctx.nodeServer.upgrades()
82
+ ctx.router.route('/', new Acryl()
83
+ // Checks run before the upgrade: own page, loopback peer, exact Origin and Host. A refusal is a plain HTTP status with Connection: close, sent before any handshake.
84
+ .use('/terminal', ownPage)
85
+ .get('/terminal', upgrade(() => ({
86
+ onMessage(event, socket) {
87
+ if (socket.bufferedAmount < 1_000_000) socket.send(`echo ${String(event.data)}`)
88
+ },
89
+ onClose(event) {
90
+ // Called exactly once, whoever closed the socket.
91
+ },
92
+ }), { textOnly: true })))
93
+ }
94
+ ```
95
+
96
+ - **Limits.** Text frames only with `{ textOnly: true }` (binary frames never reach `onMessage`); `websocket.maxPayload` (default 1 MiB, a bigger frame closes the socket with 1009); no per-message compression; `socket.bufferedAmount` for back-pressure; `socket.close(code, reason)` with application codes such as 1013 or 4404 (a code the protocol forbids on the wire becomes 1011). No raw socket is exposed.
97
+ - **Dead peers.** The server pings every `websocket.heartbeat` ms (default 30 000) and terminates a peer that did not answer the last ping. `websocket.grace` (default 2000) is how long a closing socket gets.
98
+ - **Ownership.** The sockets a plugin's routes accepted belong to that plugin. When it unloads they are closed with 1001 within the grace (what is left is terminated), its handler sees `close` once, other plugins' sockets are untouched, and `ctx.nodeServer.sockets` counts what is still open. Stopping the server closes every socket.
99
+ - **Needs `ws`.** `npm install ws`; an app that never upgrades does not need it.
100
+ - **Tests.** `testWebSocket((request, env) => app.fetch(request, env), '/terminal', { headers })` from `acrylblends/node-server` runs the route and its middleware in process: a refusal answers `{ status }`, an accepted connection gives a `socket` that sends text frames, collects what the handler sent (`received`) and closes.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-acrylblends",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "Create an Acryl app: npm create acrylblends@latest",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -36,7 +36,7 @@
36
36
  "scaffold"
37
37
  ],
38
38
  "dependencies": {
39
- "acrylblends": "^0.10.0",
39
+ "acrylblends": "^0.11.0",
40
40
  "@webboxes/app-persistence": "0.1.1"
41
41
  },
42
42
  "publishConfig": {