@crvouga/atlas 0.17.0 → 1.0.0

package/dist/server/src/main.d.ts

@@ -1,30 +1,46 @@
 /**
  * @module `atlas serve`
  *
- * Starts the Atlas server from its configuration: opens every backend (creating the data folder), proves the upload
- * backend can be written to before listening, finds or builds the client, listens at once (so a liveness probe finds the
- * process while a large backend is still being read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared
- * with `atlas dev`, so the two run the same server.
+ * Starts the Atlas server from its configuration. Storage comes first and is not optional: the required `ATLAS_S3_*`
+ * variables are checked (every problem listed together), the bucket is proven reachable and writable, and the user
+ * state (garbage collection policy and saved settings) is read from it, all before anything listens. Any failure prints
+ * a banner naming every variable and exits 2; there is no fallback to a local folder, memory or a database. Then it
+ * finds or builds the client, listens at once (so a liveness probe finds the process while a large bucket is still being
+ * read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared with `atlas dev`, so the two run the same server.
  *
  * @see docs/server.md#run-it
  */
 import type { BackendInput } from '../../reports/src/compose.js';
 import { type AtlasServerOptions } from './app.js';
 import { type ResolvedServerConfig } from './config.js';
+import { type StoredUserState } from './user-state.js';
 type Env = Readonly<Record<string, string | undefined>>;
-/** What `serveMain` and `devMain` are given besides arguments: where output goes, and, for tests and embedding, the environment, working directory and an `AbortSignal` that stops the server (otherwise SIGTERM and SIGINT do). */
+/** What `serveMain` and `devMain` are given besides arguments: where output goes, and, for tests and embedding, the environment, working directory, the `fetch` S3 requests are sent with, and an `AbortSignal` that stops the server (otherwise SIGTERM and SIGINT do). */
 export type ServeIo = {
     readonly out: (text: string) => void;
     readonly env?: Env;
     readonly cwd?: string;
     readonly signal?: AbortSignal;
+    readonly fetch?: typeof fetch;
 };
