refactor(appview): consolidate three identical error handlers into handleRouteError (#74)

handleReadError, handleWriteError, and handleSecurityCheckError had
byte-for-byte identical implementations. Replaced with a single
handleRouteError function, eliminating ~250 lines of duplicated code
across the error handler and its tests. Updated all 10 call sites.

https://claude.ai/code/session_018SH9pay3PqGo9JDdAv3iRj

Co-authored-by: Claude <[e-mail]>

apps/appview/src/lib/__tests__/route-errors.test.ts

···
 import { describe, it, expect, vi, afterEach } from "vitest";
 import { Hono } from "hono";
 import {
-  handleReadError,
-  handleWriteError,
-  handleSecurityCheckError,
+  handleRouteError,
   safeParseJsonBody,
   getForumAgentOrError,
 } from "../route-errors.js";
···
   return app;
 }
 
-// ─── handleReadError ──────────────────────────────────────────────────────────
+// ─── handleRouteError ─────────────────────────────────────────────────────────
 
-describe("handleReadError", () => {
+describe("handleRouteError", () => {
   it("returns 503 for network errors", async () => {
     const app = makeApp((c) =>
-      handleReadError(c, new Error("fetch failed"), "Failed to read resource", {
+      handleRouteError(c, new Error("fetch failed"), "Failed to read resource", {
         operation: "GET /test",
         logger: createMockLogger(),
       })
···
 
   it("returns 503 for database errors", async () => {
     const app = makeApp((c) =>
-      handleReadError(c, new Error("database query failed"), "Failed to read resource", {
+      handleRouteError(c, new Error("database query failed"), "Failed to read resource", {
         operation: "GET /test",
         logger: createMockLogger(),
       })
···
 
   it("returns 500 for unexpected errors", async () => {
     const app = makeApp((c) =>
-      handleReadError(c, new Error("Something went wrong"), "Failed to read resource", {
+      handleRouteError(c, new Error("Something went wrong"), "Failed to read resource", {
         operation: "GET /test",
         logger: createMockLogger(),
       })
···
   it("logs structured context on error", async () => {
     const mockLogger = createMockLogger();
     const app = makeApp((c) =>
-      handleReadError(c, new Error("boom"), "Failed to fetch things", {
+      handleRouteError(c, new Error("boom"), "Failed to fetch things", {
         operation: "GET /test",
         logger: mockLogger,
         resourceId: "123",
···
     const mockLogger = createMockLogger();
     const programmingError = new TypeError("Cannot read property of undefined");
     const app = makeApp((c) =>
-      handleReadError(c, programmingError, "Failed to read resource", {
+      handleRouteError(c, programmingError, "Failed to read resource", {
         operation: "GET /test",
         logger: mockLogger,
       })
···
     expect(mockLogger.error).not.toHaveBeenCalledWith(
       "Failed to read resource",
       expect.any(Object)
-    );
-  });
-});
-
-// ─── handleWriteError ─────────────────────────────────────────────────────────
-
-describe("handleWriteError", () => {
-  it("returns 503 for network errors", async () => {
-    const app = makeApp((c) =>
-      handleWriteError(c, new Error("fetch failed"), "Failed to create thing", {
-        operation: "POST /test",
-        logger: createMockLogger(),
-      })
-    );
-
-    const res = await app.request("/test", { method: "POST" });
-
-    expect(res.status).toBe(503);
-    const data = await res.json();
-    expect(data.error).toBe(
-      "Unable to reach external service. Please try again later."
     );
   });
 
-  it("returns 503 for database errors", async () => {
-    const app = makeApp((c) =>
-      handleWriteError(c, new Error("database connection lost"), "Failed to create thing", {
-        operation: "POST /test",
-        logger: createMockLogger(),
-      })
-    );
-
-    const res = await app.request("/test", { method: "POST" });
-
-    expect(res.status).toBe(503);
-    const data = await res.json();
-    expect(data.error).toBe(
-      "Database temporarily unavailable. Please try again later."
-    );
-  });
-
-  it("returns 500 for unexpected errors", async () => {
+  it("works for write-path errors (POST endpoints)", async () => {
     const app = makeApp((c) =>
-      handleWriteError(c, new Error("Something unexpected"), "Failed to create thing", {
-        operation: "POST /test",
-        logger: createMockLogger(),
-      })
-    );
-
-    const res = await app.request("/test", { method: "POST" });
-
-    expect(res.status).toBe(500);
-    const data = await res.json();
-    expect(data.error).toBe("Failed to create thing. Please contact support if this persists.");
-  });
-
-  it("re-throws TypeError (programming error) and logs CRITICAL", async () => {
-    const mockLogger = createMockLogger();
-    const programmingError = new TypeError("Cannot read property of null");
-    const app = makeApp((c) =>
-      handleWriteError(c, programmingError, "Failed to create thing", {
-        operation: "POST /test",
-        logger: mockLogger,
-      })
-    );
-
-    const res = await app.request("/test", { method: "POST" });
-    expect(res.status).toBe(500);
-
-    expect(mockLogger.error).toHaveBeenCalledWith(
-      "CRITICAL: Programming error in POST /test",
-      expect.objectContaining({
+      handleRouteError(c, new Error("fetch failed"), "Failed to create thing", {
         operation: "POST /test",
-        error: "Cannot read property of null",
-        stack: expect.any(String),
-      })
-    );
-
-    expect(mockLogger.error).not.toHaveBeenCalledWith(
-      "Failed to create thing",
-      expect.any(Object)
-    );
-  });
-});
-
-// ─── handleSecurityCheckError ─────────────────────────────────────────────────
-
-describe("handleSecurityCheckError", () => {
-  it("returns 503 for network errors", async () => {
-    const app = makeApp((c) =>
-      handleSecurityCheckError(c, new Error("fetch failed"), "Unable to verify access", {
-        operation: "POST /test - security check",
         logger: createMockLogger(),
       })
     );
···
     );
   });
 
-  it("returns 503 for database errors", async () => {
-    const app = makeApp((c) =>
-      handleSecurityCheckError(c, new Error("sql query failed"), "Unable to verify access", {
-        operation: "POST /test - security check",
-        logger: createMockLogger(),
-      })
-    );
-
-    const res = await app.request("/test", { method: "POST" });
-
-    expect(res.status).toBe(503);
-    const data = await res.json();
-    expect(data.error).toBe(
-      "Database temporarily unavailable. Please try again later."
-    );
-  });
-
-  it("returns 500 for unexpected errors (fail closed)", async () => {
+  it("works for security check errors (fail closed)", async () => {
     const app = makeApp((c) =>
-      handleSecurityCheckError(c, new Error("Something unexpected"), "Unable to verify access", {
+      handleRouteError(c, new Error("Something unexpected"), "Unable to verify access", {
         operation: "POST /test - security check",
         logger: createMockLogger(),
       })
···
     const data = await res.json();
     expect(data.error).toBe(
       "Unable to verify access. Please contact support if this persists."
-    );
-  });
-
-  it("re-throws TypeError (programming error) and logs CRITICAL", async () => {
-    const mockLogger = createMockLogger();
-    const programmingError = new TypeError("Cannot read property of undefined");
-    const app = makeApp((c) =>
-      handleSecurityCheckError(c, programmingError, "Unable to verify access", {
-        operation: "POST /test - security check",
-        logger: mockLogger,
-      })
-    );
-
-    const res = await app.request("/test", { method: "POST" });
-    expect(res.status).toBe(500);
-
-    expect(mockLogger.error).toHaveBeenCalledWith(
-      "CRITICAL: Programming error in POST /test - security check",
-      expect.objectContaining({
-        operation: "POST /test - security check",
-        error: "Cannot read property of undefined",
-        stack: expect.any(String),
-      })
-    );
-
-    expect(mockLogger.error).not.toHaveBeenCalledWith(
-      "Unable to verify access",
-      expect.any(Object)
     );
   });
 });

apps/appview/src/lib/route-errors.ts

···
 }
 
 /**
- * Handle errors in read-path route handlers (GET endpoints).
+ * Handle errors in route handlers and security checks.
  *
  * 1. Re-throws programming errors (TypeError, ReferenceError, SyntaxError)
  * 2. Logs the error with structured context
···
  * @param userMessage - User-facing error message (e.g., "Failed to retrieve forum metadata")
  * @param ctx - Structured logging context
  */
-export function handleReadError(
-  c: Context,
-  error: unknown,
-  userMessage: string,
-  ctx: ErrorContext
-): Response {
-  if (isProgrammingError(error)) {
-    const { message, stack } = formatError(error);
-    ctx.logger.error(`CRITICAL: Programming error in ${ctx.operation}`, {
-      ...ctx,
-      error: message,
-      stack,
-    });
-    throw error;
-  }
-
-  ctx.logger.error(userMessage, {
-    ...ctx,
-    error: formatError(error).message,
-  });
-
-  if (error instanceof Error && isNetworkError(error)) {
-    return c.json(
-      { error: "Unable to reach external service. Please try again later." },
-      503
-    ) as unknown as Response;
-  }
-
-  if (error instanceof Error && isDatabaseError(error)) {
-    return c.json(
-      { error: "Database temporarily unavailable. Please try again later." },
-      503
-    ) as unknown as Response;
-  }
-
-  return c.json(
-    { error: `${userMessage}. Please contact support if this persists.` },
-    500
-  ) as unknown as Response;
-}
-
-/**
- * Handle errors in write-path route handlers (POST/PUT/DELETE endpoints).
- *
- * 1. Re-throws programming errors (TypeError, ReferenceError, SyntaxError)
- * 2. Logs the error with structured context
- * 3. Classifies the error and returns the appropriate HTTP status:
- *    - 503 for network errors (PDS unreachable, user should retry)
- *    - 503 for database errors (temporary, user should retry)
- *    - 500 for unexpected errors (server bug, needs investigation)
- *
- * @param c - Hono context
- * @param error - The caught error
- * @param userMessage - User-facing error message (e.g., "Failed to create topic")
- * @param ctx - Structured logging context
- */
-export function handleWriteError(
-  c: Context,
-  error: unknown,
-  userMessage: string,
-  ctx: ErrorContext
-): Response {
-  if (isProgrammingError(error)) {
-    const { message, stack } = formatError(error);
-    ctx.logger.error(`CRITICAL: Programming error in ${ctx.operation}`, {
-      ...ctx,
-      error: message,
-      stack,
-    });
-    throw error;
-  }
-
-  ctx.logger.error(userMessage, {
-    ...ctx,
-    error: formatError(error).message,
-  });
-
-  if (error instanceof Error && isNetworkError(error)) {
-    return c.json(
-      { error: "Unable to reach external service. Please try again later." },
-      503
-    ) as unknown as Response;
-  }
-
-  if (error instanceof Error && isDatabaseError(error)) {
-    return c.json(
-      { error: "Database temporarily unavailable. Please try again later." },
-      503
-    ) as unknown as Response;
-  }
-
-  return c.json(
-    { error: `${userMessage}. Please contact support if this persists.` },
-    500
-  ) as unknown as Response;
-}
-
-/**
- * Handle errors in security-critical checks (ban check, lock check, permission verification).
- *
- * Fail-closed: returns an error response that denies the operation.
- *
- * 1. Re-throws programming errors
- * 2. Returns 503 for network errors (external service unreachable, user should retry)
- * 3. Returns 503 for database errors (temporary, user should retry)
- * 4. Returns 500 for unexpected errors (denying access)
- *
- * @param c - Hono context
- * @param error - The caught error
- * @param userMessage - User-facing error message (e.g., "Unable to verify permissions")
- * @param ctx - Structured logging context
- */
-export function handleSecurityCheckError(
+export function handleRouteError(
   c: Context,
   error: unknown,
   userMessage: string,

apps/appview/src/middleware/require-not-banned.ts

···
 import type { Context, Next } from "hono";
 import type { AppContext } from "../lib/app-context.js";
 import type { Variables } from "../types.js";
-import { handleSecurityCheckError } from "../lib/route-errors.js";
+import { handleRouteError } from "../lib/route-errors.js";
 import { getActiveBans } from "../routes/helpers.js";
 
 /**
···
         return c.json({ error: "You are banned from this forum" }, 403);
       }
     } catch (error) {
-      return handleSecurityCheckError(c, error, "Unable to verify ban status", {
+      return handleRouteError(c, error, "Unable to verify ban status", {
         operation: `${c.req.method} ${c.req.path} - ban check`,
         logger: ctx.logger,
         userId: user.did,

apps/appview/src/routes/admin.ts

···
 import { BackfillStatus } from "../lib/backfill-manager.js";
 import { CursorManager } from "../lib/cursor-manager.js";
 import {
-  handleReadError,
-  handleWriteError,
+  handleRouteError,
   safeParseJsonBody,
   getForumAgentOrError,
 } from "../lib/route-errors.js";
···
             targetDid,
           });
         } catch (error) {
-          return handleWriteError(c, error, "Failed to assign role", {
+          return handleRouteError(c, error, "Failed to assign role", {
             operation: "POST /api/admin/members/:did/role",
             logger: ctx.logger,
             targetDid,
···
           });
         }
       } catch (error) {
-        return handleReadError(c, error, "Failed to process role assignment", {
+        return handleRouteError(c, error, "Failed to process role assignment", {
           operation: "POST /api/admin/members/:did/role",
           logger: ctx.logger,
           targetDid,
···
 
         return c.json({ roles: rolesWithPermissions });
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve roles", {
+        return handleRouteError(c, error, "Failed to retrieve roles", {
           operation: "GET /api/admin/roles",
           logger: ctx.logger,
         });
···
           isTruncated: membersList.length === 100,
         });
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve members", {
+        return handleRouteError(c, error, "Failed to retrieve members", {
           operation: "GET /api/admin/members",
           logger: ctx.logger,
         });
···
         permissions,
       });
     } catch (error) {
-      return handleReadError(c, error, "Failed to retrieve your membership", {
+      return handleRouteError(c, error, "Failed to retrieve your membership", {
         operation: "GET /api/admin/members/me",
         logger: ctx.logger,
         did: user.did,
···
           errorMessage: row.errorMessage,
         });
       } catch (error) {
-        return handleReadError(c, error, "Failed to fetch backfill progress", {
+        return handleRouteError(c, error, "Failed to fetch backfill progress", {
           operation: "GET /api/admin/backfill/:id",
           logger: ctx.logger,
           id,
···
           })),
         });
       } catch (error) {
-        return handleReadError(c, error, "Failed to fetch backfill errors", {
+        return handleRouteError(c, error, "Failed to fetch backfill errors", {
           operation: "GET /api/admin/backfill/:id/errors",
           logger: ctx.logger,
           id,

apps/appview/src/routes/boards.ts

···
 import { boards, categories, posts, users } from "@atbb/db";
 import { asc, count, eq, and, desc, isNull } from "drizzle-orm";
 import { serializeBoard, parseBigIntParam, serializePost } from "./helpers.js";
-import { handleReadError } from "../lib/route-errors.js";
+import { handleRouteError } from "../lib/route-errors.js";
 
 /**
  * Factory function that creates board routes with access to app context.
···
           boards: allBoards.map(({ boards: board }) => serializeBoard(board)),
         });
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve boards", {
+        return handleRouteError(c, error, "Failed to retrieve boards", {
           operation: "GET /api/boards",
           logger: ctx.logger,
         });
···
 
         return c.json(serializeBoard(board));
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve board", {
+        return handleRouteError(c, error, "Failed to retrieve board", {
           operation: "GET /api/boards/:id",
           logger: ctx.logger,
           boardId: raw,
···
           limit,
         });
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve topics", {
+        return handleRouteError(c, error, "Failed to retrieve topics", {
           operation: "GET /api/boards/:id/topics",
           logger: ctx.logger,
           boardId: id,

apps/appview/src/routes/categories.ts

···
 import { categories, boards } from "@atbb/db";
 import { eq, asc } from "drizzle-orm";
 import { serializeCategory, serializeBoard, parseBigIntParam } from "./helpers.js";
-import { handleReadError } from "../lib/route-errors.js";
+import { handleRouteError } from "../lib/route-errors.js";
 
 /**
  * Factory function that creates category routes with access to app context.
···
           categories: allCategories.map(serializeCategory),
         });
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve categories", {
+        return handleRouteError(c, error, "Failed to retrieve categories", {
           operation: "GET /api/categories",
           logger: ctx.logger,
         });
···
 
         return c.json(serializeCategory(category));
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve category", {
+        return handleRouteError(c, error, "Failed to retrieve category", {
           operation: "GET /api/categories/:id",
           logger: ctx.logger,
           categoryId: raw,
···
           boards: categoryBoards.map(serializeBoard),
         });
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve boards", {
+        return handleRouteError(c, error, "Failed to retrieve boards", {
           operation: "GET /api/categories/:id/boards",
           logger: ctx.logger,
           categoryId: id,

apps/appview/src/routes/forum.ts

···
 import { forums } from "@atbb/db";
 import { eq } from "drizzle-orm";
 import { serializeForum } from "./helpers.js";
-import { handleReadError } from "../lib/route-errors.js";
+import { handleRouteError } from "../lib/route-errors.js";
 
 /**
  * Factory function that creates forum routes with access to app context.
···
 
       return c.json(serializeForum(forum));
     } catch (error) {
-      return handleReadError(c, error, "Failed to retrieve forum metadata", {
+      return handleRouteError(c, error, "Failed to retrieve forum metadata", {
         operation: "GET /api/forum",
         logger: ctx.logger,
       });

apps/appview/src/routes/mod.ts

···
 import { requirePermission } from "../middleware/permissions.js";
 import { isProgrammingError } from "../lib/errors.js";
 import {
-  handleWriteError,
-  handleReadError,
+  handleRouteError,
   safeParseJsonBody,
   getForumAgentOrError,
 } from "../lib/route-errors.js";
···
           return c.json({ error: "Target user not found" }, 404);
         }
       } catch (error) {
-        return handleReadError(c, error, "Failed to check user membership", {
+        return handleRouteError(c, error, "Failed to check user membership", {
           operation: "POST /api/mod/ban",
           logger: ctx.logger,
           targetDid,
···
           alreadyActive: false,
         });
       } catch (error) {
-        return handleWriteError(c, error, "Failed to record moderation action", {
+        return handleRouteError(c, error, "Failed to record moderation action", {
           operation: "POST /api/mod/ban",
           logger: ctx.logger,
           moderatorDid: user.did,
···
           return c.json({ error: "Target user not found" }, 404);
         }
       } catch (error) {
-        return handleReadError(c, error, "Failed to check user membership", {
+        return handleRouteError(c, error, "Failed to check user membership", {
           operation: "DELETE /api/mod/ban/:did",
           logger: ctx.logger,
           targetDid,
···
           alreadyActive: false,
         });
       } catch (error) {
-        return handleWriteError(c, error, "Failed to record moderation action", {
+        return handleRouteError(c, error, "Failed to record moderation action", {
           operation: "DELETE /api/mod/ban/:did",
           logger: ctx.logger,
           moderatorDid: user.did,
···
 
         topic = result;
       } catch (error) {
-        return handleReadError(c, error, "Failed to check topic", {
+        return handleRouteError(c, error, "Failed to check topic", {
           operation: "POST /api/mod/lock",
           logger: ctx.logger,
           topicId,
···
           alreadyActive: false,
         });
       } catch (error) {
-        return handleWriteError(c, error, "Failed to record moderation action", {
+        return handleRouteError(c, error, "Failed to record moderation action", {
           operation: "POST /api/mod/lock",
           logger: ctx.logger,
           moderatorDid: user.did,
···
 
         topic = result;
       } catch (error) {
-        return handleReadError(c, error, "Failed to check topic", {
+        return handleRouteError(c, error, "Failed to check topic", {
           operation: "DELETE /api/mod/lock/:topicId",
           logger: ctx.logger,
           topicId: topicIdParam,
···
           alreadyActive: false,
         });
       } catch (error) {
-        return handleWriteError(c, error, "Failed to record moderation action", {
+        return handleRouteError(c, error, "Failed to record moderation action", {
           operation: "DELETE /api/mod/lock/:topicId",
           logger: ctx.logger,
           moderatorDid: user.did,
···
 
         post = result;
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve post", {
+        return handleRouteError(c, error, "Failed to retrieve post", {
           operation: "POST /api/mod/hide",
           logger: ctx.logger,
           postId,
···
           alreadyActive: false,
         }, 200);
       } catch (error) {
-        return handleWriteError(c, error, "Failed to record moderation action", {
+        return handleRouteError(c, error, "Failed to record moderation action", {
           operation: "POST /api/mod/hide",
           logger: ctx.logger,
           moderatorDid: user.did,
···
 
         post = result;
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve post", {
+        return handleRouteError(c, error, "Failed to retrieve post", {
           operation: "DELETE /api/mod/hide/:postId",
           logger: ctx.logger,
           postId: postIdParam,
···
           alreadyActive: false,
         }, 200);
       } catch (error) {
-        return handleWriteError(c, error, "Failed to record moderation action", {
+        return handleRouteError(c, error, "Failed to record moderation action", {
           operation: "DELETE /api/mod/hide/:postId",
           logger: ctx.logger,
           moderatorDid: user.did,

apps/appview/src/routes/posts.ts

···
 import { requireAuth } from "../middleware/auth.js";
 import { requirePermission } from "../middleware/permissions.js";
 import { requireNotBanned } from "../middleware/require-not-banned.js";
-import { handleWriteError, handleSecurityCheckError, safeParseJsonBody } from "../lib/route-errors.js";
+import { handleRouteError, safeParseJsonBody } from "../lib/route-errors.js";
 import {
   validatePostText,
   parseBigIntParam,
···
         return c.json({ error: "This topic is locked and not accepting new replies" }, 403);
       }
     } catch (error) {
-      return handleSecurityCheckError(c, error, "Unable to verify topic status", {
+      return handleRouteError(c, error, "Unable to verify topic status", {
         operation: "POST /api/posts - lock check",
         logger: ctx.logger,
         userId: user.did,
···
     try {
       postsMap = await getPostsByIds(ctx.db, [rootId, parentId]);
     } catch (error) {
-      return handleWriteError(c, error, "Failed to look up posts for reply", {
+      return handleRouteError(c, error, "Failed to look up posts for reply", {
         operation: "POST /api/posts - post lookup",
         logger: ctx.logger,
         userId: user.did,
···
         201
       );
     } catch (error) {
-      return handleWriteError(c, error, "Failed to create post", {
+      return handleRouteError(c, error, "Failed to create post", {
         operation: "POST /api/posts",
         logger: ctx.logger,
         userId: user.did,

apps/appview/src/routes/topics.ts

···
 import { requirePermission } from "../middleware/permissions.js";
 import { requireNotBanned } from "../middleware/require-not-banned.js";
 import { parseAtUri } from "../lib/at-uri.js";
-import { handleReadError, handleWriteError, safeParseJsonBody } from "../lib/route-errors.js";
+import { handleRouteError, safeParseJsonBody } from "../lib/route-errors.js";
 import { isProgrammingError } from "../lib/errors.js";
 import {
   parseBigIntParam,
···
               .offset(offset),
           ]);
         } catch (error) {
-          return handleReadError(c, error, "Failed to retrieve replies for topic", {
+          return handleRouteError(c, error, "Failed to retrieve replies for topic", {
             operation: "GET /api/topics/:id - reply query",
             logger: ctx.logger,
             topicId: id,
···
           limit,
         });
       } catch (error) {
-        return handleReadError(c, error, "Failed to retrieve topic", {
+        return handleRouteError(c, error, "Failed to retrieve topic", {
           operation: "GET /api/topics/:id - topic query",
           logger: ctx.logger,
           topicId: id,
···
           201
         );
       } catch (error) {
-        return handleWriteError(c, error, "Failed to create topic", {
+        return handleRouteError(c, error, "Failed to create topic", {
           operation: "POST /api/topics",
           logger: ctx.logger,
           userId: user.did,