@rebasepro/server-core 0.0.1-canary.000dc36

package/test/error-propagation.test.ts

@@ -0,0 +1,226 @@
+import { Hono } from "hono";
+import { ApiError, errorHandler } from "../src/api/errors";
+import { HonoEnv } from "../src/api/types";
+
+/**
+ * End-to-end tests that verify ApiError thrown inside Hono sub-routers
+ * produces the correct HTTP status code and JSON body WHEN the sub-router
+ * is mounted on a parent app — exactly simulating the init.ts mounting
+ * pattern.
+ *
+ * This is critical because Hono's `onError` does NOT propagate from parent
+ * to child routers. Each sub-router must have its own `router.onError(errorHandler)`.
+ */
+describe("Error Propagation through Sub-Routers", () => {
+
+    // ── Without onError on sub-router (broken behavior) ─────────────
+
+    describe("Sub-router WITHOUT onError (demonstrates the bug)", () => {
+        function createBrokenApp() {
+            // This simulates the REAL production scenario: the consumer's Hono app
+            // (e.g. SustenTalent's index.ts) does NOT set onError on the parent app.
+            // Without onError on the sub-router either, Hono's DEFAULT error handler
+            // catches ApiErrors and returns a generic 500 with a plain text body.
+            const parentApp = new Hono<HonoEnv>();
+            // NOTE: no parentApp.onError(errorHandler) — this is the real scenario
+
+            const subRouter = new Hono<HonoEnv>();
+            // NOTE: no subRouter.onError(errorHandler) — this is the bug
+            subRouter.get("/login", () => {
+                throw ApiError.unauthorized("Invalid credentials", "INVALID_CREDENTIALS");
+            });
+
+            parentApp.route("/api/auth", subRouter);
+            return parentApp;
+        }
+
+        it("ApiError.unauthorized returns 500 plain text without ANY onError handler", async () => {
+            const app = createBrokenApp();
+            const res = await app.request("/api/auth/login");
+            // Without any onError handler, Hono's default handler returns 500
+            expect(res.status).toBe(500);
+            // And the body is NOT our structured JSON — it's plain text
+            const text = await res.text();
+            expect(text).toBe("Internal Server Error");
+        });
+    });
+
+    // ── With onError on sub-router (fixed behavior) ─────────────────
+
+    describe("Sub-router WITH onError (correct behavior)", () => {
+        function createFixedApp() {
+            const parentApp = new Hono<HonoEnv>();
+            parentApp.onError(errorHandler);
+
+            const subRouter = new Hono<HonoEnv>();
+            subRouter.onError(errorHandler); // ← THE FIX
+
+            subRouter.get("/login", () => {
+                throw ApiError.unauthorized("Invalid credentials", "INVALID_CREDENTIALS");
+            });
+            subRouter.get("/register", () => {
+                throw ApiError.conflict("Email already exists", "EMAIL_EXISTS");
+            });
+            subRouter.get("/refresh", () => {
+                throw ApiError.unauthorized("Refresh token expired", "TOKEN_EXPIRED");
+            });
+            subRouter.get("/forbidden", () => {
+                throw ApiError.forbidden("Admin only");
+            });
+            subRouter.get("/not-found", () => {
+                throw ApiError.notFound("User not found");
+            });
+            subRouter.get("/bad-request", () => {
+                throw ApiError.badRequest("Missing email", "INVALID_INPUT", { field: "email" });
+            });
+            subRouter.get("/service-unavailable", () => {
+                throw ApiError.serviceUnavailable("Google login not configured", "NOT_CONFIGURED");
+            });
+            subRouter.get("/generic-error", () => {
+                throw new Error("Unexpected failure");
+            });
+
+            parentApp.route("/api/auth", subRouter);
+            return parentApp;
+        }
+
+        it("returns 401 for unauthorized errors", async () => {
+            const app = createFixedApp();
+            const res = await app.request("/api/auth/login");
+            expect(res.status).toBe(401);
+            const body = await res.json() as { error: { message: string; code: string } };
+            expect(body.error.message).toBe("Invalid credentials");
+            expect(body.error.code).toBe("INVALID_CREDENTIALS");
+        });
+
+        it("returns 409 for conflict errors", async () => {
+            const app = createFixedApp();
+            const res = await app.request("/api/auth/register");
+            expect(res.status).toBe(409);
+            const body = await res.json() as { error: { message: string; code: string } };
+            expect(body.error.message).toBe("Email already exists");
+            expect(body.error.code).toBe("EMAIL_EXISTS");
+        });
+
+        it("returns 401 for expired refresh token", async () => {
+            const app = createFixedApp();
+            const res = await app.request("/api/auth/refresh");
+            expect(res.status).toBe(401);
+            const body = await res.json() as { error: { message: string; code: string } };
+            expect(body.error.code).toBe("TOKEN_EXPIRED");
+        });
+
+        it("returns 403 for forbidden errors", async () => {
+            const app = createFixedApp();
+            const res = await app.request("/api/auth/forbidden");
+            expect(res.status).toBe(403);
+        });
+
+        it("returns 404 for not found errors", async () => {
+            const app = createFixedApp();
+            const res = await app.request("/api/auth/not-found");
+            expect(res.status).toBe(404);
+        });
+
+        it("returns 400 with details for bad request errors", async () => {
+            const app = createFixedApp();
+            const res = await app.request("/api/auth/bad-request");
+            expect(res.status).toBe(400);
+            const body = await res.json() as { error: { message: string; code: string; details: unknown } };
+            expect(body.error.code).toBe("INVALID_INPUT");
+            expect(body.error.details).toEqual({ field: "email" });
+        });
+
+        it("returns 503 for service unavailable errors", async () => {
+            const app = createFixedApp();
+            const res = await app.request("/api/auth/service-unavailable");
+            expect(res.status).toBe(503);
+            const body = await res.json() as { error: { message: string; code: string } };
+            expect(body.error.code).toBe("NOT_CONFIGURED");
+        });
+
+        it("returns 500 with sanitized message for generic errors", async () => {
+            const app = createFixedApp();
+            const res = await app.request("/api/auth/generic-error");
+            expect(res.status).toBe(500);
+            const body = await res.json() as { error: { message: string; code: string } };
+            expect(body.error.code).toBe("INTERNAL_ERROR");
+            // Should NOT leak the raw error message
+            expect(body.error.message).toBe("Internal Server Error");
+        });
+
+        it("returns consistent { error: { message, code } } shape for all error types", async () => {
+            const app = createFixedApp();
+            const paths = ["/api/auth/login", "/api/auth/register", "/api/auth/forbidden", "/api/auth/not-found", "/api/auth/bad-request"];
+
+            for (const path of paths) {
+                const res = await app.request(path);
+                const body = await res.json() as Record<string, unknown>;
+                expect(body).toHaveProperty("error");
+                expect(body.error).toHaveProperty("message");
+                expect(body.error).toHaveProperty("code");
+            }
+        });
+    });
+
+    // ── Multi-level nesting ─────────────────────────────────────────
+
+    describe("Deeply nested sub-routers", () => {
+        it("error handler works through two levels of nesting", async () => {
+            const root = new Hono<HonoEnv>();
+            root.onError(errorHandler);
+
+            const level1 = new Hono<HonoEnv>();
+            level1.onError(errorHandler);
+
+            const level2 = new Hono<HonoEnv>();
+            level2.onError(errorHandler);
+
+            level2.get("/deep", () => {
+                throw ApiError.unauthorized("Deep error");
+            });
+
+            level1.route("/nested", level2);
+            root.route("/api", level1);
+
+            const res = await root.request("/api/nested/deep");
+            expect(res.status).toBe(401);
+            const body = await res.json() as { error: { message: string } };
+            expect(body.error.message).toBe("Deep error");
+        });
+    });
+
+    // ── Data router simulation ──────────────────────────────────────
+
+    describe("Data router error propagation (simulates init.ts pattern)", () => {
+        function createDataApp() {
+            const app = new Hono<HonoEnv>();
+            app.onError(errorHandler);
+
+            const dataRouter = new Hono<HonoEnv>();
+            dataRouter.onError(errorHandler);
+
+            dataRouter.get("/posts/:id", () => {
+                throw ApiError.notFound("Entity not found");
+            });
+            dataRouter.post("/posts", () => {
+                throw ApiError.badRequest("Validation failed", "INVALID_INPUT");
+            });
+
+            app.route("/api/data", dataRouter);
+            return app;
+        }
+
+        it("returns 404 for entity not found", async () => {
+            const app = createDataApp();
+            const res = await app.request("/api/data/posts/999");
+            expect(res.status).toBe(404);
+        });
+
+        it("returns 400 for validation errors", async () => {
+            const app = createDataApp();
+            const res = await app.request("/api/data/posts", { method: "POST" });
+            expect(res.status).toBe(400);
+        });
+    });
+});

