woodland 20.2.1 → 20.2.3

package/README.md

@@ -289,7 +289,8 @@ app.always((req, res, next) => {
 // Route-specific middleware
 app.get("/protected", authenticate, authorize, handler);
 
-// Error handling middleware
+// ❌ WRONG: Do NOT register error middleware with 'always'
+// This will execute BEFORE route handlers, not after errors occur
 app.always((error, req, res, next) => {
   if (error) {
     console.error(error);
@@ -298,8 +299,40 @@ app.always((error, req, res, next) => {
     next();
   }
 });
+
+// ✅ CORRECT: Register error middleware with specific routes LAST
+app.get("/api/users", 
+  authenticate,        // Normal middleware
+  authorize,          // Normal middleware
+  getUserHandler,     // Route handler
+  (error, req, res, next) => {  // Error middleware - LAST
+    if (error) {
+      console.error(error);
+      res.error(500);
+    } else {
+      next();
+    }
+  }
+);
+
+// ✅ CORRECT: Global error handling should be done with route patterns
+app.use("/(.*)", (error, req, res, next) => {
+  if (error) {
+    console.error(`Global error for ${req.url}:`, error);
+    res.error(500, "Internal Server Error");
+  } else {
+    next();
+  }
+});
 ```
 
+**Important Notes:**
+- **Error middleware** (functions with 4 parameters: `error, req, res, next`) should **never** be registered with `app.always()`
+- Error middleware registered with `always` will execute **before** route handlers, making them ineffective for catching route errors
+- **`.use()` without a method defaults to GET** - it behaves like `.get()`, not like `.always()`
+- Always register error middleware **last** in the middleware chain for each route
+- For global error handling, use `app.use("/(.*)", errorHandler)` as the **last route registration**
+
 ### Middleware Examples
 
 ```javascript
@@ -389,42 +422,72 @@ app.files("/", "./public");
 
 ## 🌐 CORS
 
-### Basic CORS
+**Woodland handles CORS automatically when you configure origins.** Here's what you get for free:
 
 ```javascript
 const app = woodland({
   origins: ["https://myapp.com", "https://api.myapp.com"],
   corsExpose: "x-total-count,x-page-count"
 });
+
+// Woodland automatically provides:
+// ✅ Preflight OPTIONS route for all paths
+// ✅ Access-Control-Allow-Origin header (set to request origin if allowed)
+// ✅ Access-Control-Allow-Credentials: true
+// ✅ Access-Control-Allow-Methods (based on registered routes)
+// ✅ Access-Control-Allow-Headers (for OPTIONS requests)
+// ✅ Access-Control-Expose-Headers (for non-OPTIONS requests)
+// ✅ Timing-Allow-Origin header
+// ✅ Origin validation and security
 ```
 
-### Advanced CORS
+### What Woodland Does Automatically
+
+1. **Preflight Route Registration**: When origins are configured, Woodland automatically registers an OPTIONS handler that responds with 204 No Content
+2. **CORS Headers**: For valid cross-origin requests, automatically sets all required CORS headers
+3. **Origin Validation**: Checks request origin against configured allowed origins
+4. **Method Detection**: Access-Control-Allow-Methods reflects actual registered routes
+5. **Security**: Empty origins array denies all CORS requests by default
+
+### Manual CORS Control (When Needed)
 
 ```javascript
-// Dynamic CORS
+// Override automatic behavior for specific routes
+app.options("/api/special", (req, res) => {
+  res.header("access-control-allow-methods", "GET,POST"); // Restrict methods
+  res.header("access-control-allow-headers", "content-type"); // Restrict headers
+  res.header("access-control-max-age", "86400"); // Set cache duration
+  res.send("");
+});
+
+// Dynamic origin validation (replaces automatic validation)
 app.always((req, res, next) => {
   const origin = req.headers.origin;
-  const allowedOrigins = [
-    "https://myapp.com",
-    "https://admin.myapp.com"
-  ];
   
-  if (allowedOrigins.includes(origin)) {
+  // Custom logic for origin validation
+  if (isValidOriginForUser(origin, req.user)) {
     res.header("access-control-allow-origin", origin);
   }
   
   next();
 });
 
-// Preflight handling
-app.options("*", (req, res) => {
-  res.header("access-control-allow-methods", "GET,POST,PUT,DELETE,OPTIONS");
-  res.header("access-control-allow-headers", "content-type,authorization");
-  res.header("access-control-max-age", "86400");
-  res.send("");
+// Conditional CORS (disable automatic CORS, use manual)
+const app = woodland({
+  origins: [] // Empty = no automatic CORS
+});
+
+app.always((req, res, next) => {
+  if (shouldAllowCORS(req)) {
+    res.header("access-control-allow-origin", req.headers.origin);
+    res.header("access-control-allow-credentials", "true");
+  }
+  next();
 });
 ```
 
+**Most applications only need to configure `origins` and `corsExpose` - manual CORS handling is rarely necessary.**
+
 ## ❌ Error Handling
 
 ### Built-in Error Handling

package/dist/cli.cjs

@@ -4,7 +4,7 @@
  *
  * @copyright 2025 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 20.2.1
+ * @version 20.2.3
  */
 'use strict';
 

package/dist/woodland.cjs

@@ -3,7 +3,7 @@
  *
  * @copyright 2025 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 20.2.1
+ * @version 20.2.3
  */
 'use strict';
 

package/dist/woodland.js

@@ -3,7 +3,7 @@
  *
  * @copyright 2025 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 20.2.1
+ * @version 20.2.3
  */
 import {STATUS_CODES,METHODS}from'node:http';import {join,extname,resolve}from'node:path';import {EventEmitter}from'node:events';import {stat,readdir}from'node:fs/promises';import {readFileSync,createReadStream}from'node:fs';import {etag}from'tiny-etag';import {precise}from'precise';import {lru}from'tiny-lru';import {createRequire}from'node:module';import {fileURLToPath,URL}from'node:url';import {coerce}from'tiny-coerce';import mimeDb from'mime-db';const __dirname$1 = fileURLToPath(new URL(".", import.meta.url));
 const require = createRequire(import.meta.url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "woodland",
-  "version": "20.2.1",
+  "version": "20.2.3",
   "description": "High-performance HTTP framework",
   "type": "module",
   "types": "types/woodland.d.ts",