@selvajs/server 0.2.0-beta.1 → 0.2.0-beta.3

package/src/access/index.ts

@@ -0,0 +1,9 @@
+// Access-rule input assembly — marshals providers + flags into what
+// platform's pure canView/canEdit/… rules consume.
+
+export {
+	createProjectAccessInputBuilder,
+	type ProjectAccessFlags,
+	type ProjectAccessInputBuilder,
+	type ProjectAccessInputDeps
+} from './project-access-input.js';

package/src/access/project-access-input.ts

@@ -0,0 +1,145 @@
+import type { Project, ProjectAccessInput, RequestContext } from '@selvajs/platform';
+
+/**
+ * Assembly of `ProjectAccessInput` — the marshalling layer between an app's
+ * providers and platform's pure access rules (`canView`/`canEdit`/`canSolve`/
+ * `canManage`/…). The rules are pure functions over one input shape; the
+ * knowledge captured here is **which rows each project visibility needs**, so
+ * a consuming app doesn't reimplement (and mis-fetch) it:
+ *
+ * - `platform` → grants (skipped entirely while the feature flag is off)
+ * - `private`  → caller's project member row
+ * - `org` / `public` → caller's project member row (for canEdit/canManage) and
+ *   org member row (for canView). Cross-org public skips the org row.
+ *
+ * Wiring is injected: row lookups as functions (so lazily-initialized
+ * providers work unchanged) and flags read per call (so runtime flag flips
+ * behave like the app's own `flag()` reads).
+ */
+
+export interface ProjectAccessFlags {
+	/** `ALLOW_CROSS_ORG_PUBLIC` — public visibility spans orgs when true. */
+	allowCrossOrgPublic: boolean;
+	/** `ENABLE_PLATFORM_PROJECTS` — platform visibility is live when true. */
+	enablePlatformProjects: boolean;
+}
+
+export interface ProjectAccessInputDeps {
+	getProjectMember(
+		ctx: RequestContext,
+		projectId: string,
+		userId: string
+	): Promise<ProjectAccessInput['member']>;
+	getOrgMember(
+		ctx: RequestContext,
+		orgId: string,
+		userId: string
+	): Promise<ProjectAccessInput['orgMember']>;
+	listPlatformGrants(
+		ctx: RequestContext,
+		projectId: string
+	): Promise<ProjectAccessInput['platformGrants']>;
+	/** Read the two access-relevant feature flags. Called once per assembly. */
+	flags(): ProjectAccessFlags;
+}
+
+export interface ProjectAccessInputBuilder {
+	/**
+	 * Build the rule input for any project-scope rule, fetching exactly the
+	 * rows the rule will consult based on `project.visibility`. Other fields
+	 * default to safe values; pass `overrides` for the rare callers that
+	 * already loaded a row (e.g. tests, batched listing pages).
+	 */
+	buildProjectAccessInput(
+		ctx: RequestContext,
+		project: Project,
+		overrides?: Partial<ProjectAccessInput>
+	): Promise<ProjectAccessInput>;
+	/**
+	 * Build a `ProjectAccessInput` from caller-provided rows without any I/O.
+	 * Used by listing pages that have already batch-loaded membership for many
+	 * projects; the per-row predicate calls this instead of
+	 * `buildProjectAccessInput` to avoid an N+1 fetch.
+	 */
+	projectAccessInputFromRows(
+		ctx: RequestContext,
+		project: Project,
+		rows: {
+			member?: ProjectAccessInput['member'];
+			orgMember?: ProjectAccessInput['orgMember'];
+			platformGrants?: ProjectAccessInput['platformGrants'];
+		}
+	): ProjectAccessInput;
+}
+
+export function createProjectAccessInputBuilder(
+	deps: ProjectAccessInputDeps
+): ProjectAccessInputBuilder {
+	return {
+		async buildProjectAccessInput(
+			ctx: RequestContext,
+			project: Project,
+			overrides: Partial<ProjectAccessInput> = {}
+		): Promise<ProjectAccessInput> {
+			const { allowCrossOrgPublic, enablePlatformProjects } = deps.flags();
+
+			let member: ProjectAccessInput['member'] = null;
+			let orgMember: ProjectAccessInput['orgMember'] = null;
+			let platformGrants: ProjectAccessInput['platformGrants'] = [];
+
+			if (project.visibility === 'platform') {
+				// When the flag is off the rule short-circuits before reading grants —
+				// skip the lookup to keep "feature disabled" cheap.
+				if (enablePlatformProjects) {
+					platformGrants = await deps.listPlatformGrants(ctx, project.id);
+				}
+			} else if (project.visibility === 'private') {
+				member = await deps.getProjectMember(ctx, project.id, ctx.userId);
+			} else {
+				const skipOrgMember = project.visibility === 'public' && allowCrossOrgPublic;
+				[member, orgMember] = await Promise.all([
+					deps.getProjectMember(ctx, project.id, ctx.userId),
+					skipOrgMember ? Promise.resolve(null) : deps.getOrgMember(ctx, project.orgId, ctx.userId)
+				]);
+			}
+
+			return {
+				orgPermissions: ctx.orgPermissions,
+				platformPermissions: ctx.platformPermissions,
+				project,
+				member,
+				orgMember,
+				allowCrossOrgPublic,
+				enablePlatformProjects,
+				platformGrants,
+				actingOrgId: ctx.actingOrgId ?? null,
+				userId: ctx.userId,
+				...overrides
+			};
+		},
+
+		projectAccessInputFromRows(
+			ctx: RequestContext,
+			project: Project,
+			rows: {
+				member?: ProjectAccessInput['member'];
+				orgMember?: ProjectAccessInput['orgMember'];
+				platformGrants?: ProjectAccessInput['platformGrants'];
+			}
+		): ProjectAccessInput {
+			const { allowCrossOrgPublic, enablePlatformProjects } = deps.flags();
+			return {
+				orgPermissions: ctx.orgPermissions,
+				platformPermissions: ctx.platformPermissions,
+				project,
+				member: rows.member ?? null,
+				orgMember: rows.orgMember ?? null,
+				allowCrossOrgPublic,
+				enablePlatformProjects,
+				platformGrants: rows.platformGrants ?? [],
+				actingOrgId: ctx.actingOrgId ?? null,
+				userId: ctx.userId
+			};
+		}
+	};
+}

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

