@ripple-ts/adapter 0.2.213 → 0.2.214

package/CHANGELOG.md

@@ -1,5 +1,7 @@
 # @ripple-ts/adapter
 
+## 0.2.214
+
 ## 0.2.213
 
 ## 0.2.212

package/package.json

@@ -3,7 +3,7 @@
   "description": "Shared adapter primitives for Ripple metaframework adapters",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.213",
+  "version": "0.2.214",
   "type": "module",
   "module": "src/index.js",
   "main": "src/index.js",
@@ -12,9 +12,14 @@
       "types": "./types/index.d.ts",
       "import": "./src/index.js",
       "default": "./src/index.js"
+    },
+    "./rpc": {
+      "types": "./types/rpc.d.ts",
+      "import": "./src/rpc.js",
+      "default": "./src/rpc.js"
     }
   },
-  "homepage": "https://ripplejs.com",
+  "homepage": "https://ripple-ts.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ripple-TS/ripple.git",

package/src/index.js

@@ -1,9 +1,3 @@
-// NOTE: For now we'd not have it fully runtime-agnostic
-// When we'd like to move away from Node.js modules or explore other runtime options.
-import { createReadStream, existsSync, statSync } from 'node:fs';
-import { extname, resolve, sep } from 'node:path';
-import { Readable } from 'node:stream';
-
 export const DEFAULT_HOSTNAME = 'localhost';
 export const DEFAULT_PORT = 3000;
 export const DEFAULT_STATIC_PREFIX = '/';
@@ -116,87 +110,7 @@ export function get_static_cache_control(
  * @returns {string}
  */
 export function get_mime_type(pathname) {
-	const extension = extname(pathname).toLowerCase();
+	const dot = pathname.lastIndexOf('.');
+	const extension = dot !== -1 ? pathname.slice(dot).toLowerCase() : '';
 	return MIME_TYPES[extension] || 'application/octet-stream';
 }
-
-/**
- * @param {string} base_dir
- * @param {string} pathname
- * @returns {string | null}
- */
-function resolve_static_file_path(base_dir, pathname) {
-	const file_path = resolve(base_dir, `.${pathname}`);
-	const is_within_base_dir = file_path === base_dir || file_path.startsWith(base_dir + sep);
-	return is_within_base_dir ? file_path : null;
-}
-
-/**
- * Create a request-based static file handler that can be used by adapters.
- *
- * @param {string} dir - Directory to serve files from (relative to cwd or absolute)
- * @param {{ prefix?: string, maxAge?: number, immutable?: boolean }} [options]
- * @returns {(request: Request) => Response | null}
- */
-export function serveStatic(dir, options = {}) {
-	const {
-		prefix = DEFAULT_STATIC_PREFIX,
-		maxAge = DEFAULT_STATIC_MAX_AGE,
-		immutable = false,
-	} = options;
-
-	const base_dir = resolve(dir);
-
-	return function serve_static_request(request) {
-		const request_method = (request.method || 'GET').toUpperCase();
-		if (request_method !== 'GET' && request_method !== 'HEAD') {
-			return null;
-		}
-
-		let pathname;
-		try {
-			pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname);
-		} catch {
-			return null;
-		}
-
-		if (!pathname.startsWith(prefix)) {
-			return null;
-		}
-
-		pathname = pathname.slice(prefix.length) || '/';
-		if (!pathname.startsWith('/')) {
-			pathname = '/' + pathname;
-		}
-
-		const file_path = resolve_static_file_path(base_dir, pathname);
-		if (file_path === null || !existsSync(file_path)) {
-			return null;
-		}
-
-		let file_stats;
-		try {
-			file_stats = statSync(file_path);
-		} catch {
-			return null;
-		}
-
-		if (file_stats.isDirectory()) {
-			return null;
-		}
-
-		const headers = new Headers();
-		headers.set('Content-Type', get_mime_type(file_path));
-		headers.set('Content-Length', String(file_stats.size));
-		headers.set('Cache-Control', get_static_cache_control(pathname, maxAge, immutable));
-
-		if (request_method === 'HEAD') {
-			return new Response(null, { status: 200, headers });
-		}
-
-		// `Readable.toWeb()` can be typed differently across Node/Bun/libdom contexts.
-		/** @type {BodyInit} */
-		const file_body = /** @type {any} */ (Readable.toWeb(createReadStream(file_path)));
-		return new Response(file_body, { status: 200, headers });
-	};
-}

package/src/rpc.js

