🏧 fix: Initialize Debit-Created Balances With Configured Allowances (#18056)

* fix: initialize debit-created balances from configured allowances

* style: sort balance initialization imports
This commit is contained in:
Danny Avila 2026-11-11 12:49:34 -05:00 • committed by GitHub
parent 4da2b9d2a3
commit 6c479ef244
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 252 additions and 8 deletions

View file

@ -258,6 +258,39 @@ describe('prepareStructuredTokenSpend', () => {
});
describe('bulkWriteTransactions (real DB)', () => {
it('initializes a missing balance with the effective allowance before the bulk debit', async () => {
const balance = {
enabled: true,
startBalance: 1000,
autoRefillEnabled: true,
refillAmount: 1000,
refillMode: 'reset' as const,
refillIntervalValue: 7,
refillIntervalUnit: 'days' as const,
};
const docs: PreparedEntry[] = [
{
doc: { user: testUserId, conversationId: 'c1', tokenType: 'prompt', tokenValue: -300 },
tokenValue: -300,
balance,
},
];
await bulkWriteTransactions(
{ user: testUserId, docs },
{
insertMany: dbMethods.bulkInsertTransactions,
updateBalance: dbMethods.updateBalance,
},
);
expect(await Balance.findOne({ user: testUserId }).lean()).toMatchObject({
tokenCredits: 700,
allotment: 1000,
refillMode: 'reset',
refillAmount: 1000,
});
expect(await Transaction.countDocuments({ user: testUserId })).toBe(1);
});
it('should return early for empty docs without DB writes', async () => {
const dbOps = {
insertMany: dbMethods.bulkInsertTransactions,

View file

@ -92,7 +92,11 @@ export interface TxMetadata {
export interface BulkWriteDeps {
insertMany: (docs: TransactionData[]) => Promise<unknown>;
updateBalance: (params: { user: string; incrementValue: number }) => Promise<unknown>;
updateBalance: (params: {
user: string;
incrementValue: number;
balanceConfig?: Partial<TCustomConfig['balance']>;
}) => Promise<unknown>;
}
function calculateTokenValue(
@ -362,10 +366,10 @@ export async function bulkWriteTransactions(
}
let totalTokenValue = 0;
let balanceEnabled = false;
let balanceConfig: Partial<TCustomConfig['balance']> | undefined;
const plainDocs = docs.map(({ doc, tokenValue, balance }) => {
if (balance?.enabled) {
balanceEnabled = true;
balanceConfig ??= balance;
totalTokenValue += tokenValue;
}
return doc;
@ -377,7 +381,7 @@ export async function bulkWriteTransactions(
*/
await dbOps.insertMany(plainDocs);
if (balanceEnabled) {
await dbOps.updateBalance({ user, incrementValue: totalTokenValue });
if (balanceConfig) {
await dbOps.updateBalance({ user, incrementValue: totalTokenValue, balanceConfig });
}
}

View file

@ -8,7 +8,7 @@ export interface SpendTxData {
model?: string;
context?: string;
endpointTokenConfig?: Record<string, Record<string, number>> | null;
balance?: { enabled?: boolean };
balance?: TxData['balance'];
transactions?: { enabled?: boolean };
valueKey?: string;
}

View file

@ -0,0 +1,178 @@
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import type { ITransaction } from '~/schema/transaction';
import type { IBalance } from '~/types';
import { createSpendTokensMethods } from './spendTokens';
import { createTransactionMethods } from './transaction';
import transactionSchema from '~/schema/transaction';
import balanceSchema from '~/schema/balance';
jest.mock('~/config/winston', () => ({ error: jest.fn(), debug: jest.fn() }));
let server: MongoMemoryServer;
let Balance: mongoose.Model<IBalance>;
let Transaction: mongoose.Model<ITransaction>;
let methods: ReturnType<typeof createTransactionMethods>;
let spend: ReturnType<typeof createSpendTokensMethods>;
const policy = {
enabled: true,
startBalance: 1000,
autoRefillEnabled: true,
refillAmount: 1000,
refillMode: 'reset' as const,
refillIntervalValue: 7,
refillIntervalUnit: 'days' as const,
};
beforeAll(async () => {
server = await MongoMemoryServer.create();
await mongoose.connect(server.getUri());
Balance = mongoose.model<IBalance>('Balance', balanceSchema);
Transaction = mongoose.model<ITransaction>('Transaction', transactionSchema);
methods = createTransactionMethods(mongoose, {
getMultiplier: () => 2,
getCacheMultiplier: () => 1,
});
spend = createSpendTokensMethods(mongoose, methods);
});
beforeEach(async () => {
await mongoose.connection.dropDatabase();
});
afterAll(async () => {
await mongoose.disconnect();
await server?.stop();
});
describe('debit-first balance initialization', () => {
test.each(['regular', 'structured'] as const)(
'%s spending grants the configured start balance before charging a missing record',
async (kind) => {
const user = new mongoose.Types.ObjectId();
const context = { user, balance: policy };
if (kind === 'regular') {
await spend.spendTokens(context, { promptTokens: 100, completionTokens: 50 });
} else {
await spend.spendStructuredTokens(context, {
promptTokens: { input: 100 },
completionTokens: 50,
});
}
const balance = await Balance.findOne({ user }).lean();
expect(balance).toMatchObject({
tokenCredits: 700,
autoRefillEnabled: true,
refillMode: 'reset',
refillAmount: 1000,
refillIntervalValue: 7,
refillIntervalUnit: 'days',
allotment: 1000,
});
expect(balance?.allottedAt).toEqual(balance?.lastRefill);
expect(await Balance.countDocuments({ user })).toBe(1);
expect(await Transaction.countDocuments({ user })).toBe(2);
},
);
test('concurrent debits and admission grant the starting allowance only once', async () => {
const user = new mongoose.Types.ObjectId();
await Promise.all([
methods.createTransaction({ user, balance: policy, tokenType: 'completion', rawAmount: -10 }),
methods.createStructuredTransaction({
user,
balance: policy,
tokenType: 'completion',
rawAmount: -20,
}),
methods.reserveBalance({
user: user.toString(),
reservationId: 'admission',
amount: 0,
expiresAt: new Date(Date.now() + 60000),
initialBalance: {
tokenCredits: 1000,
autoRefillEnabled: true,
refillAmount: 1000,
refillMode: 'reset',
refillIntervalValue: 7,
refillIntervalUnit: 'days',
},
}),
]);
expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(940);
expect(await Balance.countDocuments({ user })).toBe(1);
});
test.each([0, 400])('never restores an existing balance of %s credits', async (tokenCredits) => {
const user = new mongoose.Types.ObjectId();
const lastRefill = new Date();
await Balance.create({ user, tokenCredits, lastRefill });
await methods.createTransaction({
user,
balance: policy,
tokenType: 'completion',
rawAmount: -10,
});
const balance = await Balance.findOne({ user }).lean();
expect(balance?.tokenCredits).toBe(Math.max(0, tokenCredits - 20));
expect(balance?.lastRefill).toEqual(lastRefill);
});
test('preserves legacy zero initialization without a configured starting allowance', async () => {
const user = new mongoose.Types.ObjectId();
await methods.createTransaction({
user,
balance: { enabled: true },
tokenType: 'completion',
rawAmount: -10,
});
expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(0);
});
test('an administrative credit grants only the requested amount', async () => {
const user = new mongoose.Types.ObjectId();
await methods.createTransaction({
user,
balance: policy,
tokenType: 'credits',
context: 'admin',
rawAmount: 200,
});
expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(400);
});
test('an explicitly zero starting allowance stays zero', async () => {
const user = new mongoose.Types.ObjectId();
await methods.createTransaction({
user,
balance: { ...policy, startBalance: 0 },
tokenType: 'completion',
rawAmount: -10,
});
expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(0);
});
test('a zero-cost first transaction does not poison the next debit', async () => {
const user = new mongoose.Types.ObjectId();
await methods.createTransaction({ user, balance: policy, tokenType: 'prompt', rawAmount: 0 });
await methods.createTransaction({
user,
balance: policy,
tokenType: 'completion',
rawAmount: -10,
});
expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(980);
});
test('a bulk debit can initialize from the effective balance policy', async () => {
const user = new mongoose.Types.ObjectId();
await methods.updateBalance({
user: user.toString(),
incrementValue: -300,
balanceConfig: policy,
});
expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(700);
});
});

View file

@ -1,5 +1,6 @@
import { isBalanceRefillDue } from 'librechat-data-provider';
import type { AnyBulkWriteOperation, FilterQuery, Model, Types } from 'mongoose';
import type { TCustomConfig } from 'librechat-data-provider';
import type {
BalanceReservationRequest,
BalanceReservationRenewal,
@ -70,7 +71,7 @@ export interface TxData {
/** Subset of `writeTokens` written to the 1-hour cache */
write1hTokens?: number;
readTokens?: number;
balance?: { enabled?: boolean };
balance?: Partial<TCustomConfig['balance']>;
transactions?: { enabled?: boolean };
}
@ -84,6 +85,24 @@ export interface TransactionResult {
credits?: number;
}
function initialDebitBalance(balance: TxData['balance']): IBalanceUpdate | undefined {
if (!balance?.enabled || balance.startBalance == null) {
return;
}
const grantedAt = new Date();
return {
tokenCredits: balance.startBalance,
allotment: balance.startBalance,
allottedAt: grantedAt,
lastRefill: grantedAt,
autoRefillEnabled: balance.autoRefillEnabled ?? false,
refillAmount: balance.refillAmount,
refillMode: balance.refillMode ?? 'add',
refillIntervalValue: balance.refillIntervalValue,
refillIntervalUnit: balance.refillIntervalUnit,
};
}
export function createTransactionMethods(
mongoose: typeof import('mongoose'),
txMethods: {
@ -95,10 +114,12 @@ export function createTransactionMethods(
user,
incrementValue,
setValues,
balanceConfig,
}: {
user: string;
incrementValue: number;
setValues?: IBalanceUpdate;
balanceConfig?: TxData['balance'];
}) => Promise<IBalance>;
bulkInsertTransactions: (docs: TransactionData[]) => Promise<void>;
findBalanceByUser: (
@ -247,10 +268,12 @@ export function createTransactionMethods(
user,
incrementValue,
setValues,
balanceConfig,
}: {
user: string;
incrementValue: number;
setValues?: IBalanceUpdate;
balanceConfig?: TxData['balance'];
}): Promise<IBalance> {
const Balance = mongoose.models.Balance as Model<IBalance>;
const maxRetries = 10;
@ -285,7 +308,11 @@ export function createTransactionMethods(
}
lastError = new Error(`Concurrency conflict for user ${user} on attempt ${attempt}.`);
} else {
await upsertBalanceRecord(user, {}, { tokenCredits: 0 });
await upsertBalanceRecord(
user,
{},
initialDebitBalance(balanceConfig) ?? { tokenCredits: 0 },
);
continue;
}
} catch (error) {
@ -650,6 +677,7 @@ export function createTransactionMethods(
const balanceResponse = await updateBalance({
user: transaction.user as string,
incrementValue,
balanceConfig: transaction.tokenType === 'credits' ? undefined : balance,
});
return {
@ -690,6 +718,7 @@ export function createTransactionMethods(
const balanceResponse = await updateBalance({
user: transaction.user as string,
incrementValue,
balanceConfig: transaction.tokenType === 'credits' ? undefined : balance,
});
return {