Skip to content

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

Route gateway-funded orgs through firebill regardless of the ramp (#4403)

Rakshith Ramprakash0b85d9d0c726
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 456d768c0..d4b399c79 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -480,6 +480,14 @@ const configSchema = z.object({
FIREBILL_URL: emptyStringAsUndefined(z.string().url()),
FIREBILL_SECRET: emptyStringAsUndefined(z.string().trim().min(1)),
FIREBILL_ORG_IDS: delimitedList(",").optional(),
+ // How long "this team is not partner-provisioned" is trusted. Only the
+ // negative is bounded: provisioning is one-way, so a positive cannot go
+ // stale, while a negative does the moment a partner provisions an account.
+ // Capped at firebill's own gateway lookup TTL (300s) β€” the two sides answer
+ // the same question, and trusting a negative for longer than firebill trusts
+ // an answer turns this cache back into the stale allowlist it replaced. 0
+ // disables caching negatives entirely.
+ FIREBILL_GATEWAY_NEGATIVE_TTL_SECONDS: z.coerce.number().int().min(0).max(300).default(60),
// Sticky percentage ramp, on top of the allowlist above. The bucket is a
// hash of the org id, so an org that is in at 5 is still in at 30 β€” a ramp
// only ever adds, and never reshuffles who is on which path mid-rollout.
diff --git a/apps/api/src/db/schema/public.ts b/apps/api/src/db/schema/public.ts
index 812a370d9..a2070a5d9 100644
--- a/apps/api/src/db/schema/public.ts
+++ b/apps/api/src/db/schema/public.ts
@@ -680,6 +680,16 @@ export const subscriptions = pgTable("subscriptions", {
pending_schedule_id: text("pending_schedule_id"),
});
+export const partner_provisioned_accounts = pgTable(
+ "partner_provisioned_accounts",
+ {
+ id: bigintNum("id").notNull().generatedByDefaultAsIdentity(),
+ integration_id: bigintNum("integration_id").notNull(),
+ team_id: uuid("team_id").notNull(),
+ org_id: uuid("org_id").notNull(),
+ },
+);
+
export const teams = pgTable("teams", {
id: uuid("id").notNull().defaultRandom(),
created_at: ts("created_at").defaultNow(),
diff --git a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts b/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
index c260330fc..67f97d354 100644
--- a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
+++ b/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
@@ -48,14 +48,35 @@ const {
};
// Minimal Drizzle query-builder stub: .select().from().where().limit() β†’ rows.
- const makeDbStub = (data: unknown) => ({
- select: () => ({
- from: () => ({
- where: () => ({
- limit: () => Promise.resolve(data ? [data] : []),
+ //
+ // Table-aware by the selected columns, because two different lookups share it:
+ // the team β†’ org_id resolution, and the gateway-provisioning check. Returning
+ // one row for both would make every team look partner-provisioned.
+ const makeDbStub = (
+ data: unknown,
+ gatewayRow: unknown,
+ gatewayThrows = false,
+ ) => ({
+ select: (fields?: Record<string, unknown>) => {
+ const isGatewayLookup = !!fields && "team_id" in fields;
+ if (isGatewayLookup && gatewayThrows) {
+ throw new Error("replica unavailable");
+ }
+ const rows = isGatewayLookup
+ ? gatewayRow
+ ? [gatewayRow]
+ : []
+ : data
+ ? [data]
+ : [];
+ return {
+ from: () => ({
+ where: () => ({
+ limit: () => Promise.resolve(rows),
+ }),
}),
- }),
- }),
+ };
+ },
});
return {
@@ -75,6 +96,11 @@ const {
data: unknown;
error: unknown;
},
+ // Row the partner_provisioned_accounts lookup finds. null = not
+ // which is what almost every team is.
+ gatewayStubRow: null as unknown,
+ // Makes the gateway lookup throw, to prove a failure is never cached.
+ gatewayStubThrows: false,
configRef: {} as Record<string, unknown>,
},
};
@@ -88,7 +114,11 @@ vi.mock("../client", () => ({
vi.mock("../../../db/connection", () => ({
get dbRr() {
- return makeDbStub(state.supabaseStubData.data);
+ return makeDbStub(
+ state.supabaseStubData.data,
+ state.gatewayStubRow,
+ state.gatewayStubThrows,
+ );
},
}));
@@ -692,6 +722,9 @@ describe("firebill routing", () => {
mockFetch.mockReset();
mockFetch.mockResolvedValue(firebillResponse(true));
vi.stubGlobal("fetch", mockFetch);
+ // Default every test to not partner-provisioned, which almost every team is.
+ state.gatewayStubRow = null;
+ state.gatewayStubThrows = false;
});
afterEach(() => {
@@ -827,6 +860,68 @@ describe("firebill routing", () => {
expect(body.properties.endpoint).toBe("extract");
});
+ it("routes a gateway-provisioned team even when it is off the allowlist and at 0 percent", async () => {
+ // The property the whole branch exists for: a partner's usage cannot depend
+ // on a sampling bucket. Only firebill knows how to split it between the
+ // provisioned org's balance and the partner's pool.
+ state.configRef = {
+ ...firebillConfig(),
+ FIREBILL_ORG_IDS: ["some-other-org"],
+ FIREBILL_ROLLOUT_PERCENT: 0,
+ };
+ state.gatewayStubRow = { team_id: "team-1" };
+ const svc = makeService();
+
+ const result = await svc.trackCredits({ teamId: "team-1", value: 42 });
+
+ expect(result).toBe(true);
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ expect(mockTrack).not.toHaveBeenCalled();
+ });
+
+ it("caches a positive without re-querying, since provisioning is one-way", async () => {
+ state.configRef = {
+ ...firebillConfig(),
+ FIREBILL_ORG_IDS: [],
+ FIREBILL_ROLLOUT_PERCENT: 0,
+ };
+ state.gatewayStubRow = { team_id: "team-1" };
+ // A fresh Response per call: firebill reads the body, and a reused one looks
+ // like a failure and triggers its retry.
+ mockFetch.mockImplementation(async () => firebillResponse(true));
+ const svc = makeService();
+
+ await svc.trackCredits({ teamId: "team-1", value: 1 });
+ // The row vanishing must not un-route the team: provisioning is one-way,
+ // and re-reading would put a query on every billing event.
+ state.gatewayStubRow = null;
+ await svc.trackCredits({ teamId: "team-1", value: 1 });
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ expect(mockTrack).not.toHaveBeenCalled();
+ });
+
+ it("does not cache a negative when the lookup fails", async () => {
+ // A blip must not become a TTL's worth of partner usage billed to the
+ // provisioned account alone: that event routes direct, the next asks again.
+ state.configRef = {
+ ...firebillConfig(),
+ FIREBILL_ORG_IDS: [],
+ FIREBILL_ROLLOUT_PERCENT: 0,
+ };
+ state.gatewayStubThrows = true;
+ state.gatewayStubRow = { team_id: "team-1" };
+ mockFetch.mockImplementation(async () => firebillResponse(true));
+ const svc = makeService();
+
+ await svc.trackCredits({ teamId: "team-1", value: 1 });
+ expect(mockFetch).not.toHaveBeenCalled();
+
+ state.gatewayStubThrows = false;
+ await svc.trackCredits({ teamId: "team-1", value: 1 });
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ });
+
it("uses the direct Autumn path for orgs NOT on the allowlist", async () => {
state.configRef = {
...firebillConfig(),
diff --git a/apps/api/src/services/autumn/__tests__/firebill.test.ts b/apps/api/src/services/autumn/__tests__/firebill.test.ts
index e6081886a..cfa904854 100644
--- a/apps/api/src/services/autumn/__tests__/firebill.test.ts
+++ b/apps/api/src/services/autumn/__tests__/firebill.test.ts
@@ -49,17 +49,31 @@ describe("shouldRouteToFirebill", () => {
it("routes nobody else at 0 percent β€” the kill switch", () => {
const others = Array.from({ length: 200 }, (_, i) => `other-${i}`);
- expect(others.some(shouldRouteToFirebill)).toBe(false);
+ expect(others.some(orgId => shouldRouteToFirebill(orgId))).toBe(false);
});
it("routes roughly the configured share once ramped", () => {
const orgs = Array.from({ length: 1000 }, (_, i) => `ramp-${i}`);
configState.FIREBILL_ROLLOUT_PERCENT = 30;
const share =
- (orgs.filter(shouldRouteToFirebill).length / orgs.length) * 100;
+ (orgs.filter(orgId => shouldRouteToFirebill(orgId)).length /
+ orgs.length) *
+ 100;
expect(Math.abs(share - 30)).toBeLessThan(6);
});
+ it("ignores a non-object second argument, so callback use cannot route everyone", () => {
+ // `orgs.filter(shouldRouteToFirebill)` would pass the array index as the
+ // options argument. TypeScript rejects that now, but the runtime must be
+ // safe too: destructuring a field off a number yields undefined.
+ configState.FIREBILL_ROLLOUT_PERCENT = 0;
+ const asCallback = shouldRouteToFirebill as unknown as (
+ orgId: string,
+ index: number,
+ ) => boolean;
+ expect(asCallback("not-allow-listed", 7)).toBe(false);
+ });
+
it("stays off entirely when firebill is not configured", () => {
configState.FIREBILL_ROLLOUT_PERCENT = 100;
configState.FIREBILL_SECRET = "";
diff --git a/apps/api/src/services/autumn/autumn.service.ts b/apps/api/src/services/autumn/autumn.service.ts
index a26b7efcc..5b60be146 100644
--- a/apps/api/src/services/autumn/autumn.service.ts
+++ b/apps/api/src/services/autumn/autumn.service.ts
@@ -3,6 +3,7 @@ import { logger } from "../../lib/logger";
import { eq } from "drizzle-orm";
import { dbRr } from "../../db/connection";
import * as schema from "../../db/schema";
+import { config } from "../../config";
import { autumnClient } from "./client";
import {
firebillFinalize,
@@ -96,6 +97,8 @@ export class BoundedSet<V> extends Set<V> {
*/
export class AutumnService {
private customerOrgCache = new BoundedMap<string, string>(50_000);
+ private gatewayTeams = new BoundedSet<string>(50_000);
+ private nonGatewayTeamsUntil = new BoundedMap<string, number>(50_000);
private ensuredOrgs = new BoundedSet<string>(50_000);
private ensuredTeams = new BoundedSet<string>(50_000);
@@ -117,6 +120,62 @@ export class AutumnService {
return data.org_id;
}
+ /**
+ * Whether this team is an account a gateway partner provisioned, which is
+ * what makes the partner responsible for part of its usage, and forces it
+ * through firebill.
+ *
+ * Reads `partner_provisioned_accounts` rather than any config, because these
+ * are created at runtime by the partner API β€” an allowlist of org ids cannot
+ * keep up, and every new one would otherwise need a config change and a
+ * fleet restart before its usage billed correctly.
+ *
+ * Existence of the row is the question, deliberately β€” not the integration's
+ * `gateway_enabled` flag. Provisioning is the durable fact; whether to split
+ * right now is firebill's to decide, and keeping the kill switch there means
+ * flipping it stops splitting without also changing which service bills.
+ *
+ * Never throws: an unanswerable lookup falls back to "not gateway", which is
+ * the same outcome as this code not existing. Wrong in the direction of a
+ * missed split rather than a failed customer request.
+ */
+ private async isGatewayProvisioned(teamId: string): Promise<boolean> {
+ if (this.gatewayTeams.has(teamId)) return true;
+
+ const trustedUntil = this.nonGatewayTeamsUntil.get(teamId);
+ if (trustedUntil !== undefined && trustedUntil > Date.now()) return false;
+
+ try {
+ const [row] = await dbRr
+ .select({ team_id: schema.partner_provisioned_accounts.team_id })
+ .from(schema.partner_provisioned_accounts)
+ .where(eq(schema.partner_provisioned_accounts.team_id, teamId))
+ .limit(1);
+
+ if (row) {
+ this.gatewayTeams.add(teamId);
+ return true;
+ }
+
+ const ttlMs = config.FIREBILL_GATEWAY_NEGATIVE_TTL_SECONDS * 1000;
+ if (ttlMs > 0) {
+ this.nonGatewayTeamsUntil.set(teamId, Date.now() + ttlMs);
+ }
+ return false;
+ } catch (error) {
+ // Do not cache a failure as a negative: that would turn one blip into a
+ // TTL's worth of partner usage billed to the wrong account.
+ logger.warn(
+ "gateway provisioning lookup failed; treating as not gateway",
+ {
+ teamId,
+ error,
+ },
+ );
+ return false;
+ }
+ }
+
private getErrorStatus(error: unknown): number | undefined {
const status = (error as any)?.statusCode ?? (error as any)?.status;
if (typeof status === "number") return status;
@@ -225,7 +284,11 @@ export class AutumnService {
async isRoutedThroughFirebill(teamId: string): Promise<boolean> {
if (this.isPreviewTeam(teamId)) return false;
try {
- return shouldRouteToFirebill(await this.resolveOrgId(teamId));
+ const [orgId, gatewayProvisioned] = await Promise.all([
+ this.resolveOrgId(teamId),
+ this.isGatewayProvisioned(teamId),
+ ]);
+ return shouldRouteToFirebill(orgId, { gatewayProvisioned });
} catch {
return false;
}
@@ -239,11 +302,16 @@ export class AutumnService {
properties,
idempotencyKey,
}: TrackParams): Promise<boolean> {
- // Gradual rollout: allowlisted orgs, and those in the sticky
- // FIREBILL_ROLLOUT_PERCENT bucket, bill through firebill. No fallback to
- // Autumn on failure β€” firebill may already own the event, and the SDK sends
- // no idempotency key, so the pair could not be deduped.
- if (shouldRouteToFirebill(customerId)) {
+ // Gradual rollout: allowlisted orgs, partner-provisioned orgs, and those in
+ // sticky FIREBILL_ROLLOUT_PERCENT bucket bill through firebill. No fallback
+ // to Autumn on failure β€” firebill may already own the event, and the SDK
+ // sends no idempotency key, so the pair could not be deduped.
+ // No entity means no team, and every provisioned account has one β€” so there
+ // is nothing to look up.
+ const gatewayProvisioned = entityId
+ ? await this.isGatewayProvisioned(entityId)
+ : false;
+ if (shouldRouteToFirebill(customerId, { gatewayProvisioned })) {
billingRouteTotal.labels("firebill").inc();
return await firebillTrack({
customerId,
@@ -458,7 +526,11 @@ export class AutumnService {
// keeps no lock state), but only firebill pins the retry/timeout budget
// around the call. An unavailable answer maps to "skipped" β€” proceed
// unlocked β€” exactly like a direct-Autumn check failure below.
- if (shouldRouteToFirebill(customerId)) {
+ if (
+ shouldRouteToFirebill(customerId, {
+ gatewayProvisioned: await this.isGatewayProvisioned(teamId),
+ })
+ ) {
const result = await firebillLock({
customerId,
entityId: teamId,
diff --git a/apps/api/src/services/autumn/firebill.ts b/apps/api/src/services/autumn/firebill.ts
index 18dadeeed..c756f8c5b 100644
--- a/apps/api/src/services/autumn/firebill.ts
+++ b/apps/api/src/services/autumn/firebill.ts
@@ -48,12 +48,37 @@ function firebillOrgIds(): Set<string> {
/**
* Whether this org's usage goes through firebill rather than straight to Autumn.
- * Needs firebill configured, then either the allowlist or the sticky percentage.
+ * Needs firebill configured, then any of: the allowlist, being
+ * partner-provisioned, or the sticky percentage.
+ *
+ * `gatewayProvisioned` is deliberately a parameter rather than a lookup in here:
+ * this stays a pure function of config so it can be reasoned about and tested
+ * without a database, and the caller already has the answer cached.
+ *
+ * It arrives in an options object rather than as a second positional argument
+ * because this predicate is used as a callback β€” `orgs.filter(shouldRouteToFirebill)`
+ * would otherwise pass the array *index* as it, routing everything but element
+ * zero. Destructuring a field off a number yields undefined, so the object form
+ * cannot be fooled that way.
+ *
+ * **This whole gateway branch is meant to be deleted.** It exists only because
+ * the ramp is below 100: a gateway partner's usage must route deterministically,
+ * and a sticky sample is a probability. At `FIREBILL_ROLLOUT_PERCENT=100` every
+ * org routes anyway, the branch stops changing any outcome, and it β€” along with
+ * the lookup feeding it β€” should go.
*/
-export function shouldRouteToFirebill(orgId: string): boolean {
+export function shouldRouteToFirebill(
+ orgId: string,
+ opts?: { gatewayProvisioned?: boolean },
+): boolean {
if (!config.FIREBILL_URL || !config.FIREBILL_SECRET) return false;
// Always-on set: test orgs stay routed even at 0 percent.
if (firebillOrgIds().has(orgId)) return true;
+ // A partner-provisioned org always routes: firebill is the only thing that
+ // knows how to split its usage between that org's own balance and the
+ // partner's, so a charge that misses firebill is billed wholly to an account
+ // nobody pays for, and the partner is silently never charged.
+ if (opts?.gatewayProvisioned) return true;
// Sticky by org, so a ramp only ever adds and 0 is the kill switch.
return sampled(orgId, config.FIREBILL_ROLLOUT_PERCENT);
}