@@ -0,0 +1,184 @@
+/**
+ * Shared RPC utilities for Ripple metaframework.
+ *
+ * These functions are platform-agnostic — they use only standard Web APIs
+ * (Request, Response, Headers, URL) and receive platform-specific capabilities
+ * (hashing, async context) from the adapter's runtime.
+ *
+ * Used by both the Vite dev server and production server runtime.
+ */
+
+/**
+@import {
+	RipplePatchedFetch,
+	RpcEntry,
+	handle_rpc_request,
+	is_rpc_request,
+	build_rpc_lookup,
+	patch_global_fetch,
+} from '@ripple-ts/adapter/rpc';
+ */
+
+const RPC_PATH_PREFIX = '/_$_ripple_rpc_$_/';
+
+// ============================================================================
+// Origin derivation
+// ============================================================================
+
+/** @type {import('@ripple-ts/adapter/rpc').derive_origin} */
+export function derive_origin(request, trust_proxy) {
+	const url = new URL(request.url);
+	let protocol = url.protocol.replace(':', '');
+	let host = url.host;
+
+	if (trust_proxy) {
+		const forwarded_proto = request.headers.get('x-forwarded-proto');
+		if (forwarded_proto) {
+			protocol = forwarded_proto.split(',')[0].trim();
+		}
+
+		const forwarded_host = request.headers.get('x-forwarded-host');
+		if (forwarded_host) {
+			host = forwarded_host.split(',')[0].trim();
+		}
+	}
+
+	return `${protocol}://${host}`;
+}
+
+// ============================================================================
+// Global fetch patching
+// ============================================================================
+
+/**
+ * Quick check whether a string looks like it already has a URL scheme.
+ * @param {string} url
+ * @returns {boolean}
+ */
+function has_scheme(url) {
+	return /^[a-z][a-z0-9+\-.]*:/i.test(url);
+}
+
+/** @type {patch_global_fetch} */
+export function patch_global_fetch(async_context) {
+	// Guard: if fetch is already patched by Ripple, don't wrap it again.
+	// This prevents layered wrapping when createHandler() or getDevAsyncContext()
+	// is called more than once in the same process (tests, hot reload, etc.).
+	if (/** @type {RipplePatchedFetch} */ (globalThis.fetch).__ripple_patched) {
+		return () => {};
+	}
+
+	/** @type {typeof globalThis.fetch} */
+	const original_fetch = globalThis.fetch;
+
+	/**
+	 * @param {string | Request | URL} input
+	 * @param {RequestInit} [init]
+	 * @returns {ReturnType<typeof globalThis.fetch>}
+	 */
+	const patched_fetch = function (input, init) {
+		const context = async_context.getStore();
+
+		if (context?.origin) {
+			if (typeof input === 'string' && !has_scheme(input)) {
+				input = new URL(input, context.origin).href;
+			} else if (input instanceof Request) {
+				const url = input.url;
+				if (!has_scheme(url)) {
+					input = new Request(new URL(url, context.origin).href, input);
+				}
+			} else if (input instanceof URL) {
+				if (!input.protocol || input.protocol === '' || input.origin === 'null') {
+					const relative = input.pathname + (input.search || '') + (input.hash || '');
+					input = new URL(relative, context.origin);
+				}
+			}
+		}
+
+		return original_fetch(input, init);
+	};
+
+	// Copy static properties (e.g. fetch.preconnect) so the patched
+	// function satisfies the full `typeof fetch` contract.
+	Object.assign(patched_fetch, original_fetch);
+
+	// Mark as patched so subsequent calls are idempotent
+	/** @type {RipplePatchedFetch} */ (patched_fetch).__ripple_patched = true;
+
+	globalThis.fetch = /** @type {typeof globalThis.fetch} */ (patched_fetch);
+
+	return () => {
+		globalThis.fetch = original_fetch;
+	};
+}
+
+// ============================================================================
+// RPC lookup
+// ============================================================================
+
+/** @type {build_rpc_lookup} */
+export function build_rpc_lookup(rpc_modules, hash_fn) {
+	/** @type {Map<string, RpcEntry>} */
+	const lookup = new Map();
+
+	for (const [entry_path, server_obj] of Object.entries(rpc_modules)) {
+		for (const func_name of Object.keys(server_obj)) {
+			const func_path = entry_path + '#' + func_name;
+			const hash = hash_fn(func_path);
+			lookup.set(hash, { serverObj: server_obj, funcName: func_name });
+		}
+	}
+
+	return lookup;
+}
+
+// ============================================================================
+// RPC request handler
+// ============================================================================
+
+/** @type {is_rpc_request} */
+export function is_rpc_request(pathname) {
+	return pathname.startsWith(RPC_PATH_PREFIX);
+}
+
+/** @type {handle_rpc_request} */
+export async function handle_rpc_request(request, options) {
+	const { resolveFunction, executeServerFunction, asyncContext, trustProxy } = options;
+
+	try {
+		const url = new URL(request.url);
+		const hash = url.pathname.slice(RPC_PATH_PREFIX.length);
+
+		// Validate hash format — compiler always generates 8 lowercase hex chars
+		if (!hash || !/^[a-f0-9]{8}$/.test(hash)) {
+			return new Response('Invalid RPC request', { status: 400 });
+		}
+
+		const body = await request.text();
+
+		const fn = await resolveFunction(hash);
+		if (!fn) {
+			return new Response(`RPC function not found: ${hash}`, { status: 404 });
+		}
+
+		const origin = derive_origin(request, trustProxy);
+
+		return await asyncContext.run({ origin }, async () => {
+			const result = await executeServerFunction(fn, body);
+
+			return new Response(result, {
+				status: 200,
+				headers: { 'Content-Type': 'application/json' },
+			});
+		});
+	} catch (error) {
+		console.error('[ripple] RPC error:', error);
+		return new Response(
+			JSON.stringify({ error: error instanceof Error ? error.message : 'RPC failed' }),
+			{
+				status: 500,
+				headers: { 'Content-Type': 'application/json' },
+			},
+		);
+	}
+}

