Commit dd48bfd98c440029c1ecaf946916105850cfd0ab | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-06-20 15:12:36-07:00
committer	GitHub <noreply@github.com> 2026-06-20 15:12:36-07:00
log	dd48bfd98c440029c1ecaf946916105850cfd0ab
tree	a0936825d098e7a412040e1197d65d33a7da3355
parent	6d8d995621065e0513def2fa28bf0f7d8b54dd90
signature	Signed by PGP key B5690EEEBB952194

[codex] Structure server settings failures (#3376)

Co-authored-by: codex <codex@users.noreply.github.com>

4 files changed, 150 insertions(+), 53 deletions(-)

apps
- server
  - src
    serverRuntimeStartup.ts
    serverSettings.test.ts
    serverSettings.ts
packages
- contracts
  - src
    settings.ts

apps/server/src/serverRuntimeStartup.ts+3-1

 @@ -327,7 +327,9 @@ export const make = Effect.gen(function* () {
         Effect.catch((error) =>
           Effect.logWarning("failed to start server settings runtime", {
             path: error.settingsPath,
-            detail: error.detail,
+            operation: error.operation,
+            providerInstanceId: error.providerInstanceId,
+            environmentVariable: error.environmentVariable,
             cause: error.cause,
           }),
         ),

apps/server/src/serverSettings.test.ts+57

...	@@ -12,6 +12,7 @@ import * as Effect from "effect/Effect";	...	@@ -12,6 +12,7 @@ import * as Effect from "effect/Effect";
12	import * as Duration from "effect/Duration";	12	import * as Duration from "effect/Duration";
13	import * as FileSystem from "effect/FileSystem";	13	import * as FileSystem from "effect/FileSystem";
14	import * as Layer from "effect/Layer";	14	import * as Layer from "effect/Layer";
		15	import * as PlatformError from "effect/PlatformError";
15	import * as Schema from "effect/Schema";	16	import * as Schema from "effect/Schema";
16	import * as ServerSecretStore from "./auth/ServerSecretStore.ts";	17	import * as ServerSecretStore from "./auth/ServerSecretStore.ts";
17	import * as ServerConfig from "./config.ts";	18	import * as ServerConfig from "./config.ts";
...	@@ -32,7 +33,63 @@ const makeServerSettingsLayer = () =>	...	@@ -32,7 +33,63 @@ const makeServerSettingsLayer = () =>
32	),	33	),
33	);	34	);
34		35
		36	const makeFailingSecretStoreLayer = (cause: ServerSecretStore.SecretStoreError) =>
		37	Layer.succeed(
		38	ServerSecretStore.ServerSecretStore,
		39	ServerSecretStore.ServerSecretStore.of({
		40	get: () => Effect.fail(cause),
		41	set: () => Effect.void,
		42	create: () => Effect.void,
		43	getOrCreateRandom: () => Effect.succeed(new Uint8Array()),
		44	remove: () => Effect.void,
		45	}),
		46	);
		47
