Tighten HTTP error schemas, keep rich causes internally (#137)

* Tighten HTTP error schemas, keep rich causes internally Establish a clear rule: Schema.TaggedError is HTTP wire-facing — every field must be a safe public field. Data.TaggedError is internal-only; it can carry rich cause: unknown for logging/debugging and can't be accidentally wired to an HttpApi endpoint because it isn't a Schema. - OpenApiParseError (HTTP-exposed): drop error: Schema.Defect field - GraphqlIntrospectionError (HTTP-exposed): drop error: Schema.Defect field; log underlying causes via Effect.logError at construction sites in introspect.ts - OpenApiInvocationError, GraphqlInvocationError, GoogleDiscoveryParseError, GoogleDiscoveryInvocationError, KeychainError, ToolInvocationError: convert Schema.TaggedError -> Data.TaggedError, rename error -> cause - Cloud auth (UserStoreError, WorkOSError): keep empty schema + 500 annotation, log full cause via Effect.tapErrorCause at service wrappers * Extract withServiceLogging helper + errors.test.ts contract Collapse the repetitive tapErrorCause + mapError + withSpan ceremony at each service wrapper into one helper in auth/errors.ts. Add a real HttpApi integration test that pins down the contract: - Wire response contains only declared tagged-error fields - Server-side logs capture the full Cause chain (drizzle query, params, nested pg Error.cause) The test uses a real HttpApi + HttpApiBuilder.toWebHandler + fetch round-trip with a capturing Logger to verify both sides without mocking. Validates Option C from the earlier discussion: service-level logging is the only pattern that preserves the full cause because mapError discards it before any edge middleware could see it. * Remove errors.test.ts * Simplify graphql introspection error handling Drop ad-hoc Effect.logError sprinkles on branch-level failures (bad status, returned errors, missing __schema) — the tagged error's message already carries the useful info and there's no Cause chain to tap. Keep tapErrorCause + mapError inline for the two cases where an upstream error exists (HTTP request failure, JSON parse failure).

Rhys Sullivan committed 7 months ago

Commit d2ce9d71 parent 0ccccd914 files · +93 −107Browse files

Unified · Split

14 files

apps/cloud/src/auth/context.ts +9 −19
apps/cloud/src/auth/errors.ts +24 −5
apps/cloud/src/auth/workos.ts +5 −13
packages/core/sdk/src/errors.ts +7 −8
packages/plugins/google-discovery/src/sdk/document.ts +2 −4
packages/plugins/google-discovery/src/sdk/errors.ts +13 −14
packages/plugins/google-discovery/src/sdk/invoke.ts +1 −2
packages/plugins/graphql/src/sdk/errors.ts +8 −9
packages/plugins/graphql/src/sdk/introspect.ts +9 −11
packages/plugins/graphql/src/sdk/invoke.ts +1 −1
packages/plugins/keychain/src/errors.ts +5 −8
packages/plugins/openapi/src/sdk/errors.ts +8 −9
packages/plugins/openapi/src/sdk/invoke.ts +1 −3
packages/plugins/openapi/src/sdk/parse.ts +0 −1

apps/cloud/src/auth/context.ts+9−19

 import { Context, Effect, Layer } from "effect";
 import { makeUserStore } from "../services/user-store";
 import { DbService } from "../services/db";
-import { UserStoreError } from "./errors";
+import { UserStoreError, withServiceLogging } from "./errors";
 // AuthContext is defined in ./middleware.ts to keep middleware-related types together.
 export { AuthContext } from "./middleware";
 type RawStore = ReturnType<typeof makeUserStore>;
-const makeService = (store: RawStore) => {
+const makeService = (store: RawStore) => ({
-  const use = <A>(fn: (s: RawStore) => Promise<A>) =>
+  use: <A>(fn: (s: RawStore) => Promise<A>) =>
-    Effect.tryPromise({
+    withServiceLogging(
-      try: () => fn(store),
+      "user_store",
-      catch: (cause) => cause,
+      () => new UserStoreError(),
-    }).pipe(
+      Effect.tryPromise({ try: () => fn(store), catch: (e) => e }),
-      Effect.tapError((cause) =>
+    ),
-        Effect.sync(() => {
+});
-          // eslint-disable-next-line no-console
-          console.error("[user_store] query failed:", cause);
-        }),
-      ),
-      Effect.mapError(() => new UserStoreError()),
-      Effect.withSpan("user_store"),
-    );
-  return { use };
-};
 type UserStoreServiceType = ReturnType<typeof makeService>;

apps/cloud/src/auth/errors.ts+24−5

@@ -1,10 +1,6 @@
1	import { HttpApiSchema } from "@effect/platform";	1	import { HttpApiSchema } from "@effect/platform";
2	import { Schema } from "effect";	2	import { Effect, Schema } from "effect";
3		3
4	// Tagged errors returned to HTTP clients. The response payload must NEVER
5	// include internal details (SQL, stack traces, WorkOS error bodies) — those
6	// can leak schema + secrets. Keep the schema empty and log the `cause`
7	// server-side via Effect's logger when the error is constructed.
8	export class UserStoreError extends Schema.TaggedError<UserStoreError>()(	4	export class UserStoreError extends Schema.TaggedError<UserStoreError>()(
9	"UserStoreError",	5	"UserStoreError",
10	{},	6	{},
@@ -16,3 +12,26 @@ export class WorkOSError extends Schema.TaggedError<WorkOSError>()( · 5 unmodified lines
16	{},	12	{},
17	HttpApiSchema.annotations({ status: 500 }),	13	HttpApiSchema.annotations({ status: 500 }),
18	) {}	14	) {}
		15
		16	/**
		17	* Service-boundary error wrapper. Logs the full Cause chain (drizzle
		18	* query/params, pg error codes, nested Error.cause, etc.) via Effect's
		19	* structured logger, then maps to a tagged error so the HTTP wire
		20	* response contains only safe fields.
		21	*
		22	* Use this whenever a Promise-based API gets lifted into an Effect and
		23	* its failure needs both debuggable server-side logging and a safe
		24	* public shape.
		25	*/
		26	export const withServiceLogging = <A, E, R>(
		27	name: string,
		28	publicError: () => E,
		29	effect: Effect.Effect<A, unknown, R>,
		30	): Effect.Effect<A, E, R> =>
		31	effect.pipe(
		32	Effect.tapErrorCause((cause) =>
		33	Effect.logError(`${name} failed`, cause),
		34	),
		35	Effect.mapError(publicError),
		36	Effect.withSpan(name),
		37	);

apps/cloud/src/auth/workos.ts+5−13

 import { Context, Effect, Layer } from "effect";
 import { WorkOS } from "@workos-inc/node/worker";
-import { WorkOSError } from "./errors";
+import { WorkOSError, withServiceLogging } from "./errors";
 import { server } from "../env";
 const COOKIE_NAME = "wos-session";
   const workos = new WorkOS({ apiKey, clientId });
   const use = <A>(fn: (wos: WorkOS) => Promise<A>) =>
-    Effect.tryPromise({
+    withServiceLogging(
-      try: () => fn(workos),
+      "workos",
-      catch: (cause) => cause,
+      () => new WorkOSError(),
-    }).pipe(
+      Effect.tryPromise({ try: () => fn(workos), catch: (e) => e }),
-      Effect.tapError((cause) =>
-        Effect.sync(() => {
-          // eslint-disable-next-line no-console
-          console.error("[workos] call failed:", cause);
-        }),
-      ),
-      Effect.mapError(() => new WorkOSError()),
-      Effect.withSpan("workos"),
     );
   const authenticateSealedSession = (sessionData: string) =>

packages/core/sdk/src/errors.ts+7−8

@@ -1,4 +1,4 @@
1	import { Schema } from "effect";	1	import { Data, Schema } from "effect";
2		2
3	import { ToolId, SecretId, PolicyId } from "./ids";	3	import { ToolId, SecretId, PolicyId } from "./ids";
4		4
@@ -7,14 +7,13 @@ export class ToolNotFoundError extends Schema.TaggedError<ToolNotFoundError>()( · 2 unmodified lines
7	{ toolId: ToolId },	7	{ toolId: ToolId },
8	) {}	8	) {}
9		9
10	export class ToolInvocationError extends Schema.TaggedError<ToolInvocationError>()(	10	export class ToolInvocationError extends Data.TaggedError(
11	"ToolInvocationError",	11	"ToolInvocationError",
12	{	12	)<{
13	toolId: ToolId,	13	readonly toolId: ToolId;
14	message: Schema.String,	14	readonly message: string;
15	cause: Schema.optional(Schema.Unknown),	15	readonly cause?: unknown;
16	},	16	}> {}
17	) {}
18		17
19	export class SecretNotFoundError extends Schema.TaggedError<SecretNotFoundError>()(	18	export class SecretNotFoundError extends Schema.TaggedError<SecretNotFoundError>()(
20	"SecretNotFoundError",	19	"SecretNotFoundError",

packages/plugins/google-discovery/src/sdk/document.ts+2−4

 });
 type DiscoveryDocument = typeof DiscoveryDocumentModel.Type;
-const toParseError = (message: string, error: unknown) =>
+const toParseError = (message: string, cause: unknown) =>
-  new GoogleDiscoveryParseError({ message, error });
+  new GoogleDiscoveryParseError({ message, cause });
 const decodeUnknownWith = <A>(
   message: string,
     if (!method.httpMethod) {
       return yield* new GoogleDiscoveryParseError({
         message: `Google Discovery method '${methodId}' is missing httpMethod`,
-        error: new Error(`Missing httpMethod for ${methodId}`),
       });
     }
     return yield* new GoogleDiscoveryParseError({
       message:
         "Google Discovery document is missing one of: name, version, rootUrl",
-      error: new Error("Invalid document"),
     });
   }

packages/plugins/google-discovery/src/sdk/errors.ts+13−14

@@ -1,21 +1,20 @@
1	import { Schema } from "effect";	1	import { Data, Schema } from "effect";
		2	import type { Option } from "effect";
2		3
3	export class GoogleDiscoveryParseError extends Schema.TaggedError<GoogleDiscoveryParseError>()(	4	export class GoogleDiscoveryParseError extends Data.TaggedError(
4	"GoogleDiscoveryParseError",	5	"GoogleDiscoveryParseError",
5	{	6	)<{
6	message: Schema.String,	7	readonly message: string;
7	error: Schema.Defect,	8	readonly cause?: unknown;
8	},	9	}> {}
9	) {}
10		10
11	export class GoogleDiscoveryInvocationError extends Schema.TaggedError<GoogleDiscoveryInvocationError>()(	11	export class GoogleDiscoveryInvocationError extends Data.TaggedError(
12	"GoogleDiscoveryInvocationError",	12	"GoogleDiscoveryInvocationError",
13	{	13	)<{
14	message: Schema.String,	14	readonly message: string;
15	statusCode: Schema.optionalWith(Schema.Number, { as: "Option" }),	15	readonly statusCode: Option.Option<number>;
16	error: Schema.Defect,	16	readonly cause?: unknown;
17	},	17	}> {}
18	) {}
19		18
20	export class GoogleDiscoveryOAuthError extends Schema.TaggedError<GoogleDiscoveryOAuthError>()(	19	export class GoogleDiscoveryOAuthError extends Schema.TaggedError<GoogleDiscoveryOAuthError>()(
21	"GoogleDiscoveryOAuthError",	20	"GoogleDiscoveryOAuthError",

packages/plugins/google-discovery/src/sdk/invoke.ts+1−2

         return yield* new GoogleDiscoveryInvocationError({
           message: `Missing required ${parameter.location} parameter: ${parameter.name}`,
           statusCode: Option.none(),
-          error: undefined,
         });
       }
       continue;
         new GoogleDiscoveryInvocationError({
           message: `HTTP request failed: ${err.message}`,
           statusCode: Option.none(),
-          error: err,
+          cause: err,
         }),
     ),
   );

packages/plugins/graphql/src/sdk/errors.ts+8−9

-import { Schema } from "effect";
+import { Data, Schema } from "effect";
+import type { Option } from "effect";
 export class GraphqlIntrospectionError extends Schema.TaggedError<GraphqlIntrospectionError>()(
   "GraphqlIntrospectionError",
   {
     message: Schema.String,
-    error: Schema.Defect,
   },
 ) {}
   },
 ) {}
