@ripple-ts/adapter 0.2.208

package/README.md

@@ -0,0 +1,33 @@
+# @ripple-ts/adapter
+
+Shared adapter primitives for Ripple metaframework adapters.
+
+This package contains common runtime helpers and shared type contracts used by
+environment-specific adapters like:
+
+- `@ripple-ts/adapter-node`
+- `@ripple-ts/adapter-bun`
+
+## Exports
+
+- `DEFAULT_PORT`
+- `DEFAULT_HOSTNAME`
+- `internal_server_error_response()`
+- `run_next_middleware()`
+- `serveStatic()`
+- `MIME_TYPES`
+- `get_mime_type()`
+- `is_hashed_asset()`
+- `get_static_cache_control()`
+
+Type exports:
+
+- `FetchHandler`
+- `AdapterCoreOptions`
+- `NextMiddleware`
+- `ServeResult`
+- `ServeStaticOptions`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ripple-ts/adapter",
+  "description": "Shared adapter primitives for Ripple metaframework adapters",
+  "license": "MIT",
+  "author": "Dominic Gannaway",
+  "version": "0.2.208",
+  "type": "module",
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "pnpm -w test --project adapter"
+  },
+  "homepage": "https://ripplejs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ripple-TS/ripple.git",
+    "directory": "packages/adapter"
+  },
+  "bugs": {
+    "url": "https://github.com/Ripple-TS/ripple/issues"
+  }
+}

package/src/index.js

