@stacksjs/server 0.70.294 → 0.70.297

package/dist/proxy.d.ts

@@ -1,7 +1,76 @@
-/**` prefix, or uses a verb that never matches a
- * static stx page render. Without the verb rule,
- * `route.post('/subscribe', ...)` declared at the root hits stx-serve
- * and 404s.
+/**
+ * Normalise app configuration into the rules the predicate reads.
+ *
+ * `/api/` is always present: it is the prefix the framework's own generated
+ * routes use, and an app that dropped it would find its auto-CRUD endpoints
+ * unreachable with no indication why. Configuring `prefixes` ADDS to it.
+ *
+ * Resolve this once at boot rather than per request. `@stacksjs/config`
+ * populates `overrides` asynchronously, so a per-request read would answer
+ * differently depending on how far boot had progressed.
  */
-export declare function isApiBoundRequest(req: Request, pathname: string): boolean;
+export declare function resolveApiProxyRules(input?: ApiProxyConfig): ApiProxyRules;
+/**`
+ * prefix, or a mutating verb. Callers that have resolved the app's
+ * configuration pass it in.
+ */
+export declare function isApiBoundRequest(req: Request, pathname: string, rules?: ApiProxyRules): boolean;
+/**
+ * A one-line summary of what will be forwarded, for the dev server's boot
+ * output.
+ *
+ * Asked for directly in stacksjs/stacks#2230: a 404 on a route you know you
+ * registered is very hard to diagnose when the rule that swallowed it is
+ * invisible.
+ */
+export declare function describeApiProxyRules(rules: ApiProxyRules): string;
 export declare function proxyToBackend(req: Request, backendBase: string, stripPrefix?: string): Promise<Response>;
+/**` traffic behaves identically
+ * in both topologies (stacksjs/stacks#1950).
+ */
+/** The prefix that is always API-bound, with or without configuration. */
+export declare const DEFAULT_API_PREFIX: '/api/';
+/**
+ * Verbs that never match a static stx page render, so they always belong to
+ * bun-router. Without this rule, `route.post('/subscribe', ...)` declared at
+ * the root hits stx-serve and 404s.
+ */
+export declare const DEFAULT_API_METHODS: readonly string[];
+/**
+ * What the views server forwards to the API process.
+ *
+ * ## Why this is configuration and not a route lookup
+ *
+ * The obvious fix for stacksjs/stacks#2230 is to ask the router:
+ * `route.getAllowedMethods(pathname)` already answers exactly the right
+ * question. It is not reachable from here. `isApiBoundRequest` is called from
+ * an `onRequest` hook inside the VIEWS process, and the route table is
+ * registered in the API process — a different process in `buddy dev`, and
+ * potentially a different host in production, where `production-server.ts`
+ * proxies to an `apiBase` URL. Importing the app's route files into the views
+ * process to consult them would execute route registration there, pulling the
+ * models and database in with it, and in a split deployment the views site may
+ * not ship that code at all.
+ *
+ * So the app declares it, the way Next's `rewrites()` does. Empty by default,
+ * so nothing changes for an app that does not set it.
+ *
+ * ## The cost of adding a path here
+ *
+ * stx's `onRequest` runs BEFORE static file serving, so any path this matches
+ * permanently shadows a `public/` file of the same name. Adding `/script.js`
+ * means `public/script.js` stops being reachable. That is a fine trade when
+ * the API really does own the path, and a confusing one otherwise, which is
+ * why `describeApiProxyRules` exists and the dev server prints it at boot.
+ */
+export declare interface ApiProxyRules {
+  prefixes: string[]
+  paths: string[]
+  methods: Set<string>
+}
+/** The shape an app writes in `config/server.ts` under `proxy`. */
+export declare interface ApiProxyConfig {
+  prefixes?: readonly string[]
+  paths?: readonly string[]
+  methods?: readonly string[]
+}

package/dist/proxy.js

