Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { logger, createMethods, createModels } from '@librechat/data-schemas';
import {
ViolationTypes,
MIN_BALANCE_RESERVATION_TTL_MS,
DEFAULT_BALANCE_RESERVATION_TTL_MS,
} from 'librechat-data-provider';
import type { BalanceConfig, IBalance } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { BalanceReservation, CheckBalanceDeps } from './checkBalance';
import type { ServerRequest } from '~/types/http';
import { checkBalance, createBalanceReservations, withBalanceReservations } from './checkBalance';
jest.mock('@librechat/data-schemas', () => ({
...jest.requireActual('@librechat/data-schemas'),
logger: {
debug: jest.fn(),
error: jest.fn(),
warn: jest.fn(),
},
}));
describe('checkBalance', () => {
const createMockDeps = (overrides: Partial<CheckBalanceDeps> = {}): CheckBalanceDeps => ({
reserveBalance: jest.fn().mockResolvedValue({ reserved: true, balance: 1000 }),
renewBalanceReservation: jest.fn().mockResolvedValue(undefined),
releaseBalanceReservation: jest.fn().mockResolvedValue(undefined),
getMultiplier: jest.fn().mockReturnValue(1),
logViolation: jest.fn().mockResolvedValue(undefined),
...overrides,
});
const req = { user: { id: 'user-1' } } as ServerRequest;
const res = {} as Response;
const baseTxData = {
user: 'user-1',
tokenType: 'prompt',
amount: 100,
endpoint: 'openAI',
model: 'gpt-4',
};
const reserveRequest = (deps: CheckBalanceDeps) =>
(deps.reserveBalance as jest.Mock).mock.calls[0][0];
it('reserves the token cost and releases that reservation exactly once', async () => {
const deps = createMockDeps({ getMultiplier: jest.fn().mockReturnValue(2) });
const reservation = await checkBalance({ req, res, txData: baseTxData }, deps);
expect(deps.reserveBalance).toHaveBeenCalledWith({
user: 'user-1',
amount: 200,
reservationId: expect.any(String),
expiresAt: expect.any(Date),
initialBalance: undefined,
});
const { reservationId } = reserveRequest(deps);
expect(deps.releaseBalanceReservation).not.toHaveBeenCalled();
await Promise.all([reservation.release(), reservation.release()]);
await reservation.release();
expect(deps.releaseBalanceReservation).toHaveBeenCalledTimes(1);
expect(deps.releaseBalanceReservation).toHaveBeenCalledWith({
user: 'user-1',
reservationId,
amount: 200,
});
});
it('logs instead of throwing when a release fails', async () => {
const deps = createMockDeps({
releaseBalanceReservation: jest.fn().mockRejectedValue(new Error('DB unavailable')),
});
const reservation = await checkBalance({ req, res, txData: baseTxData }, deps);
await expect(reservation.release()).resolves.toBeUndefined();
expect(logger.error).toHaveBeenCalledWith(
'[Balance.check] Failed to release balance reservation',
expect.objectContaining({ user: 'user-1' }),
);
});
it('throws a TOKEN_BALANCE violation with the unreserved balance when refused', async () => {
const deps = createMockDeps({
reserveBalance: jest.fn().mockResolvedValue({ reserved: false, balance: 10 }),
});
await expect(
checkBalance({ req, res, txData: { ...baseTxData, amount: 100 } }, deps),
).rejects.toThrow();
expect(deps.logViolation).toHaveBeenCalledWith(
req,
res,
ViolationTypes.TOKEN_BALANCE,
expect.objectContaining({ balance: 10, tokenCost: 100 }),
0,
);
});
it('reports no less than zero balance when reservations exceed the credits', async () => {
const deps = createMockDeps({
reserveBalance: jest.fn().mockResolvedValue({ reserved: false, balance: -200 }),
});
await expect(checkBalance({ req, res, txData: baseTxData }, deps)).rejects.toThrow();
expect(deps.logViolation).toHaveBeenCalledWith(
req,
res,
ViolationTypes.TOKEN_BALANCE,
expect.objectContaining({ balance: 0, tokenCost: 100 }),
0,
);
});
it('propagates a failure of the balance store instead of reporting a balance violation', async () => {
const deps = createMockDeps({
reserveBalance: jest.fn().mockRejectedValue(new Error('DB unavailable')),
});
await expect(checkBalance({ req, res, txData: baseTxData }, deps)).rejects.toThrow(
'DB unavailable',
);
expect(deps.logViolation).not.toHaveBeenCalled();
});
describe('reservation expiry', () => {
const expiryOf = (deps: CheckBalanceDeps) => reserveRequest(deps).expiresAt.getTime();
it('expires reservations after the configured TTL', async () => {
const deps = createMockDeps({ balanceConfig: { reservationTtlMs: 20_000 } });
const before = Date.now();
await checkBalance({ req, res, txData: baseTxData }, deps);
expect(expiryOf(deps)).toBeGreaterThanOrEqual(before + 20_000);
expect(expiryOf(deps)).toBeLessThanOrEqual(Date.now() + 20_000);
});
it('falls back to the default TTL, warning once, when the configured TTL is invalid', async () => {
const balanceConfig = { reservationTtlMs: -1 } as BalanceConfig;
const before = Date.now();
for (let i = 0; i < 2; i++) {
const deps = createMockDeps({ balanceConfig });
await checkBalance({ req, res, txData: baseTxData }, deps);
expect(expiryOf(deps)).toBeGreaterThanOrEqual(before + DEFAULT_BALANCE_RESERVATION_TTL_MS);
}
expect(logger.warn).toHaveBeenCalledTimes(1);
});
});
describe('reservation renewal', () => {
beforeEach(() => {
jest.useFakeTimers();
});
afterEach(() => {
jest.useRealTimers();
});
it('renews a held reservation every half TTL until it is released', async () => {
const deps = createMockDeps({ balanceConfig: { reservationTtlMs: 10_000 } });
const reservation = await checkBalance({ req, res, txData: baseTxData }, deps);
const { reservationId } = reserveRequest(deps);
await jest.advanceTimersByTimeAsync(5_000);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(1);
expect(deps.renewBalanceReservation).toHaveBeenCalledWith({
user: 'user-1',
reservationId,
expiresAt: new Date(Date.now() + 10_000),
});
await jest.advanceTimersByTimeAsync(5_000);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(2);
await reservation.release();
await jest.advanceTimersByTimeAsync(50_000);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(2);
});
it('retries a failed renewal well before the reservation would expire', async () => {
const deps = createMockDeps({
balanceConfig: { reservationTtlMs: 10_000 },
renewBalanceReservation: jest
.fn()
.mockRejectedValueOnce(new Error('DB unavailable'))
.mockResolvedValue(undefined),
});
const reservation = await checkBalance({ req, res, txData: baseTxData }, deps);
await jest.advanceTimersByTimeAsync(5_000);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(1);
await jest.advanceTimersByTimeAsync(500);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(2);
await jest.advanceTimersByTimeAsync(4_999);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(2);
await reservation.release();
});
it('renews from the stored expiry when the admission write is slow', async () => {
const deps = createMockDeps({
balanceConfig: { reservationTtlMs: 10_000 },
reserveBalance: jest.fn(
() =>
new Promise((resolve) =>
setTimeout(() => resolve({ reserved: true, balance: 1000 }), 3_000),
),
),
});
const admission = checkBalance({ req, res, txData: baseTxData }, deps);
await jest.advanceTimersByTimeAsync(3_000);
const reservation = await admission;
await jest.advanceTimersByTimeAsync(1_999);
expect(deps.renewBalanceReservation).not.toHaveBeenCalled();
await jest.advanceTimersByTimeAsync(1);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(1);
await reservation.release();
});
it('renews from the stored expiry when a renewal write is slow', async () => {
const deps = createMockDeps({
balanceConfig: { reservationTtlMs: 10_000 },
renewBalanceReservation: jest.fn(
() => new Promise<void>((resolve) => setTimeout(resolve, 3_000)),
),
});
const reservation = await checkBalance({ req, res, txData: baseTxData }, deps);
await jest.advanceTimersByTimeAsync(5_000);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(1);
await jest.advanceTimersByTimeAsync(4_999);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(1);
await jest.advanceTimersByTimeAsync(1);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(2);
await reservation.release();
});
it('keeps the renewal delay within the timer range for a very long TTL', async () => {
const deps = createMockDeps({ balanceConfig: { reservationTtlMs: 6_000_000_000 } });
const reservation = await checkBalance({ req, res, txData: baseTxData }, deps);
await jest.advanceTimersByTimeAsync(60_000);
expect(deps.renewBalanceReservation).not.toHaveBeenCalled();
await reservation.release();
});
it('raises a TTL below the minimum so renewal stays bounded', async () => {
const deps = createMockDeps({ balanceConfig: { reservationTtlMs: 1 } });
const before = Date.now();
const reservation = await checkBalance({ req, res, txData: baseTxData }, deps);
expect(reserveRequest(deps).expiresAt.getTime()).toBe(
before + MIN_BALANCE_RESERVATION_TTL_MS,
);
await jest.advanceTimersByTimeAsync(MIN_BALANCE_RESERVATION_TTL_MS / 2 - 1);
expect(deps.renewBalanceReservation).not.toHaveBeenCalled();
await jest.advanceTimersByTimeAsync(1);
expect(deps.renewBalanceReservation).toHaveBeenCalledTimes(1);
await reservation.release();
});
it('does not renew a zero-cost admission, which holds nothing', async () => {
const deps = createMockDeps({ balanceConfig: { reservationTtlMs: 10_000 } });
const reservation = await checkBalance(
{ req, res, txData: { ...baseTxData, amount: 0 } },
deps,
);
await jest.advanceTimersByTimeAsync(50_000);
expect(deps.renewBalanceReservation).not.toHaveBeenCalled();
await reservation.release();
});
});
describe('lazy balance initialization', () => {
it('creates a missing record from startBalance', async () => {
const deps = createMockDeps({ balanceConfig: { startBalance: 5000 } });
await checkBalance({ req, res, txData: baseTxData }, deps);
expect(reserveRequest(deps).initialBalance).toEqual({ user: 'user-1', tokenCredits: 5000 });
});
it('includes auto-refill fields when configured', async () => {
const deps = createMockDeps({
balanceConfig: {
startBalance: 5000,
autoRefillEnabled: true,
refillIntervalValue: 1,
refillIntervalUnit: 'days',
refillAmount: 1000,
},
});
await checkBalance({ req, res, txData: baseTxData }, deps);
expect(reserveRequest(deps).initialBalance).toEqual({
user: 'user-1',
tokenCredits: 5000,
autoRefillEnabled: true,
refillIntervalValue: 1,
refillIntervalUnit: 'days',
refillAmount: 1000,
lastRefill: expect.any(Date),
});
});
it('omits auto-refill fields when the refill config is partial', async () => {
const deps = createMockDeps({
balanceConfig: { startBalance: 5000, autoRefillEnabled: true },
});
await checkBalance({ req, res, txData: baseTxData }, deps);
expect(reserveRequest(deps).initialBalance).toEqual({ user: 'user-1', tokenCredits: 5000 });
});
it('creates a record with a startBalance of 0', async () => {
const deps = createMockDeps({ balanceConfig: { startBalance: 0 } });
await checkBalance({ req, res, txData: baseTxData }, deps);
expect(reserveRequest(deps).initialBalance).toEqual({ user: 'user-1', tokenCredits: 0 });
});
it.each([
['no balance config', undefined],
['no startBalance', {}],
])(
'throws a TOKEN_BALANCE violation for a missing record with %s',
async (_case, balanceConfig) => {
const deps = createMockDeps({
reserveBalance: jest.fn().mockResolvedValue(null),
balanceConfig,
});
await expect(checkBalance({ req, res, txData: baseTxData }, deps)).rejects.toThrow();
expect(reserveRequest(deps).initialBalance).toBeUndefined();
expect(deps.logViolation).toHaveBeenCalledWith(
req,
res,
ViolationTypes.TOKEN_BALANCE,
expect.objectContaining({ balance: 0 }),
0,
);
},
);
});
describe('balance reservations of a turn', () => {
const createReservation = () => {
const reservation: BalanceReservation = { release: jest.fn().mockResolvedValue(undefined) };
return reservation;
};
it('releases an admission that settles after the release was requested', async () => {
const reservations = createBalanceReservations();
const reservation = createReservation();
let admit: (value: BalanceReservation) => void = () => undefined;
reservations.track(new Promise<BalanceReservation>((resolve) => (admit = resolve)));
const released = reservations.release();
expect(reservation.release).not.toHaveBeenCalled();
admit(reservation);
await released;
expect(reservation.release).toHaveBeenCalledTimes(1);
});
it('releases nothing for a refused admission and does not reject', async () => {
const reservations = createBalanceReservations();
const refused = Promise.reject(new Error('insufficient'));
await expect(reservations.track(refused)).rejects.toThrow('insufficient');
await expect(reservations.release()).resolves.toBeUndefined();
});
it('releases each tracked reservation once across repeated releases', async () => {
const reservations = createBalanceReservations();
const first = createReservation();
const second = createReservation();
await reservations.track(Promise.resolve(first));
await reservations.release();
await reservations.track(Promise.resolve(second));
await reservations.release();
await reservations.release();
expect(first.release).toHaveBeenCalledTimes(1);
expect(second.release).toHaveBeenCalledTimes(1);
});
it('keeps reservations held until background work settles, even when it fails', async () => {
const reservations = createBalanceReservations();
const reservation = createReservation();
let finishWork: (error: Error) => void = () => undefined;
await reservations.track(Promise.resolve(reservation));
reservations.holdUntil(new Promise((_resolve, reject) => (finishWork = reject)));
const released = reservations.release();
await new Promise((resolve) => setImmediate(resolve));
expect(reservation.release).not.toHaveBeenCalled();
finishWork(new Error('background run failed'));
await released;
expect(reservation.release).toHaveBeenCalledTimes(1);
});
it('releases the turn reservations whether the turn resolves or throws', async () => {
const kept = createReservation();
const failed = createReservation();
await expect(
withBalanceReservations(async (reservations) => {
await reservations.track(Promise.resolve(kept));
return 'done';
}),
).resolves.toBe('done');
await expect(
withBalanceReservations(async (reservations) => {
await reservations.track(Promise.resolve(failed));
throw new Error('turn failed');
}),
).rejects.toThrow('turn failed');
expect(kept.release).toHaveBeenCalledTimes(1);
expect(failed.release).toHaveBeenCalledTimes(1);
});
});
describe('against a real balance store', () => {
let mongoServer: MongoMemoryServer;
let Balance: mongoose.Model<IBalance>;
let methods: ReturnType<typeof createMethods>;
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
await mongoose.connect(mongoServer.getUri());
createModels(mongoose);
Balance = mongoose.models.Balance as mongoose.Model<IBalance>;
methods = createMethods(mongoose);
});
afterAll(async () => {
await mongoose.disconnect();
await mongoServer.stop();
});
beforeEach(async () => {
await mongoose.connection.dropDatabase();
});
const realDeps = (balanceConfig?: BalanceConfig): CheckBalanceDeps => ({
getMultiplier: () => 1,
reserveBalance: methods.reserveBalance,
renewBalanceReservation: methods.renewBalanceReservation,
releaseBalanceReservation: methods.releaseBalanceReservation,
logViolation: jest.fn().mockResolvedValue(undefined),
balanceConfig,
});
const admitConcurrently = (user: string, count: number, deps: CheckBalanceDeps, amount = 400) =>
Promise.allSettled(
Array.from({ length: count }, () =>
checkBalance({ req, res, txData: { ...baseTxData, user, amount } }, deps),
),
);
const admittedOf = (outcomes: PromiseSettledResult<BalanceReservation>[]) =>
outcomes.flatMap((outcome) => (outcome.status === 'fulfilled' ? [outcome.value] : []));
it('admits concurrent requests only against credits no in-flight request holds', async () => {
const user = new mongoose.Types.ObjectId().toString();
await Balance.create({ user, tokenCredits: 1000 });
const deps = realDeps();
const admitted = admittedOf(await admitConcurrently(user, 20, deps));
expect(admitted).toHaveLength(2);
expect(deps.logViolation).toHaveBeenCalledTimes(18);
await Promise.all(admitted.map((reservation) => reservation.release()));
expect(admittedOf(await admitConcurrently(user, 3, deps))).toHaveLength(2);
});
it('admits every request of a funded concurrent burst', async () => {
const user = new mongoose.Types.ObjectId().toString();
await Balance.create({ user, tokenCredits: 100_000 });
const outcomes = await admitConcurrently(user, 40, realDeps(), 100);
expect(admittedOf(outcomes)).toHaveLength(40);
});
it('refills once for concurrent requests arriving in one refill window', async () => {
const user = new mongoose.Types.ObjectId().toString();
await Balance.create({
user,
tokenCredits: 5,
autoRefillEnabled: true,
refillAmount: 1000,
refillIntervalValue: 30,
refillIntervalUnit: 'days',
lastRefill: new Date('2020-01-01T00:00:00.000Z'),
});
const outcomes = await admitConcurrently(user, 10, realDeps());
expect(admittedOf(outcomes)).toHaveLength(2);
const stored = await Balance.findOne({ user }).lean();
expect(stored?.tokenCredits).toBe(1005);
const refills = await methods.getTransactions({ user, context: 'autoRefill' });
expect(refills).toHaveLength(1);
});
it.each([
['increased', 2000, true, 'reset' as const, 2000],
['decreased', 400, true, 'reset' as const, 400],
['disabled', 1000, false, 'reset' as const, 500],
['changed to additive', 1000, true, 'add' as const, 500],
])(
'uses the %s current policy for direct admission without a balance read',
async (_case, refillAmount, autoRefillEnabled, refillMode, expectedCredits) => {
const user = new mongoose.Types.ObjectId().toString();
const lastRefill = new Date('2020-01-01');
await Balance.create({
user,
tokenCredits: 500,
autoRefillEnabled: true,
refillMode: 'reset',
refillAmount: 1000,
refillIntervalValue: 1,
refillIntervalUnit: 'weeks',
lastRefill,
});
const reservation = await checkBalance(
{ req, res, txData: { ...baseTxData, user, amount: 100 } },
realDeps({
startBalance: 9999,
refillAmount,
autoRefillEnabled,
refillMode,
refillIntervalValue: 1,
refillIntervalUnit: 'weeks',
}),
);
await reservation.release();
expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(expectedCredits);
const ledger = await methods.getTransactions({ user, context: 'balanceReset' });
expect(ledger).toHaveLength(autoRefillEnabled && refillMode === 'reset' ? 1 : 0);
},
);
it('preserves the period and held credits when policy is synchronized before concurrent admissions', async () => {
const user = new mongoose.Types.ObjectId().toString();
const lastRefill = new Date();
await Balance.create({
user,
tokenCredits: 500,
autoRefillEnabled: true,
refillMode: 'reset',
refillAmount: 1000,
refillIntervalValue: 1,
refillIntervalUnit: 'weeks',
lastRefill,
reservations: [{ id: 'held', amount: 400, expiresAt: new Date(Date.now() + 60_000) }],
reservedCredits: 400,
});
const deps = realDeps({
startBalance: 9999,
autoRefillEnabled: true,
refillMode: 'reset',
refillAmount: 2000,
refillIntervalValue: 1,
refillIntervalUnit: 'weeks',
});
const admitted = admittedOf(await admitConcurrently(user, 10, deps, 100));
expect(admitted).toHaveLength(1);
await Promise.all(admitted.map((reservation) => reservation.release()));
const record = await Balance.findOne({ user }).select('+reservedCredits').lean();
expect(record).toMatchObject({
tokenCredits: 500,
reservedCredits: 400,
refillAmount: 2000,
lastRefill,
});
expect(await methods.getTransactions({ user, context: 'balanceReset' })).toHaveLength(0);
});
it('lazily initializes a missing record and reserves against it', async () => {
const user = new mongoose.Types.ObjectId().toString();
const deps = realDeps({ startBalance: 1000 });
await checkBalance({ req, res, txData: { ...baseTxData, user, amount: 400 } }, deps);
const outcomes = await admitConcurrently(user, 4, deps);
expect(admittedOf(outcomes)).toHaveLength(1);
const stored = await Balance.findOne({ user }).select('+reservedCredits').lean();
expect(stored?.tokenCredits).toBe(1000);
expect(stored?.reservedCredits).toBe(800);
});
});
});