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