@adonix.org/cloud-spark 0.0.187 → 0.0.188

package/README.md

@@ -56,7 +56,7 @@ And it's ready on http://localhost:8787
 As shown in the [Quickstart](#rocket-quickstart), BasicWorker is the base class for building Cloudflare Workers with CloudSpark. It handles common tasks, including:
 
 - Dispatching incoming HTTP requests to the corresponding handler (GET, POST, PUT, etc.).
-- Providing defaults for standard HTTP behavior, such as HEAD requests and OPTIONS responses.
+- Providing defaults for standard HTTP behavior, such as HEAD and OPTIONS requests.
 - Ensuring type safety and consistent response formatting.
 - Support for built-in and custom middleware.
 - Catching unhandled errors.
@@ -90,7 +90,7 @@ export class MyWorker extends BasicWorker {
      * If a requested method is not listed, the response is:
      *     405 Method Not Allowed
      *
-     * If an allowed method isn’t implemented, the response is:
+     * If an allowed method is not implemented, the response is:
      *     GET or HEAD: 404 Not Found
      *     All other methods: 501 Not Implemented
      *
@@ -380,7 +380,7 @@ class ChatWorker extends RouteWorker {
     /**
      * Handles WebSocket upgrade requests.
      *
-     * Expects a DurableObject binding named CHAT 
+     * Expects a DurableObject binding named CHAT
      * in wrangler.jsonc
      */
     protected upgrade(params: PathParams): Promise<Response> {
@@ -388,7 +388,7 @@ class ChatWorker extends RouteWorker {
         const chat = this.env.CHAT;
 
         /**
-         * Request has already been validated by the 
+         * Request has already been validated by the
          * WebSocket middleware.
          */
         return chat.get(chat.idFromName(room)).fetch(this.request);
@@ -403,6 +403,80 @@ export default ChatWorker.ignite();
 
 ### 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.
+
+Here is a simple example:
+
+```ts
+import { BadRequest, CopyResponse, Middleware, Worker } from "@adonix.org/cloud-spark";
+
+/**
+ * Custom middleware example.
+ *
+ * Demonstrates several key middleware capabilities:
+ *   • Options via constructor parameters.
+ *   • Inspection of the incoming request.
+ *   • Short-circuiting by returning a response directly.
+ *   • Modifying outgoing responses dispatched by the worker.
+ */
+class PoweredBy implements Middleware {
+    /**
+     * Optional constructor parameter to customize the "X-Powered-By" header.
+     */
+    constructor(private readonly name = "CloudSpark") {}
+
+    public async handle(worker: Worker, next: () => Promise<Response>): Promise<Response> {
+        /**
+         * Extract the User-Agent header from the request.
+         */
+        const userAgent = worker.request.headers.get("User-Agent")?.trim();
+
+        /**
+         * If the User-Agent is missing, short-circuit by directly
+         * returning 400 Bad Request.
+         */
+        if (!userAgent) {
+            return new BadRequest(`Missing User-Agent`).response();
+        }
+
+        /**
+         * Calls the next middleware or worker dispatch method.
+         */
+        const response = await next();
+
+        /**
+         * Wrap the response in a mutable copy.
+         */
+        const copy = new CopyResponse(response);
+
+        /**
+         * Append custom headers to the response.
+         */
+        copy.setHeader("X-User-Agent", userAgent);
+        copy.setHeader("X-Powered-By", this.name);
+        copy.setHeader("X-Processed-At", new Date().toUTCString());
+
+        /**
+         * Return the modified response.
+         */
+        return copy.response();
+    }
+}
+
+/**
+ * Factory function for registering the middleware, with an optional
+ * name parameter. Workers interact with the `Middleware` interface,
+ * and not the concrete implementation.
+ *
+ * Example:
+ *   this.use(poweredby());
+ *   this.use(poweredby("My Project Name"));
+ */
+export function poweredby(name?: string): Middleware {
+    return new PoweredBy(name);
+}
+```
+
 <br>
 
 ## :left_right_arrow: Web Sockets

package/dist/index.d.ts

@@ -1036,9 +1036,9 @@ declare class R2ObjectStream extends OctetStream {
      * This function normalizes a Cloudflare R2 `R2Range` into the shape expected
      * by `OctetStream`. It handles the following cases:
      *
-     * - No range provided → returns `{ size }` (full content).
-     * - `suffix` range → calculates the offset and length from the end of the file.
-     * - Explicit `offset` and/or `length` → passed through as-is.
+     * - No range provided: returns `{ size }` (full content).
+     * - `suffix` range: calculates the offset and length from the end of the file.
+     * - Explicit `offset` and/or `length`: passed through as-is.
      *
      * @param size - The total size of the file/object.
      * @param range - Optional range to extract (from R2). Can be: