Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

refactor(billing): parse firebill responses with Zod schemas (#4551)

Rakshith Ramprakash1cfe7d9dfc50
diff --git a/apps/api/src/services/autumn/__tests__/firebill.test.ts b/apps/api/src/services/autumn/__tests__/firebill.test.ts
index c52442c44..1a3085a30 100644
--- a/apps/api/src/services/autumn/__tests__/firebill.test.ts
+++ b/apps/api/src/services/autumn/__tests__/firebill.test.ts
@@ -1,6 +1,8 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
firebillCheck,
+ firebillFinalize,
+ firebillLock,
firebillTrack,
shouldRouteToFirebill,
} from "../firebill";
@@ -663,3 +665,151 @@ describe("firebillCheck", () => {
expect(fetchMock).toHaveBeenCalledTimes(1);
});
});
+
+describe("firebillLock", () => {
+ const lockParams = {
+ customerId: "org-1",
+ entityId: "team-1",
+ featureId: "CREDITS",
+ value: 10,
+ lockId: "monitor_check-1",
+ expiresAt: Date.now() + 60_000,
+ };
+
+ const answer = (body: unknown, status = 200) =>
+ vi.stubGlobal(
+ "fetch",
+ vi.fn().mockResolvedValue(new Response(JSON.stringify(body), { status })),
+ );
+
+ it("locks and carries the operation token back on a gated hold", async () => {
+ answer({
+ success: true,
+ allowed: true,
+ lock_id: "monitor_check-1",
+ operation_token: "op-tok",
+ });
+ await expect(firebillLock(lockParams)).resolves.toEqual({
+ status: "locked",
+ lockId: "monitor_check-1",
+ operationToken: "op-tok",
+ });
+ });
+
+ it("falls back to the caller's lock id when firebill echoes none", async () => {
+ answer({ success: true, allowed: true });
+ await expect(firebillLock(lockParams)).resolves.toEqual({
+ status: "locked",
+ lockId: "monitor_check-1",
+ });
+ });
+
+ it("reads a denial and its reason", async () => {
+ answer({ success: true, allowed: false, reason: "out_of_credits" });
+ await expect(firebillLock(lockParams)).resolves.toEqual({
+ status: "denied",
+ reason: "out_of_credits",
+ });
+ });
+
+ it("drops an unrecognised denial reason rather than passing it through", async () => {
+ answer({ success: true, allowed: false, reason: "some_new_reason" });
+ await expect(firebillLock(lockParams)).resolves.toEqual({
+ status: "denied",
+ });
+ });
+
+ // A shape firebill sent on purpose (`success: false`) is `refused`; one we
+ // could not read is `unusable`. Both proceed unlocked, but slicing the cause
+ // counter must tell them apart.
+ it("calls an explicit success:false refused", async () => {
+ answer({ success: false });
+ await expect(firebillLock(lockParams)).resolves.toEqual({
+ status: "unavailable",
+ });
+ expect(await failureCauses()).toEqual({ "lock/refused": 1 });
+ });
+
+ it.each([
+ ["a missing allowed", { success: true }],
+ ["a non-boolean allowed", { success: true, allowed: "yes" }],
+ ["a missing success", { locked: true }],
+ ])("calls %s unusable, not refused", async (_label, body) => {
+ answer(body);
+ await expect(firebillLock(lockParams)).resolves.toEqual({
+ status: "unavailable",
+ });
+ expect(await failureCauses()).toEqual({ "lock/unusable": 1 });
+ });
+
+ it("calls an unreadable body unusable", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi
+ .fn()
+ .mockResolvedValue(new Response("<html>502</html>", { status: 200 })),
+ );
+ await expect(firebillLock(lockParams)).resolves.toEqual({
+ status: "unavailable",
+ });
+ expect(await failureCauses()).toEqual({ "lock/unusable": 1 });
+ });
+
+ it("names a non-OK status as its own cause", async () => {
+ answer({ success: true, allowed: true }, 503);
+ await expect(firebillLock(lockParams)).resolves.toEqual({
+ status: "unavailable",
+ });
+ expect(await failureCauses()).toEqual({ "lock/non_ok": 1 });
+ });
+});
+
+describe("firebillFinalize", () => {
+ const finalizeParams = {
+ lockId: "monitor_check-1",
+ action: "confirm" as const,
+ };
+
+ const answer = (body: unknown, status = 200) =>
+ vi.stubGlobal(
+ "fetch",
+ vi.fn().mockResolvedValue(new Response(JSON.stringify(body), { status })),
+ );
+
+ it("returns true when firebill accepted the settle", async () => {
+ answer({ success: true });
+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(true);
+ });
+
+ it("calls an explicit success:false refused", async () => {
+ answer({ success: false });
+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);
+ expect(await failureCauses()).toEqual({ "finalize/refused": 1 });
+ });
+
+ it.each([
+ ["a missing success", { queued: true }],
+ ["a non-boolean success", { success: "yes" }],
+ ])("calls %s unusable, not refused", async (_label, body) => {
+ answer(body);
+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);
+ expect(await failureCauses()).toEqual({ "finalize/unusable": 1 });
+ });
+
+ it("calls an unreadable body unusable", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi
+ .fn()
+ .mockResolvedValue(new Response("<html>502</html>", { status: 200 })),
+ );
+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);
+ expect(await failureCauses()).toEqual({ "finalize/unusable": 1 });
+ });
+
+ it("reads a 504 as ambiguous rather than refused", async () => {
+ answer({ success: false, ambiguous: true }, 504);
+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);
+ expect(await failureCauses()).toEqual({ "finalize/ambiguous": 1 });
+ });
+});
diff --git a/apps/api/src/services/autumn/firebill.ts b/apps/api/src/services/autumn/firebill.ts
index 26506d754..5c1580a68 100644
--- a/apps/api/src/services/autumn/firebill.ts
+++ b/apps/api/src/services/autumn/firebill.ts
@@ -1,4 +1,5 @@
import { randomUUID } from "crypto";
+import { z } from "zod";
import { config } from "../../config";
import { logger } from "../../lib/logger";
import { sampled } from "../../lib/rollout";
@@ -189,6 +190,38 @@ function saysAmbiguous(
return (body !== UNUSABLE_BODY && body.ambiguous === true) || status === 504;
}
+// firebill's answer bodies (firebill `src/api.rs`). `success` discriminates: it
+// sends `allowed`/`remaining` (check) and `allowed`/`lock_id`/… (lock) only when
+// `success: true`. Splitting the arms keeps an explicit `success: false`
+// (`refused`) distinct from a shape that matches neither (`unusable`).
+
+// `ambiguous` is read off the raw body by saysAmbiguous before this.
+const usageAnswerSchema = z.object({ success: z.boolean() });
+
+// `remaining` is lenient β€” a missing or non-finite figure falls back to the
+// clamp below rather than discarding the answer.
+const checkAnswerSchema = z.discriminatedUnion("success", [
+ z.object({
+ success: z.literal(true),
+ allowed: z.boolean(),
+ remaining: z.number().finite().optional().catch(undefined),
+ }),
+ z.object({ success: z.literal(false) }),
+]);
+
+// `lock_id` is caught to undefined so a mis-shaped echo falls back to the
+// caller's own id; reason/operation_token are validated where they are read.
+const lockAnswerSchema = z.discriminatedUnion("success", [
+ z.object({
+ success: z.literal(true),
+ allowed: z.boolean(),
+ lock_id: z.string().optional().catch(undefined),
+ reason: z.unknown().optional(),
+ operation_token: z.unknown().optional(),
+ }),
+ z.object({ success: z.literal(false) }),
+]);
+
// FIREBILL_ORG_IDS is decoded once at startup by the config schema; the Set is
// built lazily on first use and cached, keyed on the decoded array reference.
let allowlistCache: { source: string[] | undefined; ids: Set<string> } | null =
@@ -436,11 +469,13 @@ async function firebillAttempt(
// telling us it took the event in a shape we did not understand β€” so it is
// ambiguous, and the caller retries under the same key rather than logging
// usage as lost.
- if (body !== UNUSABLE_BODY && body.success === false) {
+ const parsed =
+ body === UNUSABLE_BODY ? undefined : usageAnswerSchema.safeParse(body);
+ if (parsed?.success && parsed.data.success === false) {
logger.warn("firebill refused the event β€” it did not take it", context);
return { ok: false, reason: "not_success", cause: "refused" };
}
- if (body === UNUSABLE_BODY || body.success !== true) {
+ if (!parsed?.success) {
logger.warn("firebill answered with a body we could not read", {
...context,
status: response.status,
@@ -582,29 +617,20 @@ export async function firebillCheck({
status: response.status,
});
}
- const body = answered as {
- success?: boolean;
- allowed?: boolean;
- remaining?: number;
- };
+ const parsed = checkAnswerSchema.safeParse(answered);
+ // Unreadable, not refused: a missing `success` or a mis-shaped `allowed` read
+ // as a denial would 402 a paying customer, and counting it `refused` would
+ // have anyone slicing by cause counting it a decline. So it fails open.
+ if (!parsed.success) {
+ return unavailable("answered without a usable shape", "unusable");
+ }
// `success: false` is firebill saying it does not know β€” an unanswered
// balance, or a gateway lookup that failed. Never a denial.
- if (body.success === false) {
+ if (parsed.data.success === false) {
return unavailable("firebill could not answer", "refused");
}
- // Anything else that is not `success: true` is an answer we cannot read
- // rather than one firebill gave: `refused` is documented as an explicit
- // `success: false`, and labelling a shape we did not understand with it
- // would have anyone slicing by cause counting these as declines.
- if (body.success !== true) {
- return unavailable("answered without a usable `success`", "unusable");
- }
- // A missing or mis-shaped `allowed` is not something firebill sends today.
- // Reading it as a denial would 402 a paying customer, so it fails open.
- if (typeof body.allowed !== "boolean") {
- return unavailable("answered without a usable `allowed`", "unusable");
- }
+ const body = parsed.data;
// `remaining` clamps downstream limits, and the safe default inverts with
// `allowed`, so there is no single one.
@@ -719,21 +745,17 @@ export async function firebillLock({
firebillFailureCauseTotal.labels("lock", "unusable").inc();
return { status: "unavailable" };
}
- const body = answered as {
- success?: boolean;
- allowed?: boolean;
- lock_id?: string;
- reason?: unknown;
- operation_token?: unknown;
- };
-
- if (body.success !== true) {
+ const parsed = lockAnswerSchema.safeParse(answered);
+ // Both proceed unlocked, but the cause has to tell them apart: an explicit
+ // `success: false` is `refused`, a shape matching neither arm is `unusable`.
+ if (!parsed.success || parsed.data.success === false) {
logger.error("firebill lock did not succeed", context);
firebillFailureCauseTotal
- .labels("lock", body.success === false ? "refused" : "unusable")
+ .labels("lock", parsed.success ? "refused" : "unusable")
.inc();
return { status: "unavailable" };
}
+ const body = parsed.data;
if (body.allowed === false) {
const reason = lockDeniedReason(body.reason);
@@ -748,19 +770,8 @@ export async function firebillLock({
return { status: "denied", ...(reason ? { reason } : {}) };
}
- // Only an explicit `allowed: false` is a denial. `success: true` with a
- // missing or mis-shaped `allowed` is not an answer firebill sends today;
- // treating it as a denial would hard-stop the check (skipped_no_credits),
- // so it maps to unavailable β€” proceed unlocked β€” instead.
- if (body.allowed !== true) {
- logger.error(
- "firebill lock answered without a usable `allowed`",
- context,
- );
- firebillFailureCauseTotal.labels("lock", "unusable").inc();
- return { status: "unavailable" };
- }
-
+ // allowed is a schema-guaranteed boolean and the denial above took the
+ // false, so this is allowed: true.
const operationToken =
typeof body.operation_token === "string" &&
body.operation_token.length > 0
@@ -906,11 +917,12 @@ export async function firebillFinalize({
firebillFailureCauseTotal.labels("finalize", "unusable").inc();
return false;
}
- const body = answered as { success?: boolean };
- if (body.success !== true) {
+ const parsed = usageAnswerSchema.safeParse(answered);
+ if (!parsed.success || parsed.data.success !== true) {
logger.error("firebill finalize did not succeed", context);
firebillFailureCauseTotal
- .labels("finalize", body.success === false ? "refused" : "unusable")
+ // Explicit `success: false` is `refused`; an unreadable shape `unusable`.
+ .labels("finalize", parsed.success ? "refused" : "unusable")
.inc();
return false;
}