package/tests/index.test.js

@@ -1,7 +1,4 @@
 import { describe, expect, it } from 'vitest';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
 import {
 	DEFAULT_HOSTNAME,
 	DEFAULT_PORT,
@@ -10,7 +7,6 @@ import {
 	internal_server_error_response,
 	is_hashed_asset,
 	run_next_middleware,
-	serveStatic,
 } from '../src/index.js';
 
 describe('@ripple-ts/adapter', () => {
@@ -95,98 +91,4 @@ describe('@ripple-ts/adapter', () => {
 		);
 		expect(get_static_cache_control('/assets/app.js', 60, false)).toBe('public, max-age=60');
 	});
-
-	it('serveStatic serves files for GET and HEAD requests', async () => {
-		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-static-'));
-		try {
-			writeFileSync(join(temp_dir, 'app.js'), 'console.log("ok");');
-
-			const static_handler = serveStatic(temp_dir, { prefix: '/assets' });
-
-			const get_response = static_handler(new Request('http://localhost/assets/app.js'));
-			expect(get_response).not.toBeNull();
-			if (get_response === null) {
-				throw new Error('Expected static GET response');
-			}
-			expect(get_response.status).toBe(200);
-			expect(get_response.headers.get('content-type')).toBe('text/javascript; charset=utf-8');
-			expect(get_response.headers.get('cache-control')).toBe('public, max-age=86400');
-			expect(await get_response.text()).toContain('console.log');
-
-			const head_response = static_handler(
-				new Request('http://localhost/assets/app.js', { method: 'HEAD' }),
-			);
-			expect(head_response).not.toBeNull();
-			if (head_response === null) {
-				throw new Error('Expected static HEAD response');
-			}
-			expect(head_response.status).toBe(200);
-			expect(await head_response.text()).toBe('');
-		} finally {
-			rmSync(temp_dir, { recursive: true, force: true });
-		}
-	});
-
-	it('serveStatic falls through for non-matching requests', () => {
-		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-static-fallthrough-'));
-		try {
-			writeFileSync(join(temp_dir, 'index.html'), '<h1>ok</h1>');
-			const static_handler = serveStatic(temp_dir, { prefix: '/assets' });
-
-			expect(static_handler(new Request('http://localhost/index.html'))).toBeNull();
-			expect(static_handler(new Request('http://localhost/assets/missing.js'))).toBeNull();
-			expect(
-				static_handler(new Request('http://localhost/assets/index.html', { method: 'POST' })),
-			).toBeNull();
-		} finally {
-			rmSync(temp_dir, { recursive: true, force: true });
-		}
-	});
-
-	it('serveStatic applies configured cache-control options', async () => {
-		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-static-cache-'));
-		try {
-			writeFileSync(join(temp_dir, 'app.js'), 'console.log("cache");');
-
-			const max_age_handler = serveStatic(temp_dir, { prefix: '/assets', maxAge: 120 });
-			const max_age_response = max_age_handler(new Request('http://localhost/assets/app.js'));
-			expect(max_age_response).not.toBeNull();
-			if (max_age_response === null) {
-				throw new Error('Expected static response');
-			}
-			expect(max_age_response.headers.get('cache-control')).toBe('public, max-age=120');
-
-			const immutable_handler = serveStatic(temp_dir, {
-				prefix: '/assets',
-				maxAge: 120,
-				immutable: true,
-			});
-			const immutable_response = immutable_handler(new Request('http://localhost/assets/app.js'));
-			expect(immutable_response).not.toBeNull();
-			if (immutable_response === null) {
-				throw new Error('Expected static response');
-			}
-			expect(immutable_response.headers.get('cache-control')).toBe(
-				'public, max-age=31536000, immutable',
-			);
-		} finally {
-			rmSync(temp_dir, { recursive: true, force: true });
-		}
-	});
-
-	it('serveStatic blocks traversal and directory targets', () => {
-		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-static-security-'));
-		try {
-			const public_dir = join(temp_dir, 'public');
-			mkdirSync(public_dir);
-			mkdirSync(join(public_dir, 'nested'));
-			writeFileSync(join(temp_dir, 'secret.txt'), 'secret');
-
-			const static_handler = serveStatic(public_dir, { prefix: '/assets' });
-			expect(static_handler(new Request('http://localhost/assets/%2e%2e/secret.txt'))).toBeNull();
-			expect(static_handler(new Request('http://localhost/assets/nested'))).toBeNull();
-		} finally {
-			rmSync(temp_dir, { recursive: true, force: true });
-		}
-	});
 });