package/test/errors-hono.test.ts

@@ -0,0 +1,133 @@
+import { Hono } from "hono";
+import { ApiError, errorHandler } from "../src/api/errors";
+import { HonoEnv } from "../src/api/types";
+
+describe("Error Handler (Hono)", () => {
+    function createApp() {
+        const app = new Hono<HonoEnv>();
+        app.onError(errorHandler);
+
+        // Test routes that throw different errors
+        app.get("/bad-request", () => {
+            throw ApiError.badRequest("Missing required field", "MISSING_FIELD", { field: "email" });
+        });
+        app.get("/unauthorized", () => {
+            throw ApiError.unauthorized("Token expired", "TOKEN_EXPIRED");
+        });
+        app.get("/forbidden", () => {
+            throw ApiError.forbidden("Admin only", "FORBIDDEN");
+        });
+        app.get("/not-found", () => {
+            throw ApiError.notFound("Entity not found");
+        });
+        app.get("/conflict", () => {
+            throw ApiError.conflict("Email already exists", "EMAIL_EXISTS");
+        });
+        app.get("/internal", () => {
+            throw ApiError.internal("Database connection failed");
+        });
+        app.get("/service-unavailable", () => {
+            throw ApiError.serviceUnavailable("Feature not configured");
+        });
+        app.get("/generic-error", () => {
+            throw new Error("Something went wrong");
+        });
+        app.get("/error-with-code", () => {
+            const err = new Error("Rate limited") as Error & { code: string };
+            err.code = "RATE_LIMITED";
+            throw err;
+        });
+
+        return app;
+    }
+
+    it("formats ApiError with correct status and body structure", async () => {
+        const app = createApp();
+        const res = await app.request("/bad-request");
+        expect(res.status).toBe(400);
+        const body = await res.json() as any;
+        expect(body.error.message).toBe("Missing required field");
+        expect(body.error.code).toBe("MISSING_FIELD");
+        expect(body.error.details).toEqual({ field: "email" });
+    });
+
+    it("handles 401 Unauthorized", async () => {
+        const app = createApp();
+        const res = await app.request("/unauthorized");
+        expect(res.status).toBe(401);
+        const body = await res.json() as any;
+        expect(body.error.code).toBe("TOKEN_EXPIRED");
+    });
+
+    it("handles 403 Forbidden", async () => {
+        const app = createApp();
+        const res = await app.request("/forbidden");
+        expect(res.status).toBe(403);
+        const body = await res.json() as any;
+        expect(body.error.code).toBe("FORBIDDEN");
+    });
+
+    it("handles 404 Not Found", async () => {
+        const app = createApp();
+        const res = await app.request("/not-found");
+        expect(res.status).toBe(404);
+        const body = await res.json() as any;
+        expect(body.error.code).toBe("NOT_FOUND");
+    });
+
+    it("handles 409 Conflict", async () => {
+        const app = createApp();
+        const res = await app.request("/conflict");
+        expect(res.status).toBe(409);
+        const body = await res.json() as any;
+        expect(body.error.code).toBe("EMAIL_EXISTS");
+    });
+
+    it("handles 500 Internal", async () => {
+        const app = createApp();
+        const res = await app.request("/internal");
+        expect(res.status).toBe(500);
+    });
+
+    it("handles 503 Service Unavailable", async () => {
+        const app = createApp();
+        const res = await app.request("/service-unavailable");
+        expect(res.status).toBe(503);
+    });
+
+    it("converts generic Error to 500 with INTERNAL_ERROR code", async () => {
+        const app = createApp();
+        const res = await app.request("/generic-error");
+        expect(res.status).toBe(500);
+        const body = await res.json() as any;
+        expect(body.error.code).toBe("INTERNAL_ERROR");
+        expect(body.error.message).toBe("Internal Server Error");
+    });
+
+    it("maps known error codes to HTTP status codes", async () => {
+        const app = createApp();
+        const res = await app.request("/error-with-code");
+        // RATE_LIMITED is not in the code-to-status map, so it should default to 500
+        expect(res.status).toBe(500);
+    });
+
+    it("omits details when not provided", async () => {
+        const app = createApp();
+        const res = await app.request("/unauthorized");
+        const body = await res.json() as any;
+        expect(body.error.details).toBeUndefined();
+    });
+
+    it("returns consistent error shape for all error types", async () => {
+        const app = createApp();
+        const paths = ["/bad-request", "/unauthorized", "/forbidden", "/not-found", "/internal", "/generic-error"];
+
+        for (const path of paths) {
+            const res = await app.request(path);
+            const body = await res.json() as any;
+            expect(body).toHaveProperty("error");
+            expect(body.error).toHaveProperty("message");
+            expect(body.error).toHaveProperty("code");
+        }
+    });
+});

