@chidchanun/bcp 0.1.17 → 0.1.18

package/docs/middleware.md

@@ -1,58 +1,520 @@
 # Middleware
 
+BCP Middleware runs before application routing and can inspect requests, rewrite URLs, redirect requests, change request headers, return responses directly, and add response headers.
+
+BCP 0.1.18 adds Middleware System v2 while keeping the v1 API backward-compatible.
+
+## Create middleware
+
 Create `middleware.ts` in the project root.
 
+```text
+my-app/
+├─ app/
+├─ middleware.ts
+├─ bcp.config.ts
+└─ package.json
+```
+
+Import middleware APIs from `bcp/middleware`.
+
+## Middleware System v2
+
+Middleware v2 uses an onion-style pipeline. A handler can run code before the next handler/application, call `await next()`, then inspect or change the final `Response` on the way back out.
+
 ```ts
-import {
-    next,
-    redirect,
-    rewrite,
-    type MiddlewareConfig,
-    type MiddlewareRequest,
+import type {
+    MiddlewarePipelineHandler,
 } from "bcp/middleware";
 
-export const config: MiddlewareConfig = {
+export const middleware:
+    MiddlewarePipelineHandler =
+    async (
+        request,
+        next,
+        context
+    ) => {
+        const started =
+            performance.now();
+
+        context.state.requestPath =
+            request.nextUrl.pathname;
+
+        const response =
+            await next();
+
+        response.headers.set(
+            "X-Response-Time",
+            `${Math.round(
+                performance.now() -
+                started
+            )}ms`
+        );
+
+        return response;
+    };
+```
+
+`await next()` executes the rest of the middleware chain and then the BCP application. The returned value is the real downstream Web `Response`.
+
+This makes response interception possible without creating an extra API abstraction.
+
+## Middleware chains
+
+Export an array to compose several middleware handlers.
+
+```ts
+import type {
+    MiddlewarePipelineHandler,
+} from "bcp/middleware";
+
+const logger:
+    MiddlewarePipelineHandler =
+    async (
+        request,
+        next
+    ) => {
+        console.log(
+            "request",
+            request.method,
+            request.nextUrl.pathname
+        );
+
+        const response =
+            await next();
+
+        console.log(
+            "response",
+            response.status
+        );
+
+        return response;
+    };
+
+const responseHeaders:
+    MiddlewarePipelineHandler =
+    async (
+        _request,
+        next
+    ) => {
+        const response =
+            await next();
+
+        response.headers.set(
+            "X-App",
+            "BCP"
+        );
+
+        return response;
+    };
+
+export const middleware = [
+    logger,
+    responseHeaders,
+];
+```
+
+Execution order is:
+
+```text
+Request
+  ↓
+logger before
+  ↓
+responseHeaders before
+  ↓
+BCP router / page / API
+  ↑
+responseHeaders after
+  ↑
+logger after
+  ↓
+Response
+```
+
+A middleware handler may call `next()` only once. Calling it more than once throws an error because a request body and downstream application execution cannot safely be replayed automatically.
+
+## Shared request state
+
+The third argument is a `MiddlewareContext` shared by every handler in one request.
+
+```ts
+import type {
+    MiddlewarePipelineHandler,
+} from "bcp/middleware";
+
+const identify:
+    MiddlewarePipelineHandler =
+    async (
+        request,
+        next,
+        context
+    ) => {
+        context.state.requestSource =
+            request.headers.get(
+                "X-Request-Source"
+            ) ??
+            "web";
+
+        return next();
+    };
+
+const observe:
+    MiddlewarePipelineHandler =
+    async (
+        _request,
+        next,
+        context
+    ) => {
+        console.log(
+            context.state.requestSource
+        );
+
+        return next();
+    };
+
+export const middleware = [
+    identify,
+    observe,
+];
+```
+
+`context.state` starts empty for every request and is not shared across concurrent requests.
+
+Use it for lightweight request-scoped information such as timing metadata, correlation IDs, feature flags, or values computed by an earlier middleware handler.
+
+Do not treat it as persistent storage.
+
+## Matchers
+
+Use `config.matcher` to limit the routes that execute middleware.
+
+```ts
+import type {
+    MiddlewareConfig,
+} from "bcp/middleware";
+
+export const config:
+    MiddlewareConfig = {
     matcher: [
         "/dashboard/:path*",
         "/api/private/:path*",
     ],
 };
+```
+
+String matchers support:
+
+```text
+/dashboard
+/users/:id
+/dashboard/:path*
+```
+
+A JavaScript `RegExp` is also supported.
+
+## Request data
+
+The middleware request contains:
+
+```ts
+request.url
+request.method
+request.headers
+request.nextUrl
+request.cookies
+```
+
+Example:
+
+```ts
+export async function middleware(
+    request,
+    next
+) {
+    const theme =
+        request.cookies.get(
+            "theme"
+        );
+
+    console.log(
+        request.method,
+        request.nextUrl.pathname,
+        theme
+    );
+
+    return next();
+}
+```
+
+## Response interception
+
+Because `next()` returns the downstream `Response`, middleware can add or change headers after a page or API route finishes.
+
+```ts
+export async function middleware(
+    request,
+    next
+) {
+    const response =
+        await next();
+
+    response.headers.set(
+        "X-Route",
+        request.nextUrl.pathname
+    );
+
+    return response;
+}
+```
+
+Middleware may also replace the response completely:
+
+```ts
+export async function middleware(
+    request,
+    next
+) {
+    const response =
+        await next();
+
+    if (
+        response.status === 404 &&
+        request.nextUrl.pathname
+            .startsWith("/api/")
+    ) {
+        return Response.json(
+            {
+                error:
+                    "API endpoint not found",
+            },
+            {
+                status: 404,
+            }
+        );
+    }
+
+    return response;
+}
+```
+
+## Rewrite
+
+`rewrite()` keeps the browser URL but changes the route processed by BCP.
+
+```ts
+import {
+    rewrite,
+} from "bcp/middleware";
+
+export function middleware(
+    request
+) {
+    if (
+        request.nextUrl.pathname ===
+        "/old-dashboard"
+    ) {
+        return rewrite(
+            "/dashboard"
+        );
+    }
+}
+```
+
+Rewrites must remain on the same origin.
+
+In a v2 chain, return `rewrite()` before calling `next()`.
+
+## Redirect
+
+```ts
+import {
+    redirect,
+} from "bcp/middleware";
+
+export function middleware(
+    request
+) {
+    if (
+        !request.cookies.has(
+            "session"
+        )
+    ) {
+        return redirect(
+            "/login",
+            {
+                status: 303,
+            }
+        );
+    }
+}
+```
+
+Supported redirect statuses are `301`, `302`, `303`, `307`, and `308`.
+
+Middleware redirects continue to work with direct document requests and BCP SPA navigation.
+
+## Request and response headers
+
+The existing v1 helpers continue to work inside a v2 chain.
+
+```ts
+import {
+    next,
+} from "bcp/middleware";
+
+export function middleware() {
+    return next({
+        request: {
+            headers: {
+                "X-Internal-Request":
+                    "true",
+            },
+        },
+        response: {
+            headers: {
+                "X-Powered-By-App":
+                    "BCP",
+            },
+        },
+    });
+}
+```
+
+Request headers are visible to later middleware and the application. Response headers are applied after downstream execution.
+
+## Direct responses
+
+A middleware handler can stop the chain by returning a Web `Response` without calling `next()`.
+
+```ts
+export function middleware(
+    request
+) {
+    if (
+        request.nextUrl.pathname ===
+        "/maintenance"
+    ) {
+        return new Response(
+            "Maintenance",
+            {
+                status: 503,
+            }
+        );
+    }
+}
+```
+
+## Error middleware pattern
+
+A v2 handler can wrap downstream execution with `try/catch`.
+
+```ts
+export async function middleware(
+    request,
+    next
+) {
+    try {
+        return await next();
+    } catch (error) {
+        console.error(
+            "Request failed",
+            request.nextUrl.pathname,
+            error
+        );
+
+        return Response.json(
+            {
+                error:
+                    "Internal Server Error",
+            },
+            {
+                status: 500,
+            }
+        );
+    }
+}
+```
+
+Use this for application-specific error translation. Framework security and server error boundaries still have their own responsibilities.
+
+## v1 compatibility
+
+BCP 0.1.18 does not require existing middleware to be rewritten.
+
+A v1 handler remains valid:
+
+```ts
+import {
+    next,
+    redirect,
+} from "bcp/middleware";
 
 export function middleware(
-    request: MiddlewareRequest
+    request
 ) {
     if (
-        !request.cookies.has("session")
+        request.nextUrl.pathname ===
+        "/private" &&
+        !request.cookies.has(
+            "session"
+        )
     ) {
-        return redirect("/login");
+        return redirect(
+            "/login"
+        );
     }
 
     return next();
 }
 ```
 