package/types/index.d.ts

@@ -3,6 +3,9 @@ export type FetchHandler<Platform = any, ResultValue = Response> = (
 	platform?: Platform,
 ) => ResultValue | Promise<ResultValue>;
 
+// Re-export runtime primitive types from rpc module for adapter authors
+export type { RuntimePrimitives, AsyncContext } from './rpc.js';
+
 export type AdapterCoreOptions = {
 	port?: number;
 	hostname?: string;
@@ -70,8 +73,3 @@ export function get_static_cache_control(
 ): string;
 
 export function get_mime_type(pathname: string): string;
-
-export function serveStatic(
-	dir: string,
-	options?: ServeStaticOptions,
-): (request: Request) => Response | null;

package/types/rpc.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Async context abstraction — wraps platform-specific implementations
+ * (e.g., Node.js AsyncLocalStorage, Bun AsyncLocalStorage).
+ */
+export type AsyncContext<T = any> = {
+	/** Run a function with the given store value visible to getStore() */
+	run: <R>(store: T, fn: () => R | Promise<R>) => R | Promise<R>;
+	/** Get the current store value (undefined if outside a run() call) */
+	getStore: () => T | undefined;
+};
+
+/**
+ * Platform-specific runtime primitives provided by each adapter.
+ *
+ * These allow the shared server runtime to operate without depending
+ * on Node.js-specific APIs like `node:crypto` or `node:async_hooks`.
+ */
+export type RuntimePrimitives = {
+	/**
+	 * Hash a string for RPC function identification.
+	 *
+	 * Must produce the same output as the compiler's ServerBlock transform:
+	 * SHA-256 hex digest truncated to 8 characters.
+	 *
+	 * @param str - The string to hash (typically "filePath#funcName")
+	 * @returns The hash string (8 hex chars)
+	 */
+	hash: (str: string) => string;
+
+	/**
+	 * Create a request-scoped async context.
+	 *
+	 * Used to propagate the request origin through async call stacks
+	 * so that the patched `fetch` can resolve relative URLs.
+	 */
+	createAsyncContext: <T = any>() => AsyncContext<T>;
+};
+
+/**
+ * Entry in the RPC lookup table.
+ */
+export type RpcEntry = {
+	serverObj: Record<string, Function>;
+	funcName: string;
+};
+
+/**
+ * Options for handle_rpc_request.
+ */
+export type HandleRpcOptions = {
+	/** Resolve a hash to the server function to call */
+	resolveFunction: (hash: string) => Function | null | Promise<Function | null>;
+	/** Execute a resolved server function with the request body */
+	executeServerFunction: (fn: Function, body: string) => Promise<string>;
+	/** Request-scoped async context for fetch patching */
+	asyncContext: AsyncContext;
+	/** Whether to trust X-Forwarded-* headers */
+	trustProxy: boolean;
+};
+
+/**
+ * Derive the request origin (protocol + host) from a Web Request.
+ * Honors proxy headers only when trustProxy is true.
+ */
+export function derive_origin(request: Request, trust_proxy: boolean): string;
+
+/**
+ * Patch globalThis.fetch to resolve relative URLs using the async context.
+ * Returns a cleanup function that restores the original fetch.
+ */
+export function patch_global_fetch(async_context: AsyncContext): () => void;
+
+/**
+ * Build a hash → RpcEntry lookup from rpcModules.
+ */
+export function build_rpc_lookup(
+	rpc_modules: Record<string, Record<string, Function>>,
+	hash_fn: (str: string) => string,
+): Map<string, RpcEntry>;
+
+/**
+ * Check whether a URL pathname is an RPC request.
+ */
+export function is_rpc_request(pathname: string): boolean;
+
+/**
+ * Handle an RPC request. Platform-agnostic (Web Request/Response).
+ */
+export function handle_rpc_request(request: Request, options: HandleRpcOptions): Promise<Response>;
+
+export type RipplePatchedFetch = typeof globalThis.fetch & {
+	__ripple_patched?: boolean;
+};