@chidchanun/bcp 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable framework changes are tracked here before release.
 
+## 0.1.7 - Server request context and cookies
+
+### Server APIs
+
+- Added the server-only `bcp/server` entrypoint for request-scoped helpers.
+- Added `headers()` for reading an isolated copy of the active request headers.
+- Added `requestUrl()` for reading an isolated copy of the active request URL, including pathname and search parameters.
+- Added `requestMethod()` for reading the normalized HTTP method of the active request.
+- Added `requestId()` with incoming `X-Request-Id` reuse and stable per-request UUID generation when no valid ID is supplied.
+- Added `bearerToken()` for extracting Bearer credentials without imposing a JWT implementation.
+- Added `clientIp()` with direct socket addresses by default and explicit `trustProxy` support for `Forwarded`, `X-Forwarded-For` and `X-Real-IP`.
+- Forwarded client IP values are accepted only when they validate as IPv4 or IPv6 addresses, and IPv4-mapped IPv6 addresses are normalized.
+- Added `json()` as a typed convenience wrapper around the standard Web `Response.json()` API.
+- Added `redirect()` with relative URL resolution, HTTP/HTTPS validation and support for 301, 302, 303, 307 and 308 responses; the default redirect status is 307.
+- Added `cookies()` with request-cookie `get`, `getAll` and `has` helpers.
+- Added response-cookie `set` and `delete` support with domain, path, expires, max-age, HttpOnly, Secure and SameSite attributes.
+- Response cookies created through `cookies()` are merged with cookies already present on the returned `Response` and remain separate `Set-Cookie` header values, including redirect responses.
+- Request state is isolated with Node.js `AsyncLocalStorage` so concurrent requests do not share URL, method, request ID, header or cookie data.
+- `bcp/server` is blocked from page/client graphs by the application boundary validator and is currently intended for API route handlers.
+
+### Reliability
+
+- Added request-context unit tests for URL/header access, cookie parsing, concurrent request isolation, response cookie serialization, deletion and validation.
+- Added auth-request unit coverage for HTTP methods, incoming/generated request IDs, Bearer parsing, direct IP addresses, trusted proxy precedence and invalid forwarded-IP rejection.
+- Added response-helper unit coverage for JSON responses, relative and absolute redirects, redirect status validation and protocol validation.
+- Added client-boundary coverage for the new `bcp/server` entrypoint.
+- Added development integration coverage for request URL/header helpers, auth request helpers, direct/proxy client IPs, JSON responses, redirects and response cookies through the full dev gateway stack.
+- Added standalone production E2E coverage to verify `bcp/server` resolution, auth request helpers, direct/proxy client IPs, helper responses and multiple `Set-Cookie` values after production bundling.
+- Package smoke checks verify that the `bcp/server` entrypoint and request-context runtime are included in publish artifacts.
+
 ## 0.1.6 - Critical CSS and release visibility
 
 ### Performance
@@ -36,7 +66,7 @@ All notable framework changes are tracked here before release.
 
 - Tailwind projects now install the official `@tailwindcss/cli` package and compile CSS before starting BCP.
 - Development runs Tailwind in watch mode alongside `bcp dev` using `concurrently`.
-- Production builds minify Tailwind CSS before `bcp build`.
+- Production builds minify Tailwind CSS before the BCP production build.
 - Generated Tailwind CSS is served through a framework API stylesheet endpoint with cache disabled during development.
 - Root layout automatically links the generated stylesheet.
 - Tailwind source detection is explicitly rooted at the generated project so utility classes in `app/` and other project files are discovered.

package/README.md

@@ -2,7 +2,7 @@
 
 BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, security defaults and standalone production builds.
 
