@octanejs/app-core 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/app-core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -79,10 +79,10 @@
     "esbuild": "^0.28.1"
   },
   "peerDependencies": {
-    "octane": "^0.8.0"
+    "octane": "^0.10.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "octane": "0.8.0"
+    "octane": "0.10.0"
   }
 }

package/src/resolve-config.js

@@ -203,6 +203,10 @@ export function resolveOctaneConfig(raw, options = {}) {
 
 	validate_root_boundary(raw.rootBoundary);
 
+	if (raw.server?.trustProxy !== undefined && typeof raw.server.trustProxy !== 'boolean') {
+		throw new Error('[octane] server.trustProxy must be a boolean when provided.');
+	}
+
 	if (
 		raw.server?.render !== undefined &&
 		raw.server.render !== 'streaming' &&

package/src/server/node-http.js

@@ -128,17 +128,53 @@ function shouldGzip(request, status, headers, hasBody) {
 	return encodingQuality(getRequestHeader(request, 'accept-encoding'), 'gzip') > 0;
 }
 
+// A host name, IPv4, or bracketed IPv6 authority with an optional port. No URL
+// delimiter can pass, so a forwarded host never reaches the path or userinfo.
+const FORWARDED_HOST = /^(?:[a-z0-9_-]+(?:\.[a-z0-9_-]+)*|\[[0-9a-f:.]+\])(?::\d{1,5})?$/i;
+
+/**
+ * @param {import('node:http').IncomingMessage} request
+ * @param {string} name
+ */
+function firstForwardedValue(request, name) {
+	const value = getRequestHeader(request, name);
+	if (value === null) return '';
+	const comma = value.indexOf(',');
+	return (comma === -1 ? value : value.slice(0, comma)).trim();
+}
+
+/**
+ * The scheme and authority a request target resolves against. Forwarded
+ * headers are client-controlled unless a trusted proxy overwrites them, so they
+ * apply only on opt-in, and a malformed one keeps the direct connection's value.
+ * @param {import('node:http').IncomingMessage} request
+ * @param {boolean} trustProxy
+ */
+function requestBase(request, trustProxy) {
+	const host = request.headers.host || 'localhost';
+	if (!trustProxy) return `http://${host}`;
+	const proto = firstForwardedValue(request, 'x-forwarded-proto').toLowerCase();
+	const scheme = proto === 'https' || proto === 'http' ? proto : 'http';
+	const forwardedHost = firstForwardedValue(request, 'x-forwarded-host');
+	const forwardedBase = `${scheme}://${forwardedHost}`;
+	return FORWARDED_HOST.test(forwardedHost) && URL.canParse(forwardedBase)
+		? forwardedBase
+		: `${scheme}://${host}`;
+}
+
 /**
  * Convert a Node.js IncomingMessage to a Web Request. Passing its response
  * keeps request.signal active through streaming and cancels it on disconnect.
  * Without a response, cancellation only covers interrupted request uploads.
+ * With `trustProxy`, the URL's scheme and host come from the first
+ * `X-Forwarded-Proto` and `X-Forwarded-Host` entries when they are valid.
  * @param {import('node:http').IncomingMessage} nodeRequest
  * @param {import('node:http').ServerResponse} [nodeResponse]
+ * @param {{ trustProxy?: boolean }} [options]
  * @returns {Request}
  */
-export function nodeRequestToWebRequest(nodeRequest, nodeResponse) {
-	const host = nodeRequest.headers.host || 'localhost';
-	const url = new URL(nodeRequest.url || '/', `http://${host}`);
+export function nodeRequestToWebRequest(nodeRequest, nodeResponse, options) {
+	const url = nodeRequestUrl(nodeRequest, options);
 
 	const headers = new Headers();
 	for (const [key, value] of Object.entries(nodeRequest.headers)) {
@@ -210,6 +246,33 @@ export function nodeRequestToWebRequest(nodeRequest, nodeResponse) {
 	return request;
 }
 
+/**
+ * The URL a Node request targets, as `nodeRequestToWebRequest` builds it: the
+ * request target on the origin from `requestBase`.
+ * @param {import('node:http').IncomingMessage} nodeRequest
+ * @param {{ trustProxy?: boolean }} [options]
+ * @returns {URL}
+ */
+export function nodeRequestUrl(nodeRequest, options) {
+	const { origin } = new URL(requestBase(nodeRequest, options?.trustProxy === true));
+	return resolveRequestTarget(nodeRequest.url || '/', origin);
+}
+
+const ABSOLUTE_FORM_TARGET = /^https?:\/\//i;
+
+/**
+ * Origin-form targets are joined to the origin, never resolved against it:
+ * URL resolution reads a leading `//` or `/\` as another host. An http(s)
+ * absolute-form target keeps its own origin (RFC 9112 section 3.2.2). Any
+ * other target, such as `*` or another scheme, becomes a path under the root.
+ * @param {string} target
+ * @param {string} origin
+ */
+function resolveRequestTarget(target, origin) {
+	if (ABSOLUTE_FORM_TARGET.test(target)) return new URL(target);
+	return new URL(target.startsWith('/') ? origin + target : `${origin}/${target}`);
+}
+
 /**
  * Pipe a Web Response to a Node.js ServerResponse. Streams chunk-by-chunk so a
  * streaming SSR body flushes as it renders (no buffering). A HEAD response ends
@@ -390,10 +453,38 @@ const MIME_TYPES = {
 	'.map': 'application/json',
 };
 
+const BYTE_RANGE = /^bytes=(\d*)-(\d*)$/i;
+
+/**
+ * The one `bytes=` range of a non-empty file a request selects (RFC 9110
+ * section 14.1.2). `null` means the header is ignored and the whole file is
+ * served: several ranges, another unit, or a malformed or invalid range.
+ * `false` means the range is unsatisfiable.
+ *
+ * @param {string | undefined} header
+ * @param {number} size
+ * @returns {{ start: number, end: number } | false | null}
+ */
+function byteRange(header, size) {
+	const match = BYTE_RANGE.exec(header?.trim() ?? '');
+	if (!match) return null;
+	const [, first, last] = match;
+	if (first === '') {
+		if (last === '') return null;
+		const suffix = Number(last);
+		return suffix === 0 ? false : { start: Math.max(0, size - suffix), end: size - 1 };
+	}
+	const start = Number(first);
+	if (last !== '' && Number(last) < start) return null;
+	if (start >= size) return false;
+	return { start, end: last === '' ? size - 1 : Math.min(Number(last), size - 1) };
+}
+
 /**
  * Serve a static file from `staticDir` if the request path maps to one.
  * Hash-named build assets (Vite's /assets/ and Rsbuild's /static/) get
  * immutable caching; other files (favicon, robots.txt, …) revalidate.
+ * A GET for one byte range gets 206, or 416 past the end of the file.
  *
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
@@ -414,7 +505,9 @@ function serveStaticFileFromRoot(req, res, staticDir, configuredRoot) {
 	const method = (req.method || 'GET').toUpperCase();
 	if (method !== 'GET' && method !== 'HEAD') return false;
 
-	const pathname = decodeURIComponent(new URL(req.url || '/', 'http://localhost').pathname);
+	const pathname = decodeURIComponent(
+		resolveRequestTarget(req.url || '/', 'http://localhost').pathname,
+	);
 	// Resolve inside staticDir only — a `..` escape must not leave the client dir.
 	const filePath = path.normalize(path.join(staticDir, pathname));
 	if (!filePath.startsWith(path.normalize(staticDir + path.sep))) return false;
@@ -450,21 +543,39 @@ function serveStaticFileFromRoot(req, res, staticDir, configuredRoot) {
 
 	try {
 		const ext = path.extname(filePath).toLowerCase();
+		// Range applies to GET only (RFC 9110 section 14.2). Static files send no
+		// validator, so no If-Range can match and that request gets the whole file.
+		// An empty file has no byte a 206 could carry.
+		const range =
+			method === 'GET' && stat.size > 0 && req.headers['if-range'] === undefined
+				? byteRange(req.headers.range, stat.size)
+				: null;
+		if (range === false) {
+			res.statusCode = 416;
+			res.setHeader('Content-Range', `bytes */${stat.size}`);
+			res.end();
+			return true;
+		}
 		const headers = new Headers({
 			'Content-Type': MIME_TYPES[ext] || 'application/octet-stream',
-			'Content-Length': String(stat.size),
+			'Content-Length': String(range ? range.end - range.start + 1 : stat.size),
 			'Cache-Control':
 				pathname.startsWith('/assets/') || pathname.startsWith('/static/')
 					? 'public, max-age=31536000, immutable'
 					: 'public, max-age=0, must-revalidate',
 		});
-		const gzip = shouldGzip(req, 200, headers, method !== 'HEAD');
+		const status = range ? 206 : 200;
+		// Ranges address the identity bytes: shouldGzip declines any request with a
+		// Range header, and a gzip body does not advertise ranges.
+		const gzip = shouldGzip(req, status, headers, method !== 'HEAD');
 		if (gzip) {
 			headers.set('Content-Encoding', 'gzip');
 			headers.delete('Content-Length');
 		}
 
-		res.statusCode = 200;
+		res.statusCode = status;
+		if (range) res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${stat.size}`);
+		if (!gzip) res.setHeader('Accept-Ranges', 'bytes');
 		res.setHeader('Content-Type', /** @type {string} */ (headers.get('Content-Type')));
 		const contentLength = headers.get('Content-Length');
 		if (contentLength !== null) res.setHeader('Content-Length', contentLength);
@@ -476,7 +587,12 @@ function serveStaticFileFromRoot(req, res, staticDir, configuredRoot) {
 		if (method === 'HEAD') {
 			res.end();
 		} else {
-			const source = fs.createReadStream(resolvedFile, { fd, autoClose: true });
+			const source = fs.createReadStream(resolvedFile, {
+				fd,
+				autoClose: true,
+				start: range?.start,
+				end: range?.end,
+			});
 			fd = -1; // The stream now owns and closes the descriptor.
 			if (gzip) {
 				pipeline(source, createGzip(), res, (error) => {
@@ -500,11 +616,12 @@ function serveStaticFileFromRoot(req, res, staticDir, configuredRoot) {
  * when octane.config.ts has no adapter — an adapter's `serve()` replaces it.
  *
  * @param {(request: Request) => Response | Promise<Response>} handler
- * @param {{ staticDir?: string }} [options]
+ * @param {{ staticDir?: string, trustProxy?: boolean }} [options]
  * @returns {{ listen: (port?: number) => import('node:http').Server, close: () => void }}
  */
 export function createNodeServer(handler, options = {}) {
 	const staticDir = options.staticDir;
+	const requestOptions = { trustProxy: options.trustProxy === true };
 	/** @type {string | null} */
 	let configuredRoot = null;
 	try {
@@ -523,7 +640,7 @@ export function createNodeServer(handler, options = {}) {
 			) {
 				return;
 			}
-			const response = await handler(nodeRequestToWebRequest(req, res));
+			const response = await handler(nodeRequestToWebRequest(req, res, requestOptions));
 			await sendWebResponseForRequest(res, response, req);
 		})().catch((error) => {
 			console.error('[octane] Request error:', error);

package/src/server/server-entry.js

@@ -469,13 +469,15 @@ export const handler = createHandler(
 	},
 );
 
+const nodeRequestOptions = { trustProxy: octaneConfig.server.trustProxy };
+
 /**
  * Node-style (req, res) wrapper — for serverless platforms whose functions
  * speak Node HTTP (e.g. Vercel's Node runtime).
  */
 export async function nodeHandler(req, res) {
 	try {
-		const response = await handler(nodeRequestToWebRequest(req, res));
+		const response = await handler(nodeRequestToWebRequest(req, res, nodeRequestOptions));
 		await sendWebResponse(res, response);
 	} catch (error) {
 		console.error('[octane] Request error:', error);
@@ -503,7 +505,7 @@ if (isMainModule) {
 	const staticDir = join(__dirname, '../client');
 	const server = octaneConfig.adapter?.serve
 		? octaneConfig.adapter.serve(handler, { static: { dir: staticDir } })
-		: createNodeServer(handler, { staticDir });
+		: createNodeServer(handler, { staticDir, trustProxy: octaneConfig.server.trustProxy });
 	server.listen(port);
 	console.log('[octane] Production server listening on port ' + port);
 }

package/types/index.d.ts

@@ -482,7 +482,10 @@ export interface OctaneConfigOptions {
 	server?: {
 		/**
 		 * Trust `X-Forwarded-Proto` / `X-Forwarded-Host` when deriving the
-		 * request origin. Enable only behind a trusted reverse proxy.
+		 * request origin: the request URL (`Context.url`) on the built-in Node
+		 * servers and dev servers, and the server-function origin check. Uses the
+		 * first entry of each header and ignores a malformed one. Enable only when
+		 * a trusted proxy overwrites both headers; clients can set them otherwise.
 		 * @default false
 		 */
 		trustProxy?: boolean;

package/types/node.d.ts

@@ -5,10 +5,18 @@ import type { IncomingMessage, ServerResponse, Server } from 'node:http';
  * cancel request.signal on a disconnect until the response finishes, including
  * after the request body has been consumed. Without a response, cancellation
  * only covers interrupted request uploads.
+ *
+ * The URL is `http://` plus the Host header. With `trustProxy`, its scheme comes
+ * from the first `X-Forwarded-Proto` entry when that is `http` or `https`, and
+ * its host from the first `X-Forwarded-Host` entry when that is a plain
+ * `host[:port]`; a malformed value keeps the direct connection's. The path and
+ * query always come from the request. Enable it only when a trusted proxy
+ * overwrites both headers.
  */
 export function nodeRequestToWebRequest(
 	nodeRequest: IncomingMessage,
 	nodeResponse?: ServerResponse,
+	options?: { trustProxy?: boolean },
 ): Request;
 
 /**
@@ -23,10 +31,24 @@ export function nodeRequestToWebRequest(
  */
 export function sendWebResponse(nodeResponse: ServerResponse, webResponse: Response): Promise<void>;
 
+/**
+ * The URL `nodeRequestToWebRequest` gives a Node request, with the same
+ * `trustProxy` rule for its origin. An origin-form target keeps its whole path
+ * and query on that origin, so a path that starts with `//` or `/\` never names
+ * another host. An `http://` or `https://` absolute-form target keeps its own
+ * origin (RFC 9112). Any other target, such as `*`, becomes a path under the root.
+ */
+export function nodeRequestUrl(
+	nodeRequest: IncomingMessage,
+	options?: { trustProxy?: boolean },
+): URL;
+
 /**
  * Serve a static file from `staticDir` when the request path maps to one.
  * Vite's `/assets/*` and Rsbuild's `/static/*` hash-named output get immutable
- * caching; other files revalidate. Returns true when the request was handled.
+ * caching; other files revalidate. A GET for one byte range gets an
+ * uncompressed 206, or 416 past the end of the file; any other Range request
+ * gets the whole file. Returns true when the request was handled.
  */
 export function serveStaticFile(
 	req: IncomingMessage,
@@ -38,8 +60,9 @@ export function serveStaticFile(
  * Minimal production HTTP server: static files from `staticDir` first (the
  * built client assets), then the fetch-style SSR handler. The default boot for
  * `node dist/server/entry.js` when octane.config.ts has no adapter.
+ * `trustProxy` applies to each request as in `nodeRequestToWebRequest`.
  */
 export function createNodeServer(
 	handler: (request: Request) => Response | Promise<Response>,
-	options?: { staticDir?: string },
+	options?: { staticDir?: string; trustProxy?: boolean },
 ): { listen: (port?: number) => Server; close: () => void };

package/types/production.d.ts

@@ -54,7 +54,7 @@ export interface ServerManifest {
 	/** Layout module path → module namespace */
 	layouts: Record<string, Record<string, unknown>>;
 	middlewares: Middleware[];
-	/** Trust X-Forwarded-* headers when deriving origin for RPC fetch */
+	/** Trust X-Forwarded-Proto/Host when deriving the request origin */
 	trustProxy?: boolean;
 	/** Validated `module server` origin and body-size policy. */
 	rpc?: Partial<ResolvedOctaneConfig['server']['rpc']>;