@adonix.org/cloud-spark 0.0.185 → 0.0.186

package/README.md

@@ -61,7 +61,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 that 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:
 
@@ -143,12 +143,12 @@ export default MyWorker.ignite();
 
 ## :twisted_rightwards_arrows: Route Worker
 
-RouteWorker extends [BasicWorker](#arrow_right-basic-worker) to provide route-based request handling making it easy to define multiple endpoints in a single Worker. It provides:
+RouteWorker extends [BasicWorker](#arrow_right-basic-worker) to provide route-based request handling making it easy to define multiple endpoints in a single worker. It provides:
 
 - Registering routes individually or in bulk.
 - Matching incoming requests to registered routes by HTTP method and path.
-- Support for URL path patterns using [path-to-regex](https://github.com/pillarjs/path-to-regexp) syntax.
-- Dispatching requests to either a callback function or another Worker.
+- Support for URL path patterns using [path-to-regexp](https://github.com/pillarjs/path-to-regexp) syntax.
+- Dispatching requests to either a callback function or another worker.
 
 Example:
 
@@ -167,7 +167,7 @@ class GreetingWorker extends RouteWorker {
      */
     protected override init(): void {
         /**
-         * Example of path-to-regex and local method routing.
+         * Example of path-to-regexp and local method routing.
          */
         this.route(GET, "/hello/:name", this.hello);
 
@@ -178,7 +178,7 @@ class GreetingWorker extends RouteWorker {
     }
 
     /**
-     * Path parameters are provided via path-to-regex parsing
+     * Path parameters are provided via path-to-regexp parsing
      * of the request path.
      *
      * For example, http://localhost:8787/hello/Inigo will yield
@@ -212,14 +212,195 @@ class GoodbyeWorker extends BasicWorker {
 export default GreetingWorker.ignite();
 ```
 
+:bulb: Requests with no matching route fall back to the corresponding [BasicWorker](#arrow_right-basic-worker) method.
+
 <br>
 
 ## :gear: Middleware
 
+Middleware extends your worker’s behavior in a modular way. Each middleware can inspect the incoming request, return a custom response early, or modify the response produced by later handlers. It’s a simple way to add logic such as authentication checks, request logging, or response transformations without touching your core code.
+
+CloudSpark includes built-in middleware for common functionality like caching and CORS, and you can easily create your own to handle behavior specific to your application.
+
 ### CORS
 
+Register the built-in CORS middleware as follows:
+
+:page_facing_up: index.ts
+
+```ts
+import { BasicWorker, cors } from "@adonix.org/cloud-spark";
+
+class MyWorker extends BasicWorker {
+    /**
+     * Register middleware in the init method.
+     */
+    protected override init(): void {
+        /**
+         * Create and register the built-in CORS middleware
+         * with default options:
+         *
+         * {
+         *   allowedOrigins: ["*"],
+         *   allowedHeaders: ["Content-Type"],
+         *   exposedHeaders: [],
+         *   allowCredentials: false,
+         *   maxAge: 300,
+         * }
+         *
+         */
+        this.use(cors());
+
+        /**
+         * To override specific default CORS options:
+         *
+         * this.use(cors({ allowedOrigins: ["https://www.adonix.org"], maxAge: 604800 }));
+         *
+         */
+    }
+}
+```
+
+:bulb: The middleware adds CORS headers to the response **ONLY** if the request includes an `Origin` header.
+
 ### Cache
 
+CloudSpark includes built-in caching middleware that stores responses for improving performance. Only responses that are safe to cache are stored, including:
+
+- Responses to GET requests with a 200 OK status.
+- Responses that specify a time-to-live via `Cache-Control` headers (max-age or s-maxage).
+- Responses with `Vary` headers are fully supported, so the cache respects variations based on headers like `Accept-Language`.
+- Responses that **do not** include user-specific data (such as Set-Cookie or requests with Authorization/Cookie headers).
+
+Other types of responses (non-GET, errors, partial content, or requests marked no-store) are never cached. This ensures caching is safe and consistent with HTTP standards.
+
+Register the built-in cache middleware as follows:
+
+:page_facing_up: index.ts
+
+```ts
+import { BasicWorker, cache, CacheControl, JsonResponse, Time } from "@adonix.org/cloud-spark";
+
+class MyWorker extends BasicWorker {
+    /**
+     * Enable middleware in the worker init method.
+     */
+    protected override init(): void {
+        /**
+         * Create and register the built-in cache middleware.
+         */
+        this.use(cache());
+
+        /**
+         * Optionally pass settings to the cache function:
+         *
+         * 	name — the name of the cache storage to use. If omitted,
+         *         the default cache is used.
+         *  getKey — a function that maps the incoming request to a
+         *           cache key.
+         *           Built-in key functions include:
+         *               • sortSearchParams (Default)
+         *               • stripSearchParams
+         *
+         * this.use(cache({
+         *     name: "my-cache",
+         *     getKey: stripSearchParams,
+         * }));
+         *
+         */
+    }
+
+    /**
+     * Create a cacheable response.
+     */
+    protected override get(): Promise<Response> {
+        /**
+         * Example JSON message.
+         */
+        const json = {
+            message: "Hi from Cloud Spark!",
+            timestamp: new Date().toLocaleString(),
+        };
+
+        /**
+         * Cache the response for 10 seconds.
+         */
+        const cc: CacheControl = {
+            "s-maxage": 10 * Time.Second,
+        };
+
+        return this.response(JsonResponse, json, cc);
+    }
+}
+
+/**
+ * Connects MyWorker to the Cloudflare runtime.
+ */
+export default MyWorker.ignite();
+```
+
+:bulb: The `cf-cache-status` response header will contain **HIT** when serving from the cache.
+
+### WebSocket
+
+The WebSocket middleware ensures upgrade requests are valid before they reach your handler. You can provide a path (default: `"/"`) and register multiple instances for multiple paths. Invalid upgrade requests are intercepted, and the correct error response is returned.
+
+A valid WebSocket upgrade request must use the `GET` method and include the following:
+
+| Header                | Value     |
+| --------------------- | --------- |
+| Connection            | Upgrade   |
+| Upgrade               | websocket |
+| Sec-WebSocket-Version | 13        |
+
+Register the built-in websocket middleware as follows:
+
+:page_facing_up: index.ts
+
+```ts
+import { GET, PathParams, RouteWorker, websocket } from "@adonix.org/cloud-spark";
+
+class ChatWorker extends RouteWorker {
+    /**
+     * Register both the upgrade route and middleware.
+     */
+    protected override init(): void {
+        /**
+         * Route for WebSocket upgrades.
+         */
+        this.route(GET, "/chat/:room", this.upgrade);
+
+        /**
+         * Register WebSocket middleware to match the
+         * upgrade route.
+         */
+        this.use(websocket("/chat/:room"));
+    }
+
+    /**
+     * Handles WebSocket upgrade requests.
+     *
+     * Expects a DurableObject binding named CHAT 
+     * in wrangler.jsonc
+     */
+    protected upgrade(params: PathParams): Promise<Response> {
+        const room = params["room"];
+        const chat = this.env.CHAT;
+
+        /**
+         * Request has already been validated by the 
+         * WebSocket middleware.
+         */
+        return chat.get(chat.idFromName(room)).fetch(this.request);
+    }
+}
+
+/**
+ * Connects ChatWorker to the Cloudflare runtime.
+ */
+export default ChatWorker.ignite();
+```
+
 ### Custom
 
 <br>

package/dist/index.d.ts

@@ -419,7 +419,7 @@ declare function cors(init?: CorsInit): Middleware;
  * - Only validates the upgrade request; it does **not** perform the actual WebSocket upgrade.
  * - Ensures the request:
  *   - Uses the `GET` method.
- *   - Matches the specified path, supporting `path-to-regex` style patterns
+ *   - Matches the specified path, supporting `path-to-regexp` style patterns
  *     (e.g., `/chat/:name`).
  *   - Contains required WebSocket headers:
  *     - `Connection: Upgrade`
@@ -429,7 +429,7 @@ declare function cors(init?: CorsInit): Middleware;
  *   the next middleware or origin handler.
  *
  * @param path - The URL path to intercept for WebSocket upgrades. Defaults to `/`.
- *               Supports dynamic segments using `path-to-regex` syntax.
+ *               Supports dynamic segments using `path-to-regexp` syntax.
  * @returns A {@link Middleware} instance that can be used in your middleware chain.
  *
  * @example
@@ -725,7 +725,7 @@ declare abstract class BaseWorker implements Worker {
      * @param args Additional constructor arguments
      * @returns A Promise resolving to the {@link Response} object
      */
-    protected response<Ctor extends new (...args: any[]) => {
+    response<Ctor extends new (...args: any[]) => {
         response(): Promise<Response>;
     }>(ResponseClass: Ctor, ...args: ConstructorParameters<Ctor>): Promise<Response>;
     /**
@@ -828,7 +828,7 @@ declare abstract class RouteWorker extends BasicWorker {
      * - A Worker subclass that will handle the request.
      *
      * @param method  - HTTP method for the route (`GET`, `POST`, etc.).
-     * @param path    - URL path pattern (path-to-regex, e.g., "/users/:id").
+     * @param path    - URL path pattern (path-to-regexp, e.g., "/users/:id").
      * @param handler - The function or Worker class to run when the route matches.
      * @returns The current worker instance, allowing method chaining.
      */
@@ -838,7 +838,7 @@ declare abstract class RouteWorker extends BasicWorker {
      *
      * Each route should be a tuple `[method, path, handler]` where:
      * - `method`  - HTTP method for the route (`GET`, `POST`, etc.).
-     * - `path`    - URL path pattern (path-to-regex e.g., "/users/:id").
+     * - `path`    - URL path pattern (path-to-regexp e.g., "/users/:id").
      * - `handler` - A function that receives URL parameters or a Worker subclass
      *               that will handle the request.
      *