@@ -1 +1 @@
-const API_METHODS=new Set(["POST","PUT","PATCH","DELETE"]);export function isApiBoundRequest(req,pathname){return pathname.startsWith("/api/")||API_METHODS.has(req.method)}export async function proxyToBackend(req,backendBase,stripPrefix){const incoming=new URL(req.url);let pathname=incoming.pathname;if(stripPrefix&&(pathname===stripPrefix||pathname.startsWith(`${stripPrefix}/`)))pathname=pathname.slice(stripPrefix.length)||"/";const target=`${backendBase}${pathname}${incoming.search}`,fwd=new Headers(req.headers);fwd.delete("host");fwd.delete("content-length");fwd.set("x-forwarded-host",incoming.host);fwd.set("x-forwarded-proto",incoming.protocol.replace(":",""));const body=req.method==="GET"||req.method==="HEAD"?void 0:await req.arrayBuffer(),upstream=await fetch(target,{method:req.method,headers:fwd,body,redirect:"manual"}),out=new Headers(upstream.headers);out.delete("content-length");out.delete("content-encoding");return new Response(upstream.body,{status:upstream.status,statusText:upstream.statusText,headers:out})}
+export const DEFAULT_API_PREFIX="/api/",DEFAULT_API_METHODS=["POST","PUT","PATCH","DELETE"];export function resolveApiProxyRules(input={}){const prefixes=[DEFAULT_API_PREFIX];for(const raw of input.prefixes??[]){const prefix=String(raw).trim();if(!prefix||!prefix.startsWith("/"))continue;const normalized=prefix.endsWith("/")?prefix:`${prefix}/`;if(!prefixes.includes(normalized))prefixes.push(normalized)}const paths=[];for(const raw of input.paths??[]){const path=String(raw).trim();if(!path||!path.startsWith("/"))continue;const normalized=path.length>1&&path.endsWith("/")?path.slice(0,-1):path;if(!paths.includes(normalized))paths.push(normalized)}const methods=new Set((input.methods??DEFAULT_API_METHODS).map((method)=>String(method).toUpperCase()));return{prefixes,paths,methods}}function matchesPrefix(pathname,prefix){return pathname.startsWith(prefix)||pathname===prefix.slice(0,-1)}export function isApiBoundRequest(req,pathname,rules){if(!rules)return pathname.startsWith(DEFAULT_API_PREFIX)||DEFAULT_API_METHODS.includes(req.method);if(rules.methods.has(req.method))return!0;if(rules.paths.includes(pathname))return!0;return rules.prefixes.some((prefix)=>matchesPrefix(pathname,prefix))}export function describeApiProxyRules(rules){const parts=[`prefixes ${rules.prefixes.join(" ")}`,`methods ${[...rules.methods].sort().join("/")}`];if(rules.paths.length>0)parts.push(`paths ${rules.paths.join(" ")}`);return parts.join(", ")}export async function proxyToBackend(req,backendBase,stripPrefix){const incoming=new URL(req.url);let pathname=incoming.pathname;if(stripPrefix&&(pathname===stripPrefix||pathname.startsWith(`${stripPrefix}/`)))pathname=pathname.slice(stripPrefix.length)||"/";const target=`${backendBase}${pathname}${incoming.search}`,fwd=new Headers(req.headers);fwd.delete("host");fwd.delete("content-length");fwd.set("x-forwarded-host",incoming.host);fwd.set("x-forwarded-proto",incoming.protocol.replace(":",""));const body=req.method==="GET"||req.method==="HEAD"?void 0:await req.arrayBuffer(),upstream=await fetch(target,{method:req.method,headers:fwd,body,redirect:"manual"}),out=new Headers(upstream.headers);out.delete("content-length");out.delete("content-encoding");return new Response(upstream.body,{status:upstream.status,statusText:upstream.statusText,headers:out})}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/server",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.294",
+  "version": "0.70.297",
   "description": "Local development and production-ready.",
   "author": "Chris Breuer",
   "contributors": [
@@ -58,11 +58,11 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@stacksjs/config": "0.70.294",
+    "@stacksjs/config": "0.70.297",
     "better-dx": "^0.2.17",
-    "@stacksjs/path": "0.70.294",
-    "@stacksjs/router": "0.70.294",
-    "@stacksjs/validation": "0.70.294"
+    "@stacksjs/path": "0.70.297",
+    "@stacksjs/router": "0.70.297",
+    "@stacksjs/validation": "0.70.297"
   },
   "dependencies": {
     "bun-plugin-auto-imports": "^0.4.0"