@selvajs/server 0.2.0-beta.1

package/src/compute/__tests__/client-cache.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Tests for `createClientCache` — the per-server warm-client LRU.
+ *
+ * `@selvajs/compute`'s `GrasshopperClient.create` does a real network preflight,
+ * so we mock the module: `create` records the config it was called with and
+ * returns a fake client whose `createScheduler` returns a disposable stub. That
+ * lets us assert the cache's own behavior (id-keying, LRU eviction, evict,
+ * disposeAll, the `X-Selva-Definition` header) without a live compute server.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// --- Mock @selvajs/compute -------------------------------------------------
+const createdConfigs: any[] = [];
+const disposedSchedulers: any[] = [];
+
+vi.mock('@selvajs/compute', () => {
+	class GrasshopperClient {
+		static async create(config: any) {
+			createdConfigs.push(config);
+			return new GrasshopperClient(config);
+		}
+		constructor(public config: any) {}
+		createScheduler() {
+			const scheduler = {
+				disposed: false,
+				dispose() {
+					this.disposed = true;
+					disposedSchedulers.push(this);
+				}
+			};
+			return scheduler;
+		}
+	}
+	return { GrasshopperClient, enableDebugLogging: vi.fn() };
+});
+
+import { createClientCache, serverIdentity } from '../client-cache.js';
+
+function baseConfig() {
+	return {
+		maxSolveDurationMs: 30_000,
+		cachesolve: true,
+		cacheerroredsolves: false,
+		reuseServerDefinitionCache: true,
+		debug: false,
+		debugVerbose: false
+	};
+}
+
+const server = (id: string, over: Partial<{ serverUrl: string; apiKey: string }> = {}) => ({
+	id,
+	serverUrl: over.serverUrl ?? `http://compute-${id}:6500`,
+	apiKey: over.apiKey ?? `key-${id}`
+});
+
+beforeEach(() => {
+	createdConfigs.length = 0;
+	disposedSchedulers.length = 0;
+});
+
+describe('createClientCache — keying', () => {
+	it('keys on id: two calls for the same id build one client', async () => {
+		const cache = createClientCache(baseConfig());
+		const a = await cache.getClient(server('s1'));
+		const b = await cache.getClient(server('s1'));
+		expect(a).toBe(b);
+		expect(createdConfigs).toHaveLength(1);
+	});
+
+	it('reuses the entry even when the URL/apiKey rotate under the same id', async () => {
+		// The whole point of ADR 0004 D1: identity is the id, so a rotated URL is
+		// the SAME entry (stale until evicted) — not a new client.
+		const cache = createClientCache(baseConfig());
+		const a = await cache.getClient(server('s1', { serverUrl: 'http://old:6500' }));
+		const b = await cache.getClient(server('s1', { serverUrl: 'http://new:6500' }));
+		expect(a).toBe(b);
+		expect(createdConfigs).toHaveLength(1);
+		// It kept the ORIGINAL connection details — proving eviction is required.
+		expect(createdConfigs[0].serverUrl).toBe('http://old:6500');
+	});
+
+	it('builds distinct clients for distinct ids', async () => {
+		const cache = createClientCache(baseConfig());
+		const a = await cache.getClient(server('s1'));
+		const b = await cache.getClient(server('s2'));
+		expect(a).not.toBe(b);
+		expect(createdConfigs).toHaveLength(2);
+	});
+});
+
+describe('createClientCache — LRU eviction', () => {
+	it('evicts the least-recently-used entry past capacity and disposes its scheduler', async () => {
+		const cache = createClientCache({ ...baseConfig(), maxCachedClients: 2 });
+		const s1 = await cache.getClient(server('s1'));
+		await cache.getClient(server('s2'));
+		// Touch s1 so s2 becomes the LRU.
+		await cache.getClient(server('s1'));
+		await cache.getClient(server('s3')); // over capacity → evict s2
+
+		expect(disposedSchedulers).toHaveLength(1);
+		// s1 still warm (same entry, no rebuild); s2 rebuilt on next access.
+		expect(await cache.getClient(server('s1'))).toBe(s1);
+		expect(createdConfigs.filter((c) => c.serverUrl.includes('s2'))).toHaveLength(1);
+		await cache.getClient(server('s2'));
+		expect(createdConfigs.filter((c) => c.serverUrl.includes('s2'))).toHaveLength(2);
+	});
+});
+
+describe('createClientCache — explicit invalidation', () => {
+	it('evict(id) disposes the scheduler and forces a rebuild (config-write hook)', async () => {
+		const cache = createClientCache(baseConfig());
+		await cache.getClient(server('s1'));
+		cache.evict('s1');
+		expect(disposedSchedulers).toHaveLength(1);
+		await cache.getClient(server('s1'));
+		expect(createdConfigs).toHaveLength(2);
+	});
+
+	it('evict accepts a ServerIdentity', async () => {
+		const cache = createClientCache(baseConfig());
+		await cache.getClient(server('s1'));
+		cache.evict(serverIdentity({ id: 's1' }));
+		expect(disposedSchedulers).toHaveLength(1);
+	});
+
+	it('evict on an unknown id is a no-op', async () => {
+		const cache = createClientCache(baseConfig());
+		await cache.getClient(server('s1'));
+		cache.evict('nope');
+		expect(disposedSchedulers).toHaveLength(0);
+	});
+
+	it('disposeAll disposes every warm scheduler and clears the cache', async () => {
+		const cache = createClientCache(baseConfig());
+		await cache.getClient(server('s1'));
+		await cache.getClient(server('s2'));
+		cache.disposeAll();
+		expect(disposedSchedulers).toHaveLength(2);
+		// Next access rebuilds.
+		await cache.getClient(server('s1'));
+		expect(createdConfigs).toHaveLength(3);
+	});
+});
+
+describe('createClientCache — X-Selva-Definition (ADR 0004 D2)', () => {
+	it('stamps the definition guid on the client headers when provided', async () => {
+		const cache = createClientCache(baseConfig());
+		await cache.getClient(server('s1'), { definitionGuid: 'guid-123' });
+		expect(createdConfigs[0].headers).toEqual({ 'X-Selva-Definition': 'guid-123' });
+	});
+
+	it('omits the header entirely when no guid is given', async () => {
+		const cache = createClientCache(baseConfig());
+		await cache.getClient(server('s1'));
+		expect(createdConfigs[0].headers).toBeUndefined();
+	});
+});
+
+describe('serverIdentity', () => {
+	it('derives identity from the id', () => {
+		expect(serverIdentity({ id: 'abc' })).toBe('abc');
+	});
+});