-## Results
+The important difference is:
 
-Middleware may:
+| Capability | v1 | v2 |
+| --- | --- | --- |
+| Inspect request | Yes | Yes |
+| Match routes | Yes | Yes |
+| Redirect | Yes | Yes |
+| Rewrite | Yes | Yes |
+| Request/response header helpers | Yes | Yes |
+| Return direct `Response` | Yes | Yes |
+| Multiple middleware handlers | No | Yes |
+| `await next()` executes downstream | No | Yes |
+| Inspect final route response | No | Yes |
+| Shared request context | No | Yes |
+| Before/after onion flow | No | Yes |
 
-- continue with `next()`
-- rewrite to another same-origin route with `rewrite()`
-- redirect to an HTTP(S) URL with `redirect()`
-- return a `Response` directly
-- mutate request and response headers through middleware options
+Existing v1 middleware can be migrated gradually. A project may mix legacy one-argument handlers and v2 handlers in the same exported array.
 
-## Matchers
+## Execution model
 
-Matchers support exact paths, dynamic path segments and catch-all patterns such as:
+At runtime, middleware sits in front of the BCP application.
 
 ```text
-/dashboard
-/users/:id
-/dashboard/:path*
+Browser
+  ↓
+BCP outer gateways
+  ↓
+Middleware v2 pipeline
+  ↓
+Actions / Guards / Loaders / Pages / APIs
+  ↑
+Middleware v2 response path
+  ↓
+Browser
 ```
 
