[codex] Structure APNs delivery queue errors (#3326)

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

Author: juliusmarminge

infra/relay/src/agentActivity/ApnsDeliveryQueue.test.ts

@@ -0,0 +1,79 @@
+import * as NodeCryptoLayer from "@effect/platform-node/NodeCrypto";
+import { describe, expect, it } from "@effect/vitest";
+import * as Cloudflare from "alchemy/Cloudflare";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+
+import * as RelayConfiguration from "../Config.ts";
+import * as ApnsDeliveryQueue from "./ApnsDeliveryQueue.ts";
+
+const config: RelayConfiguration.RelayConfiguration["Service"] = {
+  relayIssuer: "https://relay.example.com",
+  apns: {
+    teamId: "team-1",
+    keyId: "key-1",
+    privateKey: Redacted.make("apns-private-key"),
+    bundleId: "com.t3tools.test",
+    environment: "sandbox",
+  },
+  clerkSecretKey: Redacted.make("clerk-secret"),
+  clerkPublishableKey: "pk_test_test",
+  clerkJwtAudience: "t3-code-relay",
+  apnsDeliveryJobSigningSecret: Redacted.make("apns-job-secret"),
+  cloudMintPrivateKey: Redacted.make("cloud-private-key"),
+  cloudMintPublicKey: "cloud-public-key",
+  managedEndpointBaseDomain: undefined,
+  managedEndpointNamespace: undefined,
+};
+
+describe("ApnsDeliveryQueue", () => {
+  it.effect("preserves job identity and the queue sender cause", () => {
+    const cause = new Error("queue unavailable");
+    const senderCause = new Cloudflare.QueueSendError({
+      message: cause.message,
+      cause,
+    });
+    const layer = ApnsDeliveryQueue.layer.pipe(
+      Layer.provide(NodeCryptoLayer.layer),
+      Layer.provide(RelayConfiguration.layer(config)),
+      Layer.provide(
+        Layer.succeed(ApnsDeliveryQueue.ApnsDeliveryQueueSender, {
+          send: () => Effect.fail(senderCause),
+        }),
+      ),
+    );
+
+    return Effect.gen(function* () {
+      const queue = yield* ApnsDeliveryQueue.ApnsDeliveryQueue;
+      const error = yield* Effect.flip(
+        queue.enqueuePushNotification({
+          userId: "user-1",
+          deviceId: "device-1",
+          token: "push-token",
+          notification: {
+            title: "Thread",
+            body: "Input: Project",
+            environmentId: "env-1",
+            threadId: "thread-1",
+            deepLink: "/threads/env-1/thread-1",
+          },
+        }),
+      );
+
+      expect(error).toMatchObject({
+        _tag: "ApnsDeliveryQueueSendError",
+        operation: "send",
+        jobId: expect.any(String),
+        kind: "push_notification",
+        userId: "user-1",
+        deviceId: "device-1",
+        cause: senderCause,
+      });
+      expect(senderCause.cause).toBe(cause);
+      expect(error.message).toBe(
+        "Failed to enqueue APNs push notification delivery during send for device device-1.",
+      );
+    }).pipe(Effect.provide(layer));
+  });
+});

infra/relay/src/agentActivity/ApnsDeliveryQueue.ts

@@ -7,7 +7,10 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
 
-import type { RelayDeliveryResult } from "@t3tools/contracts/relay";
+import {
+  RelayDeliveryKind as RelayDeliveryKindSchema,
+  type RelayDeliveryResult,
+} from "@t3tools/contracts/relay";
 
 import {
   sanitizeAgentActivityAggregateState,
@@ -24,10 +27,17 @@ import * as RelayConfiguration from "../Config.ts";
 
 export class ApnsDeliveryQueueSendError extends Schema.TaggedErrorClass<ApnsDeliveryQueueSendError>()(
   "ApnsDeliveryQueueSendError",
-  { cause: Schema.Defect() },
+  {
+    operation: Schema.Literals(["generate-job-id", "send"]),
+    jobId: Schema.NullOr(Schema.String),
+    kind: RelayDeliveryKindSchema,
+    userId: Schema.String,
+    deviceId: Schema.String,
+    cause: Schema.Defect(),
+  },
 ) {
   override get message(): string {
-    return "Failed to enqueue APNs delivery";
+    return `Failed to enqueue APNs ${this.kind.replaceAll("_", " ")} delivery during ${this.operation} for device ${this.deviceId}.`;
   }
 }
 
@@ -36,7 +46,7 @@ export type ApnsDeliveryQueueError = ApnsDeliveryQueueSendError;
 export class ApnsDeliveryQueueSender extends Context.Service<
   ApnsDeliveryQueueSender,
   {
-    readonly send: (body: SignedApnsDeliveryJob) => Effect.Effect<void, ApnsDeliveryQueueSendError>;
+    readonly send: (body: SignedApnsDeliveryJob) => Effect.Effect<void, Cloudflare.QueueSendError>;
   }
 >()("t3code-relay/agentActivity/ApnsDeliveryQueue/ApnsDeliveryQueueSender") {}
 
@@ -73,7 +83,17 @@ export const make = Effect.gen(function* () {
         });
         const now = yield* DateTime.now;
         const jobId = yield* crypto.randomUUIDv4.pipe(
-          Effect.mapError((cause) => new ApnsDeliveryQueueSendError({ cause })),
+          Effect.mapError(
+            (cause) =>
+              new ApnsDeliveryQueueSendError({
+                operation: "generate-job-id",
+                jobId: null,
+                kind: input.kind,
+                userId: input.userId,
+                deviceId: input.deviceId,
+                cause,
+              }),
+          ),
         );
         yield* Effect.annotateCurrentSpan({ "relay.delivery.job_id": jobId });
         const payload = makeApnsDeliveryJobPayload({
@@ -88,7 +108,19 @@ export const make = Effect.gen(function* () {
           secret: config.apnsDeliveryJobSigningSecret,
           payload,
         });
-        yield* sender.send(signed);
+        yield* sender.send(signed).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ApnsDeliveryQueueSendError({
+                operation: "send",
+                jobId,
+                kind: input.kind,
+                userId: input.userId,
+                deviceId: input.deviceId,
+                cause,
+              }),
+          ),
+        );
         return {
           deviceId: input.deviceId,
           kind: input.kind,
@@ -110,7 +142,17 @@ export const make = Effect.gen(function* () {
         });
         const now = yield* DateTime.now;
         const jobId = yield* crypto.randomUUIDv4.pipe(
-          Effect.mapError((cause) => new ApnsDeliveryQueueSendError({ cause })),
+          Effect.mapError(
+            (cause) =>
+              new ApnsDeliveryQueueSendError({
+                operation: "generate-job-id",
+                jobId: null,
+                kind: "push_notification",
+                userId: input.userId,
+                deviceId: input.deviceId,
+                cause,
+              }),
+          ),
         );
         yield* Effect.annotateCurrentSpan({ "relay.delivery.job_id": jobId });
         const payload = makeApnsDeliveryJobPayload({
@@ -128,7 +170,19 @@ export const make = Effect.gen(function* () {
           secret: config.apnsDeliveryJobSigningSecret,
           payload,
         });
-        yield* sender.send(signed);
+        yield* sender.send(signed).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ApnsDeliveryQueueSendError({
+                operation: "send",
+                jobId,
+                kind: "push_notification",
+                userId: input.userId,
+                deviceId: input.deviceId,
+                cause,
+              }),
+          ),
+        );
         return {
           deviceId: input.deviceId,
           kind: "push_notification" as const,
@@ -155,10 +209,9 @@ export const layerCloudflareQueues = (
         ApnsDeliveryQueueSender,
         ApnsDeliveryQueueSender.of({
           send: (body) =>
-            sender.send(body).pipe(
-              Effect.mapError((cause) => new ApnsDeliveryQueueSendError({ cause })),
-              Effect.provideService(Alchemy.RuntimeContext, alchemyRuntimeContext),
-            ),
+            sender
+              .send(body)
+              .pipe(Effect.provideService(Alchemy.RuntimeContext, alchemyRuntimeContext)),
         }),
       ),
     ),