cloudfrontize 1.1.7 → 1.3.0

package/README.md

@@ -1,10 +1,74 @@
 # cloudfrontize
+
 [![Sponsor](https://img.shields.io/badge/Sponsor-❤️-ff69b4?style=for-the-badge&logo=github)](https://github.com/sponsors/felipecarrillo100)
+![npm](https://img.shields.io/npm/v/cloudfrontize)
+![node](https://img.shields.io/node/v/cloudfrontize)
+
+📜 **Changelog:** See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+---
+
+#### A high-fidelity local development server for AWS Lambda@Edge and CloudFront Functions.
+
+Test your Edge logic locally in milliseconds instead of waiting 15 minutes for CloudFront deployments.
+
+<div style="display: flex; justify-content: space-around; align-items: center;">
+<img alt="Cloudfrontize Banner" src="https://raw.githubusercontent.com/felipecarrillo100/cloudfrontize/main/assets/cloudfrontize.png" width="45%" />
+<img alt="Cloudfrontize Web UI" src="https://raw.githubusercontent.com/felipecarrillo100/cloudfrontize/main/assets/cloudfrontize-webui.jpg" width="45%" />
+</div>
+
+---
+## 📦 Getting started
+Get up and running in seconds. No complex AWS IAM roles, no stack traces—just your code, running locally.
+
+### Install **globally:**
+
+```bash
+npm install -g cloudfrontize
+```
+Once installed, you can run CloudFrontize from any directory: by simply typing `cloudfrontize ./www` (specifying your static folder).
+
+Point it at your static files folder (`./www`, `./dist` or `./public`) and point to your Lambda@Edge `.js` file. CloudFrontize handles the rest.
+
+## ⚡ Quick Example
+
+1️⃣ Create a simple Lambda@Edge function, for instance: `viewer-request-rewrite.js`
+
+```javascript
+exports.hookType = 'viewer-request';
+
+exports.handler = (event, context, callback) => {
+    const request = event.Records[0].cf.request;
+    console.log("Original request", request.uri);
+    request.uri = "/index-alt.html";
+    callback(null, request);
+};
+```
+
+2️⃣ Run CloudFrontize
+
+```
+cloudfrontize ./www --edge ./viewer-request-rewrite.js --debug
+```
+For this sample, place two HTML files inside the `www` folder: `index.html` and `index-alt.html`.
+
+3️⃣ Open
+
+Open your browser and navigate to: http://localhost:3000
+
+Because the `viewer-request` hook is active, every request is rewritten to `/index-alt.html`. As a result, the browser will display the contents of that file regardless of the requested path.
+
+Check the CloudFrontize terminal output. You should see a log entry confirming the internal URI rewrite:
+```text
+2026-03-16T22:18:51.465Z  [44ff0e42] [viewer-request]  Original request /
+[Debug] Mode: rest, isRestMode: true, URL: /index-alt.html, FullPath: C:\tmp\www\index-alt.html
+```
 
-A high-performance, high-fidelity local emulator for AWS Lambda@Edge and CloudFront Functions. 
-### 📣 Stop bowing to the deployment bar! 
+---
+
+## 📣 Stop waiting for CloudFront deployments! 
 
-**Rule the Edge** and become the Hero of the Cloud. **Escape the "Deploy-and-Pray" cycle.** We’ve all been there: you tweak one security header, hit "Deploy," and... **you wait.** For 15 agonizing minutes, you watch a spinning "In Progress" status as AWS propagates your code globally. If there’s a tiny typo? You won't know until you hit a **502 Bad Gateway** and go hunting through CloudWatch logs buried in a random region.
+**Take control** of your Edge development workflow. **Escape the "Deploy-and-Pray" cycle.** We’ve all been there: you tweak one security header, hit "Deploy," and... **you wait.** For 15 agonizing minutes, you watch a spinning "In Progress" status as AWS propagates your code globally. If there’s a tiny typo? You won't know until you hit a **502 Bad Gateway** and go hunting through CloudWatch logs buried in a random region.
 
 It’s a workflow that kills momentum and turns "quick fixes" into afternoon-long ordeals.
 
@@ -26,7 +90,7 @@ The CloudFront/Lambda@Edge development loop is notoriously painful. Propagation
 
 **CloudFrontize** eliminates the wait and the risk:
 
-* **Zero-Config Integration:** If you know how to use Vercel's [serve](https://www.google.com/search?q=%5Bhttps://www.npmjs.com/package/serve%5D(https://www.npmjs.com/package/serve)) package, you already know how to use `cloudfrontize`.
+* **Zero-Config Integration:** If you know how to use Vercel's [serve](https://www.npmjs.com/package/serve) package, you already know how to use `cloudfrontize`.
 * **Real-Time Hot Reloading:** Tweak your URI rewrites or security headers and see the results instantly on browser refresh. No packaging, no uploading, no waiting for the "In Progress" spinner.
 * **Debug directly to the console:** Stop hunting for logs in hidden CloudWatch streams across random regions. See your console.log outputs and execution errors live **in your terminal**. 
 * **Production Fidelity:** Emulates in detail CloudFront-specific features & quirks, like the **10MB auto-compression limit**, header blacklisting, and URI normalization.
@@ -50,48 +114,11 @@ While tools like `serverless-offline` or `SAM CLI` are great for standard Lambda
 
 **CloudFrontize** is not just a runner; it's a **Linter at the Edge**, ensuring your code is valid *before* the 15-minute propagation wait.
 
-
----
-
-## 📦 Install & Go
-Get up and running in seconds. No complex AWS IAM roles, no stack traces—just your code, running locally.
-
-### Install it **Globally:**
-
-```bash
-npm install -g cloudfrontize
-```
-Once installed, you can rule the Edge from any directory by simply typing `cloudfrontize ./www` (specifying your static folder).
-
-Point it at your static files  folder (`./www`, `./dist` or `./public`) and point to your Lambda@Edge `.js` file. CloudFrontize handles the rest.
-
-```bash
-cloudfrontize ./folder --edge ./lambda-at-age-logic.js
-```
-OR
-```bash
-npx cloudfrontize ./folder --edge ./lambda-at-age-logic.js
-```
-
----
-
-## 🎓 CloudFrontize Academy (Tutorial)
-
-New to Lambda@Edge? We've built a comprehensive, hands-on tutorial to take you from **Newbie to Production Pro**.
-
-Our **[CloudFrontize Academy](./tutorial/README.md)** includes 10 thematic exercises covering:
-* **Module 1: Foundations** (Security Headers, Redirects, Normalization)
-* **Module 2: Origin Intelligence** (A/B Testing, Geo-Localization, Header Cleaning)
-* **Module 3: Edge Computing** (Custom Auth, Maintenance Pages, Payload Inspection)
-* **Module 4: Production Workflows** (Variable Baking & Deployment)
-
-Each exercise comes with a **Business Scenario**, **Starter Template**, and **Full Solution**.
-
 ---
 
 ## 🛠️ CLI Options & Configuration
 
-`cloudfrontize` is designed to be a drop-in replacement for the popular [serve](https://www.google.com/search?q=%5Bhttps://www.npmjs.com/package/serve%5D(https://www.npmjs.com/package/serve)), we all know and love, but with "Edge Superpowers!"
+`cloudfrontize` is designed to be a drop-in replacement for the popular [serve](https://www.npmjs.com/package/serve), we all know and love, but with "Edge Superpowers!"
 
 | Flag | Description                                                                                                                                                                                                                                                                   | Default                                                                                            |
 | --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
@@ -105,6 +132,7 @@ Each exercise comes with a **Business Scenario**, **Starter Template**, and **Fu
 | **`-o, --output <path>`**| Output the baked `.js` file(s) for production deployment                                                                                                                                                                                                                      | `null`                                                                                             |
 | **`-p, --port <number>`** | Port to listen on                                                                                                                                                                                                                                                             | `3000`                                                                                             |
 | **`-l, --listen <uri>`** | Listen URI (overrides `--port`)                                                                                                                                                                                                                                               | `3000`                                                                                             |
+| **`--webui <port>`**    | Enable the visual control plane for real-time traffic inspection and header debugging | `disabled` |
 | **`-s, --single`** | SPA mode — rewrite all 404s to `index.html`                                                                                                                                                                                                                                   | `off`                                                                                              |
 | **`-C, --cors`** | Enable `Access-Control-Allow-Origin: *`                                                                                                                                                                                                                                       | `off`                                                                                              |
 | **`-d, --debug`** | Show Lambda execution logs and URI rewrites                                                                                                                                                                                                                                   | `off`                                                                                              |
@@ -116,6 +144,17 @@ Each exercise comes with a **Business Scenario**, **Starter Template**, and **Fu
 
 ---
 
+## 🖥️ Visual Control Plane (Web UI)
+
+CloudFrontize includes an optional, browser-based UI to help you visualize your edge logic in real-time. Inspect headers, track URI rewrites, and debug Lambda@Edge execution without leaving your browser.
+
+Using the **Header Intelligence** panel, you can inject or override headers on-the-fly to test Geo-routing, Auth tokens, or Security policies without changing a single line of code.
+
+**[👉 Learn how to use the Web UI](docs/web-ui.md)**
+
+---
+
+
 ## 🚀 Lambda@Edge Integration
 
 Since there is no AWS CloudFront Console to configure your triggers locally, **it is mandatory to include `exports.hookType` in your JavaScript file.** If this line is missing, CloudFrontize will not know when to fire your function and will ignore the file.
@@ -139,27 +178,15 @@ When pointing `--cff` to a directory, files must follow a strict naming conventi
 
 Files within a directory are executed in **lexicographical order**.
 
-### CFF Example (`viewer-request-redirect.js`)
+## 🛡️ Engineered for Fidelity
 
-```javascript
-function handler(event) {
-    var request = event.request;
-    var uri = request.uri;
-
-    // Direct response (short-circuits the pipeline)
-    if (uri === '/old-path') {
-        return {
-            statusCode: 301,
-            statusDescription: 'Moved Permanently',
-            headers: {
-                'location': { value: '/new-path' }
-            }
-        };
-    }
+Don't just simulate the Edge—**master it.** CloudFrontize is built to mirror the high-stakes environment of a live AWS PoP (Point of Presence).
 
-    return request;
-}
-```
+* **⚡ Native Async/Await Support:** Whether your middleware is a simple redirect or a complex, asynchronous database lookup, CloudFrontize handles `async` handlers and Promises with the same grace as the live Lambda@Edge runtime.
+* **🧩 Multi-Hook Testing:** Pass a directory to `--edge` and CloudFrontize will automatically mount every valid Lambda it finds. Orchestrate your **Viewer Request**, **Origin Request**, and **Response** hooks in one unified local environment.
+* **📦 RequestBody Access:** Use `event.Records[0].cf.request.body` to access base64 encoded payloads. We support the standard AWS buffering logic.
+* **🚫 Strict Header & Body Validation:** Use `--strict` to identify "Read-only" or "Forbidden" headers for **both request and response hooks**, as well as the **40KB viewer-request body limit** and the **1MB generated response limit** in real-time. We trigger **502 Bad Gateway** errors locally for the same illegal mutations that fail in production.
+* **🎭 Mocked Context & Events:** We provide a high-fidelity `event` and `context` object, ensuring your logging, metrics, and custom error-handling tools work exactly as they would in production.
 
 ---
 
@@ -168,19 +195,11 @@ function handler(event) {
 
 We’ve bundled a complete, interactive sample to show you the power of **CloudFrontize**. It protects a premium dog photography gallery using a `viewer-request` authentication gate.
 
-### Launch the Secure Demo
+### Lambda@Edge sample
 Clone the GitHub repo 
 ```shell
 git clone https://github.com/felipecarrillo100/cloudfrontize.git
 ```
-Then run 
-```bash
-cloudfrontize ./www -e ./samples/medium/lambda-edge-authorization.js -d -C
-```
-* The `www` folder contains the sample files (html, js, css, etc.)
-* The `lambda-edge-authorization.js` contains the lambda@edge logic
-* The `-d` option enables debug messages while `-C` enables CORS
-* Default port is 3000, you can now open your browser at http://localhost:3000/
 
 ### The Sample Logic (`lambda-edge-authorization.js`)
 
@@ -200,7 +219,7 @@ exports.handler = (event, context, callback) => {
 
     // Credentials for demo purposes
     const user = "admin";
-    const password = "pass";
+    const password = "password";
 
     const authString = "Basic " + Buffer.from(user + ":" + password).toString("base64");
 
@@ -227,29 +246,68 @@ exports.handler = (event, context, callback) => {
     callback(null, request);
 };
 ```
+Then run
+```bash
+cloudfrontize ./www -e ./samples/medium/lambda-edge-authorization.js -d -C
+```
+* The `www` folder contains the sample files (html, js, css, etc.)
+* The `lambda-edge-authorization.js` file contains the lambda@edge logic
+* The `-d` option enables debug messages while `-C` enables CORS
+* Default port is 3000, you can now open your browser at http://localhost:3000/
+* The username is `admin` and the password is `password`, as defined in the Lambda@Edge logic.  
+
+### A CFF Example
+Your file must start with `viewer-request` or `viewer-response` to let the simulator know the type of CFF we want to execute. In this case we have called it: `viewer-request-redirect.js`
+```javascript
+function handler(event) {
+    var request = event.request;
+    var uri = request.uri;
+
+    // Direct response (short-circuits the pipeline)
+    if (uri === '/promo') {
+        return {
+            statusCode: 301,
+            statusDescription: 'Moved Permanently',
+            headers: {
+                'location': { value: '/summer-sale' }
+            }
+        };
+    }
+
+    return request;
+}
+```
 
+Run with:
+```bash
+cloudfrontize ./www --cff ./samples/cff/viewer-request-redirect.js -d --mode website
+```
+* `-d` Enables debug, and `--mode website` takes care of appending `index.html` to folders
+* Open in browser  http://localhost:3000/promo
+* You will be redirected to http://localhost:3000/summer-sale
 ---
 
-### 🛡️ Engineered for Fidelity 
+## 🎓 CloudFrontize Academy (Tutorial)
 
-Don't just simulate the Edge—**master it.** CloudFrontize is built to mirror the high-stakes environment of a live AWS PoP (Point of Presence).
+New to Lambda@Edge? We've built a comprehensive, hands-on tutorial to take you from **Newbie to Production Pro**.
 
-* **⚡ Native Async/Await Support:** Whether your middleware is a simple redirect or a complex, asynchronous database lookup, CloudFrontize handles `async` handlers and Promises with the same grace as the live Lambda@Edge runtime.
-* **🧩 Multi-Hook Testing:** Pass a directory to `--edge` and CloudFrontize will automatically mount every valid Lambda it finds. Orchestrate your **Viewer Request**, **Origin Request**, and **Response** hooks in one unified local environment.
-* **📦 RequestBody Access:** Use `event.Records[0].cf.request.body` to access base64 encoded payloads. We support the standard AWS buffering logic.
-* **🚫 Strict Header & Body Validation:** Use `--strict` to identify "Read-only" or "Forbidden" headers for **both request and response hooks**, as well as the **40KB viewer-request body limit** and the **1MB generated response limit** in real-time. We trigger **502 Bad Gateway** errors locally for the same illegal mutations that fail in production.
-* **🎭 Mocked Context & Events:** We provide a high-fidelity `event` and `context` object, ensuring your logging, metrics, and custom error-handling tools work exactly as they would in production.
+Our **[CloudFrontize Academy](./tutorial/README.md)** includes 20+ thematic exercises covering:
+* **Module 1: Foundations** (Security Headers, Redirects, Normalization)
+* **Module 2: Origin Intelligence** (A/B Testing, Geo-Localization, Header Cleaning)
+* **Module 3: Edge Computing** (Custom Auth, Maintenance Pages, Payload Inspection)
+* **Module 4: Production Workflows** (Variable Baking & Deployment)
+* **Module 5: CloudFront Functions** (CFF)
 
----
+Each exercise comes with a **Business Scenario**, **Starter Template**, and **Full Solution**.
 
+---
 
 ### License
 
-**CloudFrontize** is licensed under the **[PolyForm Noncommercial 1.0.0](https://www.google.com/search?q=https://polyformproject.org/licenses/noncommercial/1.0.0/)**. For the full legal text and specific terms, please refer to the [LICENSE](https://www.google.com/search?q=./LICENSE) file in this package.
-
+**CloudFrontize** is licensed under the **[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)**. For the full legal text and specific terms, please refer to the [LICENSE](https://polyformproject.org/licenses/noncommercial/1.0.0/) file in this package.
 
 * **✅ Free for Individuals & Education:** 100% free for personal projects, open-source contributions, students, and researchers. This includes full access to the **CloudFrontize Academy**.
-* **💼 Requires a Commercial License:** Use by for-profit organizations, or for work performed on behalf of a for-profit entity, requires a paid Commercial License.
+* **💼 Requires a Commercial License:** Use by for-profit organizations, or work performed on behalf of a for-profit entity, requires a commercial license.
 * **⏳ 30-Day Business Trial:** We offer a one-month free evaluation period for professional teams. Integrate CloudFrontize into your workflow, experience the "Zero-Wait" deployment cycle, and measure your team's productivity gains before committing.
 
 
@@ -264,7 +322,7 @@ Maintaining high-fidelity AWS emulation takes significant time. If your company
 **THE SOFTWARE IS PROVIDED "AS IS"**, WITHOUT WARRANTY OF ANY KIND. Testing on CloudFrontize does not guarantee success on live AWS infrastructure. The author is not liable for any production downtime, data loss, or financial damages resulting from the use of this tool. Always validate your logic in an AWS staging environment before a full production rollout.
 
 ---
-# Donations & Sponsoring
+# Support the Project
 [<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" name="buy-me-a-coffee" alt="Buy Me A Coffee" width="180">](https://buymeacoffee.com/felipecarrillo100)
 
 Creating and maintaining open-source libraries is a passion of mine. If you find this `cloudfrontize` useful and it saves you time, please consider supporting its development. Your contributions help keep the project active and motivated!