package/src/compute/__tests__/rate-limit.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createComputeRateLimiter, type ComputeRateLimiter } from '../rate-limit.js';
+
+const WINDOW_MS = 100_000;
+const MAX_PER_WINDOW = 120;
+
+describe('createComputeRateLimiter', () => {
+	let limiter: ComputeRateLimiter;
+
+	beforeEach(() => {
+		limiter = createComputeRateLimiter({ windowMs: WINDOW_MS, maxPerWindow: MAX_PER_WINDOW });
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it('allows up to maxPerWindow requests in the window', () => {
+		for (let i = 0; i < MAX_PER_WINDOW; i++) {
+			expect(limiter.check('user:alice').allowed).toBe(true);
+		}
+	});
+
+	it('rejects the (MAX+1)th request with retryAfter set', () => {
+		for (let i = 0; i < MAX_PER_WINDOW; i++) limiter.check('user:alice');
+		const result = limiter.check('user:alice');
+		expect(result.allowed).toBe(false);
+		expect(result.retryAfter).toBeGreaterThan(0);
+		expect(result.retryAfter).toBeLessThanOrEqual(WINDOW_MS / 1000);
+	});
+
+	it('isolates buckets per key', () => {
+		for (let i = 0; i < MAX_PER_WINDOW; i++) limiter.check('user:alice');
+		expect(limiter.check('user:alice').allowed).toBe(false);
+		expect(limiter.check('user:bob').allowed).toBe(true);
+	});
+
+	it("share-link buckets don't collide with user buckets sharing an id", () => {
+		const id = '00000000-0000-0000-0000-000000000001';
+		for (let i = 0; i < MAX_PER_WINDOW; i++) limiter.check(`share:${id}`);
+		expect(limiter.check(`share:${id}`).allowed).toBe(false);
+		expect(limiter.check(`user:${id}`).allowed).toBe(true);
+	});
+
+	it('rolls over when the window expires', () => {
+		for (let i = 0; i < MAX_PER_WINDOW; i++) limiter.check('user:alice');
+		expect(limiter.check('user:alice').allowed).toBe(false);
+
+		vi.advanceTimersByTime(WINDOW_MS + 1);
+
+		expect(limiter.check('user:alice').allowed).toBe(true);
+	});
+
+	it('does not pre-increment a fresh bucket past the cap', () => {
+		// Regression guard: an off-by-one in the "no entry yet" branch could
+		// initialize at count=1 but treat the FIRST call as already capped.
+		expect(limiter.check('user:fresh').allowed).toBe(true);
+	});
+
+	it('separate limiters own separate bucket state', () => {
+		const other = createComputeRateLimiter({ windowMs: WINDOW_MS, maxPerWindow: MAX_PER_WINDOW });
+		for (let i = 0; i < MAX_PER_WINDOW; i++) limiter.check('user:alice');
+		expect(limiter.check('user:alice').allowed).toBe(false);
+		// A different limiter instance is unaffected.
+		expect(other.check('user:alice').allowed).toBe(true);
+	});
+});

package/src/compute/__tests__/remote-definition.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Tests for `createRemoteDefinitionFetcher` — the SSRF-guarded, capped, TTL-cached
+ * remote `.gh` fetch (K3).
+ *
+ * `safe-url` is mocked so the host check is a controllable pass/fail (its own
+ * SSRF logic is covered in safe-url.test.ts), and `fetch` is stubbed per test to
+ * return scripted bodies/headers. The injected `now` clock makes the TTL cache
+ * deterministic without real time.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// --- Mock the SSRF guard ---------------------------------------------------
+const assertSafe = vi.fn(async (_url: string) => {});
+vi.mock('../safe-url.js', () => ({
+	assertSafeRemoteDefinitionUrl: (url: string) => assertSafe(url)
+}));
+
+import { createRemoteDefinitionFetcher, readBodyWithCap } from '../index.js';
+
+/** A Response whose body streams the given bytes in one chunk. */
+function streamResponse(bytes: Uint8Array, init: { contentLength?: string | null } = {}): Response {
+	const body = new ReadableStream<Uint8Array>({
+		start(controller) {
+			controller.enqueue(bytes);
+			controller.close();
+		}
+	});
+	const headers = new Headers();
+	if (init.contentLength !== null && init.contentLength !== undefined) {
+		headers.set('content-length', init.contentLength);
+	}
+	return new Response(body, { status: 200, headers });
+}
+
+const baseConfig = () => ({
+	maxBytes: 1024,
+	fetchTimeoutMs: 5_000,
+	cacheTtlMs: 60_000,
+	now: () => 1_000
+});
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+	assertSafe.mockClear();
+	assertSafe.mockResolvedValue(undefined);
+	fetchMock = vi.fn();
+	vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+});
+
+describe('createRemoteDefinitionFetcher — happy path', () => {
+	it('runs the SSRF guard and returns the fetched bytes', async () => {
+		const bytes = new Uint8Array([9, 8, 7]);
+		fetchMock.mockResolvedValue(streamResponse(bytes, { contentLength: '3' }));
+		const fetcher = createRemoteDefinitionFetcher(baseConfig());
+
+		const out = await fetcher.load('https://example.com/def.gh');
+		expect(out).toEqual(bytes);
+		expect(assertSafe).toHaveBeenCalledWith('https://example.com/def.gh');
+		expect(fetchMock).toHaveBeenCalledWith(
+			'https://example.com/def.gh',
+			expect.objectContaining({ redirect: 'error' })
+		);
+	});
+
+	it('caches within TTL (one fetch) and refetches after TTL expires', async () => {
+		const bytes = new Uint8Array([1]);
+		// Fresh Response per call — a stream body can only be read once.
+		fetchMock.mockImplementation(async () => streamResponse(bytes, { contentLength: '1' }));
+		let clock = 1_000;
+		const fetcher = createRemoteDefinitionFetcher({ ...baseConfig(), now: () => clock });
+
+		await fetcher.load('https://example.com/a.gh');
+		await fetcher.load('https://example.com/a.gh'); // within TTL → cached
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+
+		clock += 60_001; // past the 60s TTL
+		await fetcher.load('https://example.com/a.gh');
+		expect(fetchMock).toHaveBeenCalledTimes(2);
+	});
+});
+
+describe('createRemoteDefinitionFetcher — rejections', () => {
+	it('does not fetch when the SSRF guard rejects', async () => {
+		assertSafe.mockRejectedValue(new Error('blocked private host'));
+		const fetcher = createRemoteDefinitionFetcher(baseConfig());
+		await expect(fetcher.load('http://169.254.169.254/')).rejects.toThrow('blocked private host');
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it('throws on a non-2xx response', async () => {
+		fetchMock.mockResolvedValue(new Response('nope', { status: 404, statusText: 'Not Found' }));
+		const fetcher = createRemoteDefinitionFetcher(baseConfig());
+		await expect(fetcher.load('https://example.com/missing.gh')).rejects.toThrow('HTTP 404');
+	});
+
+	it('rejects early when the declared content-length exceeds the cap', async () => {
+		fetchMock.mockResolvedValue(streamResponse(new Uint8Array([1, 2]), { contentLength: '99999' }));
+		const fetcher = createRemoteDefinitionFetcher({ ...baseConfig(), maxBytes: 10 });
+		await expect(fetcher.load('https://example.com/big.gh')).rejects.toThrow('exceeds size limit');
+	});
+
+	it('rejects when the streamed body exceeds the cap despite a missing content-length', async () => {
+		// No content-length header — the streaming cap must still catch it.
+		fetchMock.mockResolvedValue(streamResponse(new Uint8Array(50), { contentLength: null }));
+		const fetcher = createRemoteDefinitionFetcher({ ...baseConfig(), maxBytes: 10 });
+		await expect(fetcher.load('https://example.com/lying.gh')).rejects.toThrow(
+			'exceeds size limit'
+		);
+	});
+});
+
+describe('readBodyWithCap', () => {
+	it('reads a streamed body under the cap', async () => {
+		const bytes = new Uint8Array([1, 2, 3, 4]);
+		const out = await readBodyWithCap(streamResponse(bytes), 10, new AbortController());
+		expect(out).toEqual(bytes);
+	});
+
+	it('aborts and throws once the running total crosses the cap', async () => {
+		const controller = new AbortController();
+		await expect(
+			readBodyWithCap(streamResponse(new Uint8Array(20)), 5, controller)
+		).rejects.toThrow('exceeds size limit');
+		expect(controller.signal.aborted).toBe(true);
+	});
+
+	it('falls back to arrayBuffer when there is no stream body', async () => {
+		// A Response built from a string still exposes a body stream in undici, so
+		// construct one without a body to hit the fallback branch.
+		const noBody = new Response(null, { status: 200 });
+		const out = await readBodyWithCap(noBody, 10, new AbortController());
+		expect(out).toEqual(new Uint8Array(0));
+	});
+});

package/src/compute/__tests__/safe-url.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { isSafeRemoteDefinitionUrl } from '../safe-url.js';
+
+/**
+ * SSRF guard for `loadRemoteDefinition`. Each rejection row corresponds to
+ * an attack the helper exists to block — leaving any of them unsuppressed
+ * would let an authenticated user have the server fetch arbitrary
+ * intranet/cloud-metadata/loopback hosts on their behalf.
+ *
+ * Hostname-only — DNS rebinding is not addressed here. See the helper's
+ * file-level comment.
+ */
+describe('isSafeRemoteDefinitionUrl', () => {
+	it.each([
+		'https://example.com/foo.gh',
+		'http://example.com/foo.gh',
+		'https://cdn.example.com:443/path/to/file.ghx',
+		'https://1.2.3.4/file.gh',
+		// 172.32 is outside the 172.16-31 private range — must be allowed.
+		'https://172.32.0.1/file.gh',
+		// Edge of the private /16 — 192.169 is public.
+		'https://192.169.0.1/file.gh'
+	])('accepts public URL %j', (url) => {
+		expect(isSafeRemoteDefinitionUrl(url)).toBe(true);
+	});
+
+	it.each([
+		// Loopback
+		['http://localhost/foo', 'localhost'],
+		['http://localhost:8080/foo', 'localhost with port'],
+		['http://api.localhost/foo', '*.localhost'],
+		['http://127.0.0.1/foo', '127.0.0.1'],
+		['http://127.0.0.5/foo', '127/8'],
+		['http://0.0.0.0/foo', '0.0.0.0'],
+		['http://[::1]/foo', 'IPv6 loopback'],
+		// Cloud metadata service — the canonical reason this guard exists.
+		['http://169.254.169.254/latest/meta-data/', 'AWS/GCP/Azure metadata'],
+		['http://169.254.0.1/foo', '169.254/16 link-local'],
+		// IPv4 RFC1918 private ranges
+		['http://10.0.0.1/foo', '10/8'],
+		['http://10.255.255.255/foo', '10/8 upper'],
+		['http://192.168.0.1/foo', '192.168/16'],
+		['http://172.16.0.1/foo', '172.16 lower bound'],
+		['http://172.31.255.255/foo', '172.31 upper bound'],
+		['http://172.20.0.1/foo', '172.20 mid-range'],
+		// IPv6 unique-local + link-local
+		['http://[fc00::1]/foo', 'IPv6 unique-local fc'],
+		['http://[fd12:3456::1]/foo', 'IPv6 unique-local fd'],
+		['http://[fe80::1]/foo', 'IPv6 link-local'],
+		// IPv4-mapped IPv6 — must unwrap and apply the v4 rules.
+		['http://[::ffff:127.0.0.1]/foo', 'IPv4-mapped loopback'],
+		['http://[::ffff:169.254.169.254]/foo', 'IPv4-mapped metadata'],
+		['http://[::ffff:10.0.0.1]/foo', 'IPv4-mapped RFC1918'],
+		// Alternate IPv4 encodings that glibc/inet_aton resolve to loopback.
+		['http://2130706433/foo', 'integer loopback'],
+		['http://0x7f000001/foo', 'hex loopback'],
+		['http://0177.0.0.1/foo', 'octal loopback'],
+		['http://127.1/foo', 'short-form loopback'],
+		['http://0/foo', 'integer 0.0.0.0'],
+		// Alternate encodings of the cloud-metadata address.
+		['http://2852039166/foo', 'integer metadata 169.254.169.254'],
+		// Non-http(s) schemes
+		['file:///etc/passwd', 'file scheme'],
+		['gopher://evil/', 'gopher scheme'],
+		['javascript:alert(1)', 'javascript scheme'],
+		// Malformed
+		['not a url', 'unparseable'],
+		['', 'empty']
+	])('rejects %j (%s)', (url) => {
+		expect(isSafeRemoteDefinitionUrl(url)).toBe(false);
+	});
+});