35	it.layer(NodeServices.layer)("server settings", (it) => {	48	it.layer(NodeServices.layer)("server settings", (it) => {
		49	it.effect("preserves context when reading a provider environment secret fails", () => {
		50	const platformCause = PlatformError.systemError({
		51	_tag: "PermissionDenied",
		52	module: "FileSystem",
		53	method: "readFile",
		54	pathOrDescriptor: "provider environment secret",
		55	description: "Secret backend unavailable.",
		56	});
		57	const cause = new ServerSecretStore.SecretStoreReadError({
		58	resource: "provider environment secret",
		59	cause: platformCause,
		60	});
		61	const configLayer = Layer.fresh(
		62	ServerConfig.layerTest(process.cwd(), {
		63	prefix: "t3code-server-settings-secret-failure-test-",
		64	}),
		65	);
		66	const settingsLayer = ServerSettingsModule.layer.pipe(
		67	Layer.provide(makeFailingSecretStoreLayer(cause)),
		68	Layer.provideMerge(configLayer),
		69	);
		70
		71	return Effect.gen(function* () {
		72	const serverConfig = yield* ServerConfig.ServerConfig;
		73	const fileSystem = yield* FileSystem.FileSystem;
		74	const serverSettings = yield* ServerSettingsModule.ServerSettingsService;
		75	yield* fileSystem.writeFileString(
		76	serverConfig.settingsPath,
		77	'{"providerInstances":{"codex_personal":{"driver":"codex","environment":[{"name":"OPENROUTER_API_KEY","value":"","sensitive":true,"valueRedacted":true}],"config":{}}}}',
		78	);
		79
		80	const error = yield* Effect.flip(serverSettings.getSettings);
		81
		82	assert.deepInclude(error, {
		83	_tag: "ServerSettingsError",
		84	operation: "read-secret",
		85	providerInstanceId: "codex_personal",
		86	environmentVariable: "OPENROUTER_API_KEY",
		87	});
		88	assert.strictEqual(error.cause, cause);
		89	assert.notInclude(error.message, cause.message);
		90	}).pipe(Effect.provide(settingsLayer));
		91	});
		92
36	it.effect("decodes nested settings patches", () =>	93	it.effect("decodes nested settings patches", () =>
37	Effect.gen(function* () {	94	Effect.gen(function* () {
38	assert.deepEqual(	95	assert.deepEqual(

apps/server/src/serverSettings.ts+66-49

 @@ -40,7 +40,6 @@ import * as Path from "effect/Path";
 import * as PubSub from "effect/PubSub";
 import * as Ref from "effect/Ref";
 import * as Schema from "effect/Schema";
-import * as SchemaIssue from "effect/SchemaIssue";
 import * as Semaphore from "effect/Semaphore";
 import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
 @@ -67,7 +66,7 @@ const normalizeServerSettings = (
       (cause) =>
         new ServerSettingsError({
           settingsPath: "<memory>",
-          detail: `failed to normalize server settings: ${SchemaIssue.makeFormatterDefault()(cause.issue)}`,
+          operation: "normalize",
           cause,
         }),
     ),
 @@ -277,7 +276,7 @@ const make = Effect.gen(function* () {
       (cause) =>
         new ServerSettingsError({
           settingsPath,
-          detail: "failed to check settings file existence",
+          operation: "check-exists",
           cause,
         }),
     ),
 @@ -288,7 +287,7 @@ const make = Effect.gen(function* () {
       (cause) =>
         new ServerSettingsError({
           settingsPath,
-          detail: "failed to read settings file",
+          operation: "read-file",
           cause,
         }),
     ),
 @@ -305,6 +304,7 @@ const make = Effect.gen(function* () {
       yield* Effect.logWarning("failed to parse settings.json, using defaults", {
         path: settingsPath,
         issues: Cause.pretty(decoded.cause),
+        cause: decoded.cause,
       });
       return DEFAULT_SERVER_SETTINGS;
     }
 @@ -318,13 +318,6 @@ const make = Effect.gen(function* () {
   const getSettingsFromCache = Cache.get(settingsCache, cacheKey);
-  const toSettingsError = (detail: string, cause: unknown) =>
-    new ServerSettingsError({
-      settingsPath,
-      detail,
-      cause,
-    });
   const materializeProviderEnvironmentSecrets = (
     settings: ServerSettings,
   ): Effect.Effect<ServerSettings, ServerSettingsError> =>
 @@ -343,11 +336,15 @@ const make = Effect.gen(function* () {
           const secret = yield* secretStore
             .get(providerEnvironmentSecretName({ instanceId, name: variable.name }))
             .pipe(
-              Effect.mapError((cause) =>
+              Effect.mapError(
-                toSettingsError(
+                (cause) =>
-                  `failed to read sensitive environment variable ${variable.name}`,
+                  new ServerSettingsError({
-                  cause,
+                    settingsPath,
-                ),
+                    operation: "read-secret",
+                    providerInstanceId: instanceId,
+                    environmentVariable: variable.name,
+                    cause,
+                  }),
               ),
             );
           environment.push({
 @@ -382,13 +379,18 @@ const make = Effect.gen(function* () {
         for (const variable of instance.environment) {
           const secretName = providerEnvironmentSecretName({ instanceId, name: variable.name });
           if (!variable.sensitive) {
-            yield* secretStore
+            yield* secretStore.remove(secretName).pipe(
-              .remove(secretName)
+              Effect.mapError(
-              .pipe(
+                (cause) =>
-                Effect.mapError((cause) =>
+                  new ServerSettingsError({
-                  toSettingsError(`failed to remove environment secret ${variable.name}`, cause),
+                    settingsPath,
-                ),
+                    operation: "remove-secret",
-              );
+                    providerInstanceId: instanceId,
+                    environmentVariable: variable.name,
+                    cause,
+                  }),
+              ),
+            );
             environment.push(redactProviderEnvironmentVariable(variable));
             continue;
           }
 @@ -396,22 +398,32 @@ const make = Effect.gen(function* () {
           nextSecretKeys.add(secretName);
           if (!variable.valueRedacted) {
             if (variable.value.length > 0) {
-              yield* secretStore
+              yield* secretStore.set(secretName, textEncoder.encode(variable.value)).pipe(
-                .set(secretName, textEncoder.encode(variable.value))
+                Effect.mapError(
-                .pipe(
+                  (cause) =>
-                  Effect.mapError((cause) =>
+                    new ServerSettingsError({
-                    toSettingsError(`failed to persist environment secret ${variable.name}`, cause),
+                      settingsPath,
-                  ),
+                      operation: "write-secret",
-                );
+                      providerInstanceId: instanceId,
+                      environmentVariable: variable.name,
+                      cause,
+                    }),
+                ),
+              );
               environment.push({ ...variable, value: "", valueRedacted: true });
             } else {
-              yield* secretStore
+              yield* secretStore.remove(secretName).pipe(
-                .remove(secretName)
+                Effect.mapError(
-                .pipe(
+                  (cause) =>
-                  Effect.mapError((cause) =>
+                    new ServerSettingsError({
-                    toSettingsError(`failed to remove environment secret ${variable.name}`, cause),
+                      settingsPath,
-                  ),
+                      operation: "remove-secret",
-                );
+                      providerInstanceId: instanceId,
+                      environmentVariable: variable.name,
+                      cause,
+                    }),
+                ),
+              );
               const { valueRedacted: _omit, ...rest } = variable;
               environment.push(rest);
             }
 @@ -431,16 +443,18 @@ const make = Effect.gen(function* () {
           if (!variable.sensitive) continue;
           const secretName = providerEnvironmentSecretName({ instanceId, name: variable.name });
           if (nextSecretKeys.has(secretName)) continue;
-          yield* secretStore
+          yield* secretStore.remove(secretName).pipe(
-            .remove(secretName)
+            Effect.mapError(
-            .pipe(
+              (cause) =>
-              Effect.mapError((cause) =>
+                new ServerSettingsError({
-                toSettingsError(
+                  settingsPath,
-                  `failed to remove stale environment secret ${variable.name}`,
+                  operation: "remove-stale-secret",
+                  providerInstanceId: instanceId,
+                  environmentVariable: variable.name,
                   cause,
-                ),
+                }),
-              ),
+            ),
-            );
+          );
         }
       }
 @@ -468,7 +482,7 @@ const make = Effect.gen(function* () {
       (cause) =>
         new ServerSettingsError({
           settingsPath,
-          detail: "failed to write settings file",
+          operation: "write-file",
           cause,
         }),
     ),
 @@ -492,7 +506,7 @@ const make = Effect.gen(function* () {
         (cause) =>
           new ServerSettingsError({
             settingsPath,
-            detail: "failed to prepare settings directory",
+            operation: "prepare-directory",
             cause,
           }),
       ),
 @@ -571,7 +585,10 @@ const make = Effect.gen(function* () {
           materializeProviderEnvironmentSecrets(settings).pipe(
             Effect.catch((error: ServerSettingsError) =>
               Effect.logWarning("failed to materialize provider environment secrets", {
-                detail: error.detail,
+                operation: error.operation,
+                providerInstanceId: error.providerInstanceId,
+                environmentVariable: error.environmentVariable,
+                cause: error.cause,
               }).pipe(Effect.as(settings)),
             ),
           ),

packages/contracts/src/settings.ts+24-3

...	@@ -414,16 +414,37 @@ export type ServerSettings = typeof ServerSettings.Type;	...	@@ -414,16 +414,37 @@ export type ServerSettings = typeof ServerSettings.Type;
414		414
415	export const DEFAULT_SERVER_SETTINGS: ServerSettings = Schema.decodeSync(ServerSettings)({});	415	export const DEFAULT_SERVER_SETTINGS: ServerSettings = Schema.decodeSync(ServerSettings)({});
416		416
		417	export const ServerSettingsOperation = Schema.Literals([
		418	"normalize",
		419	"check-exists",
		420	"read-file",
		421	"read-secret",
		422	"remove-secret",
		423	"remove-stale-secret",
		424	"write-secret",
		425	"write-file",
		426	"prepare-directory",
		427	]);
		428	export type ServerSettingsOperation = typeof ServerSettingsOperation.Type;
		429
417	export class ServerSettingsError extends Schema.TaggedErrorClass<ServerSettingsError>()(	430	export class ServerSettingsError extends Schema.TaggedErrorClass<ServerSettingsError>()(
418	"ServerSettingsError",	431	"ServerSettingsError",
419	{	432	{
420	settingsPath: Schema.String,	433	settingsPath: Schema.String,
421	detail: Schema.String,	434	operation: ServerSettingsOperation,
422	cause: Schema.optional(Schema.Defect()),	435	providerInstanceId: Schema.optional(Schema.String),
		436	environmentVariable: Schema.optional(Schema.String),
		437	cause: Schema.Defect(),
423	},	438	},
424	) {	439	) {
425	override get message(): string {	440	override get message(): string {
426	return `Server settings error at ${this.settingsPath}: ${this.detail}`;	441	const provider =
		442	this.providerInstanceId === undefined ? "" : ` for provider ${this.providerInstanceId}`;
		443	const variable =
		444	this.environmentVariable === undefined
		445	? ""
		446	: ` and environment variable ${this.environmentVariable}`;
		447	return `Server settings ${this.operation} failed${provider}${variable} at ${this.settingsPath}.`;
427	}	448	}
428	}	449	}
429		450