-export class GraphqlInvocationError extends Schema.TaggedError<GraphqlInvocationError>()(
+export class GraphqlInvocationError extends Data.TaggedError(
   "GraphqlInvocationError",
-  {
+)<{
-    message: Schema.String,
+  readonly message: string;
-    statusCode: Schema.optionalWith(Schema.Number, { as: "Option" }),
+  readonly statusCode: Option.Option<number>;
-    error: Schema.Defect,
+  readonly cause?: unknown;
-  },
+}> {}
-) {}

packages/plugins/graphql/src/sdk/introspect.ts+9−11

   }
   const response = yield* client.execute(request).pipe(
+    Effect.tapErrorCause((cause) =>
+      Effect.logError("graphql introspection request failed", cause),
+    ),
     Effect.mapError(
       (err) =>
         new GraphqlIntrospectionError({
           message: `Failed to reach GraphQL endpoint: ${err.message}`,
-          error: err,
         }),
     ),
   );
   if (response.status !== 200) {
-    const body = yield* response.text.pipe(Effect.catchAll(() => Effect.succeed("")));
     return yield* new GraphqlIntrospectionError({
-      message: `Introspection failed with status ${response.status}: ${body}`,
+      message: `Introspection failed with status ${response.status}`,
-      error: undefined,
     });
   }
   const raw = yield* response.json.pipe(
+    Effect.tapErrorCause((cause) =>
+      Effect.logError("graphql introspection JSON parse failed", cause),
+    ),
     Effect.mapError(
-      (err) =>
+      () =>
         new GraphqlIntrospectionError({
           message: `Failed to parse introspection response as JSON`,
-          error: err,
         }),
     ),
   );
   if (json.errors && Array.isArray(json.errors) && json.errors.length > 0) {
     return yield* new GraphqlIntrospectionError({
-      // @effect-diagnostics-next-line preferSchemaOverJson:off
+      message: `Introspection returned ${json.errors.length} error(s)`,
-      message: `Introspection returned errors: ${JSON.stringify(json.errors)}`,
-      error: undefined,
     });
   }
   if (!json.data?.__schema) {
     return yield* new GraphqlIntrospectionError({
       message: "Introspection response missing __schema",
-      error: undefined,
     });
   }
     catch: (err) =>
       new GraphqlIntrospectionError({
         message: `Failed to parse introspection JSON: ${err instanceof Error ? err.message : String(err)}`,
-        error: err,
       }),
   });