+Development and standalone production use the same middleware pipeline semantics.
+
+## Performance note
+
+Middleware response interception crosses a Web `Response` boundary so BCP can expose the completed downstream response to user middleware. Avoid unnecessary body replacement for large responses when only a header change is needed.
+
 ## Security constraints
 
-Rewrites must stay on the same origin. Redirects and rewrites reject unsupported URL protocols and embedded URL credentials. Header values ultimately pass through Node.js response validation, while framework configuration rejects CR/LF/null-byte injection in security header settings.
+Rewrites must stay on the same origin. Redirects and rewrites reject unsupported URL protocols and embedded URL credentials.
+
+Framework-internal `/_bcp/*` requests bypass user middleware where required by the runtime. BCP SPA navigation still evaluates middleware against the intended destination URL rather than exposing internal navigation transport details to application policy.
 
-Framework-internal `/_bcp/*` requests bypass user middleware execution where required by the runtime.
+Do not use middleware as a replacement for route authorization when authorization is page-specific. Use route guards and `bcp/auth` helpers such as `requireAuth()` or `requireRole()` for protected application areas.

package/docs/releases/0.1.18.md

@@ -0,0 +1,119 @@
+# BCP Framework 0.1.18
+
+BCP Framework 0.1.18 introduces Middleware System v2 while preserving existing Middleware v1 applications.
+
+## Middleware System v2
+
+Middleware can now execute as an onion-style chain around the application.
+
+```ts
+export async function middleware(
+    request,
+    next,
+    context
+) {
+    const started =
+        performance.now();
+
+    const response =
+        await next();
+
+    response.headers.set(
+        "X-Response-Time",
+        `${Math.round(
+            performance.now() -
+            started
+        )}ms`
+    );
+
+    return response;
+}
+```
+
+`await next()` runs the remaining middleware and the real downstream BCP route, then returns the resulting Web `Response`.
+
+## Middleware chains
+
+Applications may export an array of handlers:
+
+```ts
+export const middleware = [
+    logger,
+    requestContext,
+    responseHeaders,
+];
+```
+
+Handlers execute from outer to inner before the application, then unwind from inner to outer after the application returns.
+
+## Shared request context
+
+The third handler argument exposes request-scoped state:
+
+```ts
+context.state.requestId =
+    "request-123";
+```
+
+The same state object is visible to later middleware in that request and is recreated for the next request.
+
+## Response interception
+
+Middleware can now inspect and modify the actual route response after page/API processing finishes.
+
+This supports patterns such as:
+
+- request/response timing
+- response metadata
+- application-specific response headers
+- error translation
+- response status observation
+- composable logging
+
+## Compatibility
+
+Middleware v1 remains supported.
+
+Existing code such as:
+
+```ts
+export function middleware(
+    request
+) {
+    return next();
+}
+```
+
+continues to work without modification.
+
+Legacy `next()`, `rewrite()`, `redirect()`, matchers, request headers, response headers, cookie reads and direct `Response` returns remain available.
+
+A project can also mix v1 and v2 handlers in the same middleware array.
+
+## Runtime
+
+The middleware proxy now exposes the real downstream application response to the v2 pipeline in both:
+
+- development
+- standalone production
+
+SPA navigation keeps middleware redirect/rewrite behavior while evaluating middleware policy against the intended destination URL.
+
+## Reliability
+
+Added regression coverage for:
+
+- onion execution order
+- response interception
+- shared request context
+- context isolation across requests
+- legacy handlers inside v2 chains
+- rewrite propagation
+- duplicate `next()` rejection
+- middleware array validation
+
+## Documentation
+
+`docs/middleware.md` now contains the complete Middleware v2 guide and v1 migration reference.
+
+`docs/README.md` provides a documentation content map, recommended navigation, feature inventory, and source-of-truth guidance for building the `bcp-docs` website.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",