@@ -12,6 +12,7 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 
 // --- Mock @selvajs/compute -------------------------------------------------
 const createdConfigs: any[] = [];
+const createdSchedulerOptions: any[] = [];
 const disposedSchedulers: any[] = [];
 
 vi.mock('@selvajs/compute', () => {
@@ -21,7 +22,8 @@ vi.mock('@selvajs/compute', () => {
 			return new GrasshopperClient(config);
 		}
 		constructor(public config: any) {}
-		createScheduler() {
+		createScheduler(options: any) {
+			createdSchedulerOptions.push(options);
 			const scheduler = {
 				disposed: false,
 				dispose() {
@@ -40,6 +42,9 @@ import { createClientCache, serverIdentity } from '../client-cache.js';
 function baseConfig() {
 	return {
 		maxSolveDurationMs: 30_000,
+		maxConcurrentSolves: 4,
+		maxQueueDepth: 0,
+		queueWaitMs: 0,
 		cachesolve: true,
 		cacheerroredsolves: false,
 		reuseServerDefinitionCache: true,
@@ -56,6 +61,7 @@ const server = (id: string, over: Partial<{ serverUrl: string; apiKey: string }>
 
 beforeEach(() => {
 	createdConfigs.length = 0;
+	createdSchedulerOptions.length = 0;
 	disposedSchedulers.length = 0;
 });
 
@@ -157,6 +163,80 @@ describe('createClientCache — X-Selva-Definition (ADR 0004 D2)', () => {
 	});
 });
 
+describe('createClientCache — scheduler concurrency (audit B6)', () => {
+	it('forwards maxConcurrentSolves as the scheduler maxConcurrent in queue mode', async () => {
+		const cache = createClientCache({ ...baseConfig(), maxConcurrentSolves: 7 });
+		await cache.getClient(server('s1'));
+		expect(createdSchedulerOptions).toHaveLength(1);
+		// Queue mode with NO maxConcurrent defaults to 1 in the scheduler,
+		// serializing every solve on the server — the option must always be set.
+		expect(createdSchedulerOptions[0].mode).toBe('queue');
+		expect(createdSchedulerOptions[0].maxConcurrent).toBe(7);
+	});
+});
+
+describe('createClientCache — scheduler backpressure (audit B7)', () => {
+	it('forwards non-zero queue bounds to the scheduler', async () => {
+		const cache = createClientCache({ ...baseConfig(), maxQueueDepth: 12, queueWaitMs: 90_000 });
+		await cache.getClient(server('s1'));
+		expect(createdSchedulerOptions[0].maxQueueDepth).toBe(12);
+		expect(createdSchedulerOptions[0].queueWaitMs).toBe(90_000);
+	});
+
+	it('maps a 0 (disabled) queue bound to undefined so the scheduler stays unbounded', async () => {
+		// The scheduler treats undefined as unbounded/no-deadline; passing 0 would
+		// shed EVERY queued solve. Our `0 = off` convention must become undefined.
+		const cache = createClientCache({ ...baseConfig(), maxQueueDepth: 0, queueWaitMs: 0 });
+		await cache.getClient(server('s1'));
+		expect(createdSchedulerOptions[0].maxQueueDepth).toBeUndefined();
+		expect(createdSchedulerOptions[0].queueWaitMs).toBeUndefined();
+	});
+});
+
+describe('createClientCache — per-request telemetry sequence counters', () => {
+	it('onServerTiming bumps rhinoTiming.seq on every write', async () => {
+		const cache = createClientCache(baseConfig());
+		const entry = await cache.getClient(server('s1'));
+		expect(entry.rhinoTiming).toEqual({ last: null, seq: 0 });
+		createdConfigs[0].onServerTiming({ decode: 5, solve: 100, encode: 3 });
+		expect(entry.rhinoTiming.seq).toBe(1);
+		expect(entry.rhinoTiming.last).toEqual({ decode: 5, solve: 100, encode: 3 });
+		createdConfigs[0].onServerTiming({ decode: 1, solve: 2, encode: 3 });
+		expect(entry.rhinoTiming.seq).toBe(2);
+		expect(entry.rhinoTiming.last).toEqual({ decode: 1, solve: 2, encode: 3 });
+	});
+
+	it('onSettle bumps solveMeta.seq on every settle but writes last only on success', async () => {
+		const cache = createClientCache(baseConfig());
+		const entry = await cache.getClient(server('s1'));
+		const onSettle = createdSchedulerOptions[0].onSettle;
+		expect(entry.solveMeta).toEqual({ last: null, seq: 0 });
+
+		onSettle(
+			{ key: 'k' },
+			{
+				status: 'success',
+				fromCache: false,
+				definitionReuploaded: false,
+				durationMs: 10,
+				response: {}
+			}
+		);
+		expect(entry.solveMeta.seq).toBe(1);
+		expect(entry.solveMeta.last).toEqual({ fromCache: false, definitionReuploaded: false });
+
+		// An error settle must still count toward seq (the attribution guard in
+		// the pipeline needs to see ALL concurrent activity) without clobbering last.
+		onSettle({ key: 'k' }, { status: 'error', error: new Error('x'), durationMs: 5 });
+		expect(entry.solveMeta.seq).toBe(2);
+		expect(entry.solveMeta.last).toEqual({ fromCache: false, definitionReuploaded: false });
+
+		onSettle({ key: 'k' }, { status: 'success', fromCache: true, durationMs: 0, response: {} });
+		expect(entry.solveMeta.seq).toBe(3);
+		expect(entry.solveMeta.last).toEqual({ fromCache: true, definitionReuploaded: undefined });
+	});
+});
+
 describe('serverIdentity', () => {
 	it('derives identity from the id', () => {
 		expect(serverIdentity({ id: 'abc' })).toBe('abc');

package/src/compute/__tests__/definition-byte-cache.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createDefinitionByteCache } from '../definition-byte-cache.js';
+
+/** A `Uint8Array` of `n` bytes filled with a marker so equality is checkable. */
+function bytes(n: number, marker = 0): Uint8Array {
+	return new Uint8Array(n).fill(marker);
+}
+
+describe('createDefinitionByteCache', () => {
+	it('serves a warm entry without re-invoking the loader (hit) and reports it', async () => {
+		const cache = createDefinitionByteCache(10 * 1024 * 1024);
+		const load = vi.fn(async () => bytes(1024, 7));
+
+		const first = await cache.getOrLoad('v-1', load).load();
+		const second = await cache.getOrLoad('v-1', load).load();
+
+		expect(first).toEqual(second);
+		expect(load).toHaveBeenCalledTimes(1); // second call served from cache
+		const s = cache.stats();
+		expect(s.hits).toBe(1);
+		expect(s.misses).toBe(1);
+		expect(s.entries).toBe(1);
+		expect(s.bytes).toBe(1024);
+	});
+
+	it('per-ref outcome distinguishes miss (loader) from hit (warm)', async () => {
+		const cache = createDefinitionByteCache(10 * 1024 * 1024);
+		const load = async () => bytes(512);
+
+		const refMiss = cache.getOrLoad('v-1', load);
+		await refMiss.load();
+		expect(refMiss.outcome).toEqual({ loaded: true, fromCache: false });
+
+		const refHit = cache.getOrLoad('v-1', load);
+		await refHit.load();
+		expect(refHit.outcome).toEqual({ loaded: true, fromCache: true });
+	});
+
+	it("a ref whose load() is never called leaves outcome.loaded false (the 'skipped' verdict)", () => {
+		const cache = createDefinitionByteCache(10 * 1024 * 1024);
+		const ref = cache.getOrLoad('v-1', async () => bytes(1));
+		// The scheduler served a pointer-known solve — load() never ran.
+		expect(ref.outcome).toEqual({ loaded: false, fromCache: false });
+	});
+
+	it('evicts least-recently-used entries when the byte budget is exceeded', async () => {
+		// Budget holds ~2 of these 1 KB entries.
+		const cache = createDefinitionByteCache(2 * 1024);
+		const load = (marker: number) => async () => bytes(1024, marker);
+
+		await cache.getOrLoad('a', load(1)).load(); // [a]
+		await cache.getOrLoad('b', load(2)).load(); // [a,b]
+		// Touch 'a' so 'b' becomes the LRU victim.
+		await cache.getOrLoad('a', load(1)).load(); // hit → [b,a]
+		await cache.getOrLoad('c', load(3)).load(); // insert c → evict b → [a,c]
+
+		expect(cache.stats().entries).toBe(2);
+		expect(cache.stats().evictions).toBe(1);
+		expect(cache.stats().bytes).toBe(2 * 1024);
+
+		// 'a' survived (it was touched, so 'b' was the LRU victim) → served from
+		// cache without the loader. Checked BEFORE re-loading 'b', since bringing 'b'
+		// back would itself evict 'a' under the 2-entry budget.
+		const aLoad = vi.fn(load(1));
+		await cache.getOrLoad('a', aLoad).load();
+		expect(aLoad).toHaveBeenCalledTimes(0);
+
+		// 'b' was evicted → its next load calls the loader again (miss).
+		const bLoad = vi.fn(load(2));
+		await cache.getOrLoad('b', bLoad).load();
+		expect(bLoad).toHaveBeenCalledTimes(1);
+	});
+
+	it('never retains an entry larger than the whole budget (serves through, caches nothing)', async () => {
+		const cache = createDefinitionByteCache(1024);
+		const load = vi.fn(async () => bytes(4096));
+
+		const out = await cache.getOrLoad('big', load).load();
+		expect(out.byteLength).toBe(4096); // still served
+		expect(cache.stats().entries).toBe(0); // but not retained
+		expect(cache.stats().bytes).toBe(0);
+
+		// Every load re-fetches — nothing was cached.
+		await cache.getOrLoad('big', load).load();
+		expect(load).toHaveBeenCalledTimes(2);
+	});
+
+	it('keys on the passed version id — two versions that reused a fileKey never collide', async () => {
+		// The trap this cache exists to avoid: delete-latest-then-reupload reused a
+		// fileKey, but the version id (the KEY) is always fresh. Distinct ids →
+		// distinct entries, so the new version never serves the old bytes.
+		const cache = createDefinitionByteCache(10 * 1024 * 1024);
+		const oldBytes = bytes(1024, 1);
+		const newBytes = bytes(1024, 2);
+
+		const a = await cache.getOrLoad('version-old', async () => oldBytes).load();
+		const b = await cache.getOrLoad('version-new', async () => newBytes).load();
+
+		expect(a).toEqual(oldBytes);
+		expect(b).toEqual(newBytes);
+		expect(a).not.toEqual(b); // no cross-contamination despite a shared fileKey
+		expect(cache.stats().entries).toBe(2);
+	});
+
+	it('budget 0 disables caching entirely (every load hits the loader, nothing retained)', async () => {
+		const cache = createDefinitionByteCache(0);
+		const load = vi.fn(async () => bytes(16));
+
+		const ref1 = cache.getOrLoad('v-1', load);
+		await ref1.load();
+		await cache.getOrLoad('v-1', load).load();
+
+		expect(load).toHaveBeenCalledTimes(2);
+		expect(cache.stats().entries).toBe(0);
+		expect(cache.stats().bytes).toBe(0);
+		// Outcome still reports loaded, but never fromCache.
+		expect(ref1.outcome).toEqual({ loaded: true, fromCache: false });
+	});
+
+	it('re-storing the same key updates bytes without double-counting the budget', async () => {
+		const cache = createDefinitionByteCache(10 * 1024 * 1024);
+		// clear() to force a re-store path: first load caches, clear drops it, second caches again.
+		await cache.getOrLoad('v-1', async () => bytes(1024)).load();
+		expect(cache.stats().bytes).toBe(1024);
+		cache.clear();
+		expect(cache.stats().bytes).toBe(0);
+		expect(cache.stats().entries).toBe(0);
+	});
+});

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

@@ -66,4 +66,41 @@ describe('createComputeRateLimiter', () => {
 		// A different limiter instance is unaffected.
 		expect(other.check('user:alice').allowed).toBe(true);
 	});
+
+	// peek + clear support failure-counting flows (login limiting): peek gates
+	// the attempt without spending budget, check records a failure, clear
+	// forgives on success.
+	describe('peek / clear', () => {
+		it('peek never increments the counter', () => {
+			for (let i = 0; i < 1000; i++) expect(limiter.peek('ip:1.2.3.4').allowed).toBe(true);
+			// Full budget still available after all those peeks.
+			for (let i = 0; i < MAX_PER_WINDOW; i++) {
+				expect(limiter.check('ip:1.2.3.4').allowed).toBe(true);
+			}
+		});
+
+		it('peek reports a full bucket with retryAfter, still without mutating it', () => {
+			for (let i = 0; i < MAX_PER_WINDOW; i++) limiter.check('ip:1.2.3.4');
+			const result = limiter.peek('ip:1.2.3.4');
+			expect(result.allowed).toBe(false);
+			expect(result.retryAfter).toBeGreaterThan(0);
+		});
+
+		it('peek allows again once the window expires', () => {
+			for (let i = 0; i < MAX_PER_WINDOW; i++) limiter.check('ip:1.2.3.4');
+			expect(limiter.peek('ip:1.2.3.4').allowed).toBe(false);
+			vi.advanceTimersByTime(WINDOW_MS + 1);
+			expect(limiter.peek('ip:1.2.3.4').allowed).toBe(true);
+		});
+
+		it('clear drops only the given key', () => {
+			for (let i = 0; i < MAX_PER_WINDOW; i++) {
+				limiter.check('ip:1.2.3.4');
+				limiter.check('ip:5.6.7.8');
+			}
+			limiter.clear('ip:1.2.3.4');
+			expect(limiter.peek('ip:1.2.3.4').allowed).toBe(true);
+			expect(limiter.peek('ip:5.6.7.8').allowed).toBe(false);
+		});
+	});
 });