packages/plugins/graphql/src/sdk/invoke.ts+1−1

@@ -109,7 +109,7 @@ export const invoke = Effect.fn("GraphQL.invoke")(function* ( · 108 unmodified lines
109	new GraphqlInvocationError({	109	new GraphqlInvocationError({
110	message: `GraphQL request failed: ${err.message}`,	110	message: `GraphQL request failed: ${err.message}`,
111	statusCode: Option.none(),	111	statusCode: Option.none(),
112	error: err,	112	cause: err,
113	}),	113	}),
114	),	114	),
115	);	115	);

packages/plugins/keychain/src/errors.ts+5−8

@@ -1,9 +1,6 @@
1	import { Schema } from "effect";	1	import { Data } from "effect";
2		2
3	export class KeychainError extends Schema.TaggedError<KeychainError>()(	3	export class KeychainError extends Data.TaggedError("KeychainError")<{
4	"KeychainError",	4	readonly message: string;
5	{	5	readonly cause?: unknown;
6	message: Schema.String,	6	}> {}
7	cause: Schema.optional(Schema.Unknown),
8	},
9	) {}

packages/plugins/openapi/src/sdk/errors.ts+8−9

-import { Schema } from "effect";
+import { Data, Schema } from "effect";
+import type { Option } from "effect";
 export class OpenApiParseError extends Schema.TaggedError<OpenApiParseError>()(
   "OpenApiParseError",
   {
     message: Schema.String,
-    error: Schema.Defect,
   },
 ) {}
   },
 ) {}