@@ -0,0 +1,202 @@
+// 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 = '/';
+export const DEFAULT_STATIC_MAX_AGE = 86400;
+
+/**
+ * Common MIME types for static files
+ * @type {Readonly<Record<string, string>>}
+ */
+export const MIME_TYPES = {
+	'.html': 'text/html; charset=utf-8',
+	'.css': 'text/css; charset=utf-8',
+	'.js': 'text/javascript; charset=utf-8',
+	'.mjs': 'text/javascript; charset=utf-8',
+	'.json': 'application/json; charset=utf-8',
+	'.png': 'image/png',
+	'.jpg': 'image/jpeg',
+	'.jpeg': 'image/jpeg',
+	'.gif': 'image/gif',
+	'.svg': 'image/svg+xml',
+	'.ico': 'image/x-icon',
+	'.woff': 'font/woff',
+	'.woff2': 'font/woff2',
+	'.ttf': 'font/ttf',
+	'.eot': 'application/vnd.ms-fontobject',
+	'.otf': 'font/otf',
+	'.webp': 'image/webp',
+	'.avif': 'image/avif',
+	'.mp4': 'video/mp4',
+	'.webm': 'video/webm',
+	'.mp3': 'audio/mpeg',
+	'.wav': 'audio/wav',
+	'.pdf': 'application/pdf',
+	'.txt': 'text/plain; charset=utf-8',
+	'.xml': 'application/xml',
+	'.wasm': 'application/wasm',
+};
+
+/**
+ * @returns {Response}
+ */
+export function internal_server_error_response() {
+	return new Response('Internal Server Error', {
+		status: 500,
+		headers: {
+			'content-type': 'text/plain; charset=utf-8',
+		},
+	});
+}
+
+/**
+ * @template RequestValue
+ * @template Server
+ * @template ResultValue
+ * @param {(request: RequestValue, server: Server, next: () => Promise<ResultValue>) => ResultValue | Promise<ResultValue> | void} middleware
+ * @param {RequestValue} request
+ * @param {Server} server
+ * @param {() => Promise<ResultValue>} next_handler
+ * @returns {Promise<ResultValue>}
+ */
+export async function run_next_middleware(middleware, request, server, next_handler) {
+	/** @type {Promise<ResultValue> | null} */
+	let next_promise = null;
+
+	const next = () => {
+		if (next_promise === null) {
+			next_promise = Promise.resolve().then(next_handler);
+		}
+		return next_promise;
+	};
+
+	const middleware_result = await middleware(request, server, next);
+	if (middleware_result !== undefined) {
+		return /** @type {ResultValue} */ (middleware_result);
+	}
+	if (next_promise !== null) {
+		return next_promise;
+	}
+	return await next_handler();
+}
+
+/**
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function is_hashed_asset(pathname) {
+	return pathname.includes('.') && /[a-f0-9]{8,}/.test(pathname);
+}
+
+/**
+ * @param {string} pathname
+ * @param {number} [max_age]
+ * @param {boolean} [immutable]
+ * @returns {string}
+ */
+export function get_static_cache_control(
+	pathname,
+	max_age = DEFAULT_STATIC_MAX_AGE,
+	immutable = false,
+) {
+	if (immutable || is_hashed_asset(pathname)) {
+		return 'public, max-age=31536000, immutable';
+	}
+
+	return `public, max-age=${max_age}`;
+}
+
+/**
+ * @param {string} pathname
+ * @returns {string}
+ */
+export function get_mime_type(pathname) {
+	const extension = extname(pathname).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/tests/index.test.js

@@ -0,0 +1,192 @@
+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,
+	get_mime_type,
+	get_static_cache_control,
+	internal_server_error_response,
+	is_hashed_asset,
+	run_next_middleware,
+	serveStatic,
+} from '../src/index.js';
+
+describe('@ripple-ts/adapter', () => {
+	it('exports stable default host and port', () => {
+		expect(DEFAULT_PORT).toBe(3000);
+		expect(DEFAULT_HOSTNAME).toBe('localhost');
+	});
+
+	it('creates standardized internal server error response', async () => {
+		const response = internal_server_error_response();
+		expect(response.status).toBe(500);
+		expect(response.headers.get('content-type')).toBe('text/plain; charset=utf-8');
+		expect(await response.text()).toBe('Internal Server Error');
+	});
+
+	it('run_next_middleware returns middleware response when short-circuited', async () => {
+		const response = await run_next_middleware(
+			() => new Response('middleware'),
+			new Request('http://localhost/'),
+			{ id: 'server' },
+			async () => new Response('handler'),
+		);
+
+		expect(await response.text()).toBe('middleware');
+	});
+
+	it('run_next_middleware resolves next() only once and returns handler response', async () => {
+		let handler_calls = 0;
+
+		const response = await run_next_middleware(
+			async (request, server, next) => {
+				void request;
+				void server;
+				await next();
+				return await next();
+			},
+			new Request('http://localhost/'),
+			{ id: 'server' },
+			async () => {
+				handler_calls += 1;
+				return new Response('handler');
+			},
+		);
+
+		expect(handler_calls).toBe(1);
+		expect(await response.text()).toBe('handler');
+	});
+
+	it('run_next_middleware falls through to next handler when middleware returns void', async () => {
+		const response = await run_next_middleware(
+			() => {},
+			new Request('http://localhost/'),
+			{ id: 'server' },
+			async () => new Response('handler'),
+		);
+
+		expect(await response.text()).toBe('handler');
+	});
+
+	it('run_next_middleware supports non-Response result types', async () => {
+		const value = await run_next_middleware(
+			() => 'middleware-value',
+			{ request: 1 },
+			{ id: 'server' },
+			async () => 'handler-value',
+		);
+
+		expect(value).toBe('middleware-value');
+	});
+
+	it('resolves MIME types with fallback', () => {
+		expect(get_mime_type('app.js')).toBe('text/javascript; charset=utf-8');
+		expect(get_mime_type('image.svg')).toBe('image/svg+xml');
+		expect(get_mime_type('file.unknown')).toBe('application/octet-stream');
+	});
+
+	it('detects hashed assets and computes cache-control', () => {
+		expect(is_hashed_asset('/assets/app.2f1abce9.js')).toBe(true);
+		expect(is_hashed_asset('/assets/app.js')).toBe(false);
+		expect(get_static_cache_control('/assets/app.2f1abce9.js')).toBe(
+			'public, max-age=31536000, immutable',
+		);
+		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/tests/types.test.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const types_source = readFileSync(new URL('../types/index.d.ts', import.meta.url), 'utf8');
+
+describe('@ripple-ts/adapter types', () => {
+	it('exports ServeStaticOptions with cache-control fields', () => {
+		expect(types_source).toMatch(
+			/export type ServeStaticOptions = \{[\s\S]*?prefix\?: string;[\s\S]*?maxAge\?: number;[\s\S]*?immutable\?: boolean;[\s\S]*?\};/,
+		);
+	});
+
+	it('exports ServeStaticDirectoryOptions with shared dir field', () => {
+		expect(types_source).toMatch(
+			/export type ServeStaticDirectoryOptions = ServeStaticOptions & \{[\s\S]*?dir\?: string;[\s\S]*?\};/,
+		);
+	});
+});

package/types/index.d.ts

@@ -0,0 +1,60 @@
+export type FetchHandler<Platform = any, ResultValue = Response> = (
+	request: Request,
+	platform?: Platform,
+) => ResultValue | Promise<ResultValue>;
+
+export type AdapterCoreOptions = {
+	port?: number;
+	hostname?: string;
+};
+
+export type ServeStaticOptions = {
+	prefix?: string;
+	maxAge?: number;
+	immutable?: boolean;
+};
+
+export type ServeStaticDirectoryOptions = ServeStaticOptions & {
+	dir?: string;
+};
+
+export type NextMiddleware<RequestValue = Request, Server = any, ResultValue = Response> = (
+	request: RequestValue,
+	server: Server,
+	next: () => Promise<ResultValue>,
+) => ResultValue | Promise<ResultValue> | void;
+
+export type ServeResult<Server = any> = {
+	listen: (port?: number) => Server;
+	close: () => void;
+};
+
+export const DEFAULT_HOSTNAME: 'localhost';
+export const DEFAULT_PORT: 3000;
+export const DEFAULT_STATIC_PREFIX: '/';
+export const DEFAULT_STATIC_MAX_AGE: 86400;
+export const MIME_TYPES: Readonly<Record<string, string>>;
+
+export function internal_server_error_response(): Response;
+
+export function run_next_middleware<RequestValue, Server, ResultValue = Response>(
+	middleware: NextMiddleware<RequestValue, Server, ResultValue>,
+	request: RequestValue,
+	server: Server,
+	next_handler: () => Promise<ResultValue>,
+): Promise<ResultValue>;
+
+export function is_hashed_asset(pathname: string): boolean;
+
+export function get_static_cache_control(
+	pathname: string,
+	max_age?: number,
+	immutable?: boolean,
+): string;
+
+export function get_mime_type(pathname: string): string;
+
+export function serveStatic(
+	dir: string,
+	options?: ServeStaticOptions,
+): (request: Request) => Response | null;