-/** Open every backend of a configuration. The data folder is made if it is not there. */
-export declare function openConfiguredBackends(config: ResolvedServerConfig, env: Env, cwd: string): (BackendInput & {
+/** The id of the one backend: the S3 bucket. */
+export declare const S3_BACKEND_ID = "s3";
+/** Open the S3 bucket named by a configuration, with exactly the credentials it gives (no ambient AWS lookup). Nothing is contacted yet. */
+export declare function openConfiguredBackends(config: ResolvedServerConfig, fetchImpl?: typeof fetch): (BackendInput & {
     readonly writable: boolean;
 })[];
 /** What `createAtlasServer` is given for a configuration: `atlas serve` and `atlas dev` run the same server. */
 export declare function serverOptionsOf(config: ResolvedServerConfig, backends: ReturnType<typeof openConfiguredBackends>, log?: (line: Record<string, unknown>) => void): AtlasServerOptions;
+/**
+ * Check the storage and read the user state, in that order, with the failure banner for each way it can go wrong.
+ * Returns the opened backends and the state, or the text to print before exiting 2.
+ */
+export declare function connectStorage(config: ResolvedServerConfig, env: Env, io: Pick<ServeIo, 'fetch'>): Promise<{
+    readonly backends: ReturnType<typeof openConfiguredBackends>;
+    readonly stored: StoredUserState;
+} | {
+    readonly failure: string;
+}>;
 /** `atlas serve`. Runs until it is told to stop; returns the exit code. */
 export declare function serveMain(argv: readonly string[], io: ServeIo): Promise<number>;
 export {};

package/dist/server/src/main.js

@@ -1,38 +1,45 @@
 /**
  * @module `atlas serve`
  *
- * Starts the Atlas server from its configuration: opens every backend (creating the data folder), proves the upload
- * backend can be written to before listening, finds or builds the client, listens at once (so a liveness probe finds the
- * process while a large backend is still being read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared
- * with `atlas dev`, so the two run the same server.
+ * Starts the Atlas server from its configuration. Storage comes first and is not optional: the required `ATLAS_S3_*`
+ * variables are checked (every problem listed together), the bucket is proven reachable and writable, and the user
+ * state (garbage collection policy and saved settings) is read from it, all before anything listens. Any failure prints
+ * a banner naming every variable and exits 2; there is no fallback to a local folder, memory or a database. Then it
+ * finds or builds the client, listens at once (so a liveness probe finds the process while a large bucket is still being
+ * read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared with `atlas dev`, so the two run the same server.
  *
  * @see docs/server.md#run-it
  */
-import { mkdirSync } from 'node:fs';
 import path from 'node:path';
-import { openStore } from '../../reports/src/store-url.js';
+import { s3Store } from '../../reports/src/s3-store.js';
 import { createAtlasServer } from './app.js';
 import { ConfigError, loadServerConfig, SERVER_USAGE } from './config.js';
 import { listen } from './host.js';
-import { fileServerSettings } from './settings.js';
+import { storedSettings } from './settings.js';
 import { findSite } from './site.js';
-/** Open every backend of a configuration. The data folder is made if it is not there. */
-export function openConfiguredBackends(config, env, cwd) {
-    return config.backends.map((spec, i) => {
-        if (i === 0)
-            mkdirSync(spec.url, { recursive: true });
-        const opened = openStore(spec.url, { base: cwd, env });
-        return { id: spec.id, label: spec.label, store: opened.store, writable: spec.id === config.writeId };
+import { describeS3, inspectS3Env, S3ConfigError, startupFailure } from './storage.js';
+import { USER_STATE_KEY, UserStateError, userStateStore } from './user-state.js';
+/** The id of the one backend: the S3 bucket. */
+export const S3_BACKEND_ID = 's3';
+/** Open the S3 bucket named by a configuration, with exactly the credentials it gives (no ambient AWS lookup). Nothing is contacted yet. */
+export function openConfiguredBackends(config, fetchImpl) {
+    const { s3 } = config;
+    const store = s3Store({
+        bucket: s3.bucket, prefix: s3.prefix, region: s3.region, endpoint: s3.endpoint, forcePathStyle: s3.pathStyle,
+        credentials: { accessKeyId: s3.accessKeyId, secretAccessKey: s3.secretAccessKey, ...(s3.sessionToken ? { sessionToken: s3.sessionToken } : {}) },
+        env: {}, ...(fetchImpl ? { fetch: fetchImpl } : {})
     });
+    return [{ id: S3_BACKEND_ID, label: describeS3(s3), store, writable: true }];
 }
-/** Can the server put things in the place uploads go? Said at the start, not at the first upload. */
-async function probeWritable(backend) {
+/** Can the server use the bucket? Said at the start, not at the first upload: list, write, read back and delete. */
+async function probeStorage(backend) {
     const key = `layers/doctor-${Math.random().toString(36).slice(2, 10)}/probe`;
     try {
+        await backend.store.listKeys('server/');
         await backend.store.put(key, new TextEncoder().encode('atlas'), 'text/plain');
         if (!(await backend.store.head(key)))
             return 'an object was written but could not be found again';
-        await backend.store.delete(key).catch(() => { });
+        await backend.store.delete(key);
         return null;
     }
     catch (error) {
@@ -46,13 +53,35 @@ export function serverOptionsOf(config, backends, log) {
         ? (layer) => (!branches?.length || (layer.branch !== null && branches.includes(layer.branch))) && (!config.include.ignoreModified || layer.freshness === undefined)
         : undefined;
     return {
-        backends, write: config.writeId,
-        ...(/^https?:\/\//.test(config.backends.find(backend => backend.id === config.writeId).url) ? { liveStore: backends[0].store } : {}), tokens: config.tokens, anonymousRead: config.anonymousRead,
+        backends, write: S3_BACKEND_ID,
+        tokens: config.tokens, anonymousRead: config.anonymousRead,
         ...(config.outlineBranch ? { outlineBranch: config.outlineBranch } : {}), ...(include ? { include } : {}),
         runTimeoutMs: config.runTimeoutSeconds * 1000, runStallMs: config.runStallSeconds * 1000, refreshMs: config.refreshSeconds * 1000, limits: config.limits, heartbeatMs: config.heartbeatSeconds * 1000,
         ...(config.log && log ? { log } : {})
     };
 }
+/** What the garbage collection policy in S3 means, in one line for the log. */
+const gcLine = (stored) => stored.state.gc
+    ? `Garbage collection policy loaded from S3 (${USER_STATE_KEY}): ${stored.state.gc.enabled ? `ON, delete superseded layers older than ${stored.state.gc.maxAgeDays} days, keep the newest ${stored.state.gc.keepLatest}, every ${stored.state.gc.intervalHours} h` : 'OFF (saved but disabled)'}.\n`
+    : `No garbage collection policy has been saved in S3 (${USER_STATE_KEY}) yet: garbage collection is OFF and nothing is deleted. Define a policy in the Atlas UI at /admin.\n`;
+/**
+ * Check the storage and read the user state, in that order, with the failure banner for each way it can go wrong.
+ * Returns the opened backends and the state, or the text to print before exiting 2.
+ */
+export async function connectStorage(config, env, io) {
+    const backends = openConfiguredBackends(config, io.fetch);
+    const problem = await probeStorage(backends[0]);
+    if (problem)
+        return { failure: startupFailure(inspectS3Env(env), `the S3 storage ${describeS3(config.s3)} cannot be used with these settings`, problem) };
+    try {
+        return { backends, stored: await userStateStore(backends[0].store).read() };
+    }
+    catch (error) {
+        if (error instanceof UserStateError)
+            return { failure: startupFailure(inspectS3Env(env), 'the user state stored in S3 cannot be read', error.message) };
+        throw error;
+    }
+}
 /** `atlas serve`. Runs until it is told to stop; returns the exit code. */
 export async function serveMain(argv, io) {
     const cwd = io.cwd ?? process.cwd();
@@ -66,24 +95,41 @@ export async function serveMain(argv, io) {
         config = loadServerConfig(argv, env, cwd);
     }
     catch (error) {
+        if (error instanceof S3ConfigError) {
+            io.out(`${error.message}\n`);
+            return 2;
+        }
         if (error instanceof ConfigError) {
             io.out(`atlas serve: ${error.message}\n`);
             return 2;
         }
         throw error;
     }
-    const backends = openConfiguredBackends(config, env, cwd);
-    const writeBackend = backends.find(backend => backend.writable);
-    io.out(`${config.configFile ? `Configuration ${path.relative(cwd, config.configFile) || config.configFile}. ` : ''}Backends: ${backends.map(backend => `${backend.id}${backend.writable ? ' (uploads)' : ''}`).join(', ')}\n`);
-    const problem = await probeWritable(writeBackend);
-    if (problem) {
-        io.out(`atlas serve: uploads would go to "${writeBackend.id}" and it cannot be written to: ${problem}\n`);
+    const connected = await connectStorage(config, env, io);
+    if ('failure' in connected) {
+        io.out(`${connected.failure}\n`);
         return 2;
     }
+    const { backends, stored } = connected;
+    if (stored.state.settings) {
+        try {
+            config = loadServerConfig(argv, env, cwd, undefined, stored.state.settings);
+        }
+        catch (error) {
+            if (error instanceof ConfigError) {
+                io.out(`atlas serve: the settings saved in S3 (${USER_STATE_KEY}) do not work with this deployment: ${error.message}\n`);
+                return 2;
+            }
+            throw error;
+        }
+    }
+    io.out(`${config.configFile ? `Configuration ${path.relative(cwd, config.configFile) || config.configFile}. ` : ''}Storage: ${describeS3(config.s3)}. All reports and user state live there.\n`);
+    io.out(gcLine(stored));
     const site = await findSite(config.site, cwd, io.out);
     if (!site)
         io.out('No Atlas client to serve: build one with `atlas client build --no-data --out atlas-site`. The API is served meanwhile.\n');
-    const server = createAtlasServer({ settings: fileServerSettings(config, argv, env, cwd), ...serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)), ...(site ? { site } : {}) });
+    const { settings, gc } = storedSettings(config, argv, env, cwd, userStateStore(backends[0].store));
+    const server = createAtlasServer({ settings, gc, ...serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)), ...(site ? { site } : {}) });
     // Listen at once: the first pass over a large backend can take a while, and a liveness probe must find the
     // process meanwhile. /readyz is 503 until there is a report to show.
     const running = await listen(server.fetch, { port: config.port, host: config.host, maxBodyBytes: Math.max(config.limits.maxObjectMiB, config.limits.maxJsonMiB) * 1024 * 1024 });

package/dist/server/src/openapi.js

@@ -15,7 +15,7 @@
 import { z } from 'zod/v4';
 import { ProjectsSchema } from '../../schema/src/project.js';
 import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, RunListSchema, RunDetailSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema } from '../../schema/src/api.js';
-import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
+import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, GcPolicySchema, GcSnapshotSchema, GcRunResultSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
 export const API_VERSION = '1.5.0';
 /** The JSON Schema of a Zod schema, as OpenAPI 3.1 embeds it. `output` for what the server sends, `input` for what it accepts. */
@@ -30,6 +30,7 @@ function schemaOf(schema, io = 'output') {
 const COMPONENTS = {
     LiveRun: [LiveRunSchema, 'output'], LiveRunStart: [LiveRunStartSchema, 'input'], LiveRunUpdate: [LiveRunUpdateSchema, 'input'],
     ServerEditableSettings: [ServerEditableSettingsSchema, 'input'], ServerSettingsSnapshot: [ServerSettingsSnapshotSchema, 'output'],
+    GcPolicy: [GcPolicySchema, 'input'], GcSnapshot: [GcSnapshotSchema, 'output'], GcRunResult: [GcRunResultSchema, 'output'],
     Problem: [ProblemSchema, 'output'], Health: [HealthSchema, 'output'], Ready: [ReadySchema, 'output'], ServerInfo: [ServerInfoSchema, 'output'],
     EffectiveEvidence: [EffectiveEvidenceSchema, 'output'], EffectiveDelta: [EffectiveDeltaSchema, 'output'], ReportStatus: [ReportStatusSchema, 'output'],
     PublishChecks: [PublishChecksSchema.partial({ recordedAtMs: true }), 'input'], ChecksResult: [ChecksResultSchema, 'output'],
@@ -92,16 +93,34 @@ const BASE_OPERATIONS = [
     },
     {
         route: 'GET /api/settings', path: '/api/settings', operationId: 'getSettings', tag: 'Operations', role: 'admin',
-        summary: 'Read server settings', description: 'Returns editable persisted storage/report settings, active settings, a revision, and configuration precedence. Authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.',
+        summary: 'Read server settings', description: 'Returns the editable report and live-run settings saved in the user state in S3, active settings, a revision, and configuration precedence. Storage and authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.',
         responses: { '200': json('Settings and revision.', 'ServerSettingsSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '503': problem('Configuration is managed by the embedding application.') }
     },
     {
         route: 'PUT /api/settings', path: '/api/settings', operationId: 'saveSettings', tag: 'Operations', role: 'admin',
-        summary: 'Save settings for the next restart', description: 'Replaces editable storage/report settings, preserving authentication and other file fields. Atomically persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.',
+        summary: 'Save settings for the next restart', description: 'Replaces the editable report and live-run settings in the user state in S3 (`server/state.json`), preserving the garbage collection policy and other fields. Persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.',
         parameters: [{ name: 'If-Match', in: 'header', required: true, description: 'The quoted revision returned by GET /api/settings.', schema: str }],
-        body: { description: 'Editable fields from ServerConfig, excluding authentication, host, port and site. Maximum 64 KiB.', contentType: 'application/json', required: true, schema: ref('ServerEditableSettings') },
+        body: { description: 'Editable fields from ServerConfig, excluding storage, authentication, host, port and site. Maximum 64 KiB.', contentType: 'application/json', required: true, schema: ref('ServerEditableSettings') },
         responses: { '200': json('Saved settings and new revision. Restart required.', 'ServerSettingsSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('Settings changed; reload before saving.'), '413': problem('Settings exceed the body limit.'), '422': problem('Invalid configuration.'), '428': problem('A quoted settings revision is required.'), '503': problem('Configuration is managed by the embedding application.') }
     },
+    {
+        route: 'GET /api/settings/gc', path: '/api/settings/gc', operationId: 'getGarbageCollectionPolicy', tag: 'Operations', role: 'admin',
+        summary: 'Read the garbage collection policy', description: 'Returns the policy kept in the user state in S3 (`server/state.json`), or `policy: null, saved: false` when none has been saved yet, in which case garbage collection is off and nothing is deleted. Also returns the revision to send back when saving and the last pass over each project. Requires an admin Bearer token. If the stored user state is unreadable the answer is 503 and the stored object is left untouched.',
+        responses: { '200': json('The policy, its revision and the last passes.', 'GcSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '503': problem('The user state in S3 cannot be read, or settings are managed by the embedding application.') }
+    },
+    {
+        route: 'PUT /api/settings/gc', path: '/api/settings/gc', operationId: 'saveGarbageCollectionPolicy', tag: 'Operations', role: 'admin',
+        summary: 'Save the garbage collection policy', description: 'Replaces the policy in the user state in S3 and leaves the rest of that document alone. The server reads the policy from S3 each time it collects, so the new policy applies at the next pass, without a restart. Requires an admin Bearer token, same-origin requests in browsers, and the current revision.',
+        parameters: [{ name: 'If-Match', in: 'header', required: true, description: 'The quoted revision returned by GET /api/settings/gc.', schema: str }],
+        body: { description: 'The policy. Maximum 16 KiB.', contentType: 'application/json', required: true, schema: ref('GcPolicy') },
+        responses: { '200': json('The saved policy and the new revision.', 'GcSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('The state changed; reload before saving.'), '413': problem('The body exceeds the limit.'), '422': problem('Invalid policy.'), '428': problem('A quoted revision is required.'), '503': problem('The user state in S3 cannot be read, or settings are managed by the embedding application.') }
+    },
+    {
+        route: 'POST /api/settings/gc/run', path: '/api/settings/gc/run', operationId: 'runGarbageCollection', tag: 'Operations', role: 'admin',
+        summary: 'Collect garbage now, or preview it', description: 'Applies the policy saved in S3 to every project now, instead of waiting for the schedule. Only report layers that were read and no longer decide any result, older than the policy allows and beyond its `keepLatest`, are deleted, with the captured files only they used. With `dryRun=1` nothing is deleted and each run reports what it would delete (a disabled policy is previewed as if enabled). Answers 409 when no policy has been saved, and, without `dryRun`, when the saved policy is disabled. Requires an admin Bearer token and a same-origin request in browsers.',
+        parameters: [{ name: 'dryRun', in: 'query', required: false, description: '`1` or `true` to only count what would be deleted.', schema: str }],
+        responses: { '200': json('One run per project.', 'GcRunResult'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('No policy has been saved, or it is disabled.') }
+    },
     {
         route: 'GET /healthz', path: '/healthz', operationId: 'getHealth', tag: 'Operations', role: 'none',
         summary: 'Is the process up',
@@ -437,7 +456,7 @@ const BASE_OPERATIONS = [
         responses: { '200': { description: 'The file.', contentType: 'application/octet-stream', schema: { type: 'string', format: 'binary' } }, '401': UNAUTHORIZED, '404': problem('No such run or file.') }
     }
 ];
-const NODE_OPERATIONS = new Set(['/api/projects', '/api/settings', '/api/server', '/api/openapi.json']);
+const NODE_OPERATIONS = new Set(['/api/projects', '/api/settings', '/api/settings/gc', '/api/settings/gc/run', '/api/server', '/api/openapi.json']);
 const PROJECT_PARAMETER = { name: 'project', in: 'query', description: 'Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.', schema: { type: 'string', pattern: '^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$', maxLength: 64 }, example: 'todo-app' };
 /** Every node operation and the same stable report protocol inside each project namespace. */
 export const OPERATIONS = BASE_OPERATIONS.flatMap(operation => {

package/dist/server/src/projects.js

@@ -9,7 +9,7 @@ import { createAuth } from './auth.js';
 import { problemResponse } from './problem.js';
 const REGISTRY = 'server/projects/';
 const SCOPED = /^\/api\/projects\/([^/]+)(\/.*)$/;
-const GLOBAL = new Set(['/api/settings', '/api/projects', '/api/openapi.json', '/api/server']);
+const GLOBAL = new Set(['/api/settings', '/api/settings/gc', '/api/settings/gc/run', '/api/projects', '/api/openapi.json', '/api/server']);
 const scopeStore = (store, slug) => typeof store.forProject === 'function'
     ? store.forProject(slug) : new ObjectStoreWithPrefix(store, `projects/${slug}`);
 /** Wrap the single-project protocol in project selection. Auth, upload validation and composition stay identical. */
@@ -61,7 +61,71 @@ export function projectServer(options, create) {
     };
     const timer = setInterval(expire, 60_000);
     timer.unref?.();
-    const routes = [...base.routes, { method: 'GET', path: '/api/projects' }];
+    /** The application of one named project, created on first use over a store scoped to it. `null` when too many are active. */
+    const ensureChild = (slug) => {
+        let child = children.get(slug);
+        if (child)
+            return child;
+        expire();
+        if (children.size >= 64)
+            return null;
+        child = { touched: Date.now(), pending: 0, server: create({ ...options,
+                ...(options.log ? { log: line => options.log({ ...line, project: slug }) } : {}),
+                backends: options.backends.map(backend => ({ ...backend, store: scopeStore(backend.store, slug) })),
+                ...(options.liveStore ? { liveStore: scopeStore(options.liveStore, slug) } : {}), site: undefined, settings: undefined, gc: undefined }) };
+        children.set(slug, child);
+        return child;
+    };
+    // Garbage collection. The policy is read from S3 every time, never cached, so a policy saved in the UI is the one applied.
+    const clock = options.now ?? Date.now;
+    let collecting;
+    let lastCollectedAt = 0;
+    const collectAll = (policy, dryRun) => {
+        collecting ??= (async () => {
+            const runs = [];
+            await discover().catch(() => { });
+            for (const slug of ['default', ...[...known].filter(item => item !== 'default').sort()]) {
+                if (closed)
+                    break;
+                if (slug === 'default') {
+                    runs.push(await base.collectGarbage(policy, { dryRun, project: slug }));
+                    continue;
+                }
+                const child = ensureChild(slug);
+                if (!child) {
+                    runs.push({ project: slug, dryRun, at: new Date(clock()).toISOString(), candidates: 0, deletedLayers: 0, deletedBlobs: 0, keptLayers: 0, error: 'Too many active projects; this one was skipped.' });
+                    continue;
+                }
+                child.pending++;
+                try {
+                    await child.server.ready;
+                    runs.push(await child.server.collectGarbage(policy, { dryRun, project: slug }));
+                }
+                finally {
+                    child.pending--;
+                    child.touched = Date.now();
+                }
+            }
+            if (!dryRun)
+                options.gc?.record(runs);
+            return runs;
+        })().finally(() => { collecting = undefined; });
+        return collecting;
+    };
+    const gcTimer = options.gc ? setInterval(() => {
+        void (async () => {
+            if (closed || collecting)
+                return;
+            const policy = await options.gc.policy();
+            if (!policy?.enabled || clock() - lastCollectedAt < policy.intervalHours * 3_600_000)
+                return;
+            await base.ready;
+            lastCollectedAt = clock();
+            await collectAll(policy, false);
+        })().catch(error => options.log?.({ level: 'error', gc: 'schedule', error: String(error) }));
+    }, options.gcCheckMs ?? 60_000) : undefined;
+    gcTimer?.unref?.();
+    const routes = [...base.routes, { method: 'GET', path: '/api/projects' }, { method: 'POST', path: '/api/settings/gc/run' }];
     for (const route of base.routes)
         if (route.path.startsWith('/api/') && route.path !== '/api/*' && !GLOBAL.has(route.path))
             routes.push({ method: route.method, path: route.path.replace('/api/', '/api/projects/:project/') });
@@ -71,6 +135,24 @@ export function projectServer(options, create) {
                 if (closed)
                     return problemResponse(503, 'Atlas is stopping.');
                 const url = new URL(request.url);
+                if (url.pathname === '/api/settings/gc/run' && request.method === 'POST') {
+                    const verdict = auth.check(request, 'admin');
+                    if (!verdict.ok)
+                        return problemResponse(verdict.status, verdict.message, verdict.status === 401 ? { 'www-authenticate': 'Basic realm="Atlas"' } : {});
+                    const origin = request.headers.get('origin');
+                    const site = request.headers.get('sec-fetch-site');
+                    if (site === 'cross-site' || (origin && origin !== url.origin && site !== 'same-origin'))
+                        return problemResponse(403, 'Changes must come from this server origin.');
+                    if (!options.gc)
+                        return problemResponse(503, 'Garbage collection settings are managed by the embedding application.');
+                    const policy = await options.gc.policy();
+                    if (!policy)
+                        return problemResponse(409, 'No garbage collection policy has been saved yet, so nothing is deleted. Save one first.');
+                    const dryRun = ['1', 'true'].includes(url.searchParams.get('dryRun') ?? '');
+                    if (!dryRun && !policy.enabled)
+                        return problemResponse(409, 'The saved garbage collection policy is disabled. Enable it, or use dryRun to preview.');
+                    return Response.json({ runs: await collectAll(dryRun ? { ...policy, enabled: true } : policy, dryRun), policy }, { headers: { 'cache-control': 'no-store' } });
+                }
                 if (url.pathname === '/api/projects' && request.method === 'GET') {
                     const verdict = auth.check(request, 'read');
                     if (!verdict.ok)
@@ -116,17 +198,9 @@ export function projectServer(options, create) {
                             return problemResponse(404, 'Unknown project. Publish reports with this project slug first.');
                     }
                 }
-                let child = children.get(slug);
-                if (!child) {
-                    expire();
-                    if (children.size >= 64)
-                        return problemResponse(429, 'Too many active projects. Retry when another project is idle.');
-                    child = { touched: Date.now(), pending: 0, server: create({ ...options,
-                            ...(options.log ? { log: line => options.log({ ...line, project: slug }) } : {}),
-                            backends: options.backends.map(backend => ({ ...backend, store: scopeStore(backend.store, slug) })),
-                            ...(options.liveStore ? { liveStore: scopeStore(options.liveStore, slug) } : {}), site: undefined, settings: undefined }) };
-                    children.set(slug, child);
-                }
+                const child = ensureChild(slug);
+                if (!child)
+                    return problemResponse(429, 'Too many active projects. Retry when another project is idle.');
                 child.touched = Date.now();
                 child.pending++;
                 try {
@@ -149,6 +223,7 @@ export function projectServer(options, create) {
                 return problemResponse(503, 'The project backend is unavailable. Retry later.');
             }
         },
-        close() { closed = true; clearInterval(timer); base.close(); for (const child of children.values())
+        close() { closed = true; clearInterval(timer); if (gcTimer)
+            clearInterval(gcTimer); base.close(); for (const child of children.values())
             child.server.close(); children.clear(); } };
 }

package/dist/server/src/settings.d.ts

@@ -1,5 +1,7 @@
+import { type GcPolicy, type GcRun, type GcSnapshot } from '../../schema/src/user-state.js';
 import { type ResolvedServerConfig } from './config.js';
-/** The persisted editable settings, active settings and a revision for optimistic concurrency. Authentication token settings are excluded. */
+import { type UserStateStore } from './user-state.js';
+/** The saved editable settings, the active settings and a revision for optimistic concurrency. Authentication token settings are excluded. */
 export type SettingsSnapshot = {
     readonly revision: string;
     readonly settings: Record<string, unknown>;
@@ -7,17 +9,31 @@ export type SettingsSnapshot = {
     readonly restartRequired: boolean;
     readonly precedence: string;
 };
-/** Storage for the admin API; saving is serialized and refuses a stale revision. */
+/** Storage for the admin API; saving is serialised and refuses a stale revision. */
 export type ServerSettings = {
     read(): Promise<SettingsSnapshot>;
     save(settings: unknown, revision: string): Promise<SettingsSnapshot>;
 };
+/** The garbage collection policy as the admin API and the collector see it. */
+export type GcSettings = {
+    /** The policy in S3 with its revision and the last passes. */
+    read(): Promise<GcSnapshot>;
+    /** Validates and saves a policy; a stale `revision` is refused. */
+    save(policy: unknown, revision: string): Promise<GcSnapshot>;
+    /** The policy in S3 right now, or `null` when none has been saved. Read from S3 every time. */
+    policy(): Promise<GcPolicy | null>;
+    /** Remembers the result of a pass, for `read`. */
+    record(runs: readonly GcRun[]): void;
+};
 /**
- * Manage the server's configuration file with atomic replacement, preserving authentication and unrelated fields.
- * Validates both the file alone and the effective configuration before saving. Never migrates or deletes report data.
- * Changes need a server restart; deployment environment variables and flags override the file.
+ * The settings and garbage collection policy kept in `userState` (S3). Validates a settings change against the
+ * whole deployment (file, environment and flags) before saving, so what is saved can start. Never moves report data.
+ *
  * @example
- * const settings = fileServerSettings(config, argv, process.env, process.cwd());
+ * const { settings, gc } = storedSettings(config, argv, process.env, process.cwd(), userStateStore(store));
  */
-export declare function fileServerSettings(config: ResolvedServerConfig, argv: readonly string[], env: Readonly<Record<string, string | undefined>>, cwd: string): ServerSettings;
+export declare function storedSettings(config: ResolvedServerConfig, argv: readonly string[], env: Readonly<Record<string, string | undefined>>, cwd: string, userState: UserStateStore): {
+    settings: ServerSettings;
+    gc: GcSettings;
+};
 export { SETTINGS_PAGE, renderSettingsPage } from './settings-page.js';

package/dist/server/src/settings.js

@@ -1,72 +1,62 @@
 /** @module Persisted server settings
- * The admin UI edits storage and report configuration in atlas.server.json. Changes take effect on restart;
- * environment variables and flags keep their documented precedence. Authentication is managed outside this UI.
+ * The settings page edits two things, and both are kept in the user state document in S3 (`server/state.json`), never on
+ * the server's disk: the report and live-run settings (applied at the next start, below the configuration file,
+ * the environment and the flags in precedence) and the garbage collection policy (read by the server each time it
+ * collects). Storage and authentication are deployment-owned and are not editable here.
  */
-import { createHash, randomUUID } from 'node:crypto';
-import { readFile, rename, rm, writeFile } from 'node:fs/promises';
-import path from 'node:path';
 import { ServerEditableSettingsSchema } from '../../schema/src/server-config.js';
-import { parseStoreLocation } from '../../reports/src/store-url.js';
+import { GcPolicySchema } from '../../schema/src/user-state.js';
 import { ConfigError, loadServerConfig } from './config.js';
+import { USER_STATE_KEY, UserStateError } from './user-state.js';
 const editable = ServerEditableSettingsSchema;
-const keys = new Set(Object.keys(editable.shape));
-const select = (value) => Object.fromEntries(Object.entries(value).filter(([key]) => keys.has(key)));
-const digest = (text) => createHash('sha256').update(text).digest('hex');
+const conflict = (error) => {
+    if (error instanceof UserStateError)
+        throw new ConfigError(error.message);
+    throw error;
+};
 /**
- * Manage the server's configuration file with atomic replacement, preserving authentication and unrelated fields.
- * Validates both the file alone and the effective configuration before saving. Never migrates or deletes report data.
- * Changes need a server restart; deployment environment variables and flags override the file.
+ * The settings and garbage collection policy kept in `userState` (S3). Validates a settings change against the
+ * whole deployment (file, environment and flags) before saving, so what is saved can start. Never moves report data.
+ *
  * @example
- * const settings = fileServerSettings(config, argv, process.env, process.cwd());
+ * const { settings, gc } = storedSettings(config, argv, process.env, process.cwd(), userStateStore(store));
  */
-export function fileServerSettings(config, argv, env, cwd) {
-    const file = config.configFile ?? path.join(cwd, 'atlas.server.json');
-    const active = { data: config.data, backends: config.backends.slice(1), write: config.writeId, outlineBranch: config.outlineBranch, include: config.include, refreshSeconds: config.refreshSeconds, limits: config.limits, heartbeatSeconds: config.heartbeatSeconds, runTimeoutSeconds: config.runTimeoutSeconds, runStallSeconds: config.runStallSeconds, log: config.log };
+export function storedSettings(config, argv, env, cwd, userState) {
+    const active = { outlineBranch: config.outlineBranch, include: config.include, refreshSeconds: config.refreshSeconds, limits: config.limits, heartbeatSeconds: config.heartbeatSeconds, runTimeoutSeconds: config.runTimeoutSeconds, runStallSeconds: config.runStallSeconds, log: config.log };
     let saved = false;
-    let pending = Promise.resolve();
-    const readText = () => readFile(file, 'utf8').catch(error => { if (error.code === 'ENOENT')
-        return '{}'; throw error; });
-    const read = async () => {
-        const text = await readText();
-        return { revision: digest(text), settings: select(JSON.parse(text)), active,
-            restartRequired: saved, precedence: 'File settings apply after restart. Environment variables and command-line flags override the file.' };
+    let lastRuns = [];
+    const snapshot = (stored) => ({
+        revision: stored.revision, settings: (stored.state.settings ?? {}), active, restartRequired: saved,
+        precedence: `Saved in S3 (${USER_STATE_KEY}) and applied after restart. The configuration file, environment variables and command-line flags override them.`
+    });
+    const gcSnapshot = (stored) => ({
+        revision: stored.revision, policy: stored.state.gc ? GcPolicySchema.parse(stored.state.gc) : null, saved: stored.state.gc !== undefined, lastRuns, stateKey: USER_STATE_KEY
+    });
+    const settings = {
+        read: async () => snapshot(await userState.read().catch(conflict)),
+        async save(input, revision) {
+            const parsed = editable.safeParse(input);
+            if (!parsed.success)
+                throw new ConfigError(parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; '));
+            // Prove the exact deployment (file, environment, flags and these settings) can start before keeping them.
+            loadServerConfig(argv, env, cwd, undefined, parsed.data);
+            // What the person chose, as sent: validated, but without the defaults filled in, so unchosen settings keep following the defaults.
+            const stored = await userState.update(revision, state => ({ ...state, settings: input })).catch(conflict);
+            saved = true;
+            return snapshot(stored);
+        }
     };
-    return { read, save(settings, revision) {
-            const update = pending.then(async () => {
-                const parsed = editable.safeParse(settings);
-                if (!parsed.success)
-                    throw new ConfigError(parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; '));
-                const before = await readText();
-                if (digest(before) !== revision)
-                    throw new ConfigError('Settings changed. Reload them before saving.');
-                const original = JSON.parse(before);
-                const merged = { ...Object.fromEntries(Object.entries(original).filter(([key]) => !keys.has(key))), ...parsed.data };
-                const text = `${JSON.stringify(merged, null, 2)}\n`;
-                // Prove it is independently usable, then prove the exact deployment (including overrides) can start.
-                const base = loadServerConfig(['--config', file], env, cwd, () => text);
-                const effective = loadServerConfig([...argv, '--config', file], env, cwd, () => text);
-                try {
-                    for (const backend of [...base.backends, ...effective.backends])
-                        parseStoreLocation(backend.url, path.dirname(file), env);
-                }
-                catch (error) {
-                    throw new ConfigError(error instanceof Error ? error.message : String(error));
-                }
-                const temporary = `${file}.${randomUUID()}.tmp`;
-                try {
-                    await writeFile(temporary, text, { mode: 0o600, flag: 'wx' });
-                    if (await readText() !== before)
-                        throw new ConfigError('Settings changed. Reload them before saving.');
-                    await rename(temporary, file);
-                }
-                finally {
-                    await rm(temporary, { force: true });
-                }
-                saved = true;
-                return read();
-            });
-            pending = update.catch(() => undefined);
-            return update;
-        } };
+    const gc = {
+        read: async () => gcSnapshot(await userState.read().catch(conflict)),
+        async save(input, revision) {
+            const parsed = GcPolicySchema.safeParse(input);
+            if (!parsed.success)
+                throw new ConfigError(parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; '));
+            return gcSnapshot(await userState.update(revision, state => ({ ...state, gc: parsed.data })).catch(conflict));
+        },
+        policy: async () => { const { state } = await userState.read(); return state.gc ? GcPolicySchema.parse(state.gc) : null; },
+        record(runs) { lastRuns = [...runs, ...lastRuns.filter(old => !runs.some(run => run.project === old.project))].slice(0, 50); }
+    };
+    return { settings, gc };
 }
 export { SETTINGS_PAGE, renderSettingsPage } from './settings-page.js';