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,
},
};
}