package/test/errors.test.ts

@@ -0,0 +1,155 @@
+import { ApiError, errorHandler } from "../src/api/errors";
+
+// ── Minimal Hono-context mock ────────────────────────────────────────────
+function createMockContext(method = "GET", path = "/test") {
+    let capturedStatus: number | undefined;
+    let capturedBody: any;
+
+    const c = {
+        req: { method,
+path },
+        json: (body: any, status?: number) => {
+            capturedBody = body;
+            capturedStatus = status ?? 200;
+            return new Response(JSON.stringify(body), { status: capturedStatus });
+        }
+    } as any;
+
+    return {
+        c,
+        getStatus: () => capturedStatus,
+        getBody: () => capturedBody
+    };
+}
+
+// ── ApiError class ────────────────────────────────────────────────────────
+describe("ApiError", () => {
+    describe("constructor", () => {
+        it("should create an error with statusCode, code, message, and details", () => {
+            const err = new ApiError(422, "VALIDATION_ERROR", "Invalid field", { field: "email" });
+            expect(err).toBeInstanceOf(Error);
+            expect(err).toBeInstanceOf(ApiError);
+            expect(err.statusCode).toBe(422);
+            expect(err.code).toBe("VALIDATION_ERROR");
+            expect(err.message).toBe("Invalid field");
+            expect(err.details).toEqual({ field: "email" });
+            expect(err.name).toBe("ApiError");
+        });
+
+        it("should default details to undefined", () => {
+            const err = new ApiError(400, "BAD_REQUEST", "Bad");
+            expect(err.details).toBeUndefined();
+        });
+    });
+
+    describe("factory methods", () => {
+        it("badRequest → 400", () => {
+            const err = ApiError.badRequest("Missing field", "MISSING_FIELD");
+            expect(err.statusCode).toBe(400);
+            expect(err.code).toBe("MISSING_FIELD");
+        });
+
+        it("badRequest uses default code", () => {
+            const err = ApiError.badRequest("Oops");
+            expect(err.code).toBe("BAD_REQUEST");
+        });
+
+        it("unauthorized → 401", () => {
+            const err = ApiError.unauthorized("Bad token");
+            expect(err.statusCode).toBe(401);
+            expect(err.code).toBe("UNAUTHORIZED");
+        });
+
+        it("forbidden → 403", () => {
+            const err = ApiError.forbidden("No access");
+            expect(err.statusCode).toBe(403);
+            expect(err.code).toBe("FORBIDDEN");
+        });
+
+        it("notFound → 404", () => {
+            const err = ApiError.notFound("Entity not found");
+            expect(err.statusCode).toBe(404);
+            expect(err.code).toBe("NOT_FOUND");
+        });
+
+        it("conflict → 409", () => {
+            const err = ApiError.conflict("Already exists", "EMAIL_EXISTS");
+            expect(err.statusCode).toBe(409);
+            expect(err.code).toBe("EMAIL_EXISTS");
+        });
+
+        it("internal → 500", () => {
+            const err = ApiError.internal("Boom");
+            expect(err.statusCode).toBe(500);
+            expect(err.code).toBe("INTERNAL_ERROR");
+        });
+
+        it("serviceUnavailable → 503", () => {
+            const err = ApiError.serviceUnavailable("Down");
+            expect(err.statusCode).toBe(503);
+            expect(err.code).toBe("SERVICE_UNAVAILABLE");
+        });
+    });
+});
+
+// ── errorHandler (Hono ErrorHandler) ──────────────────────────────────────
+describe("errorHandler", () => {
+    it("should format ApiError with statusCode, code, message", () => {
+        const { c, getStatus, getBody } = createMockContext();
+        const err = ApiError.notFound("User not found");
+        errorHandler(err, c);
+
+        expect(getStatus()).toBe(404);
+        expect(getBody()).toEqual({
+            error: { message: "User not found",
+code: "NOT_FOUND" }
+        });
+    });
+
+    it("should include details when present", () => {
+        const { c, getBody } = createMockContext();
+        const err = ApiError.badRequest("Validation failed", "VALIDATION", { fields: ["email"] });
+        errorHandler(err, c);
+
+        expect(getBody()).toEqual({
+            error: {
+                message: "Validation failed",
+                code: "VALIDATION",
+                details: { fields: ["email"] }
+            }
+        });
+    });
+
+    it("should handle plain Error with code property", () => {
+        const { c, getStatus, getBody } = createMockContext();
+        const err = Object.assign(new Error("Not found"), { code: "NOT_FOUND" });
+        errorHandler(err, c);
+
+        expect(getStatus()).toBe(404);
+        expect(getBody()).toEqual({
+            error: { message: "Not found",
+code: "NOT_FOUND" }
+        });
+    });
+
+    it("should default to 500 for unknown errors", () => {
+        const { c, getStatus, getBody } = createMockContext();
+        const err = new Error("Something broke");
+        errorHandler(err, c);
+
+        expect(getStatus()).toBe(500);
+        expect(getBody()).toEqual({
+            error: { message: "Internal Server Error",
+code: "INTERNAL_ERROR" }
+        });
+    });
+
+    it("should use statusCode from error if present", () => {
+        const { c, getStatus } = createMockContext();
+        const err = Object.assign(new Error("Rate limited"), { statusCode: 429,
+code: "RATE_LIMITED" });
+        errorHandler(err, c);
+
+        expect(getStatus()).toBe(429);
+    });
+});