-> Current development version: `0.1.6`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current development version: `0.1.7`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -121,6 +121,81 @@ export function GET() {
 
 Supported methods include GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. HEAD falls back to GET when no explicit HEAD handler exists, and OPTIONS is generated automatically when appropriate.
 
+## Server request APIs
+
+BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. In the current 0.1.x client pipeline these helpers are intended for API routes and are rejected from page/client module graphs.
+
+```ts
+import {
+    bearerToken,
+    clientIp,
+    cookies,
+    json,
+    requestId,
+    requestMethod,
+    requestUrl,
+} from "bcp/server";
+
+export async function GET() {
+    const url =
+        await requestUrl();
+
+    return json({
+        pathname:
+            url.pathname,
+        method:
+            await requestMethod(),
+        requestId:
+            await requestId(),
+        bearerToken:
+            await bearerToken(),
+        clientIp:
+            await clientIp(),
+        session:
+            (
+                await cookies()
+            ).get(
+                "session"
+            )?.value ?? null,
+    });
+}
+```
+
+`requestId()` reuses a valid incoming `X-Request-Id` or generates one stable UUID for the request. `bearerToken()` extracts a Bearer credential without decoding or verifying it. `clientIp()` uses the direct socket address by default; applications behind a trusted reverse proxy can explicitly use `clientIp({ trustProxy: true })` to read validated `Forwarded`, `X-Forwarded-For` or `X-Real-IP` values.
+
+Response cookies and redirects can be composed for login-style flows:
+
+```ts
+import {
+    cookies,
+    redirect,
+} from "bcp/server";
+
+export async function POST() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "session",
+        "session-token",
+        {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: "/",
+            maxAge: 60 * 60 * 12,
+        }
+    );
+
+    return redirect(
+        "/dashboard",
+        303
+    );
+}
+```
+
+`redirect()` defaults to status `307`; supported statuses are `301`, `302`, `303`, `307` and `308`. Use `cookieStore.delete("session")` to expire a cookie. See [Server Request APIs](docs/server-request-apis.md) for proxy trust, URL handling, response helpers, request isolation, cookie options and boundary details.
+
 ## Metadata
 
 ```ts
@@ -262,6 +337,7 @@ No real npm publish command is run automatically by the repository.
 
 - [Getting Started](docs/getting-started.md)
 - [Application Modules](docs/application-modules.md)
+- [Server Request APIs](docs/server-request-apis.md)
 - [Routing](docs/routing.md)
 - [Configuration](docs/configuration.md)
 - [Caching](docs/caching.md)

package/docs/server-request-apis.md

@@ -0,0 +1,404 @@
+# Server Request APIs
+
+BCP Framework 0.1.7 introduces request-scoped server helpers through `bcp/server`.
+
+These APIs are server-only and are intended for API route handlers in the current 0.1.x client pipeline. Importing `bcp/server` from a page, layout, client island or another module reachable from the browser bundle is rejected by the client-boundary validator.
+
+## Headers
+
+Use `headers()` to read a copy of the current request headers:
+
+```ts
+import {
+    headers,
+} from "bcp/server";
+
+export async function GET() {
+    const requestHeaders =
+        await headers();
+
+    return Response.json({
+        userAgent:
+            requestHeaders.get(
+                "user-agent"
+            ),
+        requestId:
+            requestHeaders.get(
+                "x-request-id"
+            ),
+    });
+}
+```
+
+The returned `Headers` object is a copy. Mutating it does not modify the original incoming request.
+
+## Request URL
+
+Use `requestUrl()` to read the complete URL of the current request, including pathname and search parameters:
+
+```ts
+import {
+    json,
+    requestUrl,
+} from "bcp/server";
+
+export async function GET() {
+    const url =
+        await requestUrl();
+
+    return json({
+        pathname:
+            url.pathname,
+        query:
+            url.searchParams.get(
+                "query"
+            ),
+    });
+}
+```
+
+The returned `URL` is a copy. Mutating it does not change the request context seen by another helper call.
+
+## Request method
+
+`requestMethod()` returns the normalized uppercase HTTP method for the active request:
+
+```ts
+import {
+    requestMethod,
+} from "bcp/server";
+
+export async function POST() {
+    return Response.json({
+        method:
+            await requestMethod(),
+    });
+}
+```
+
+A POST request returns `"POST"`, a GET request returns `"GET"`, and so on.
+
+## Request ID
+
+`requestId()` provides one stable identifier for the active request:
+
+```ts
+import {
+    requestId,
+} from "bcp/server";
+
+export async function GET() {
+    const id =
+        await requestId();
+
+    return Response.json({
+        requestId:
+            id,
+    });
+}
+```
+
+When the incoming request includes a valid `X-Request-Id`, BCP preserves that value. If the header is missing, blank, longer than 256 characters or contains control characters, BCP generates a UUID once and every `requestId()` call in that request returns the same generated value.
+
+## Bearer tokens
+
+Use `bearerToken()` to extract an HTTP Bearer credential from the `Authorization` header:
+
+```ts
+import {
+    bearerToken,
+} from "bcp/server";
+
+export async function GET() {
+    const token =
+        await bearerToken();
+
+    if (!token) {
+        return Response.json(
+            {
+                error:
+                    "Unauthorized",
+            },
+            {
+                status:
+                    401,
+            }
+        );
+    }
+
+    return Response.json({
+        authenticated:
+            true,
+    });
+}
+```
+
+The `Bearer` scheme is matched case-insensitively. BCP returns the credential string after the scheme and does not decode, verify or assume JWT. Missing authorization and non-Bearer schemes return `null`.
+
+## Client IP
+
+`clientIp()` reads the direct connection address attached to the BCP request context:
+
+```ts
+import {
+    clientIp,
+} from "bcp/server";
+
+export async function GET() {
+    return Response.json({
+        ip:
+            await clientIp(),
+    });
+}
+```
+
+Proxy forwarding headers are not trusted by default. Applications behind a trusted reverse proxy can opt in explicitly:
+
+```ts
+const ip =
+    await clientIp({
+        trustProxy:
+            true,
+    });
+```
+
+When `trustProxy` is enabled, BCP checks client-address sources in this order:
+
+1. the standardized `Forwarded` header (`for=`)
+2. the first usable value in `X-Forwarded-For`
+3. `X-Real-IP`
+4. the direct connection address
+
+Do not enable `trustProxy` when clients can connect directly without a trusted proxy stripping or replacing forwarding headers, because forwarded client-IP headers can otherwise be spoofed.
+
+IPv4-mapped IPv6 addresses such as `::ffff:127.0.0.1` are normalized to `127.0.0.1`.
+
+## JSON responses
+
+`json()` is a small wrapper around the standard Web `Response.json()` API. It accepts the response body and an optional `ResponseInit`:
+
+```ts
+import {
+    json,
+} from "bcp/server";
+
+export function POST() {
+    return json(
+        {
+            success: true,
+        },
+        {
+            status: 201,
+            headers: {
+                "x-created": "yes",
+            },
+        }
+    );
+}
+```
+
+BCP keeps the Web Response model, so existing `Response` objects and `Response.json()` continue to work alongside the helper.
+
+## Redirect responses
+
+Use `redirect()` to create HTTP redirects. Relative destinations are resolved against the current request URL:
+
+```ts
+import {
+    redirect,
+} from "bcp/server";
+
+export function POST() {
+    return redirect(
+        "/dashboard",
+        303
+    );
+}
+```
+
+The default status is `307`. Supported redirect statuses are `301`, `302`, `303`, `307` and `308`. Redirect destinations must use HTTP or HTTPS. Absolute HTTP/HTTPS URLs are also supported.
+
+A common login-style flow can combine response cookies and redirects:
+
+```ts
+import {
+    cookies,
+    redirect,
+} from "bcp/server";
+
+export async function POST() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "session",
+        "session-token",
+        {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: "/",
+        }
+    );
+
+    return redirect(
+        "/dashboard",
+        303
+    );
+}
+```
+
+BCP applies pending response cookies after the handler resolves, so cookies created before `redirect()` are preserved on the redirect response.
+
+## Request cookies
+
+Use `cookies()` to inspect cookies sent by the client:
+
+```ts
+import {
+    cookies,
+} from "bcp/server";
+
+export async function GET() {
+    const cookieStore =
+        await cookies();
+
+    return Response.json({
+        session:
+            cookieStore.get(
+                "session"
+            )?.value ?? null,
+        hasTheme:
+            cookieStore.has(
+                "theme"
+            ),
+        all:
+            cookieStore.getAll(),
+    });
+}
+```
+
+Request cookie values are percent-decoded when possible. Invalid percent encoding is preserved instead of failing the request.
+
+## Setting response cookies
+
+`cookies().set()` records a `Set-Cookie` value that BCP applies to the API response:
+
+```ts
+import {
+    cookies,
+} from "bcp/server";
+
+export async function POST() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "session",
+        "session-token",
+        {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: "/",
+            maxAge: 60 * 60 * 12,
+        }
+    );
+
+    return Response.json({
+        success: true,
+    });
+}
+```
+
+The object form is also supported:
+
+```ts
+cookieStore.set({
+    name: "refreshToken",
+    value: "token-value",
+    httpOnly: true,
+    secure: true,
+    sameSite: "strict",
+    path: "/api",
+    expires:
+        new Date(
+            Date.now() +
+            7 * 24 * 60 * 60 * 1000
+        ),
+});
+```
+
+Supported response-cookie options are:
+
+- `domain`
+- `path`
+- `expires`
+- `maxAge`
+- `httpOnly`
+- `secure`
+- `sameSite`: `"lax"`, `"strict"` or `"none"`
+
+Multiple response cookies remain separate `Set-Cookie` header values. Cookies already present on the returned `Response` are preserved.
+
+## Deleting cookies
+
+Deleting a cookie emits an expired cookie with `Max-Age=0`:
+
+```ts
+export async function DELETE() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.delete(
+        "session"
+    );
+
+    return Response.json({
+        success: true,
+    });
+}
+```
+
+When the original cookie uses a custom path or domain, supply the same values when deleting it:
+
+```ts
+cookieStore.delete(
+    "session",
+    {
+        path: "/admin",
+        domain: "example.com",
+    }
+);
+```
+
+## Request isolation
+
+BCP stores request state with Node.js `AsyncLocalStorage`. Concurrent requests receive independent URL, method, request ID, headers and cookies, so request data from one user is not shared with another request.
+
+Calling a request-scoped helper without an active BCP request context throws an error. A relative `redirect()` also requires the active request context because it resolves the destination against the current URL.
+
+## Client boundary
+
+This is invalid in the current 0.1.x page/client pipeline:
+
+```tsx
+import {
+    cookies,
+} from "bcp/server";
+
+export default function Page() {
+    return null;
+}
+```
+
+Move the server operation behind an API route instead:
+
+```text
+page/client
+    -> fetch("/api/session")
+    -> API route
+    -> bcp/server
+```
+
+Future server-rendered data primitives can extend these helpers to page-level server execution without exposing them to the browser bundle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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",
@@ -43,6 +43,11 @@
       "types": "./packages/client/src/config.ts",
       "default": "./packages/client/src/config.ts"
     },
+    "./server": {
+      "types": "./packages/client/src/server.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server.ts"
+    },
     "./server-only": {
       "types": "./packages/client/src/server-only.d.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -22,6 +22,8 @@ const MODULE_EXTENSIONS = [
     ".cjs",
 ] as const;
 
+const SERVER_ONLY_IMPORTS = new Set(["bcp/server","bcp/server-only"])
+
 export function validateClientBoundaries(
     routes: Route[],
     rootDirectory: string
@@ -127,13 +129,13 @@ function visitClientModule(
             source
         )
     ) {
-        if (
-            specifier ===
-            "bcp/server-only"
-        ) {
+        if (SERVER_ONLY_IMPORTS.has(specifier)){
             throw new Error(
-                `BCP Framework: ${formatApplicationPath(rootDirectory, filePath)} imports bcp/server-only but is reachable from the client bundle for ${routeName}. Move the server dependency behind an API route.`
-            );
+                `BCP Framework: ${formatApplicationPath(
+                    rootDirectory,
+                    filePath
+                )} imports ${specifier} but is reachable from the client bundle for ${routeName}. Move the server dependency behind an API route.`
+            )
         }
 
         const dependency =

package/packages/bundler/src/server-production.ts

@@ -172,6 +172,12 @@ export async function buildProductionServer(
             "../../client/src/islands.tsx"
         );
 
+    const frameworkServerEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../client/src/server.ts"
+        );
+
     await build({
         absWorkingDir:
             rootDirectory,
@@ -223,6 +229,17 @@ export async function buildProductionServer(
                                 frameworkIslandEntry,
                         })
                     );
+
+                    buildApi.onResolve(
+                        {
+                            filter:
+                                /^bcp\/server$/,
+                        },
+                        () => ({
+                            path:
+                                frameworkServerEntry,
+                        })
+                    );
                 },
             },
         ],

package/packages/client/src/server.ts

@@ -0,0 +1,23 @@
+export {
+    bearerToken,
+    clientIp,
+    cookies,
+    headers,
+    requestId,
+    requestMethod,
+    requestUrl,
+
+    type ClientIpOptions,
+    type CookieSameSite,
+    type RequestCookie,
+    type RequestCookieStore,
+    type ResponseCookie,
+    type ResponseCookieOptions,
+} from "../../server/src/request-context.js";
+
+export {
+    json,
+    redirect,
+
+    type RedirectStatus,
+} from "../../server/src/server-response.js";