Skip to content
Source
Sign inSign up
pingdotgg/t3code
Open History to see the last commit

managedSettings.ts

515 lines20.3 KB

1import {
2 DEFAULT_SERVER_SETTINGS,
3 isRuntimeModeAbove,
4 type ManagedPolicySetting,
5 ProjectSettingsOverrides,
6 type RuntimeMode,
7 ServerSettings,
8 withIdleCompaction,
9} from "@t3tools/contracts";
10import * as Exit from "effect/Exit";
11import * as Schema from "effect/Schema";
12​
13import { mapSettingsSecrets } from "../settingsSecrets.ts";
14​
15const encodeSettings = Schema.encodeSync(ServerSettings);
16const decodeSettings = Schema.decodeUnknownSync(ServerSettings);
17const decodeSettingsExit = Schema.decodeUnknownExit(ServerSettings);
18​
19/** Project overrides mirror these top-level keys, so a lock on one applies inside each project. */
20const PROJECT_OVERRIDE_KEYS: ReadonlySet<string> = new Set(
21 Object.keys(ProjectSettingsOverrides.fields),
22);
23/** Per-project stores; admins lock the top-level key and the lock reaches every project. */
24const UNMANAGEABLE_KEYS: ReadonlySet<string> = new Set([
25 "projectSettingsOverrides",
26 "projectAgentBrowserAccessOverrides",
27 "projectAutoPullOverrides",
28 "projectScriptOverrides",
29]);
30​
31/**
32 * Startup resolves OTLP endpoints from the settings file and desktop bootstrap input before the policy
33 * loads, and the user's OTLP environment variables outrank them, so a managed value would look
34 * enforced without being.
35 */
36const ENVIRONMENT_OVERRIDDEN_KEYS: ReadonlySet<string> = new Set(["observability"]);
37​
38/** Legacy settings the server derives from another on every write; manage that one instead. */
39const DERIVED_FROM: ReadonlyMap<string, string> = new Map([
40 ["compactIdleThreads", "idleCompaction"],
41]);
42​
43/**
44 * Settings another one overrides when it is set: `worktreeCleanup`, also per project, wins over
45 * the worktree rules in `storageCleanup`. A lock on the first alone would look enforced without
46 * being, so the second must be locked too.
47 */
48const OVERRIDDEN_BY: ReadonlyArray<readonly [overridden: string, by: string]> = [
49 ["storageCleanup.worktree", "worktreeCleanup"],
50];
51​
52type Segments = ReadonlyArray<string>;
53​
54/**
55 * The server derives the legacy switch from `idleCompaction` on every write, and shipped clients
56 * still read it, so values the policy sets carry the matching switch.
57 */
58const syncIdleCompaction = (settings: ServerSettings): ServerSettings =>
59 settings.idleCompaction === undefined
60 ? settings
61 : withIdleCompaction(settings, settings.idleCompaction);
62​
63const isRecord = (value: unknown): value is Record<string, unknown> =>
64 value !== null && typeof value === "object" && !Array.isArray(value);
65​
66const getPath = (tree: unknown, segments: Segments): unknown => {
67 let current = tree;
68 for (const segment of segments) {
69 if (!isRecord(current)) return undefined;
70 current = current[segment];
71 }
72 return current;
73};
74​
75const setPath = (tree: unknown, segments: Segments, value: unknown): unknown => {
76 const [head, ...rest] = segments;
77 if (head === undefined) return value;
78 const record = isRecord(tree) ? tree : {};
79 if (value === undefined && rest.length === 0) {
80 const { [head]: _removed, ...remaining } = record;
81 return remaining;
82 }
83 return { ...record, [head]: setPath(record[head], rest, value) };
84};
85​
86/** Fills keys `target` lacks from `defaults`, recursing into objects both sides hold. */
87const fillMissing = (target: unknown, defaults: unknown): unknown => {
88 if (!isRecord(target) || !isRecord(defaults)) return target;
89 const next: Record<string, unknown> = { ...target };
90 for (const [key, value] of Object.entries(defaults)) {
91 next[key] = key in target ? fillMissing(target[key], value) : value;
92 }
93 return next;
94};
95​
96const jsonEqual = (left: unknown, right: unknown): boolean => {
97 if (Object.is(left, right)) return true;
98 if (Array.isArray(left) && Array.isArray(right)) {
99 return (
100 left.length === right.length && left.every((item, index) => jsonEqual(item, right[index]))
101 );
102 }
103 if (!isRecord(left) || !isRecord(right)) return false;
104 const leftKeys = Object.keys(left).filter((key) => left[key] !== undefined);
105 const rightKeys = Object.keys(right).filter((key) => right[key] !== undefined);
106 return (
107 leftKeys.length === rightKeys.length &&
108 leftKeys.every((key) => jsonEqual(left[key], right[key]))
109 );
110};
111​
112/**
113 * Whether `value` agrees with a lock on every key it holds. Patches and project overrides carry
114 * only some of a locked object's keys, such as `{ enabled }` for a provider instance.
115 */
116const matchesLock = (value: unknown, lock: unknown): boolean =>
117 isRecord(value) && isRecord(lock)
118 ? Object.entries(value).every(
119 ([key, child]) => child === undefined || matchesLock(child, lock[key]),
120 )
121 : jsonEqual(value, lock);
122​
123/** Whether `value` holds a key `existing` does not, at any depth. */
124const addsKeys = (existing: unknown, value: unknown): boolean =>
125 isRecord(existing) &&
126 isRecord(value) &&
127 Object.entries(value).some(([key, child]) =>
128 key in existing ? addsKeys(existing[key], child) : true,
129 );
130​
131/**
132 * How a policy's `settings` shape the server's settings. Policy values are never written to
133 * the user's settings file: defaults fill keys the file leaves out, and locks are laid over the
134 * result on every read, so removing the policy brings the user's own settings back.
135 */
136export interface ManagedSettings {
137 /** Fill policy defaults into a parsed settings file before it is decoded. */
138 readonly withDefaults: (persisted: unknown) => unknown;
139 /** Built-in defaults with the policy's defaults applied; the settings file omits values equal to these. */
140 readonly defaults: ServerSettings;
141 /**
142 * Lay locked values over settings, including inside each project's overrides, and lower
143 * default runtime modes above the policy's ceiling to it.
144 */
145 readonly applyLocks: (settings: ServerSettings) => ServerSettings;
146 /**
147 * Vet a write from `current` to `next`. It is refused when it tries to move a locked path off
148 * its locked value, whether set in `patch` or changed by another route such as a legacy patch
149 * key. An allowed write keeps the user's stored values at locked paths, so a client re-sending
150 * the locked value does not overwrite what applies once the policy is gone.
151 */
152 readonly vetWrite: (
153 current: ServerSettings,
154 next: ServerSettings,
155 patch: unknown,
156 ) =>
157 | { readonly _tag: "Allowed"; readonly settings: ServerSettings }
158 | { readonly _tag: "Locked"; readonly path: string };
159 readonly lockedPaths: ReadonlyArray<string>;
160 /**
161 * Put back into a stripped settings file the values `stored`, the file before this write, held
162 * at or under paths the policy defaults: equal to the policy's default, they are still the
163 * user's choice. A key `isAtomic` names comes back whole or not at all. Undefined without
164 * policy defaults, so writers can skip reading the file.
165 */
166 readonly keepStored:
167 | ((
168 stripped: unknown,
169 settings: ServerSettings,
170 stored: unknown,
171 isAtomic: (key: string) => boolean,
172 ) => unknown)
173 | undefined;
175​
176export const unmanagedSettings: ManagedSettings = {
177 keepStored: undefined,
178 withDefaults: (persisted) => persisted,
179 defaults: DEFAULT_SERVER_SETTINGS,
180 applyLocks: (settings) => settings,
181 vetWrite: (_current, next) => ({ _tag: "Allowed", settings: next }),
182 lockedPaths: [],
183};
184​
185interface Entry {
186 readonly path: string;
187 readonly segments: Segments;
188 /** As written in the policy, the encoded form. */
189 readonly value: unknown;
191​
192interface Lock extends Entry {
193 /** The decoded form, which is what patches carry. */
194 readonly decodedValue: unknown;
196​
197/** Locked paths as stored in the top level and in each project's overrides of `encoded`. */
198const lockTargets = (encoded: unknown, entry: Entry): ReadonlyArray<Segments> => {
199 const [head] = entry.segments;
200 if (head === undefined || !PROJECT_OVERRIDE_KEYS.has(head)) return [entry.segments];
201 const projects = getPath(encoded, ["projectSettingsOverrides"]);
202 const projectTargets = isRecord(projects)
203 ? Object.entries(projects)
204 .filter(([, overrides]) => isRecord(overrides) && overrides[head] !== undefined)
205 .map(([projectId]) => ["projectSettingsOverrides", projectId, ...entry.segments])
206 : [];
207 return [entry.segments, ...projectTargets];
208};
209​
210/**
211 * A user's stored default runtime mode can sit above a ceiling deployed after it was chosen, and
212 * the built-in default is the broadest mode. Every new thread would then be refused, so the
213 * effective default is the ceiling instead. The stored value is untouched and returns with the
214 * policy's removal; existing threads keep their modes and are refused turns instead.
215 */
216const clampDefaultRuntimeModes = (
217 settings: ServerSettings,
218 ceiling: RuntimeMode,
219): ServerSettings => {
220 const projectsAbove = Object.entries(settings.projectSettingsOverrides).filter(
221 ([, overrides]) =>
222 overrides.defaultRuntimeMode !== undefined &&
223 isRuntimeModeAbove(overrides.defaultRuntimeMode, ceiling),
224 );
225 if (!isRuntimeModeAbove(settings.defaultRuntimeMode, ceiling) && projectsAbove.length === 0) {
226 return settings;
227 }
228 return {
229 ...settings,
230 defaultRuntimeMode: isRuntimeModeAbove(settings.defaultRuntimeMode, ceiling)
231 ? ceiling
232 : settings.defaultRuntimeMode,
233 projectSettingsOverrides: {
234 ...settings.projectSettingsOverrides,
235 ...Object.fromEntries(
236 projectsAbove.map(([projectId, overrides]) => [
237 projectId,
238 { ...overrides, defaultRuntimeMode: ceiling },
239 ]),
240 ),
241 },
242 };
243};
244​
245/** Build the overlay for a policy's settings, or describe the first entry this build cannot apply. */
246export function makeManagedSettings(
247 settings: Readonly<Record<string, ManagedPolicySetting>>,
248 maxRuntimeMode?: RuntimeMode,
249):
250 | { readonly _tag: "Valid"; readonly settings: ManagedSettings }
251 | { readonly _tag: "Invalid"; readonly reason: string } {
252 const defaults: Entry[] = [];
253 const locks: Entry[] = [];
254 for (const [path, setting] of Object.entries(settings)) {
255 const segments = path.split(".");
256 const [head] = segments;
257 if (head === undefined || segments.some((segment) => segment.length === 0)) {
258 return { _tag: "Invalid", reason: `"${path}" is not a settings path` };
259 }
260 if (!(head in ServerSettings.fields) || UNMANAGEABLE_KEYS.has(head)) {
261 return { _tag: "Invalid", reason: `"${path}" is not a setting this version can manage` };
262 }
263 if (ENVIRONMENT_OVERRIDDEN_KEYS.has(head)) {
264 return {
265 _tag: "Invalid",
266 reason: `"${path}" is resolved at startup from each user's environment, settings file and desktop bootstrap input, which a policy cannot override`,
267 };
268 }
269 const source = DERIVED_FROM.get(head);
270 if (source !== undefined) {
271 return {
272 _tag: "Invalid",
273 reason: `"${head}" follows "${source}"; manage "${source}" instead`,
274 };
275 }
276 (setting.locked ? locks : defaults).push({ path, segments, value: setting.value });
277 }
278​
279 for (const lock of locks) {
280 const unheld = OVERRIDDEN_BY.find(
281 ([overridden, by]) =>
282 (lock.path.startsWith(overridden) || overridden.startsWith(`${lock.path}.`)) &&
283 !locks.some((other) => other.path === by),
284 );
285 if (unheld !== undefined) {
286 return {
287 _tag: "Invalid",
288 reason: `"${lock.path}" can be overridden by "${unheld[1]}"; lock "${unheld[1]}" too`,
289 };
290 }
291 // An instance's fields override each other: a variable replaces launch arguments, a home
292 // path rewrites a home variable, and a setup mode brings its own runtime.
293 const [head, instanceId] = lock.segments;
294 if (head === "providerInstances" && instanceId !== undefined && lock.segments.length > 2) {
295 return {
296 _tag: "Invalid",
297 reason: `"${lock.path}" is one field of a provider instance whose fields override each other; lock "providerInstances.${instanceId}" as a whole, or pin fields with limits.providers.instances`,
298 };
299 }
300 }
301​
302 // Apply every entry to the built-in defaults at once, and read each value back: a typo in a
303 // nested key or a value of the wrong type does not survive the round trip.
304 const builtIn = encodeSettings(DEFAULT_SERVER_SETTINGS);
305 const all = [...defaults, ...locks];
306 // A user's stored null would leave a nested lock building a partial object, so lock the whole
307 // setting instead.
308 const insideNullable = all.find((entry) =>
309 entry.segments
310 .slice(0, -1)
311 .some((_, index) =>
312 Exit.isSuccess(
313 decodeSettingsExit(setPath(builtIn, entry.segments.slice(0, index + 1), null)),
314 ),
315 ),
316 );
317 if (insideNullable !== undefined) {
318 return {
319 _tag: "Invalid",
320 reason: `"${insideNullable.path}" is inside a setting that can be empty; manage "${insideNullable.segments[0]}" as a whole`,
321 };
322 }
323 const applied = all.reduce<unknown>(
324 (tree, entry) => setPath(tree, entry.segments, entry.value),
325 builtIn,
326 );
327 const decoded = decodeSettingsExit(applied);
328 if (Exit.isFailure(decoded)) {
329 return { _tag: "Invalid", reason: "a managed setting has a value of the wrong type" };
330 }
331 const roundTrip = encodeSettings(decoded.value);
332 const lost = all.find((entry) => !jsonEqual(getPath(roundTrip, entry.segments), entry.value));
333 if (lost !== undefined) {
334 return {
335 _tag: "Invalid",
336 reason: `"${lost.path}" is not a setting this version can manage, or its value is invalid`,
337 };
338 }
339 // The server moves a credential it finds in settings into the user's secret store, where a
340 // policy's would outlive the policy. Built-in defaults hold none, so any found is the policy's.
341 let holdsCredential = false;
342 mapSettingsSecrets(decoded.value, (secret) => {
343 if (secret.sensitive && !secret.redacted && secret.value.length > 0) holdsCredential = true;
344 return secret;
345 });
346 if (holdsCredential) {
347 return {
348 _tag: "Invalid",
349 reason:
350 "a managed setting holds a credential, which every user can read in the policy; deploy credentials another way",
351 };
352 }
353 // Defaults fill in what the file leaves out, so an entry a default adds to a record such as
354 // `providerInstances` would come back each time the user removed it.
355 const addsEntry = defaults.find((entry) => {
356 const existing = getPath(builtIn, entry.segments);
357 return existing === undefined ? entry.segments.length > 1 : addsKeys(existing, entry.value);
358 });
359 if (addsEntry !== undefined) {
360 return {
361 _tag: "Invalid",
362 reason: `"${addsEntry.path}" adds entries users could not remove; lock it instead`,
363 };
364 }
365 // A managed default above the ceiling would start every thread in a mode the policy refuses.
366 if (
367 all.some((entry) => entry.path === "defaultRuntimeMode") &&
368 isRuntimeModeAbove(decoded.value.defaultRuntimeMode, maxRuntimeMode)
369 ) {
370 return {
371 _tag: "Invalid",
372 reason: `"defaultRuntimeMode" is above "limits.maxRuntimeMode"`,
373 };
374 }
375​
376 const defaultsTree = defaults.reduce<unknown>(
377 (tree, entry) => setPath(tree, entry.segments, entry.value),
378 {},
379 );
380 const lockEntries: ReadonlyArray<Lock> = locks.map((entry) => ({
381 ...entry,
382 decodedValue: getPath(decoded.value, entry.segments),
383 }));
384 const lockedPaths = locks.map((entry) => entry.path);
385 const idleCompactionLocked = lockedPaths.includes("idleCompaction");
386 const lockCache = new WeakMap<ServerSettings, ServerSettings>();
387​
388 const applyLocks = (current: ServerSettings): ServerSettings => {
389 if (locks.length === 0 && maxRuntimeMode === undefined) return current;
390 const cached = lockCache.get(current);
391 if (cached !== undefined) return cached;
392 const locked =
393 locks.length === 0
394 ? current
395 : // Validated against the built-in defaults above, so a failure here is a bug, not bad input.
396 decodeSettings(
397 locks.reduce<unknown>(
398 (tree, entry) =>
399 lockTargets(tree, entry).reduce<unknown>(
400 (next, target) => setPath(next, target, entry.value),
401 tree,
402 ),
403 encodeSettings(current),
404 ),
405 );
406 const derived = idleCompactionLocked ? syncIdleCompaction(locked) : locked;
407 const result =
408 maxRuntimeMode === undefined ? derived : clampDefaultRuntimeModes(derived, maxRuntimeMode);
409 lockCache.set(current, result);
410 return result;
411 };
412​
413 const vetWrite: ManagedSettings["vetWrite"] = (current, next, patch) => {
414 if (locks.length === 0) return { _tag: "Allowed", settings: next };
415 const before = encodeSettings(current);
416 const after = encodeSettings(next);
417 const changed = lockEntries.find(
418 (entry) =>
419 // Re-sending a stored value the lock overrides changes nothing on disk, but it is still
420 // an attempt to change what the user sees.
421 lockTargets(patch, entry).some((target) => {
422 const value = getPath(patch, target);
423 return value !== undefined && !matchesLock(value, entry.decodedValue);
424 }) ||
425 lockTargets(after, entry).some((target) => {
426 const value = getPath(after, target);
427 // Removing a project's override of a locked key is harmless; the lock applies either way.
428 return (
429 value !== undefined &&
430 !jsonEqual(value, getPath(before, target)) &&
431 !matchesLock(value, entry.value)
432 );
433 }),
434 );
435 if (changed !== undefined) return { _tag: "Locked", path: changed.path };
436 const kept = locks.reduce<unknown>(
437 (tree, entry) =>
438 lockTargets(tree, entry).reduce<unknown>((result, target) => {
439 // A parent the write adds holds the locked value already; removing only the locked key
440 // inside it would leave a partial object.
441 const added = target
442 .slice(0, -1)
443 .some((_, index) => getPath(before, target.slice(0, index + 1)) === undefined);
444 return added ? result : setPath(result, target, getPath(before, target));
445 }, tree),
446 after,
447 );
448 return { _tag: "Allowed", settings: decodeSettings(kept) };
449 };
450​
451 // A file from before a setting replaced its legacy key holds the user's choice in that key, which
452 // a default for the new setting would otherwise override.
453 const withoutLegacyChoices = (persisted: unknown): unknown => {
454 if (!isRecord(persisted) || !isRecord(defaultsTree)) return defaultsTree;
455 const kept = { ...defaultsTree };
456 for (const [legacy, source] of DERIVED_FROM) {
457 if (persisted[legacy] !== undefined && persisted[source] === undefined) delete kept[source];
458 }
459 return kept;
460 };
461​
462 // The paths keepStored puts back: each default, cut at an atomic setting, and the legacy key a
463 // defaulted setting replaced, which an older file holds the user's choice in.
464 const restoredPaths = (isAtomic: (key: string) => boolean): ReadonlyArray<Segments> => [
465 ...defaults.map((entry) => {
466 const atomicAt = entry.segments.findIndex(isAtomic);
467 return atomicAt === -1 ? entry.segments : entry.segments.slice(0, atomicAt + 1);
468 }),
469 ...[...DERIVED_FROM]
470 .filter(([, source]) => defaults.some((entry) => entry.path === source))
471 .map(([legacy]) => [legacy]),
472 ];
473​
474 const keepStored: ManagedSettings["keepStored"] =
475 defaults.length === 0
476 ? undefined
477 : (stripped, settings, stored, isAtomic) => {
478 const encoded = encodeSettings(settings);
479 const restore = (tree: unknown, segments: Segments): unknown => {
480 const previous = getPath(stored, segments);
481 if (previous === undefined) return tree;
482 if (isRecord(previous) && !isAtomic(segments.at(-1) ?? "")) {
483 return Object.keys(previous).reduce<unknown>(
484 (next, key) => restore(next, [...segments, key]),
485 tree,
486 );
487 }
488 return getPath(tree, segments) === undefined &&
489 jsonEqual(previous, getPath(encoded, segments))
490 ? setPath(tree, segments, getPath(settings, segments))
491 : tree;
492 };
493 // A default inside an atomic setting restores that whole setting, never part of it.
494 return restoredPaths(isAtomic).reduce<unknown>(restore, stripped);
495 };
496​
497 return {
498 _tag: "Valid",
499 settings: {
500 keepStored,
501 withDefaults: (persisted) => fillMissing(persisted, withoutLegacyChoices(persisted)),
502 defaults: syncIdleCompaction(
503 decodeSettings(
504 defaults.reduce<unknown>(
505 (tree, entry) => setPath(tree, entry.segments, entry.value),
506 builtIn,
507 ),
508 ),
509 ),
510 applyLocks,
511 vetWrite,
512 lockedPaths,
513 },
514 };