-export class OpenApiInvocationError extends Schema.TaggedError<OpenApiInvocationError>()(
+export class OpenApiInvocationError extends Data.TaggedError(
   "OpenApiInvocationError",
-  {
+)<{
-    message: Schema.String,
+  readonly message: string;
-    statusCode: Schema.optionalWith(Schema.Number, { as: "Option" }),
+  readonly statusCode: Option.Option<number>;
-    error: Schema.Defect,
+  readonly cause?: unknown;
-  },
+}> {}
-) {}

packages/plugins/openapi/src/sdk/invoke.ts+1−3

         return yield* new OpenApiInvocationError({
           message: `Missing required path parameter: ${param.name}`,
           statusCode: Option.none(),
-          error: undefined,
         });
       }
       continue;
     return yield* new OpenApiInvocationError({
       message: `Unresolved path parameters: ${[...new Set(unresolved)].join(", ")}`,
       statusCode: Option.none(),
-      error: undefined,
     });
   }
         new OpenApiInvocationError({
           message: `HTTP request failed: ${err.message}`,
           statusCode: Option.none(),
-          error: err,
+          cause: err,
         }),
     ),
   );

packages/plugins/openapi/src/sdk/parse.ts+0−1

@@ -20,7 +20,6 @@ export const parse = Effect.fn("OpenApi.parse")(function* (input: string) { · 19 unmodified lines
20	catch: (error) =>	20	catch: (error) =>
21	new OpenApiParseError({	21	new OpenApiParseError({
22	message: `Failed to parse OpenAPI document: ${error instanceof Error ? error.message : String(error)}`,	22	message: `Failed to parse OpenAPI document: ${error instanceof Error ? error.message : String(error)}`,
23	error,
24	}),	23	}),
25	});	24	});
26		25