@adonix.org/cloud-spark 0.0.194 → 1.0.0

package/README.md

@@ -1,4 +1,4 @@
-# Cloud⚡️Spark
+# Cloud⚡Spark
 
 [![npm version](https://img.shields.io/npm/v/@adonix.org/cloud-spark.svg?color=blue)](https://www.npmjs.com/package/@adonix.org/cloud-spark)
 [![Apache 2.0 License](https://badges.adonix.org/License/Apache%202.0?color=blue)](https://github.com/adonix-org/cloud-spark/blob/main/LICENSE)
@@ -11,12 +11,37 @@
 
 CloudSpark provides a logical foundation for building Cloudflare Workers. It works well for simple workers or projects that grow in complexity, helping keep code organized and functionality scalable. It is lightweight and designed to let you focus on the logic that powers your worker.
 
-:bulb: If you are new to _Cloudflare Workers_, create a free [Cloudflare account](https://dash.cloudflare.com/sign-up) and install their command line interface [Wrangler](#cowboy_hat_face-wrangler).
+:bulb: If you are new to _Cloudflare Workers_, create a free [Cloudflare account](https://dash.cloudflare.com/sign-up) and install their command line interface [Wrangler](#partly_sunny-wrangler).
 
 Detailed worker documentation can also be found [here](https://developers.cloudflare.com/workers/).
 
 <br>
 
+## :books: Contents
+
+- [Install](#package-install)
+
+- [Quickstart](#rocket-quickstart)
+
+- [Basic Worker](#arrow_right-basic-worker)
+
+- [Route Worker](#twisted_rightwards_arrows-route-worker)
+
+- [Middleware](#gear-middleware)
+    - [CORS](#cors)
+    - [Cache](#cache)
+    - [WebSocket](#websocket)
+    - [Custom](#custom)
+    - [Ordering](#ordering)
+
+- [WebSockets](#left_right_arrow-web-sockets)
+
+- [Wrangler](#partly_sunny-wrangler)
+
+- [Links](#link-links)
+
+<br>
+
 ## :package: Install
 
 ```bash
@@ -27,7 +52,7 @@ npm install @adonix.org/cloud-spark
 
 ## :rocket: Quickstart
 
-:computer: Use [Wrangler](#cowboy_hat_face-wrangler) to create a new project:
+:computer: Use [Wrangler](#partly_sunny-wrangler) to create a new project:
 
 ```bash
 wrangler init
@@ -103,7 +128,7 @@ As shown in the [Quickstart](#rocket-quickstart), BasicWorker is the base class
 - Support for built-in and custom middleware.
 - Catching unhandled errors.
 
-Subclasses only need to implement the HTTP methods that their worker will handle. Each method can be overridden independently, and additional functionality such as [middleware](#gear-middleware) can be added as needed.
+Subclasses only need to implement the HTTP methods their worker will handle. Each method can be overridden independently, and additional functionality such as [middleware](#gear-middleware) can be added as needed.
 
 Building on the [Quickstart](#rocket-quickstart), what follows is a more complete example:
 
@@ -426,14 +451,17 @@ class ChatWorker extends RouteWorker {
      * in wrangler.jsonc
      */
     protected upgrade(params: PathParams): Promise<Response> {
-        const room = params["room"];
-        const chat = this.env.CHAT;
+        /**
+         * Get the Durable Object stub for the chat room
+         * defined by the "room" path parameter.
+         */
+        const stub = this.env.CHAT_ROOM.getByName(params["room"]);
 
         /**
          * Request has already been validated by the
          * WebSocket middleware.
          */
-        return chat.get(chat.idFromName(room)).fetch(this.request);
+        return stub.fetch(this.request);
     }
 }
 
@@ -443,6 +471,8 @@ class ChatWorker extends RouteWorker {
 export default ChatWorker.ignite();
 ```
 
+:bulb: See the complete WebSocket example [here](#left_right_arrow-web-sockets).
+
 ### Custom
 
 Create custom middleware by implementing the [Middleware](https://github.com/adonix-org/cloud-spark/blob/main/src/interfaces/middleware.ts) interface and its single _handle_ method, then register it with your worker. Within your middleware, you can inspect requests and modify responses or short-circuit processing entirely.
@@ -519,13 +549,261 @@ export function poweredby(name?: string): Middleware {
 }
 ```
 
+### Ordering
+
+The order in which middleware is registered by a worker can matter depending on the implementation. It helps to visualize ordering as _top-down_ for requests and _bottom-up_ for responses.
+
+Here is a what a full `GET` request flow with middleware `A`, `B`, and `C` could look like:
+
+```typescript
+                  Full
+
+      Request               Response
+         ↓     this.use(A)     ↑
+         ↓     this.use(B)     ↑
+         ↓     this.use(C)     ↑
+           →      get()      →
+
+```
+
+Now imagine `B` middleware returns a response early and short-circuits the flow:
+
+```typescript
+            Short Circuit B
+
+      Request               Response
+         ↓     this.use(A)     ↑
+         ↓     this.use(B)   →
+               this.use(C)
+                  get()
+```
+
+In this scenario, neither middleware `C` nor the worker's `get()` method executes. This is exactly what you want, for example, when using the [Cache](#cache) middleware. If a valid response is found in the cache, that response can and should be returned immediately.
+
+However, this illustrates that different behavior can occur depending on the order of middleware registration.
+
+We can use the built-in [Cache](#cache) and [CORS](#cors) middleware as a more concrete example:
+
+```typescript
+/**
+ * This version results in CORS response headers stored in
+ * the cache. On the first cacheable response, CORS middleware
+ * applies its response headers BEFORE caching.
+ */
+this.use(cache());
+this.use(cors());
+
+/**
+ * This version results in CORS response headers NOT stored
+ * in the cache, which is likely preferred. Fresh CORS headers
+ * are added to every response regardless of cache status.
+ */
+this.use(cors());
+this.use(cache());
+```
+
+The difference in behavior becomes clear when disabling the CORS middleware on the worker. In the first version, CORS headers remain on all cached responses until the cached version expires. In the second version, disabling CORS takes effect immediately—all responses, cached or not, will no longer include CORS headers.
+
 <br>
 
 ## :left_right_arrow: Web Sockets
 
+Simplify [WebSocket](https://developers.cloudflare.com/durable-objects/best-practices/websockets/#_top) connection management with CloudSpark. Features include:
+
+- Type-safe session metadata
+- Support for [Hibernation WebSocket API](https://developers.cloudflare.com/durable-objects/best-practices/websockets/#durable-objects-hibernation-websocket-api) (recommended)
+- Support for [Standard WebSocket API](https://developers.cloudflare.com/workers/runtime-apis/websockets/)
+- [Middleware](#websocket) for Upgrade request validation
+- Standardized WebSocketUpgrade response
+
+The following is a simple chat with hibernation example:
+
+:page_facing_up: wrangler.jsonc
+
+```jsonc
+/**
+ * Remember to rerun 'wrangler types' after you change your
+ * wrangler.json file.
+ */
+{
+    "$schema": "node_modules/wrangler/config-schema.json",
+    "name": "chat-room",
+    "main": "src/index.ts",
+    "compatibility_date": "2025-11-01",
+    "observability": {
+        "enabled": true,
+    },
+    "durable_objects": {
+        "bindings": [
+            {
+                "name": "CHAT_ROOM",
+                "class_name": "ChatRoom",
+            },
+        ],
+    },
+    "migrations": [
+        {
+            "tag": "v1",
+            "new_sqlite_classes": ["ChatRoom"],
+        },
+    ],
+}
+```
+
+:page_facing_up: index.ts
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+
+import {
+    GET,
+    PathParams,
+    RouteWorker,
+    websocket,
+    WebSocketSessions,
+    WebSocketUpgrade,
+} from "@adonix.org/cloud-spark";
+
+/**
+ * Metadata attached to each session.
+ */
+interface Profile {
+    name: string;
+    lastActive: number;
+}
+
+export class ChatRoom extends DurableObject {
+    /**
+     * Manage all active connections for this room.
+     */
+    protected readonly sessions = new WebSocketSessions<Profile>();
+
+    constructor(ctx: DurableObjectState, env: Env) {
+        super(ctx, env);
+
+        /**
+         * Restore all active connections on wake from
+         * hibernation.
+         */
+        this.sessions.restoreAll(this.ctx.getWebSockets());
+    }
+
+    public override fetch(request: Request): Promise<Response> {
+        /**
+         * For demo purposes, get the user's name from the `name`
+         * query parameter.
+         */
+        const name = new URL(request.url).searchParams.get("name") ?? "Anonymous";
+
+        /**
+         * Create a new connection and initialize its `Profile`
+         * attachment.
+         */
+        const con = this.sessions.create({
+            name,
+            lastActive: Date.now(),
+        });
+
+        /**
+         * Accept the WebSocket with recommended hibernation enabled.
+         *
+         * To accept without hibernation, use `con.accept()` and
+         * con.addEventListener() methods instead.
+         */
+        const client = con.acceptWebSocket(this.ctx);
+
+        /**
+         * Return the upgrade response with the client WebSocket.
+         */
+        return new WebSocketUpgrade(client).response();
+    }
+
+    /**
+     * Send a message to all active sessions.
+     */
+    public broadcast(message: string): void {
+        for (const session of this.sessions) {
+            session.send(message);
+        }
+    }
+
+    public override webSocketMessage(ws: WebSocket, message: string): void {
+        /**
+         * Get the sender's WebSocket session from the active sessions.
+         */
+        const con = this.sessions.get(ws);
+        if (!con) return;
+
+        /**
+         * Update the sender's `Profile` with current `lastActive` time.
+         */
+        con.attach({ lastActive: Date.now() });
+
+        /**
+         * Broadcast the message to all sessions, prefixed with the
+         * sender’s name.
+         */
+        this.broadcast(`${con.attachment.name}: ${message}`);
+    }
+
+    public override webSocketClose(ws: WebSocket, code: number, reason: string): void {
+        /**
+         * Closes and removes the WebSocket from active sessions.
+         */
+        this.sessions.close(ws, code, reason);
+    }
+}
+
+class ChatWorker extends RouteWorker {
+    protected override init(): void {
+        /**
+         * Define the WebSocket connection route.
+         */
+        this.route(GET, "/chat/:room", this.upgrade);
+
+        /**
+         * Register the middleware to validate WebSocket
+         * connection requests.
+         */
+        this.use(websocket("/chat/:room"));
+    }
+
+    private upgrade(params: PathParams): Promise<Response> {
+        /**
+         * Get the Durable Object stub for the chat room
+         * given by the "room" path parameter.
+         */
+        const stub = this.env.CHAT_ROOM.getByName(params["room"]);
+
+        /**
+         * Dispatch the WebSocket upgrade request to the
+         * Durable Object.
+         */
+        return stub.fetch(this.request);
+    }
+}
+
+/**
+ * Connects ChatWorker to the Cloudflare runtime.
+ */
+export default ChatWorker.ignite();
+```
+
+:computer: To run this chat example locally:
+
+```bash
+wrangler dev
+```
+
+:bulb: Apps like [Postman](https://www.postman.com/downloads/) can be used to create and join local chat rooms for testing:
+
+```
+ws://localhost:8787/chat/fencing?name=Inigo
+```
+
 <br>
 
-## :cowboy_hat_face: Wrangler
+## :partly_sunny: Wrangler
 
 First, create a **FREE** [Cloudflare account](https://dash.cloudflare.com/sign-up).
 
@@ -548,3 +826,22 @@ wrangler init
 ```
 
 [Install](#package-install) Cloud Spark
+
+<br>
+
+## :link: Links
+
+- [Cloudflare - Home](https://www.cloudflare.com)
+- [Cloudflare - Dashboard](https://dash.cloudflare.com)
+- [Wrangler](https://developers.cloudflare.com/workers/wrangler/)
+- [Workers](https://developers.cloudflare.com/workers/)
+- [Workers - SDK](https://github.com/cloudflare/workers-sdk)
+- [Hibernation WebSocket API](https://developers.cloudflare.com/durable-objects/best-practices/websockets/#durable-objects-hibernation-websocket-api)
+- [Standard WebSocket API](https://developers.cloudflare.com/workers/runtime-apis/websockets/)
+- [Postman](https://www.postman.com/downloads/)
+- [http-status-codes](https://github.com/prettymuchbryce/http-status-codes)
+- [path-to-regexp](https://github.com/pillarjs/path-to-regexp)
+
+##
+
+### [:arrow_up:](#books-contents)

package/dist/index.d.ts

@@ -511,11 +511,16 @@ interface WebSocketConnection<A extends WSAttachment> {
      */
     get attachment(): Readonly<A>;
     /**
-     * Attaches a user-defined object to this WebSocket connection.
+     * Attaches or updates a user-defined object on this connection.
      *
-     * @param attachment - Object containing the metadata to attach.
+     * Passing a partial object merges the new properties into the existing
+     * attachment, leaving other fields unchanged. Pass `null` to clear
+     * the attachment entirely.
+     *
+     * @param attachment - Partial object containing metadata to attach or update,
+     *                     or `null` to clear the attachment.
      */
-    attach(attachment: A): void;
+    attach(attachment?: Partial<A> | null): void;
     /**
      * Sends a message to the connected WebSocket client.
      *
@@ -1086,7 +1091,7 @@ declare class HttpError extends JsonResponse {
 /**
  * Creates a structured error response without exposing the error
  * details to the client. Links the sent response to the logged
- * error via a generated correlation UUID.
+ * error via a generated correlation ID.
  *
  * Status defaults to 500 Internal Server Error.
  */