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 { v4 as uuidv4 } from 'uuid';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { EToolResources, FileContext, FileSources } from 'librechat-data-provider';
import type { CodeEnvRef } from 'librechat-data-provider';
import type { IChatProject, IMongoFile } from '~/types';
import { _resetStrictCache } from '~/models/plugins/tenantIsolation';
import { createFileMethods, FileStorageConflictError } from './file';
import { tenantStorage, runAsSystem } from '~/config/tenantContext';
import { createModels } from '~/models';
let File: mongoose.Model<unknown>;
let fileMethods: ReturnType<typeof createFileMethods>;
let mongoServer: MongoMemoryServer;
let modelsToCleanup: string[] = [];
describe('File Methods', () => {
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
const mongoUri = mongoServer.getUri();
await mongoose.connect(mongoUri);
const models = createModels(mongoose);
modelsToCleanup = Object.keys(models);
Object.assign(mongoose.models, models);
File = mongoose.models.File as mongoose.Model<unknown>;
fileMethods = createFileMethods(mongoose);
});
afterAll(async () => {
const collections = mongoose.connection.collections;
for (const key in collections) {
await collections[key].deleteMany({});
}
for (const modelName of modelsToCleanup) {
if (mongoose.models[modelName]) {
delete mongoose.models[modelName];
}
}
await mongoose.disconnect();
await mongoServer.stop();
});
beforeEach(async () => {
await File.deleteMany({});
});
describe('clearFileCodeEnvRefs', () => {
const user = new mongoose.Types.ObjectId();
const updatedAt = new Date('2026-10-20T00:00:00Z');
const defaultRef: CodeEnvRef = {
kind: 'user',
id: user.toString(),
storage_session_id: 'default-session',
file_id: 'remote-default',
executionProfile: 'default',
executionRouteKey: 'default',
provisionedAt: 123,
sandboxFilename: '$notes.csv',
};
const statefulRef: CodeEnvRef = {
...defaultRef,
storage_session_id: 'stateful-session',
file_id: 'remote-stateful',
executionProfile: 'stateful',
executionRouteKey: 'stateful:a',
};
const snapshot = {
file_id: 'retained-code-file',
userId: user.toString(),
tenantId: 'tenant-a',
refs: [{ routeKey: 'default', ref: defaultRef }],
};
const metadata = {
codeEnvRef: defaultRef,
codeEnvRefs: { default: defaultRef, 'stateful:a': statefulRef },
embeddedEntities: ['agent-a'],
searchDestination: true,
destinationChosen: true,
routingMimeType: 'text/csv',
sourceDispatchedAt: 42,
toolResource: EToolResources.execute_code,
};
const seed = (overrides = {}) =>
File.collection.insertOne({
file_id: snapshot.file_id,
user,
tenantId: snapshot.tenantId,
context: FileContext.message_attachment,
conversationId: 'conversation-a',
filename: 'notes.csv',
filepath: '/uploads/notes.csv',
type: 'text/csv',
bytes: 100,
source: 'local',
llmDeliveryPath: 'none',
embedded: true,
updatedAt,
metadata,
...overrides,
});
const read = () => File.collection.findOne({ file_id: snapshot.file_id, user });
it('removes matching pointers without changing content, intent or bookkeeping', async () => {
await seed({
createdAt: updatedAt,
expiresAt: new Date('2030-01-01'),
expiredAt: new Date('2026-10-19'),
deletionAttempts: 3,
deletionRetryAt: new Date('2026-10-23'),
text: 'canonical source',
});
const before = await read();
const update = jest.spyOn(mongoose.models.File, 'updateOne');
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(true);
expect(update).toHaveBeenCalledTimes(2);
const paths = ['metadata.codeEnvRefs.default', 'metadata.codeEnvRef'];
for (const [index, path] of paths.entries()) {
expect(update).toHaveBeenNthCalledWith(
index + 1,
{
file_id: snapshot.file_id,
user: snapshot.userId,
$and: [{ tenantId: snapshot.tenantId }],
$or: [expect.any(Object)],
},
{ $unset: { [path]: '' }, $set: { 'metadata.codeDestination': true } },
{ timestamps: false },
);
}
expect(JSON.stringify(update.mock.calls)).not.toMatch(/\$expr|\$\$REMOVE/);
const after = await read();
const { codeEnvRef: _alias, codeEnvRefs: _routes, ...intent } = metadata;
expect(after).toEqual({
...before,
metadata: {
...intent,
codeDestination: true,
codeEnvRefs: { 'stateful:a': statefulRef },
},
});
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(true);
expect(await read()).toEqual(after);
});
it.each([
['kind', 'agent'],
['id', 'other-owner'],
['storage_session_id', 'new-session'],
['file_id', 'new-remote-id'],
['executionProfile', 'stateful'],
['executionRouteKey', 'stateful:b'],
['provisionedAt', 124],
['sandboxFilename', 'new-name.csv'],
['version', 2],
])('preserves reprovisioned pointers when %s differs', async (field, value) => {
const replacement = { ...defaultRef, [field]: value };
await seed({
metadata: {
...metadata,
codeEnvRef: replacement,
codeEnvRefs: { default: replacement, 'stateful:a': statefulRef },
},
});
const before = await read();
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(false);
expect(await read()).toEqual(before);
});
it.each([
[true, undefined],
[true, false],
[true, true],
[false, undefined],
[false, false],
[false, true],
] as const)(
'retains code intent only for a matching snapshot: %s, %s',
async (matches, prior) => {
const ref = matches ? defaultRef : { ...defaultRef, provisionedAt: 124 };
await seed({
metadata: {
...metadata,
codeEnvRef: ref,
codeEnvRefs: { default: ref },
...(prior === undefined ? {} : { codeDestination: prior }),
},
});
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(matches);
expect((await read())?.metadata?.codeDestination).toBe(matches ? true : prior);
},
);
it('compares absent optional fields as part of the full snapshot', async () => {
const replacement = { ...defaultRef };
delete replacement.provisionedAt;
await seed({
metadata: { codeEnvRef: replacement, codeEnvRefs: { default: replacement } },
});
const before = await read();
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(false);
expect(await read()).toEqual(before);
});
it.each([
'executionProfile',
'executionRouteKey',
'provisionedAt',
'sandboxFilename',
'version',
])('distinguishes null from absent optional snapshot fields: %s', async (field) => {
const absent = { ...defaultRef };
Reflect.deleteProperty(absent, field);
const explicitNull = { ...absent, [field]: null };
await seed({
metadata: { codeEnvRef: explicitNull, codeEnvRefs: { default: explicitNull } },
});
const before = await read();
expect(
await fileMethods.clearFileCodeEnvRefs({
...snapshot,
refs: [{ routeKey: 'default', ref: absent }],
}),
).toBe(false);
expect(await read()).toEqual(before);
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{ $set: { metadata: { codeEnvRef: absent, codeEnvRefs: { default: absent } } } },
);
const withoutField = await read();
expect(
await fileMethods.clearFileCodeEnvRefs({
...snapshot,
refs: [{ routeKey: 'default', ref: explicitNull }],
}),
).toBe(false);
expect(await read()).toEqual(withoutField);
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{
$set: { metadata: { codeEnvRef: explicitNull, codeEnvRefs: { default: explicitNull } } },
},
);
expect(
await fileMethods.clearFileCodeEnvRefs({
...snapshot,
refs: [{ routeKey: 'default', ref: explicitNull }],
}),
).toBe(true);
expect((await read())?.metadata?.codeEnvRefs?.default).toBeUndefined();
expect((await read())?.metadata?.codeEnvRef).toBeUndefined();
});
it('matches every field regardless of BSON property order', async () => {
await seed();
const { file_id, ...rest } = defaultRef;
expect(
await fileMethods.clearFileCodeEnvRefs({
...snapshot,
refs: [{ routeKey: 'default', ref: { file_id, ...rest } }],
}),
).toBe(true);
const stored = await read();
expect(stored?.metadata?.codeEnvRef).toBeUndefined();
expect(stored?.metadata?.codeEnvRefs).toEqual({ 'stateful:a': statefulRef });
});
it('clears matching sibling routes even when another snapshot was replaced', async () => {
const replacement = { ...defaultRef, provisionedAt: 124 };
await seed({
metadata: {
...metadata,
codeEnvRef: replacement,
codeEnvRefs: { default: replacement, 'stateful:a': statefulRef },
},
});
expect(
await fileMethods.clearFileCodeEnvRefs({
...snapshot,
refs: [...snapshot.refs, { routeKey: 'stateful:a', ref: statefulRef }],
}),
).toBe(false);
const stored = await read();
expect(stored?.metadata?.codeEnvRef).toEqual(replacement);
expect(stored?.metadata?.codeEnvRefs).toEqual({ default: replacement });
});
it.each([statefulRef, { ...defaultRef, provisionedAt: 124 }])(
'preserves an unrelated or replaced legacy alias: %p',
async (alias) => {
await seed({ metadata: { ...metadata, codeEnvRef: alias } });
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(alias === statefulRef);
const stored = await read();
expect(stored?.metadata?.codeEnvRef).toEqual(alias);
expect(stored?.metadata?.codeEnvRefs?.default).toBeUndefined();
},
);
it('preserves routes and aliases replaced between the independent conditional writes', async () => {
await seed();
const replacement = { ...defaultRef, provisionedAt: 124 };
const sibling = { ...statefulRef, provisionedAt: 125 };
const updateOne = File.collection.updateOne.bind(File.collection);
jest.spyOn(File.collection, 'updateOne').mockImplementation(async (...args) => {
const operation = args[1];
if (
operation != null &&
!Array.isArray(operation) &&
operation.$unset?.['metadata.codeEnvRef'] !== undefined
) {
await updateOne(
{ file_id: snapshot.file_id },
{
$set: {
'metadata.codeEnvRef': replacement,
'metadata.codeEnvRefs.stateful:a': sibling,
},
},
);
}
return updateOne(...args);
});
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(false);
const stored = await read();
expect(stored?.metadata?.codeEnvRef).toEqual(replacement);
expect(stored?.metadata?.codeEnvRefs).toEqual({ 'stateful:a': sibling });
expect(stored?.updatedAt).toEqual(updatedAt);
});
it.each(['metadata.codeEnvRefs.default', 'metadata.codeEnvRef'])(
'confirms route absence with a narrow owned read when only %s matches',
async (path) => {
await seed({ metadata: {} });
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{ $set: { [path]: defaultRef } },
);
const find = jest.spyOn(mongoose.models.File, 'findOne');
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(true);
expect(find).toHaveBeenCalledTimes(1);
expect(find).toHaveBeenCalledWith(
{
file_id: snapshot.file_id,
user: snapshot.userId,
$and: [{ tenantId: snapshot.tenantId }],
},
{ _id: 0, 'metadata.codeEnvRef': 1, 'metadata.codeEnvRefs': 1 },
);
expect((await read())?.metadata?.codeDestination).toBe(true);
},
);
it('confirms route absence when every conditional write misses', async () => {
await seed({ metadata: {} });
const find = jest.spyOn(mongoose.models.File, 'findOne');
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(true);
expect(find).toHaveBeenCalledTimes(1);
expect(find).toHaveBeenCalledWith(
{
file_id: snapshot.file_id,
user: snapshot.userId,
$and: [{ tenantId: snapshot.tenantId }],
},
{ _id: 0, 'metadata.codeEnvRef': 1, 'metadata.codeEnvRefs': 1 },
);
expect((await read())?.metadata).toEqual({});
});
it.each([false, true])(
'keeps generated files hydratable with legacy-only refs: %s',
async (legacyOnly) => {
await seed({
context: FileContext.execute_code,
metadata: {
codeEnvRef: defaultRef,
...(legacyOnly ? {} : { codeEnvRefs: { default: defaultRef } }),
},
});
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(true);
const stored = await read();
expect(stored?.metadata?.codeEnvRef).toBeUndefined();
expect(stored?.metadata?.codeEnvRefs).toEqual(legacyOnly ? undefined : {});
const generated = await fileMethods.getCodeGeneratedFiles(
'conversation-a',
[snapshot.file_id],
snapshot,
);
expect(generated.map((file) => file.file_id)).toEqual([snapshot.file_id]);
},
);
it.each([FileContext.execute_code, FileContext.message_attachment])(
'hydrates marker-only code intent without crossing owner, tenant, conversation or thread: %s',
async (context) => {
await runAsSystem(() =>
File.create({
file_id: snapshot.file_id,
user,
tenantId: snapshot.tenantId,
conversationId: 'conversation-a',
context,
filename: 'notes.csv',
filepath: '/uploads/notes.csv',
type: 'text/csv',
bytes: 100,
llmDeliveryPath: 'none',
metadata: { codeDestination: true, destinationChosen: true },
}),
);
const hydrate = (ids: string[], scope = snapshot, conversationId = 'conversation-a') =>
context === FileContext.execute_code
? fileMethods.getCodeGeneratedFiles(conversationId, ids, scope)
: fileMethods.getUserCodeFiles(ids, scope);
const files = await hydrate([snapshot.file_id]);
expect(files.map((file) => file.file_id)).toEqual([snapshot.file_id]);
expect(files[0].metadata?.codeDestination).toBe(true);
expect(files[0].metadata?.codeEnvRef).toBeUndefined();
expect(files[0].metadata?.codeEnvRefs).toBeUndefined();
expect(await hydrate(['not-in-thread'])).toEqual([]);
expect(
await hydrate([snapshot.file_id], {
...snapshot,
userId: new mongoose.Types.ObjectId().toString(),
}),
).toEqual([]);
expect(await hydrate([snapshot.file_id], { ...snapshot, tenantId: 'tenant-b' })).toEqual(
[],
);
if (context === FileContext.execute_code) {
expect(await hydrate([snapshot.file_id], snapshot, 'other-conversation')).toEqual([]);
} else {
const deferred = await fileMethods.getDeferredProvisionFiles(
[snapshot.file_id],
snapshot,
{ code: true },
);
expect(deferred.map((file) => file.file_id)).toEqual([snapshot.file_id]);
}
await File.updateOne(
{ file_id: snapshot.file_id },
{ $set: { 'metadata.codeDestination': false } },
);
expect(await hydrate([snapshot.file_id])).toEqual([]);
await File.updateOne(
{ file_id: snapshot.file_id },
{ $unset: { 'metadata.codeDestination': '' } },
);
expect(await hydrate([snapshot.file_id])).toEqual([]);
},
);
it.each([
{},
{ executionProfile: 'default' as const },
{ executionProfile: 'stateful' as const },
])('clears legacy-only refs and queues the missing route: %p', async (routeFields) => {
const ref: CodeEnvRef = {
kind: 'user',
id: user.toString(),
storage_session_id: 'legacy-session',
file_id: 'legacy-remote',
...routeFields,
};
await seed({ metadata: { ...metadata, codeEnvRef: ref, codeEnvRefs: undefined } });
const routeKey = ref.executionProfile ?? 'default';
expect(
await fileMethods.getDeferredProvisionFiles([snapshot.file_id], snapshot, {
code: true,
codeRouteKey: routeKey,
}),
).toEqual([]);
expect(
await fileMethods.clearFileCodeEnvRefs({ ...snapshot, refs: [{ routeKey, ref }] }),
).toBe(true);
const deferred = await fileMethods.getDeferredProvisionFiles([snapshot.file_id], snapshot, {
code: true,
codeRouteKey: routeKey,
});
expect(deferred.map((file) => file.file_id)).toEqual([snapshot.file_id]);
expect(deferred[0].llmDeliveryPath).toBe('none');
expect(deferred[0].metadata?.destinationChosen).toBe(true);
});
it('persists each copy without mutating input or invalidating the embedding snapshot', async () => {
await seed({
embeddingOwnersComplete: true,
embeddingOwnersTrackedAt: new Date('2026-10-20'),
});
const input = structuredClone(snapshot);
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(true);
expect(
await fileMethods.clearFileCodeEnvRefs({
...snapshot,
refs: [{ routeKey: 'stateful:a', ref: statefulRef }],
}),
).toBe(true);
expect(snapshot).toEqual(input);
expect(
await fileMethods.clearFileEmbeddings({
...snapshot,
updatedAt,
embeddedEntities: metadata.embeddedEntities,
ownershipTrackingStart: '2026-10-19T00:00:00.000Z',
}),
).toBe(true);
const stored = await read();
expect(stored?.updatedAt).toEqual(updatedAt);
expect(stored?.embedded).toBe(false);
expect(stored?.metadata?.codeEnvRefs).toEqual({});
});
it.each([
{ userId: new mongoose.Types.ObjectId().toString() },
{ tenantId: 'tenant-b' },
{ tenantId: undefined },
])('returns false without changing an unauthorized file: %p', async (scope) => {
await seed({
embeddingOwnersComplete: true,
embeddingOwnersTrackedAt: new Date('2026-10-20'),
});
const before = await read();
expect(await fileMethods.clearFileCodeEnvRefs({ ...snapshot, ...scope })).toBe(false);
expect(await read()).toEqual(before);
});
it.each([false, true])('scopes legacy missing/null tenants explicitly: %s', async (missing) => {
const foreign = await seed();
const local = await seed({ tenantId: null });
if (missing) {
await File.collection.updateOne({ _id: local.insertedId }, { $unset: { tenantId: '' } });
}
expect(await fileMethods.clearFileCodeEnvRefs({ ...snapshot, tenantId: undefined })).toBe(
true,
);
const records = await File.collection.find({ file_id: snapshot.file_id }).toArray();
expect(records.find((record) => record._id.equals(foreign.insertedId))?.metadata).toEqual(
metadata,
);
expect(
records.find((record) => record._id.equals(local.insertedId))?.metadata?.codeEnvRefs,
).toEqual({ 'stateful:a': statefulRef });
});
it.each([{ tenantId: 'tenant-b' }, { tenantId: undefined }])(
'does not let tenant middleware replace the caller scope: %p',
async (scope) => {
await seed({
embeddingOwnersComplete: true,
embeddingOwnersTrackedAt: new Date('2026-10-20'),
});
const before = await read();
const cleared = await tenantStorage.run({ tenantId: snapshot.tenantId }, () =>
fileMethods.clearFileCodeEnvRefs({ ...snapshot, ...scope }),
);
expect(cleared).toBe(false);
expect(await read()).toEqual(before);
},
);
it('confirms no code refs remain for empty or already-cleared snapshots', async () => {
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(false);
await seed({ metadata: {} });
expect(await fileMethods.clearFileCodeEnvRefs({ ...snapshot, refs: [] })).toBe(true);
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(true);
expect(
await fileMethods.clearFileCodeEnvRefs({ ...snapshot, file_id: 'missing', refs: [] }),
).toBe(false);
});
it.each(['metadata.codeEnvRef', 'metadata.codeEnvRefs.default'])(
'rejects a primary-code-only replacement at %s',
async (path) => {
await seed({
source: 'execute_code',
context: FileContext.execute_code,
embedded: false,
metadata: {},
});
const replacement = { ...defaultRef, provisionedAt: 124 };
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{ $set: { [path]: replacement } },
);
const before = await read();
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(false);
expect(await read()).toEqual(before);
},
);
it.each([false, true])(
'returns false when only one route or alias snapshot matches: %s',
async (aliasMatches) => {
const replacement = { ...defaultRef, provisionedAt: 124 };
await seed({
metadata: {
codeEnvRef: aliasMatches ? defaultRef : replacement,
codeEnvRefs: { default: aliasMatches ? replacement : defaultRef },
},
});
expect(await fileMethods.clearFileCodeEnvRefs(snapshot)).toBe(false);
const stored = await read();
expect(stored?.metadata?.codeEnvRef).toEqual(aliasMatches ? undefined : replacement);
expect(stored?.metadata?.codeEnvRefs).toEqual(aliasMatches ? { default: replacement } : {});
expect(stored?.updatedAt).toEqual(updatedAt);
},
);
it.each([defaultRef, statefulRef])(
'rejects an empty snapshot while any canonical or legacy code ref remains: %p',
async (ref) => {
await seed({ metadata: { codeEnvRef: ref } });
expect(await fileMethods.clearFileCodeEnvRefs({ ...snapshot, refs: [] })).toBe(false);
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{ $set: { metadata: { codeEnvRefs: { unknown: ref } } } },
);
expect(await fileMethods.clearFileCodeEnvRefs({ ...snapshot, refs: [] })).toBe(false);
},
);
it('propagates the final metadata read failure after writes settle', async () => {
await seed();
jest.spyOn(mongoose.models.File, 'findOne').mockImplementationOnce(() => {
throw new Error('metadata read unavailable');
});
await expect(fileMethods.clearFileCodeEnvRefs(snapshot)).rejects.toThrow(
'metadata read unavailable',
);
expect((await read())?.metadata?.codeEnvRef).toBeUndefined();
expect((await read())?.metadata?.codeEnvRefs).toEqual({ 'stateful:a': statefulRef });
});
it.each(['', 'stateful.invalid', '$stateful'])(
'rejects invalid route keys: %s',
async (routeKey) => {
await seed();
const before = await read();
await expect(
fileMethods.clearFileCodeEnvRefs({
...snapshot,
refs: [...snapshot.refs, { routeKey, ref: statefulRef }],
}),
).rejects.toThrow('Invalid code environment route key');
expect(await read()).toEqual(before);
},
);
it('settles sibling writes before propagating a persistence failure', async () => {
await seed();
let finishWrite: () => void = () => undefined;
const pendingWrite = new Promise<void>((resolve) => {
finishWrite = resolve;
});
const failure = new Error('mongo unavailable');
const updateOne = File.collection.updateOne.bind(File.collection);
jest.spyOn(File.collection, 'updateOne').mockImplementation(async (...args) => {
const operation = args[1];
if (
operation != null &&
!Array.isArray(operation) &&
operation.$unset?.['metadata.codeEnvRefs.default'] !== undefined
) {
throw failure;
}
await pendingWrite;
return updateOne(...args);
});
const find = jest.spyOn(mongoose.models.File, 'findOne');
let returned = false;
const clearing = fileMethods.clearFileCodeEnvRefs(snapshot).catch((error: Error) => {
returned = true;
return error;
});
await new Promise<void>((resolve) => setImmediate(resolve));
try {
expect(returned).toBe(false);
} finally {
finishWrite();
}
expect(await clearing).toBe(failure);
expect(find).not.toHaveBeenCalled();
const stored = await read();
expect(stored?.metadata?.codeEnvRef).toBeUndefined();
expect(stored?.metadata?.codeEnvRefs?.default).toEqual(defaultRef);
expect(stored?.metadata?.codeDestination).toBe(true);
});
it('propagates persistence failures', async () => {
await seed();
const before = await read();
jest.spyOn(mongoose.models.File, 'updateOne').mockImplementation(() => {
throw new Error('mongo unavailable');
});
await expect(fileMethods.clearFileCodeEnvRefs(snapshot)).rejects.toThrow('mongo unavailable');
expect(await read()).toEqual(before);
});
});
describe('clearFileEmbeddings', () => {
const user = new mongoose.Types.ObjectId();
const updatedAt = new Date('2026-10-20T00:00:00Z');
const snapshot = {
ownershipTrackingStart: '2026-10-19T00:00:00.000Z',
file_id: 'retained-file',
userId: user.toString(),
tenantId: 'tenant-a',
updatedAt,
embeddedEntities: ['agent-a', 'agent-b'],
};
const seed = (overrides = {}) =>
File.collection.insertOne({
file_id: snapshot.file_id,
user,
tenantId: snapshot.tenantId,
updatedAt,
embedded: true,
embeddingOwnersComplete: true,
embeddingOwnersTrackedAt: new Date('2026-10-20'),
metadata: {
embeddedEntities: snapshot.embeddedEntities,
codeEnvRef: { file_id: 'still-needed' },
destinationChosen: true,
},
...overrides,
});
it('preserves code references, TTL and retry bookkeeping', async () => {
const expiredAt = new Date('2026-10-19');
await seed({ expiredAt, deletionAttempts: 3 });
expect(await fileMethods.clearFileEmbeddings(snapshot)).toBe(true);
expect(await fileMethods.clearFileEmbeddings(snapshot)).toBe(true);
const stored = await File.collection.findOne({ file_id: snapshot.file_id });
expect(stored?.embedded).toBe(false);
expect(stored?.metadata).toEqual({
codeEnvRef: { file_id: 'still-needed' },
destinationChosen: true,
searchDestination: true,
});
expect(stored?.updatedAt).toEqual(updatedAt);
expect(stored?.expiredAt).toEqual(expiredAt);
expect(stored?.deletionAttempts).toBe(3);
});
it.each([true, false, undefined])(
'retains search intent independently of the chooser marker %s',
async (destinationChosen) => {
await seed({
metadata: {
embeddedEntities: snapshot.embeddedEntities,
...(destinationChosen !== undefined ? { destinationChosen } : {}),
},
});
expect(await fileMethods.clearFileEmbeddings(snapshot)).toBe(true);
const files = await fileMethods.getFiles({ file_id: snapshot.file_id });
expect(files?.[0]?.embedded).toBe(false);
expect(files?.[0]?.metadata?.searchDestination).toBe(true);
expect(files?.[0]?.metadata?.embeddedEntities).toBeUndefined();
expect(files?.[0]?.metadata?.destinationChosen).toBe(destinationChosen);
},
);
it('persists the optional intent through the file schema and ordinary reads', async () => {
await File.create({
file_id: snapshot.file_id,
user,
filename: 'notes.pdf',
filepath: '/uploads/notes.pdf',
type: 'application/pdf',
bytes: 1024,
embedded: false,
metadata: { searchDestination: true },
});
const files = await fileMethods.getFiles({ file_id: snapshot.file_id });
expect(files?.[0]?.metadata?.searchDestination).toBe(true);
expect(files?.[0]?.metadata?.destinationChosen).toBeUndefined();
});
it('does not change a concurrent embedding or a reused file record', async () => {
await seed({ updatedAt: new Date(updatedAt.getTime() + 1) });
expect(await fileMethods.clearFileEmbeddings(snapshot)).toBe(false);
const stored = await File.collection.findOne({ file_id: snapshot.file_id });
expect(stored?.embedded).toBe(true);
expect(stored?.metadata?.embeddedEntities).toEqual(snapshot.embeddedEntities);
});
it('does not discard a newly recorded namespace even when its timestamp matches', async () => {
await seed({ metadata: { embeddedEntities: ['agent-a', 'agent-b', 'agent-c'] } });
expect(await fileMethods.clearFileEmbeddings(snapshot)).toBe(false);
const stored = await File.collection.findOne({ file_id: snapshot.file_id });
expect(stored?.metadata?.embeddedEntities).toHaveLength(3);
});
it('matches the owner and tenant rather than a bare file id', async () => {
const first = await seed();
await seed({ user: new mongoose.Types.ObjectId() });
await seed({ tenantId: 'tenant-b' });
await seed({ tenantId: undefined });
expect(await fileMethods.clearFileEmbeddings(snapshot)).toBe(true);
const records = await File.collection.find({ file_id: snapshot.file_id }).toArray();
const clearedIds = records
.filter((record) => record.embedded === false)
.map((record) => record._id);
expect(clearedIds).toEqual([first.insertedId]);
});
it.each([null, undefined])(
'clears only the untenanted row during system reconciliation: %p',
async (tenantId) => {
const foreign = await seed();
const local = await seed({ tenantId });
const before = await File.collection.findOne({ _id: foreign.insertedId });
expect(
await runAsSystem(() => fileMethods.clearFileEmbeddings({ ...snapshot, tenantId })),
).toBe(true);
expect(await File.collection.findOne({ _id: foreign.insertedId })).toEqual(before);
const stored = await File.collection.findOne({ _id: local.insertedId });
expect(stored?.embedded).toBe(false);
expect(stored?.metadata?.embeddedEntities).toBeUndefined();
expect(stored?.metadata?.searchDestination).toBe(true);
expect(stored?.updatedAt).toEqual(updatedAt);
},
);
it.each([null, undefined, 'tenant-b'])(
'does not clear a tenant row for a mismatched system scope: %p',
async (tenantId) => {
const seeded = await seed();
const before = await File.collection.findOne({ _id: seeded.insertedId });
expect(
await runAsSystem(() => fileMethods.clearFileEmbeddings({ ...snapshot, tenantId })),
).toBe(false);
expect(await File.collection.findOne({ _id: seeded.insertedId })).toEqual(before);
},
);
it.each([null, undefined, 'tenant-b'])(
'does not let embedding tenant middleware replace the caller scope: %p',
async (tenantId) => {
const seeded = await seed();
const before = await File.collection.findOne({ _id: seeded.insertedId });
expect(
await tenantStorage.run({ tenantId: snapshot.tenantId }, () =>
fileMethods.clearFileEmbeddings({ ...snapshot, tenantId }),
),
).toBe(false);
expect(await File.collection.findOne({ _id: seeded.insertedId })).toEqual(before);
},
);
it('clears fully tracked unscoped vector flags without an entity list', async () => {
await seed({ metadata: { destinationChosen: true } });
const legacy = { ...snapshot, embeddedEntities: undefined };
expect(await fileMethods.clearFileEmbeddings(legacy)).toBe(true);
});
it('retains search intent on fully tracked records without metadata', async () => {
await File.collection.insertOne({
file_id: snapshot.file_id,
user,
tenantId: snapshot.tenantId,
updatedAt,
embedded: true,
embeddingOwnersComplete: true,
embeddingOwnersTrackedAt: new Date('2026-10-20'),
});
expect(
await fileMethods.clearFileEmbeddings({ ...snapshot, embeddedEntities: undefined }),
).toBe(true);
const stored = await File.collection.findOne({ file_id: snapshot.file_id });
expect(stored?.embedded).toBe(false);
expect(stored?.metadata).toEqual({ searchDestination: true });
});
it('propagates persistence failures instead of claiming reconciliation', async () => {
await seed();
const update = jest.spyOn(mongoose.models.File, 'updateOne').mockImplementationOnce(() => {
throw new Error('mongo unavailable');
});
try {
await expect(fileMethods.clearFileEmbeddings(snapshot)).rejects.toThrow(
'mongo unavailable',
);
} finally {
update.mockRestore();
}
expect((await File.collection.findOne({ file_id: snapshot.file_id }))?.embedded).toBe(true);
});
});
describe('final file storage snapshot', () => {
const user = new mongoose.Types.ObjectId();
const updatedAt = new Date('2026-10-20');
const snapshot = {
file_id: 'cleanup-race',
user,
tenantId: 'tenant-a',
updatedAt,
source: 'local',
};
const options = { files: [snapshot], userId: user.toString() };
const check = { ...snapshot, userId: user.toString() };
const seed = (overrides = {}) => File.collection.insertOne({ ...snapshot, ...overrides });
it('confirms a cleared snapshot and removes only its matching owned row', async () => {
await seed({ embedded: false, metadata: { codeEnvRefs: {}, codeDestination: true } });
await seed({ tenantId: 'tenant-b' });
expect(await fileMethods.isFileStorageClean(check)).toBe(true);
expect(await fileMethods.deleteFiles([snapshot.file_id], undefined, options)).toEqual({
deletedCount: 1,
deletedFileIds: [snapshot.file_id],
failedFileIds: [],
});
expect(await File.collection.countDocuments({ file_id: snapshot.file_id })).toBe(1);
expect(await fileMethods.isFileStorageClean(check)).toBe(false);
expect(await fileMethods.deleteFiles([snapshot.file_id], undefined, options)).toEqual({
deletedCount: 0,
deletedFileIds: [snapshot.file_id],
failedFileIds: [],
});
});
it.each([
{ metadata: { codeEnvRefs: { default: { file_id: 'replacement' } } } },
{ metadata: { codeEnvRef: { file_id: 'replacement' } } },
{ embedded: true, metadata: { embeddedEntities: ['new-namespace'] } },
{ updatedAt: new Date(updatedAt.getTime() + 1) },
])(
'retains a reprovisioned row and reports incomplete metadata deletion: %p',
async (change) => {
await seed();
expect(await fileMethods.isFileStorageClean(check)).toBe(true);
await File.collection.updateOne({ file_id: snapshot.file_id }, { $set: change });
const before = await File.collection.findOne({ file_id: snapshot.file_id });
expect(await fileMethods.isFileStorageClean(check)).toBe(false);
await expect(
fileMethods.deleteFiles([snapshot.file_id], undefined, options),
).resolves.toEqual({
deletedCount: 0,
deletedFileIds: [],
failedFileIds: [snapshot.file_id],
});
expect(await File.collection.findOne({ file_id: snapshot.file_id })).toEqual(before);
},
);
it('does not delete a copy attached between the metadata read and conditional delete', async () => {
await seed();
const deleteMany = File.collection.deleteMany.bind(File.collection);
jest
.spyOn(File.collection, 'deleteMany')
.mockImplementationOnce(async (filter, deleteOptions) => {
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{ $set: { 'metadata.codeEnvRefs.default': { file_id: 'late-copy' } } },
);
return deleteMany(filter, deleteOptions);
});
await expect(
fileMethods.deleteFiles([snapshot.file_id], undefined, options),
).resolves.toEqual({
deletedCount: 0,
deletedFileIds: [],
failedFileIds: [snapshot.file_id],
});
const stored = await File.collection.findOne({ file_id: snapshot.file_id });
expect(stored?.metadata?.codeEnvRefs?.default?.file_id).toBe('late-copy');
});
it('returns both receipt arrays without touching the database for an empty guarded batch', async () => {
const find = jest.spyOn(mongoose.models.File, 'find');
const remove = jest.spyOn(mongoose.models.File, 'deleteMany');
expect(await fileMethods.deleteFiles([], undefined, options)).toEqual({
deletedCount: 0,
deletedFileIds: [],
failedFileIds: [],
});
expect(find).not.toHaveBeenCalled();
expect(remove).not.toHaveBeenCalled();
});
it('detaches only confirmed successes after a mixed conditional delete in system scope', async () => {
const successful = { ...snapshot, file_id: 'cleanup-success' };
await seed();
await seed(successful);
const ChatProject = mongoose.models.ChatProject as mongoose.Model<IChatProject>;
const ids = [snapshot.file_id, successful.file_id];
const project = await ChatProject.collection.insertOne({
user: user.toString(),
tenantId: snapshot.tenantId,
file_ids: ids,
contextRevision: 4,
});
const otherTenant = await ChatProject.collection.insertOne({
user: user.toString(),
tenantId: 'tenant-b',
file_ids: ids,
contextRevision: 4,
});
const deleteMany = File.collection.deleteMany.bind(File.collection);
jest
.spyOn(File.collection, 'deleteMany')
.mockImplementationOnce(async (filter, deleteOptions) => {
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{ $set: { 'metadata.codeEnvRefs.default': { file_id: 'late-copy' } } },
);
return deleteMany(filter, deleteOptions);
});
expect(
await runAsSystem(() =>
fileMethods.deleteFiles(ids, undefined, { ...options, files: [snapshot, successful] }),
),
).toEqual({
deletedCount: 1,
deletedFileIds: [successful.file_id],
failedFileIds: [snapshot.file_id],
});
expect(await File.collection.findOne({ file_id: successful.file_id })).toBeNull();
expect(
(await File.collection.findOne({ file_id: snapshot.file_id }))?.metadata?.codeEnvRefs,
).toEqual({ default: { file_id: 'late-copy' } });
expect(await ChatProject.collection.findOne({ _id: project.insertedId })).toMatchObject({
file_ids: [snapshot.file_id],
contextRevision: 5,
});
expect(await ChatProject.collection.findOne({ _id: otherTenant.insertedId })).toMatchObject({
file_ids: ids,
contextRevision: 4,
});
});
it.each([undefined, null, 'tenant-a'])(
'detaches already-absent input only from its snapshot owner and tenant: %s',
async (tenantId) => {
const ChatProject = mongoose.models.ChatProject as mongoose.Model<IChatProject>;
const project = await ChatProject.collection.insertOne({
user: user.toString(),
...(tenantId === undefined ? {} : { tenantId }),
file_ids: [snapshot.file_id],
contextRevision: 1,
});
const otherTenant = await ChatProject.collection.insertOne({
user: user.toString(),
tenantId: 'tenant-b',
file_ids: [snapshot.file_id],
contextRevision: 1,
});
const otherOwner = await ChatProject.collection.insertOne({
user: new mongoose.Types.ObjectId().toString(),
tenantId,
file_ids: [snapshot.file_id],
contextRevision: 1,
});
expect(
await runAsSystem(() =>
fileMethods.deleteFiles([snapshot.file_id], undefined, {
userId: new mongoose.Types.ObjectId().toString(),
files: [{ ...snapshot, tenantId }],
}),
),
).toEqual({ deletedCount: 0, deletedFileIds: [snapshot.file_id], failedFileIds: [] });
expect(await ChatProject.collection.findOne({ _id: project.insertedId })).toMatchObject({
file_ids: [],
contextRevision: 2,
});
for (const inserted of [otherTenant, otherOwner]) {
expect(await ChatProject.collection.findOne({ _id: inserted.insertedId })).toMatchObject({
file_ids: [snapshot.file_id],
contextRevision: 1,
});
}
},
);
it('does not delete a replacement row that was absent from the candidate read', async () => {
await seed();
const deleteMany = File.collection.deleteMany.bind(File.collection);
jest
.spyOn(File.collection, 'deleteMany')
.mockImplementationOnce(async (filter, deleteOptions) => {
await deleteMany({ file_id: snapshot.file_id });
await seed();
return deleteMany(filter, deleteOptions);
});
expect(await fileMethods.deleteFiles([snapshot.file_id], undefined, options)).toEqual({
deletedCount: 0,
deletedFileIds: [],
failedFileIds: [snapshot.file_id],
});
expect(await File.collection.countDocuments({ file_id: snapshot.file_id })).toBe(1);
});
it('propagates operational database failures rather than issuing a receipt', async () => {
jest
.spyOn(File.collection, 'deleteMany')
.mockRejectedValueOnce(new Error('mongo unavailable'));
await expect(fileMethods.deleteFiles([snapshot.file_id], undefined, options)).rejects.toThrow(
'mongo unavailable',
);
});
it('returns the successful receipt when best-effort project cleanup fails', async () => {
await seed();
jest.spyOn(mongoose.models.ChatProject, 'updateMany').mockImplementationOnce(() => {
throw new Error('cleanup failed');
});
expect(await fileMethods.deleteFiles([snapshot.file_id], undefined, options)).toEqual({
deletedCount: 1,
deletedFileIds: [snapshot.file_id],
failedFileIds: [],
});
expect(await File.collection.findOne({ file_id: snapshot.file_id })).toBeNull();
});
it('rejects an unknown id before attempting deletion', async () => {
const remove = jest.spyOn(mongoose.models.File, 'deleteMany');
await expect(fileMethods.deleteFiles(['unknown'], undefined, options)).rejects.toThrow(
'Missing file deletion snapshot',
);
expect(remove).not.toHaveBeenCalled();
});
it.each([FileSources.openai, FileSources.azure])(
'permits an authorized missing %s record but never a changed local snapshot',
async (source) => {
const providerOnly = { ...check, source, allowMissingFileRecord: true };
expect(await fileMethods.isFileStorageClean({ ...check, source })).toBe(false);
expect(await fileMethods.isFileStorageClean(providerOnly)).toBe(true);
await seed({ source, metadata: { codeEnvRefs: { default: { file_id: 'new-copy' } } } });
expect(await fileMethods.isFileStorageClean(providerOnly)).toBe(false);
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{ $unset: { metadata: '' }, $set: { updatedAt: new Date(updatedAt.getTime() + 1) } },
);
expect(await fileMethods.isFileStorageClean(providerOnly)).toBe(false);
},
);
it('does not allow missing local records through the provider-only exception', async () => {
expect(await fileMethods.isFileStorageClean({ ...check, allowMissingFileRecord: true })).toBe(
false,
);
});
it('accepts primary vector cleanup only for its original namespace snapshot', async () => {
const vector = {
...snapshot,
source: 'vectordb',
embedded: true,
metadata: { embeddedEntities: ['original'] },
};
await seed(vector);
const primary = {
...check,
source: vector.source,
embedded: true,
embeddedEntities: ['original'],
};
expect(await fileMethods.isFileStorageClean(primary)).toBe(true);
await File.collection.updateOne(
{ file_id: snapshot.file_id },
{ $set: { 'metadata.embeddedEntities': ['replacement'] } },
);
expect(await fileMethods.isFileStorageClean(primary)).toBe(false);
await expect(
fileMethods.deleteFiles([snapshot.file_id], undefined, { ...options, files: [vector] }),
).resolves.toEqual({
deletedCount: 0,
deletedFileIds: [],
failedFileIds: [snapshot.file_id],
});
});
});
describe('adoptLegacySearchEmbeddings', () => {
const Agent = () => mongoose.models.Agent as mongoose.Model<unknown>;
const author = new mongoose.Types.ObjectId();
const createAgent = (id: string, searchFileIds: string[]) =>
Agent().create({
id,
name: id,
provider: 'openai',
model: 'gpt-4o',
author,
tool_resources: { [EToolResources.file_search]: { file_ids: searchFileIds } },
});
const createLegacyFile = (
fileId: string,
metadata?: Record<string, unknown>,
owner: mongoose.Types.ObjectId = author,
) =>
File.create({
file_id: fileId,
user: owner,
filename: `${fileId}.pdf`,
filepath: `/uploads/${fileId}.pdf`,
type: 'application/pdf',
bytes: 1024,
embedded: true,
context: FileContext.agents,
...(metadata ? { metadata } : {}),
});
afterEach(async () => {
await Agent().deleteMany({});
});
it('records the namespace of a verified legacy file', async () => {
const fileId = uuidv4();
await createAgent('agent_owner', [fileId]);
await createLegacyFile(fileId);
const adopted = await fileMethods.adoptLegacySearchEmbeddings({
files: [{ file_id: fileId, user: author.toString() }],
agentId: 'agent_owner',
});
expect(adopted).toEqual([fileId]);
const stored = (await File.findOne({ file_id: fileId }).lean()) as IMongoFile | null;
expect(stored?.metadata?.embeddedEntities).toEqual(['agent_owner']);
});
it('does not touch a tenant record that shares an untenanted file_id', async () => {
const fileId = uuidv4();
await File.collection.insertOne({
file_id: fileId,
user: author,
tenantId: 'tenant-b',
filename: `${fileId}.pdf`,
filepath: `/uploads/${fileId}.pdf`,
type: 'application/pdf',
bytes: 1024,
embedded: true,
context: FileContext.agents,
object: 'file',
usage: 0,
});
/* Inserted second, so an unscoped match would land on the tenant record first. */
await createLegacyFile(fileId);
const adopted = await fileMethods.adoptLegacySearchEmbeddings({
files: [{ file_id: fileId, user: author.toString() }],
agentId: 'agent_owner',
});
expect(adopted).toEqual([fileId]);
const tenantRecord = await File.collection.findOne({ file_id: fileId, tenantId: 'tenant-b' });
expect(tenantRecord?.metadata?.embeddedEntities).toBeUndefined();
const untenanted = (await File.findOne({
file_id: fileId,
tenantId: { $exists: false },
}).lean()) as IMongoFile | null;
expect(untenanted?.metadata?.embeddedEntities).toEqual(['agent_owner']);
});
it("does not touch another owner's record that shares the file_id", async () => {
const fileId = uuidv4();
const otherOwner = new mongoose.Types.ObjectId();
await createAgent('agent_owner', [fileId]);
await createLegacyFile(fileId);
await createLegacyFile(fileId, undefined, otherOwner);
const adopted = await fileMethods.adoptLegacySearchEmbeddings({
files: [{ file_id: fileId, user: author.toString() }],
agentId: 'agent_owner',
});
expect(adopted).toEqual([fileId]);
const foreign = (await File.findOne({
file_id: fileId,
user: otherOwner,
}).lean()) as IMongoFile | null;
expect(foreign?.metadata?.embeddedEntities).toBeUndefined();
});
it('reports a file a concurrent turn already adopted for the same agent', async () => {
const fileId = uuidv4();
await createAgent('agent_owner', [fileId]);
await createLegacyFile(fileId, { embeddedEntities: ['agent_owner'] });
const adopted = await fileMethods.adoptLegacySearchEmbeddings({
files: [{ file_id: fileId, user: author.toString() }],
agentId: 'agent_owner',
});
expect(adopted).toEqual([fileId]);
});
it('reports a committed adoption when a sibling write fails', async () => {
const adoptedId = uuidv4();
const failingId = uuidv4();
await createAgent('agent_owner', [adoptedId, failingId]);
await createLegacyFile(adoptedId);
await createLegacyFile(failingId);
const original = File.findOneAndUpdate.bind(File);
const spy = jest
.spyOn(File, 'findOneAndUpdate')
.mockImplementation(((filter: { file_id?: string }, ...rest: unknown[]) =>
filter.file_id === failingId
? { lean: () => Promise.reject(new Error('write failed')) }
: (original as (...args: unknown[]) => unknown)(filter, ...rest)) as never);
try {
const adopted = await fileMethods.adoptLegacySearchEmbeddings({
files: [
{ file_id: adoptedId, user: author.toString() },
{ file_id: failingId, user: author.toString() },
],
agentId: 'agent_owner',
});
expect(adopted).toEqual([adoptedId]);
} finally {
spy.mockRestore();
}
});
it('keeps the namespaces already recorded', async () => {
const fileId = uuidv4();
await createLegacyFile(fileId, { embeddedEntities: ['agent_source'] });
const adopted = await fileMethods.adoptLegacySearchEmbeddings({
files: [{ file_id: fileId, user: author.toString() }],
agentId: 'agent_owner',
});
expect(adopted).toEqual([fileId]);
const stored = (await File.findOne({ file_id: fileId }).lean()) as IMongoFile | null;
expect(stored?.metadata?.embeddedEntities).toEqual(['agent_source', 'agent_owner']);
});
});
describe('createFile', () => {
it('should create a new file with TTL', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
const file = await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'test.txt',
filepath: '/uploads/test.txt',
type: 'text/plain',
bytes: 100,
});
expect(file).not.toBeNull();
expect(file?.file_id).toBe(fileId);
expect(file?.filename).toBe('test.txt');
expect(file?.expiresAt).toBeDefined();
});
it('should create a file without TTL when disableTTL is true', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
const file = await fileMethods.createFile(
{
file_id: fileId,
user: userId,
filename: 'permanent.txt',
filepath: '/uploads/permanent.txt',
type: 'text/plain',
bytes: 200,
},
true,
);
expect(file).not.toBeNull();
expect(file?.file_id).toBe(fileId);
expect(file?.expiresAt).toBeUndefined();
});
it('persists independent Code API pointers for both execution profiles', async () => {
const defaultRef = {
kind: 'user' as const,
id: 'user-1',
storage_session_id: 'default-session',
file_id: 'default-file',
executionProfile: 'default' as const,
};
const statefulRef = {
...defaultRef,
storage_session_id: 'stateful-session',
file_id: 'stateful-file',
executionProfile: 'stateful' as const,
};
const file = await fileMethods.createFile({
file_id: uuidv4(),
user: new mongoose.Types.ObjectId(),
filename: 'dual-profile.txt',
filepath: '/uploads/dual-profile.txt',
type: 'text/plain',
bytes: 10,
metadata: {
codeEnvRef: defaultRef,
codeEnvRefs: { default: defaultRef, stateful: statefulRef },
},
});
expect(file?.metadata?.codeEnvRefs?.default?.file_id).toBe('default-file');
expect(file?.metadata?.codeEnvRefs?.stateful?.file_id).toBe('stateful-file');
});
it('casts string owner ids in atomic pipeline upserts', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
const file = await fileMethods.createFile({
file_id: fileId,
user: userId.toString() as unknown as mongoose.Types.ObjectId,
filename: 'owned.txt',
filepath: '/uploads/owned.txt',
type: 'text/plain',
bytes: 100,
});
expect(file?.user).toEqual(userId);
await expect(File.countDocuments({ file_id: fileId, user: userId })).resolves.toBe(1);
});
it('rejects cross-tenant mutation fields before atomic pipeline upserts', async () => {
const userId = new mongoose.Types.ObjectId();
await expect(
tenantStorage.run({ tenantId: 'tenant-a' }, async () =>
fileMethods.createFile({
file_id: uuidv4(),
user: userId,
tenantId: 'tenant-b',
filename: 'cross-tenant.txt',
filepath: '/uploads/cross-tenant.txt',
type: 'text/plain',
bytes: 100,
}),
),
).rejects.toThrow('Cross-tenant tenantId mutation is not allowed');
});
it('derives matching tenant ids from the tenant-scoped upsert filter', async () => {
const fileId = uuidv4();
const file = await tenantStorage.run({ tenantId: 'tenant-a' }, async () =>
fileMethods.createFile({
file_id: fileId,
user: new mongoose.Types.ObjectId(),
tenantId: 'tenant-a',
filename: 'tenant-owned.txt',
filepath: '/uploads/tenant-owned.txt',
type: 'text/plain',
bytes: 100,
}),
);
expect(file?.tenantId).toBe('tenant-a');
await expect(
runAsSystem(() => File.countDocuments({ file_id: fileId, tenantId: 'tenant-a' })),
).resolves.toBe(1);
});
});
describe('getAvailableProjectFiles', () => {
it('retains the embedded picker index and adds a distinct search-intent partial index', () => {
const keys = { user: 1, tenantId: 1, context: 1, _id: -1 };
expect(File.schema.indexes()).toEqual(
expect.arrayContaining([
[
keys,
expect.objectContaining({
name: 'project_file_picker',
partialFilterExpression: { embedded: true },
}),
],
[
keys,
expect.objectContaining({
name: 'project_file_picker_search_destination',
partialFilterExpression: { 'metadata.searchDestination': true },
}),
],
]),
);
});
it('treats an empty tenant id as no tenant, matching project file reads', async () => {
const userId = new mongoose.Types.ObjectId().toString();
await File.create({
user: userId,
file_id: 'untenanted',
filename: 'Untenanted.txt',
filepath: '/uploads/untenanted',
object: 'file',
type: 'text/plain',
bytes: 1,
embedded: true,
context: FileContext.message_attachment,
});
const result = await fileMethods.getAvailableProjectFiles({
userId,
tenantId: '',
excludedFileIds: [],
limit: 10,
});
expect(result.files.map((file) => file.file_id)).toEqual(['untenanted']);
});
it('paginates only eligible owner files with stable cursors and literal search', async () => {
const userId = new mongoose.Types.ObjectId().toString();
const now = new Date('2026-01-01T00:00:00.000Z');
const base = {
user: userId,
tenantId: 'tenant-a',
filename: 'Report excluded.txt',
filepath: '/uploads/report',
object: 'file',
type: 'text/plain',
bytes: 1,
usage: 0,
embedded: true,
context: FileContext.message_attachment,
text: 'secret',
storageKey: 'internal-storage-key',
};
await File.create([
{ ...base, file_id: 'report-1', filename: 'Report [literal].txt' },
{ ...base, file_id: 'report-2', filename: 'Report two.txt' },
{
...base,
file_id: 'expired',
expiredAt: new Date('2025-12-31T23:59:59.000Z'),
},
{ ...base, file_id: 'foreign-tenant', tenantId: 'tenant-b' },
{ ...base, file_id: 'foreign-owner', user: new mongoose.Types.ObjectId().toString() },
{ ...base, file_id: 'agent-knowledge', context: FileContext.agents },
{ ...base, file_id: 'not-indexed', embedded: false },
{ ...base, file_id: 'attached' },
]);
const first = await fileMethods.getAvailableProjectFiles({
userId,
tenantId: 'tenant-a',
excludedFileIds: ['attached'],
limit: 1,
search: 'report',
now,
});
await File.updateOne(
{ file_id: first.files[0].file_id },
{ $set: { filename: `Report ${'renamed'.repeat(100)}` } },
);
const second = await fileMethods.getAvailableProjectFiles({
userId,
tenantId: 'tenant-a',
excludedFileIds: ['attached'],
limit: 1,
search: 'report',
cursor: first.nextCursor,
now,
});
expect(first.files).toHaveLength(1);
expect(second.files).toHaveLength(1);
expect(first.files[0].file_id).toBe('report-2');
expect(second.files[0].file_id).toBe('report-1');
expect(first.nextCursor).toEqual(expect.any(String));
expect(second.nextCursor).toBeNull();
expect(first.files[0]).not.toHaveProperty('text');
expect(second.files[0]).not.toHaveProperty('storageKey');
/** The picker's rows reach `@librechat/api` and the client, so the identifiers must
* already be plain strings rather than driver objects. */
expect(first.files[0]).toMatchObject({ _id: expect.any(String), user: userId });
const literalMatch = await fileMethods.getAvailableProjectFiles({
userId,
tenantId: 'tenant-a',
search: '[literal]',
now,
});
expect(literalMatch.files.map((file) => file.file_id)).toEqual(['report-1']);
});
it.each([0, 51, 1.5])('rejects an unbounded page size: %p', async (limit) => {
await expect(
fileMethods.getAvailableProjectFiles({
userId: new mongoose.Types.ObjectId().toString(),
tenantId: 'tenant-a',
limit,
}),
).rejects.toThrow('Invalid project file limit');
});
});
describe('getProjectFiles', () => {
it.each([
{ searchDestination: true, routingMimeType: 'image/heic' },
{ routingMimeType: 'image/heic' },
{ searchDestination: false },
undefined,
])('preserves only routing metadata across project reads: %p', async (metadata) => {
const userId = new mongoose.Types.ObjectId().toString();
await File.create({
file_id: 'converted-project-file',
user: userId,
tenantId: 'tenant-a',
embedded: true,
context: FileContext.message_attachment,
filename: 'converted.jpeg',
filepath: '/uploads/converted.jpeg',
type: 'image/jpeg',
bytes: 1,
text: 'private extracted content',
metadata: { ...metadata, destinationChosen: true, embeddedEntities: ['private-agent'] },
});
const options = { fileIds: ['converted-project-file'], userId, tenantId: 'tenant-a' };
const [projectFile] = await fileMethods.getProjectFiles(options);
const [withContent] = await fileMethods.getProjectFiles({ ...options, includeContent: true });
const available = await fileMethods.getAvailableProjectFiles(options);
for (const record of [projectFile, withContent, available.files[0]]) {
expect(record.type).toBe('image/jpeg');
expect(record.metadata).toEqual(metadata);
if (metadata === undefined) {
expect(record).not.toHaveProperty('metadata');
}
}
expect(projectFile).not.toHaveProperty('text');
expect(available.files[0]).not.toHaveProperty('text');
expect(withContent.text).toBe('private extracted content');
});
it('hydrates and lists retained search intent without widening owner, tenant or context scope', async () => {
const userId = new mongoose.Types.ObjectId().toString();
const base = {
user: userId,
tenantId: 'tenant-a',
embedded: false,
metadata: { searchDestination: true },
context: FileContext.message_attachment,
filename: 'repair.txt',
filepath: '/uploads/repair.txt',
type: 'text/plain',
bytes: 1,
source: 's3',
storageKey: 'owner/repair',
storageRegion: 'region',
};
await File.create([
{ ...base, file_id: 'repair' },
{ ...base, file_id: 'foreign', user: new mongoose.Types.ObjectId().toString() },
{ ...base, file_id: 'other-tenant', tenantId: 'tenant-b' },
{ ...base, file_id: 'agent', context: FileContext.agents },
{ ...base, file_id: 'declined', metadata: { destinationChosen: true } },
]);
const files = await fileMethods.getProjectFiles({
fileIds: ['repair', 'foreign', 'other-tenant', 'agent', 'declined'],
userId,
tenantId: 'tenant-a',
});
expect(files).toEqual([
expect.objectContaining({
file_id: 'repair',
embedded: false,
metadata: { searchDestination: true },
source: 's3',
storageKey: 'owner/repair',
storageRegion: 'region',
}),
]);
const available = await fileMethods.getAvailableProjectFiles({
userId,
tenantId: 'tenant-a',
});
expect(available.files.map((file) => file.file_id)).toEqual(['repair']);
});
it('enforces owner scope and only includes content when requested', async () => {
const userId = new mongoose.Types.ObjectId().toString();
await File.create([
{
file_id: 'project-owned',
user: userId,
tenantId: 'tenant-a',
embedded: true,
context: FileContext.message_attachment,
filename: 'owned.txt',
filepath: '/uploads/owned.txt',
type: 'text/plain',
bytes: 1,
text: 'private project content',
},
{
file_id: 'project-foreign',
user: new mongoose.Types.ObjectId().toString(),
tenantId: 'tenant-a',
embedded: true,
context: FileContext.message_attachment,
filename: 'foreign.txt',
filepath: '/uploads/foreign.txt',
type: 'text/plain',
bytes: 1,
text: 'must not leak',
},
]);
const metadata = await fileMethods.getProjectFiles({
fileIds: ['project-owned', 'project-foreign'],
userId,
tenantId: 'tenant-a',
});
expect(metadata.map((file) => file.file_id)).toEqual(['project-owned']);
expect(metadata[0]).toEqual(
expect.objectContaining({
user: userId,
_id: expect.any(String),
}),
);
expect(metadata[0]?.updatedAt).toBeInstanceOf(Date);
expect(metadata[0]).not.toHaveProperty('text');
const withContent = await fileMethods.getProjectFiles({
fileIds: ['project-owned'],
userId,
tenantId: 'tenant-a',
includeContent: true,
});
expect(withContent[0]?.text).toBe('private project content');
});
});
describe('claimCodeFile', () => {
const fencedStates = [
{ deletionPending: true },
{ deleting: 'deletion-owner' },
{ provisioning: ['provision-owner'] },
];
it.each(fencedStates)('rejects a fenced filename claim: %j', async (storageOperations) => {
await File.init();
const input = {
filename: 'fenced.csv',
conversationId: 'fenced-conversation',
file_id: 'fenced-file',
user: new mongoose.Types.ObjectId().toString(),
tenantId: 'tenant-a',
sourceDispatchedAt: 100,
};
await fileMethods.claimCodeFile(input);
await File.updateOne({ file_id: input.file_id }, { $set: { storageOperations } });
const before = await File.findOne({ file_id: input.file_id }).lean();
await expect(
fileMethods.claimCodeFile({
...input,
file_id: 'replacement-file',
sourceDispatchedAt: 200,
}),
).rejects.toMatchObject({
name: 'FileStorageConflictError',
code: 'FILE_STORAGE_CONFLICT',
});
expect(await File.findOne({ file_id: input.file_id }).lean()).toEqual(before);
expect(await File.countDocuments()).toBe(1);
const independent = await fileMethods.claimCodeFile({
...input,
filename: 'independent.csv',
file_id: 'independent-file',
});
expect(independent.file_id).toBe('independent-file');
});
it.each(fencedStates)(
'rejects commits after a storage fence is acquired: %j',
async (storageOperations) => {
await File.init();
const input = {
filename: 'late-fence.csv',
conversationId: 'late-fence-conversation',
file_id: 'late-fence-file',
user: new mongoose.Types.ObjectId().toString(),
tenantId: 'tenant-a',
sourceDispatchedAt: 100,
};
await fileMethods.claimCodeFile(input);
await File.updateOne({ file_id: input.file_id }, { $set: { storageOperations } });
const before = await File.findOne({ file_id: input.file_id }).lean();
const output = {
...input,
context: FileContext.execute_code,
filepath: '/uploads/new.csv',
type: 'text/csv',
bytes: 20,
source: FileSources.local,
metadata: { sourceDispatchedAt: 200 },
};
await expect(fileMethods.commitCodeFile(output)).rejects.toBeInstanceOf(
FileStorageConflictError,
);
expect(await fileMethods.commitCodeFile(output, 200)).toBe(false);
await expect(
fileMethods.createFile(
{ ...output, user: new mongoose.Types.ObjectId(input.user) },
true,
),
).rejects.toBeInstanceOf(FileStorageConflictError);
expect(await File.findOne({ file_id: input.file_id }).lean()).toEqual(before);
expect(await File.countDocuments()).toBe(1);
},
);
it('reuses active rows with empty provisioning without changing their metadata', async () => {
const input = {
filename: 'active.csv',
conversationId: 'active-conversation',
file_id: 'active-file',
user: new mongoose.Types.ObjectId().toString(),
sourceDispatchedAt: 100,
};
await fileMethods.claimCodeFile(input);
await File.updateOne(
{ file_id: input.file_id },
{ $set: { storageOperations: { provisioning: [], deletionPending: false } } },
);
const before = await File.findOne({ file_id: input.file_id }).lean();
const claimed = await fileMethods.claimCodeFile({
...input,
file_id: 'unused-file',
sourceDispatchedAt: 200,
});
expect(claimed.file_id).toBe(input.file_id);
expect(await File.findOne({ file_id: input.file_id }).lean()).toEqual(before);
});
it('claims code output files independently per tenant', async () => {
const userId = new mongoose.Types.ObjectId().toString();
const tenantA = await fileMethods.claimCodeFile({
filename: 'report.csv',
conversationId: 'conversation-1',
file_id: 'file-tenant-a',
user: userId,
tenantId: 'tenant-a',
});
const tenantB = await fileMethods.claimCodeFile({
filename: 'report.csv',
conversationId: 'conversation-1',
file_id: 'file-tenant-b',
user: userId,
tenantId: 'tenant-b',
});
const tenantAAgain = await fileMethods.claimCodeFile({
filename: 'report.csv',
conversationId: 'conversation-1',
file_id: 'file-tenant-a-new',
user: userId,
tenantId: 'tenant-a',
});
expect(tenantA.file_id).toBe('file-tenant-a');
expect(tenantA.tenantId).toBe('tenant-a');
expect(tenantB.file_id).toBe('file-tenant-b');
expect(tenantB.tenantId).toBe('tenant-b');
expect(tenantAAgain.file_id).toBe('file-tenant-a');
});
it('does not bump updatedAt on re-claim (id reservation, not a content write)', async () => {
const userId = new mongoose.Types.ObjectId().toString();
const File = mongoose.models.File;
await fileMethods.claimCodeFile({
filename: 'stable.csv',
conversationId: 'conversation-ts',
file_id: 'stable-file',
user: userId,
});
const written = new Date('2024-01-01T00:00:00.000Z');
await File.updateOne(
{ file_id: 'stable-file' },
{ $set: { updatedAt: written } },
{ timestamps: false },
);
/** The background harvest's out-of-order guard compares `updatedAt`
* against the harvest start; a claim bumping it would make every
* existing filename look freshly written and misfire the guard. */
const reclaimed = await fileMethods.claimCodeFile({
filename: 'stable.csv',
conversationId: 'conversation-ts',
file_id: 'stable-file-second',
user: userId,
});
expect(reclaimed.file_id).toBe('stable-file');
expect(new Date(reclaimed.updatedAt as unknown as string).getTime()).toBe(written.getTime());
});
it('stamps sourceDispatchedAt on claim INSERT only (existing claims untouched)', async () => {
const userId = new mongoose.Types.ObjectId().toString();
const inserted = await fileMethods.claimCodeFile({
filename: 'stamped.csv',
conversationId: 'conversation-stamp',
file_id: 'stamped-file',
user: userId,
sourceDispatchedAt: 111,
});
expect(
(inserted.metadata as { sourceDispatchedAt?: number } | undefined)?.sourceDispatchedAt,
).toBe(111);
/** A later claimant's stamp must not overwrite the owner's. */
const reclaimed = await fileMethods.claimCodeFile({
filename: 'stamped.csv',
conversationId: 'conversation-stamp',
file_id: 'stamped-file-second',
user: userId,
sourceDispatchedAt: 222,
});
expect(reclaimed.file_id).toBe('stamped-file');
expect(
(reclaimed.metadata as { sourceDispatchedAt?: number } | undefined)?.sourceDispatchedAt,
).toBe(111);
});
it('keeps non-tenant code output claims in the legacy namespace', async () => {
const userId = new mongoose.Types.ObjectId().toString();
const legacy = await fileMethods.claimCodeFile({
filename: 'legacy.csv',
conversationId: 'conversation-1',
file_id: 'legacy-file',
user: userId,
});
const tenant = await fileMethods.claimCodeFile({
filename: 'legacy.csv',
conversationId: 'conversation-1',
file_id: 'tenant-file',
user: userId,
tenantId: 'tenant-a',
});
expect(legacy.file_id).toBe('legacy-file');
expect(legacy.tenantId).toBeNull();
expect(tenant.file_id).toBe('tenant-file');
expect(tenant.tenantId).toBe('tenant-a');
});
it('treats null tenantId as the legacy code output namespace', async () => {
const userId = new mongoose.Types.ObjectId().toString();
const legacy = await fileMethods.claimCodeFile({
filename: 'nullable-legacy.csv',
conversationId: 'conversation-1',
file_id: 'legacy-null-file',
user: userId,
tenantId: null,
});
const legacyAgain = await fileMethods.claimCodeFile({
filename: 'nullable-legacy.csv',
conversationId: 'conversation-1',
file_id: 'legacy-null-file-new',
user: userId,
});
expect(legacy.file_id).toBe('legacy-null-file');
expect(legacyAgain.file_id).toBe('legacy-null-file');
});
});
describe('findFileById', () => {
it('should find a file by file_id', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'find-me.txt',
filepath: '/uploads/find-me.txt',
type: 'text/plain',
bytes: 150,
});
const found = await fileMethods.findFileById(fileId);
expect(found).not.toBeNull();
expect(found?.file_id).toBe(fileId);
expect(found?.filename).toBe('find-me.txt');
});
it('should return null for non-existent file', async () => {
const found = await fileMethods.findFileById('non-existent');
expect(found).toBeNull();
});
});
describe('getFiles', () => {
it('should retrieve multiple files matching filter', async () => {
const userId = new mongoose.Types.ObjectId();
const fileIds = [uuidv4(), uuidv4(), uuidv4()];
for (const fileId of fileIds) {
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: `file-${fileId}.txt`,
filepath: `/uploads/${fileId}.txt`,
type: 'text/plain',
bytes: 100,
});
}
const files = await fileMethods.getFiles({ user: userId });
expect(files).toHaveLength(3);
expect(files!.map((f) => f.file_id)).toEqual(expect.arrayContaining(fileIds));
});
it('should exclude text field by default', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'with-text.txt',
filepath: '/uploads/with-text.txt',
type: 'text/plain',
bytes: 100,
text: 'Some content here',
});
const files = await fileMethods.getFiles({ file_id: fileId });
expect(files).toHaveLength(1);
expect(files![0].text).toBeUndefined();
});
});
describe('getExpiredFiles', () => {
it('returns only files whose expiredAt date has passed', async () => {
const userId = new mongoose.Types.ObjectId();
const now = new Date('2030-01-01T00:00:00.000Z');
const expiredFileId = uuidv4();
const futureFileId = uuidv4();
const permanentFileId = uuidv4();
const missingExpiryFileId = uuidv4();
await fileMethods.createFile(
{
file_id: expiredFileId,
user: userId,
filename: 'expired.txt',
filepath: '/uploads/expired.txt',
type: 'text/plain',
bytes: 100,
expiredAt: new Date('2029-12-31T23:59:59.000Z'),
},
true,
);
await fileMethods.createFile(
{
file_id: futureFileId,
user: userId,
filename: 'future.txt',
filepath: '/uploads/future.txt',
type: 'text/plain',
bytes: 100,
expiredAt: new Date('2030-01-01T00:00:01.000Z'),
},
true,
);
await fileMethods.createFile(
{
file_id: permanentFileId,
user: userId,
filename: 'permanent.txt',
filepath: '/uploads/permanent.txt',
type: 'text/plain',
bytes: 100,
expiredAt: null,
},
true,
);
await fileMethods.createFile(
{
file_id: missingExpiryFileId,
user: userId,
filename: 'missing-expiry.txt',
filepath: '/uploads/missing-expiry.txt',
type: 'text/plain',
bytes: 100,
},
true,
);
const files = await fileMethods.getExpiredFiles(100, { now });
expect(files.map((file) => file.file_id)).toEqual([expiredFileId]);
});
/** Seeds a sweep-eligible file, then drives its retry state through the
* same methods the sweep itself uses. */
const seedExpiredFile = async ({
file_id,
expiredAt,
attempts = 0,
retryAt,
}: {
file_id: string;
expiredAt: Date;
attempts?: number;
retryAt?: Date;
}) => {
await fileMethods.createFile(
{
file_id,
user: new mongoose.Types.ObjectId(),
filename: `${file_id}.txt`,
filepath: `/uploads/${file_id}.txt`,
type: 'text/plain',
bytes: 100,
expiredAt,
},
true,
);
for (let i = 0; i < attempts; i++) {
await fileMethods.incrementFileDeletionAttempts(file_id);
}
if (retryAt) {
await fileMethods.deferExpiredFile(file_id, retryAt);
}
};
it('holds back files whose deletion backoff has not elapsed', async () => {
const now = new Date('2030-01-01T00:00:00.000Z');
const readyFileId = uuidv4();
const backedOffFileId = uuidv4();
await seedExpiredFile({
file_id: backedOffFileId,
expiredAt: new Date('2029-12-01T00:00:00.000Z'),
attempts: 2,
retryAt: new Date('2030-01-01T00:00:01.000Z'),
});
await seedExpiredFile({
file_id: readyFileId,
expiredAt: new Date('2029-12-31T00:00:00.000Z'),
attempts: 2,
retryAt: new Date('2029-12-31T23:00:00.000Z'),
});
const files = await fileMethods.getExpiredFiles(100, { now });
expect(files.map((file) => file.file_id)).toEqual([readyFileId]);
});
it('holds a parked file back without excluding it for good', async () => {
const parkedFileId = uuidv4();
const retriableFileId = uuidv4();
/* The parked file expired first, so with nothing holding it back it
* sorts to the front of every batch and a limit-sized run of them
* starves everything that expired afterwards. */
await seedExpiredFile({
file_id: parkedFileId,
expiredAt: new Date('2029-01-01T00:00:00.000Z'),
attempts: 10,
retryAt: new Date('2030-02-01T00:00:00.000Z'),
});
await seedExpiredFile({
file_id: retriableFileId,
expiredAt: new Date('2029-12-31T00:00:00.000Z'),
attempts: 9,
});
const parked = await fileMethods.getExpiredFiles(100, {
now: new Date('2030-01-01T00:00:00.000Z'),
});
expect(parked.map((file) => file.file_id)).toEqual([retriableFileId]);
/* Nothing is excluded permanently — a record reused for different
* content in the meantime gets its object swept rather than stranded. */
const afterPark = await fileMethods.getExpiredFiles(100, {
now: new Date('2030-02-01T00:00:01.000Z'),
});
expect(afterPark.map((file) => file.file_id)).toEqual([parkedFileId, retriableFileId]);
});
it('leaves retry state alone on writes that touch the record', async () => {
const fileId = uuidv4();
await seedExpiredFile({
file_id: fileId,
expiredAt: new Date('2029-01-01T00:00:00.000Z'),
attempts: 4,
retryAt: new Date('2030-02-01T00:00:00.000Z'),
});
/* `prepareImagesLocal` clears the upload TTL with nothing but the id
* on every reuse of an image, the deferred preview only transitions
* `status`, and `processCodeOutput` repurposes a row for new content.
* None of them need to reason about sweep bookkeeping: the deferral
* is a deadline, so the worst a survivor can do is delay. */
await fileMethods.updateFile({ file_id: fileId });
await fileMethods.updateFile({ file_id: fileId, status: 'ready' });
const [file] = (await fileMethods.getFiles({ file_id: fileId }))!;
expect(file.deletionAttempts).toBe(4);
expect(file.deletionRetryAt).toEqual(new Date('2030-02-01T00:00:00.000Z'));
});
it('records retry bookkeeping without posing as a content write', async () => {
const fileId = uuidv4();
await seedExpiredFile({ file_id: fileId, expiredAt: new Date('2029-01-01T00:00:00.000Z') });
const [before] = (await fileMethods.getFiles({ file_id: fileId }))!;
/* `processCodeOutput` falls back to `updatedAt` as the writer-order
* stamp for records predating `metadata.sourceDispatchedAt`. A sweep
* that bumped it would look like a newer content writer and a
* background harvest would drop its attachment. */
await fileMethods.incrementFileDeletionAttempts(fileId);
await fileMethods.deferExpiredFile(fileId, new Date('2030-06-01T00:00:00.000Z'));
const [after] = (await fileMethods.getFiles({ file_id: fileId }))!;
expect(after.deletionAttempts).toBe(1);
expect(after.updatedAt).toEqual(before.updatedAt);
});
});
describe('deferExpiredFile', () => {
const createDeferrableFile = async (file_id: string) => {
await fileMethods.createFile(
{
file_id,
user: new mongoose.Types.ObjectId(),
filename: 'deferred.txt',
filepath: '/uploads/deferred.txt',
type: 'text/plain',
bytes: 100,
expiredAt: new Date('2029-12-31T00:00:00.000Z'),
},
true,
);
};
it('stamps the next retry and counts the attempt', async () => {
const fileId = uuidv4();
const retryAt = new Date('2030-02-01T00:00:00.000Z');
await createDeferrableFile(fileId);
expect(await fileMethods.incrementFileDeletionAttempts(fileId)).toBe(1);
await fileMethods.deferExpiredFile(fileId, retryAt);
const [file] = (await fileMethods.getFiles({ file_id: fileId }))!;
expect(file.deletionAttempts).toBe(1);
expect(file.deletionRetryAt).toEqual(retryAt);
});
it('hands concurrent sweeps distinct attempt numbers', async () => {
const fileId = uuidv4();
await createDeferrableFile(fileId);
/* Two nodes recording a failure for the same file in the same pass.
* Deriving the attempt from the queried snapshot would give both the
* same number and neither would see the cap being reached. */
const attempts = await Promise.all([
fileMethods.incrementFileDeletionAttempts(fileId),
fileMethods.incrementFileDeletionAttempts(fileId),
fileMethods.incrementFileDeletionAttempts(fileId),
]);
expect([...attempts].sort()).toEqual([1, 2, 3]);
});
it('never pulls a deferral earlier than one already committed', async () => {
const fileId = uuidv4();
const later = new Date('2030-02-01T00:00:00.000Z');
const earlier = new Date('2030-01-01T00:00:00.000Z');
await createDeferrableFile(fileId);
await fileMethods.deferExpiredFile(fileId, later);
await fileMethods.deferExpiredFile(fileId, earlier);
const [file] = (await fileMethods.getFiles({ file_id: fileId }))!;
expect(file.deletionRetryAt).toEqual(later);
});
});
describe('getToolFilesByIds', () => {
it('should retrieve files for file_search tool (embedded files)', async () => {
const userId = new mongoose.Types.ObjectId();
const embeddedFileId = uuidv4();
const regularFileId = uuidv4();
await fileMethods.createFile({
file_id: embeddedFileId,
user: userId,
filename: 'embedded.txt',
filepath: '/uploads/embedded.txt',
type: 'text/plain',
bytes: 100,
embedded: true,
});
await fileMethods.createFile({
file_id: regularFileId,
user: userId,
filename: 'regular.txt',
filepath: '/uploads/regular.txt',
type: 'text/plain',
bytes: 100,
});
const toolSet = new Set([EToolResources.file_search]);
const files = await fileMethods.getToolFilesByIds([embeddedFileId, regularFileId], toolSet);
expect(files).toHaveLength(1);
expect(files[0].file_id).toBe(embeddedFileId);
});
it('should retrieve files for context tool', async () => {
const userId = new mongoose.Types.ObjectId();
const contextFileId = uuidv4();
await fileMethods.createFile({
file_id: contextFileId,
user: userId,
filename: 'context.txt',
filepath: '/uploads/context.txt',
type: 'text/plain',
bytes: 100,
text: 'Context content',
context: FileContext.agents,
});
const toolSet = new Set([EToolResources.context]);
const files = await fileMethods.getToolFilesByIds([contextFileId], toolSet);
expect(files).toHaveLength(1);
expect(files[0].file_id).toBe(contextFileId);
});
it('should not retrieve execute_code files (handled by getCodeGeneratedFiles)', async () => {
const userId = new mongoose.Types.ObjectId();
const codeFileId = uuidv4();
await fileMethods.createFile({
file_id: codeFileId,
user: userId,
filename: 'code.py',
filepath: '/uploads/code.py',
type: 'text/x-python',
bytes: 100,
context: FileContext.execute_code,
metadata: {
codeEnvRef: {
kind: 'user',
id: userId.toString(),
storage_session_id: 'session-x',
file_id: codeFileId,
},
},
});
// execute_code files are explicitly excluded from getToolFilesByIds
// They are retrieved via getCodeGeneratedFiles and getUserCodeFiles instead
const toolSet = new Set([EToolResources.execute_code]);
const files = await fileMethods.getToolFilesByIds([codeFileId], toolSet);
expect(files).toHaveLength(0);
});
it('owner-scopes historical tool file lookups', async () => {
const ownerId = new mongoose.Types.ObjectId();
const victimId = new mongoose.Types.ObjectId();
const ownerFileId = uuidv4();
const victimFileId = uuidv4();
await runAsSystem(() =>
fileMethods.createFile({
file_id: ownerFileId,
user: ownerId,
tenantId: 'tenant-a',
filename: 'owner-embedded.txt',
filepath: '/uploads/owner-embedded.txt',
type: 'text/plain',
bytes: 100,
embedded: true,
}),
);
await runAsSystem(() =>
fileMethods.createFile({
file_id: victimFileId,
user: victimId,
tenantId: 'tenant-a',
filename: 'victim-embedded.txt',
filepath: '/uploads/victim-embedded.txt',
type: 'text/plain',
bytes: 100,
embedded: true,
}),
);
const toolSet = new Set([EToolResources.file_search]);
const files = await fileMethods.getToolFilesByIds([ownerFileId, victimFileId], toolSet, {
userId: ownerId.toString(),
tenantId: 'tenant-a',
});
expect(files).toHaveLength(1);
expect(files[0].file_id).toBe(ownerFileId);
});
});
describe('getCodeGeneratedFiles', () => {
/* The function filters by `file_id IN threadFileIds` — the file_ids
* referenced by messages in the current conversation thread —
* rather than by `messageId IN threadMessageIds`. The change
* matters when a code-output file is shared across sibling branches
* (regenerations); the File record's own `messageId` points at
* whichever sibling FIRST created it (preserved deliberately by
* processCodeOutput for provenance), but `threadFileIds` reaches
* any sibling that references the file via `messages.files[]`. */
it('finds a code-output file referenced by the current thread', async () => {
const userId = new mongoose.Types.ObjectId();
const conversationId = uuidv4();
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
conversationId,
messageId: 'msg-original-creator',
filename: 'output.csv',
filepath: '/uploads/output.csv',
type: 'text/csv',
bytes: 100,
context: FileContext.execute_code,
metadata: {
codeEnvRef: {
kind: 'user',
id: userId.toString(),
storage_session_id: 'sess',
file_id: fileId,
},
},
});
const files = await fileMethods.getCodeGeneratedFiles(conversationId, [fileId]);
expect(files).toHaveLength(1);
expect(files[0].file_id).toBe(fileId);
});
it('reaches a file whose creator messageId is on a sibling branch (regression)', async () => {
/* Branched-conversation case: sibling A creates the file (its
* messageId is preserved on the File record), sibling N
* recreates the same filename — claimCodeFile finds the existing
* record and the messageId stays at A. The current thread (parent
* = N) doesn't include A. Filtering by threadFileIds (which
* includes the file_id N's message references) reaches it. */
const userId = new mongoose.Types.ObjectId();
const conversationId = uuidv4();
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
conversationId,
/* The file's messageId points at sibling A — NOT in the
* current thread [siblingN, root]. The old `messageId IN`
* filter would have excluded the file here. */
messageId: 'siblingA',
filename: 'output.csv',
filepath: '/uploads/output.csv',
type: 'text/csv',
bytes: 100,
context: FileContext.execute_code,
metadata: {
codeEnvRef: {
kind: 'user',
id: userId.toString(),
storage_session_id: 'sess',
file_id: fileId,
},
},
});
const files = await fileMethods.getCodeGeneratedFiles(conversationId, [fileId]);
expect(files).toHaveLength(1);
expect(files[0].file_id).toBe(fileId);
});
it('returns empty when threadFileIds is missing or empty', async () => {
const conversationId = uuidv4();
expect(await fileMethods.getCodeGeneratedFiles(conversationId)).toEqual([]);
expect(await fileMethods.getCodeGeneratedFiles(conversationId, [])).toEqual([]);
});
it('does not cross conversation boundaries even with matching file_id', async () => {
const userId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
conversationId: 'other-conv',
messageId: 'msg-creator',
filename: 'output.csv',
filepath: '/uploads/output.csv',
type: 'text/csv',
bytes: 100,
context: FileContext.execute_code,
metadata: {
codeEnvRef: {
kind: 'user',
id: userId.toString(),
storage_session_id: 'sess',
file_id: fileId,
},
},
});
const files = await fileMethods.getCodeGeneratedFiles('this-conv', [fileId]);
expect(files).toEqual([]);
});
it('excludes non-execute_code files even when file_id matches', async () => {
/* `tool_resources.execute_code.file_ids` is the source of
* threadFileIds, but `messages.files[]` includes files of
* every context. The `context: execute_code` filter prevents
* a user-uploaded chat file from being mistakenly fetched via
* this function (it'd go through getUserCodeFiles instead). */
const userId = new mongoose.Types.ObjectId();
const conversationId = uuidv4();
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
conversationId,
messageId: 'msg-1',
filename: 'note.txt',
filepath: '/uploads/note.txt',
type: 'text/plain',
bytes: 100,
context: FileContext.message_attachment,
metadata: {
codeEnvRef: {
kind: 'user',
id: userId.toString(),
storage_session_id: 'sess',
file_id: fileId,
},
},
});
const files = await fileMethods.getCodeGeneratedFiles(conversationId, [fileId]);
expect(files).toEqual([]);
});
it('owner-scopes code-generated file lookups', async () => {
const ownerId = new mongoose.Types.ObjectId();
const victimId = new mongoose.Types.ObjectId();
const conversationId = uuidv4();
const ownerFileId = uuidv4();
const victimFileId = uuidv4();
for (const [fileId, userId, filename] of [
[ownerFileId, ownerId, 'owner-output.csv'],
[victimFileId, victimId, 'victim-output.csv'],
] as const) {
await runAsSystem(() =>
fileMethods.createFile({
file_id: fileId,
user: userId,
tenantId: 'tenant-a',
conversationId,
messageId: `msg-${fileId}`,
filename,
filepath: `/uploads/${filename}`,
type: 'text/csv',
bytes: 100,
context: FileContext.execute_code,
metadata: {
codeEnvRef: {
kind: 'user',
id: userId.toString(),
storage_session_id: `sess-${fileId}`,
file_id: fileId,
},
},
}),
);
}
const files = await fileMethods.getCodeGeneratedFiles(
conversationId,
[ownerFileId, victimFileId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
);
expect(files).toHaveLength(1);
expect(files[0].file_id).toBe(ownerFileId);
});
});
describe('getDeferredProvisionFiles', () => {
it('rejects route keys that cannot be used as MongoDB field segments', async () => {
const ownerScope = { userId: new mongoose.Types.ObjectId().toString() };
await expect(
fileMethods.getDeferredProvisionFiles([uuidv4()], ownerScope, {
code: true,
codeRouteKey: 'stateful.invalid',
}),
).rejects.toThrow('Invalid code environment route key');
});
const makeFile = (
fileId: string,
ownerId: mongoose.Types.ObjectId,
overrides: Record<string, unknown> = {},
) =>
runAsSystem(() =>
fileMethods.createFile({
file_id: fileId,
user: ownerId,
tenantId: 'tenant-a',
conversationId: 'conversation-a',
filename: `${fileId}.csv`,
filepath: `/uploads/${fileId}.csv`,
source: 'local',
type: 'text/csv',
bytes: 100,
context: FileContext.message_attachment,
...overrides,
}),
);
it('returns attachments that carry neither an embedding nor a code reference', async () => {
const ownerId = new mongoose.Types.ObjectId();
const deferredId = uuidv4();
await makeFile(deferredId, ownerId);
const results = await fileMethods.getDeferredProvisionFiles([deferredId], {
userId: ownerId.toString(),
tenantId: 'tenant-a',
});
expect(results.map((file) => file.file_id)).toEqual([deferredId]);
});
it('returns an agent file embedded only in another agent namespace', async () => {
/* Its vectors are under the other agent's entity, so the namespace this turn
* searches has none of them. The record-wide flag cannot say that, and skipping
* hydration here means nothing downstream ever notices. */
const ownerId = new mongoose.Types.ObjectId();
const foreignId = uuidv4();
await makeFile(foreignId, ownerId, {
context: FileContext.agents,
embedded: true,
metadata: { embeddedEntities: ['other-agent'] },
});
const results = await fileMethods.getDeferredProvisionFiles(
[foreignId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{
search: true,
searchNamespaces: ['this-agent', ownerId.toString()],
},
);
expect(results.map((file) => file.file_id)).toEqual([foreignId]);
});
it('leaves an agent file embedded in every candidate namespace alone', async () => {
const ownerId = new mongoose.Types.ObjectId();
const settledId = uuidv4();
await makeFile(settledId, ownerId, {
context: FileContext.agents,
embedded: true,
metadata: { embeddedEntities: ['this-agent', ownerId.toString()] },
});
const results = await fileMethods.getDeferredProvisionFiles(
[settledId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{
search: true,
searchNamespaces: ['this-agent', ownerId.toString()],
},
);
expect(results).toEqual([]);
});
it('returns a default-route reference so liveness can screen it', async () => {
/* A usable reference is not a live one. With resendFiles off this is the only query
* that runs, so excluding it leaves an expired session unnoticed and the code tool
* running without the file. */
const ownerId = new mongoose.Types.ObjectId();
const refId = uuidv4();
await makeFile(refId, ownerId, {
metadata: {
codeEnvRef: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
codeEnvRefs: {
default: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
},
},
});
const results = await fileMethods.getDeferredProvisionFiles(
[refId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ code: true, codeRouteKey: 'default', hydrateProvisioned: true },
);
expect(results.map((file) => file.file_id)).toEqual([refId]);
});
it('leaves a default reference alone when another query already hydrates it', async () => {
/* With resendFiles on, getToolFilesByIds loads provisioned files and the probe sees
* them there, so widening this query would only duplicate the read. */
const ownerId = new mongoose.Types.ObjectId();
const refId = uuidv4();
await makeFile(refId, ownerId, {
metadata: {
codeEnvRef: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
codeEnvRefs: {
default: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
},
},
});
const results = await fileMethods.getDeferredProvisionFiles(
[refId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ code: true, codeRouteKey: 'default', hydrateProvisioned: false },
);
expect(results).toEqual([]);
});
it('returns a usable stateful reference so priming can add it to the tool resources', async () => {
/* Being provisioned already is not a reason to skip it: with no other query running,
* this is what puts the record into tool_resources. Omitting it drops the file the
* previous turn provisioned successfully while retrying the one that failed. */
const ownerId = new mongoose.Types.ObjectId();
const refId = uuidv4();
const statefulRef = {
kind: 'user',
id: 'u1',
storage_session_id: 's2',
file_id: 'r2',
executionRouteKey: 'stateful:a',
};
await makeFile(refId, ownerId, {
metadata: {
codeEnvRef: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
codeEnvRefs: { 'stateful:a': statefulRef },
},
});
const results = await fileMethods.getDeferredProvisionFiles(
[refId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ code: true, codeRouteKey: 'stateful:a', hydrateProvisioned: true },
);
expect(results.map((file) => file.file_id)).toEqual([refId]);
});
it('returns an embedded attachment to a search-only agent when nothing else hydrates', async () => {
/* With resendFiles off, getToolFilesByIds does not run, so this is the only query
* that can put an already-embedded attachment into tool_resources.file_search.
* Excluding it on the embedded flag leaves the next search with no reference to a
* file the previous turn embedded successfully. */
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await makeFile(fileId, ownerId, { embedded: true });
const results = await fileMethods.getDeferredProvisionFiles(
[fileId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ search: true, searchNamespaces: [ownerId.toString()], hydrateProvisioned: true },
);
expect(results.map((file) => file.file_id)).toEqual([fileId]);
});
it('leaves an embedded attachment alone when another query already hydrates it', async () => {
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await makeFile(fileId, ownerId, { embedded: true });
const results = await fileMethods.getDeferredProvisionFiles(
[fileId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ search: true, searchNamespaces: [ownerId.toString()], hydrateProvisioned: false },
);
expect(results).toEqual([]);
});
it('surfaces a read failure rather than reporting nothing to provision', async () => {
/* An empty list is indistinguishable from nothing needing provisioning, so a
* swallowed error would let the tool run without the attachment. */
const ownerId = new mongoose.Types.ObjectId();
const failing = createFileMethods({
...mongoose,
models: {
...mongoose.models,
File: {
find: () => {
throw new Error('mongo unavailable');
},
},
},
} as unknown as typeof mongoose);
await expect(
failing.getDeferredProvisionFiles([uuidv4()], { userId: ownerId.toString() }),
).rejects.toThrow(/mongo unavailable/);
});
it('still queues a file whose only code reference is for another route', async () => {
const ownerId = new mongoose.Types.ObjectId();
const otherRouteId = uuidv4();
await makeFile(otherRouteId, ownerId, {
embedded: true,
metadata: {
codeEnvRefs: {
'stateful:a': {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'session-a',
file_id: otherRouteId,
executionRouteKey: 'stateful:a',
},
},
},
});
const results = await fileMethods.getDeferredProvisionFiles(
[otherRouteId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ code: true, codeRouteKey: 'stateful:b' },
);
expect(results.map((file) => file.file_id)).toEqual([otherRouteId]);
});
it('omits a file already provisioned for the active route', async () => {
const ownerId = new mongoose.Types.ObjectId();
const sameRouteId = uuidv4();
await makeFile(sameRouteId, ownerId, {
embedded: true,
metadata: {
codeEnvRefs: {
'stateful:b': {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'session-b',
file_id: sameRouteId,
executionRouteKey: 'stateful:b',
},
},
},
});
const results = await fileMethods.getDeferredProvisionFiles(
[sameRouteId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ code: true, codeRouteKey: 'stateful:b' },
);
expect(results).toEqual([]);
});
it('treats a legacy pointer without a route key as the default deployment', async () => {
const ownerId = new mongoose.Types.ObjectId();
const legacyId = uuidv4();
await makeFile(legacyId, ownerId, {
embedded: true,
metadata: {
codeEnvRef: {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'session',
file_id: legacyId,
},
},
});
const ownerScope = { userId: ownerId.toString(), tenantId: 'tenant-a' };
const onDefault = await fileMethods.getDeferredProvisionFiles([legacyId], ownerScope, {
code: true,
codeRouteKey: 'default',
});
const onStateful = await fileMethods.getDeferredProvisionFiles([legacyId], ownerScope, {
code: true,
codeRouteKey: 'stateful:b',
});
expect(onDefault).toEqual([]);
expect(onStateful.map((file) => file.file_id)).toEqual([legacyId]);
});
it('omits a file that already carries every requested result', async () => {
const ownerId = new mongoose.Types.ObjectId();
const embeddedId = uuidv4();
const provisionedId = uuidv4();
const generatedId = uuidv4();
await makeFile(embeddedId, ownerId, {
embedded: true,
metadata: {
codeEnvRef: {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'session',
file_id: embeddedId,
},
},
});
await makeFile(provisionedId, ownerId, {
embedded: true,
metadata: {
codeEnvRef: {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'session',
file_id: provisionedId,
},
},
});
await makeFile(generatedId, ownerId, { context: FileContext.execute_code });
const results = await fileMethods.getDeferredProvisionFiles(
[embeddedId, provisionedId, generatedId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
);
expect(results).toEqual([]);
});
it('returns a search-embedded file when the agent needs code provisioning', async () => {
const ownerId = new mongoose.Types.ObjectId();
const embeddedOnlyId = uuidv4();
await makeFile(embeddedOnlyId, ownerId, { embedded: true });
const forCode = await fileMethods.getDeferredProvisionFiles(
[embeddedOnlyId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ code: true },
);
const forSearch = await fileMethods.getDeferredProvisionFiles(
[embeddedOnlyId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ search: true },
);
expect(forCode.map((file) => file.file_id)).toEqual([embeddedOnlyId]);
expect(forSearch).toEqual([]);
});
it('returns a code-provisioned file when the agent needs search provisioning', async () => {
const ownerId = new mongoose.Types.ObjectId();
const codeOnlyId = uuidv4();
await makeFile(codeOnlyId, ownerId, {
metadata: {
codeEnvRef: {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'session',
file_id: codeOnlyId,
},
},
});
const forSearch = await fileMethods.getDeferredProvisionFiles(
[codeOnlyId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ search: true },
);
const forCode = await fileMethods.getDeferredProvisionFiles(
[codeOnlyId],
{ userId: ownerId.toString(), tenantId: 'tenant-a' },
{ code: true },
);
expect(forSearch.map((file) => file.file_id)).toEqual([codeOnlyId]);
expect(forCode).toEqual([]);
});
it('does not cross the authenticated owner scope', async () => {
const ownerId = new mongoose.Types.ObjectId();
const victimId = new mongoose.Types.ObjectId();
const victimFileId = uuidv4();
await makeFile(victimFileId, victimId);
const results = await fileMethods.getDeferredProvisionFiles([victimFileId], {
userId: ownerId.toString(),
tenantId: 'tenant-a',
});
expect(results).toEqual([]);
});
});
describe('updateFileCodeEnvRef', () => {
const makeRefFile = (fileId: string, ownerId: mongoose.Types.ObjectId) =>
runAsSystem(() =>
fileMethods.createFile({
file_id: fileId,
user: ownerId,
tenantId: 'tenant-a',
conversationId: 'conversation-a',
filename: `${fileId}.csv`,
filepath: `/uploads/${fileId}.csv`,
source: 'local',
type: 'text/csv',
bytes: 100,
context: FileContext.message_attachment,
metadata: { sourceDispatchedAt: 42 },
}),
);
const ref = (routeKey: string, remoteId: string) => ({
kind: 'user' as const,
id: 'u1',
storage_session_id: `session-${routeKey}`,
file_id: remoteId,
executionRouteKey: routeKey,
});
it('keeps concurrently written sibling routes', async () => {
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await makeRefFile(fileId, ownerId);
await Promise.all([
runAsSystem(() =>
fileMethods.updateFileCodeEnvRef({
file_id: fileId,
routeKey: 'default',
ref: ref('default', 'remote-default'),
}),
),
runAsSystem(() =>
fileMethods.updateFileCodeEnvRef({
file_id: fileId,
routeKey: 'stateful:a',
ref: ref('stateful:a', 'remote-stateful'),
}),
),
]);
const stored = await runAsSystem(() => fileMethods.findFileById(fileId));
const refs = stored?.metadata?.codeEnvRefs as Record<string, { file_id: string }> | undefined;
expect(refs?.default?.file_id).toBe('remote-default');
expect(refs?.['stateful:a']?.file_id).toBe('remote-stateful');
});
it('leaves sibling metadata fields in place', async () => {
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await makeRefFile(fileId, ownerId);
await runAsSystem(() =>
fileMethods.updateFileCodeEnvRef({
file_id: fileId,
routeKey: 'default',
ref: ref('default', 'remote-default'),
legacyRef: ref('default', 'remote-default'),
}),
);
const stored = await runAsSystem(() => fileMethods.findFileById(fileId));
expect(stored?.metadata?.sourceDispatchedAt).toBe(42);
expect((stored?.metadata?.codeEnvRef as { file_id: string } | undefined)?.file_id).toBe(
'remote-default',
);
});
it('rejects a route key that would write outside its entry', async () => {
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await makeRefFile(fileId, ownerId);
await expect(
runAsSystem(() =>
fileMethods.updateFileCodeEnvRef({
file_id: fileId,
routeKey: 'a.b',
ref: ref('a.b', 'remote'),
}),
),
).rejects.toThrow(/Invalid code environment route key/);
});
});
describe('recordFileWorkspaceImport', () => {
const makeFile = (fileId: string, ownerId: mongoose.Types.ObjectId, tenantId = 'tenant-a') =>
runAsSystem(() =>
fileMethods.createFile({
file_id: fileId,
user: ownerId,
tenantId,
filename: 'report.pdf',
filepath: '/uploads/report.pdf',
source: 'local',
type: 'application/pdf',
bytes: 3,
context: FileContext.message_attachment,
metadata: { routingMimeType: 'application/pdf' },
}),
);
const keyA = 'a'.repeat(32);
const keyB = 'b'.repeat(32);
const copy = (path: string) => ({ sha256: 'c'.repeat(64), path });
it('records copies and the digest without replacing sibling targets or metadata', async () => {
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await makeFile(fileId, ownerId);
await Promise.all([
runAsSystem(() =>
fileMethods.recordFileWorkspaceImport({
file_id: fileId,
user: ownerId.toString(),
tenantId: 'tenant-a',
copy: { key: keyA, target: copy('.librechat/attachments/report.pdf') },
}),
),
runAsSystem(() =>
fileMethods.recordFileWorkspaceImport({
file_id: fileId,
user: ownerId.toString(),
tenantId: 'tenant-a',
copy: { key: keyB, target: copy('.librechat/attachments/report (2).pdf') },
}),
),
runAsSystem(() =>
fileMethods.recordFileWorkspaceImport({
file_id: fileId,
user: ownerId.toString(),
tenantId: 'tenant-a',
digest: { source: 's/o', sha256: 'c'.repeat(64), bytes: 3 },
}),
),
]);
const stored = await runAsSystem(() => fileMethods.findFileById(fileId));
expect(stored?.metadata?.workspaceImports).toEqual({
digest: { source: 's/o', sha256: 'c'.repeat(64), bytes: 3 },
targets: {
[keyA]: copy('.librechat/attachments/report.pdf'),
[keyB]: copy('.librechat/attachments/report (2).pdf'),
},
});
expect(stored?.metadata?.routingMimeType).toBe('application/pdf');
});
it("never marks another user's file", async () => {
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await makeFile(fileId, ownerId);
const matched = await runAsSystem(() =>
fileMethods.recordFileWorkspaceImport({
file_id: fileId,
user: new mongoose.Types.ObjectId().toString(),
tenantId: 'tenant-a',
copy: { key: keyA, target: copy('.librechat/attachments/report.pdf') },
}),
);
expect(matched).toBe(false);
const stored = await runAsSystem(() => fileMethods.findFileById(fileId));
expect(stored?.metadata?.workspaceImports).toBeUndefined();
});
it("never marks the same user's record in another tenant", async () => {
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await makeFile(fileId, ownerId, 'tenant-b');
const matched = await runAsSystem(() =>
fileMethods.recordFileWorkspaceImport({
file_id: fileId,
user: ownerId.toString(),
tenantId: 'tenant-a',
copy: { key: keyA, target: copy('.librechat/attachments/report.pdf') },
}),
);
expect(matched).toBe(false);
const stored = await runAsSystem(() => fileMethods.findFileById(fileId));
expect(stored?.metadata?.workspaceImports).toBeUndefined();
});
it('rejects a key that would address another metadata path', async () => {
await expect(
fileMethods.recordFileWorkspaceImport({
file_id: uuidv4(),
user: new mongoose.Types.ObjectId().toString(),
copy: { key: 'targets.$where', target: copy('.librechat/attachments/report.pdf') },
}),
).rejects.toThrow('hex digests');
});
});
describe('getUserCodeFiles', () => {
it('returns only authenticated owner code-env uploads', async () => {
const ownerId = new mongoose.Types.ObjectId();
const victimId = new mongoose.Types.ObjectId();
const ownerFileId = uuidv4();
const victimFileId = uuidv4();
await runAsSystem(() =>
fileMethods.createFile({
file_id: ownerFileId,
user: ownerId,
tenantId: 'tenant-a',
conversationId: 'conversation-owner',
filename: 'owner.csv',
filepath: '/uploads/owner.csv',
source: 'local',
type: 'text/csv',
bytes: 100,
context: FileContext.message_attachment,
metadata: {
codeEnvRef: {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'owner-session',
file_id: ownerFileId,
},
},
}),
);
await runAsSystem(() =>
fileMethods.createFile({
file_id: victimFileId,
user: victimId,
tenantId: 'tenant-a',
conversationId: 'conversation-victim',
filename: 'victim.csv',
filepath: '/uploads/victim.csv',
source: 'local',
type: 'text/csv',
bytes: 100,
context: FileContext.message_attachment,
metadata: {
codeEnvRef: {
kind: 'user',
id: victimId.toString(),
storage_session_id: 'victim-session',
file_id: victimFileId,
},
},
}),
);
const files = await fileMethods.getUserCodeFiles([ownerFileId, victimFileId], {
userId: ownerId.toString(),
tenantId: 'tenant-a',
});
expect(files).toHaveLength(1);
expect(files[0]).toMatchObject({
file_id: ownerFileId,
filename: 'owner.csv',
filepath: '/uploads/owner.csv',
source: 'local',
metadata: {
codeEnvRef: {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'owner-session',
file_id: ownerFileId,
},
},
});
});
it('excludes files outside the authenticated tenant scope', async () => {
const ownerId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await runAsSystem(() =>
fileMethods.createFile({
file_id: fileId,
user: ownerId,
tenantId: 'tenant-b',
filename: 'tenant-b.csv',
filepath: '/uploads/tenant-b.csv',
source: 'local',
type: 'text/csv',
bytes: 100,
context: FileContext.message_attachment,
metadata: {
codeEnvRef: {
kind: 'user',
id: ownerId.toString(),
storage_session_id: 'tenant-b-session',
file_id: fileId,
},
},
}),
);
const files = await fileMethods.getUserCodeFiles([fileId], {
userId: ownerId.toString(),
tenantId: 'tenant-a',
});
expect(files).toEqual([]);
});
});
describe('updateFile', () => {
it('should update file data and remove TTL', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'original.txt',
filepath: '/uploads/original.txt',
type: 'text/plain',
bytes: 100,
});
const updated = await fileMethods.updateFile({
file_id: fileId,
filename: 'updated.txt',
bytes: 200,
});
expect(updated).not.toBeNull();
expect(updated?.filename).toBe('updated.txt');
expect(updated?.bytes).toBe(200);
expect(updated?.expiresAt).toBeUndefined();
});
/* `prepareImageURL` clears the upload TTL with nothing but the id on every
* reuse of an image. Project resume compatibility fingerprints canonical
* content by `updatedAt`, so that bookkeeping must not read as a new
* version while a real field write still must. */
it('clears the upload TTL without posing as a content write', async () => {
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: new mongoose.Types.ObjectId(),
filename: 'reused.png',
filepath: '/uploads/reused.png',
type: 'image/png',
bytes: 100,
});
const stamp = new Date('2020-01-01T00:00:00.000Z');
await File.updateOne(
{ file_id: fileId },
{ $set: { updatedAt: stamp } },
{
timestamps: false,
},
);
const reused = await fileMethods.updateFile({ file_id: fileId });
expect(reused?.expiresAt).toBeUndefined();
expect(reused?.updatedAt).toEqual(stamp);
const rewritten = await fileMethods.updateFile({ file_id: fileId, text: 'extracted' });
expect(rewritten?.updatedAt).not.toEqual(stamp);
});
/* The optional `extraFilter` enables conditional updates — used by
* the deferred-preview render's `finalizePreview` to guard against
* an older render of the same `file_id` overwriting a newer turn's
* record on cross-turn filename reuse. (Codex P1 review on PR
* #12957.) */
describe('extraFilter (conditional update)', () => {
it('commits when the extra filter matches the current document', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'data.xlsx',
filepath: '/uploads/data.xlsx',
type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
bytes: 100,
status: 'pending',
previewRevision: 'rev-A',
});
const updated = await fileMethods.updateFile(
{ file_id: fileId, status: 'ready', text: '<table></table>' },
{ previewRevision: 'rev-A' },
);
expect(updated).not.toBeNull();
expect(updated?.status).toBe('ready');
expect(updated?.text).toBe('<table></table>');
});
it('returns null and skips the write when the extra filter does NOT match', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'data.xlsx',
filepath: '/uploads/data.xlsx',
type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
bytes: 100,
status: 'pending',
previewRevision: 'rev-B', // newer turn has rotated the revision
});
/* An older render that started while revision was 'rev-A' tries
* to commit. The newer turn has since rotated to 'rev-B'. The
* conditional update silently no-ops. */
const updated = await fileMethods.updateFile(
{ file_id: fileId, status: 'ready', text: '<stale/>' },
{ previewRevision: 'rev-A' },
);
expect(updated).toBeNull();
/* Critical: the newer record's text MUST be untouched. */
const fresh = await fileMethods.findFileById(fileId);
expect(fresh?.previewRevision).toBe('rev-B');
expect(fresh?.status).toBe('pending');
expect(fresh?.text).toBeUndefined();
});
it('falls back to single-key update when extraFilter is omitted (back-compat)', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'plain.txt',
filepath: '/uploads/plain.txt',
type: 'text/plain',
bytes: 50,
});
const updated = await fileMethods.updateFile({
file_id: fileId,
bytes: 99,
});
expect(updated).not.toBeNull();
expect(updated?.bytes).toBe(99);
});
});
});
describe('updateFileUsage', () => {
it('should increment usage count', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'usage-test.txt',
filepath: '/uploads/usage-test.txt',
type: 'text/plain',
bytes: 100,
usage: 0,
});
const updated = await fileMethods.updateFileUsage({ file_id: fileId });
expect(updated?.usage).toBe(1);
const updated2 = await fileMethods.updateFileUsage({ file_id: fileId, inc: 5 });
expect(updated2?.usage).toBe(6);
});
it('scopes usage and hold consumption without advancing the content version', async () => {
const fileId = uuidv4();
const ownerId = new mongoose.Types.ObjectId();
const otherUserId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
temp_file_id: 'tmp-file',
user: ownerId,
filename: 'owned.txt',
filepath: '/uploads/owned.txt',
type: 'text/plain',
bytes: 100,
usage: 0,
});
const contentUpdatedAt = new Date('2020-01-01');
await File.collection.updateOne(
{ file_id: fileId },
{ $set: { updatedAt: contentUpdatedAt } },
);
const denied = await fileMethods.updateFileUsage({
file_id: fileId,
user: otherUserId.toString(),
});
const unchanged = await fileMethods.findFileById(fileId);
expect(denied).toBeNull();
expect(unchanged?.usage).toBe(0);
expect(unchanged?.temp_file_id).toBe('tmp-file');
expect(unchanged?.expiresAt).toBeDefined();
const allowed = await fileMethods.updateFileUsage({
file_id: fileId,
user: ownerId.toString(),
});
expect(allowed?.usage).toBe(1);
expect(allowed?.temp_file_id).toBeUndefined();
expect(allowed?.expiresAt).toBeUndefined();
expect(allowed?.updatedAt).toEqual(contentUpdatedAt);
const changedContent = await fileMethods.updateFile({
file_id: fileId,
text: 'Updated canonical file contents.',
});
expect(changedContent?.updatedAt?.getTime()).toBeGreaterThan(contentUpdatedAt.getTime());
});
});
describe('updateFilesUsage', () => {
it('should update usage for multiple files', async () => {
const userId = new mongoose.Types.ObjectId();
const fileIds = [uuidv4(), uuidv4()];
for (const fileId of fileIds) {
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: `file-${fileId}.txt`,
filepath: `/uploads/${fileId}.txt`,
type: 'text/plain',
bytes: 100,
usage: 0,
});
}
const files = fileIds.map((file_id) => ({ file_id }));
const updated = await fileMethods.updateFilesUsage(files);
expect(updated).toHaveLength(2);
for (const file of updated) {
expect((file as { usage: number }).usage).toBe(1);
}
});
it('should deduplicate files', async () => {
const userId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'duplicate-test.txt',
filepath: '/uploads/duplicate-test.txt',
type: 'text/plain',
bytes: 100,
usage: 0,
});
const files = [{ file_id: fileId }, { file_id: fileId }, { file_id: fileId }];
const updated = await fileMethods.updateFilesUsage(files);
expect(updated).toHaveLength(1);
expect((updated[0] as { usage: number }).usage).toBe(1);
});
it('should filter out null results when files do not exist', async () => {
const userId = new mongoose.Types.ObjectId();
const existingFileId = uuidv4();
await fileMethods.createFile({
file_id: existingFileId,
user: userId,
filename: 'existing.txt',
filepath: '/uploads/existing.txt',
type: 'text/plain',
bytes: 100,
usage: 0,
});
const files = [{ file_id: existingFileId }, { file_id: 'non-existent-file' }];
const updated = await fileMethods.updateFilesUsage(files);
expect(updated.length).toBeGreaterThan(0);
expect(updated).not.toContain(null);
expect(updated).not.toContain(undefined);
const existingFile = updated.find(
(f) => (f as { file_id: string }).file_id === existingFileId,
);
expect(existingFile).toBeDefined();
expect((existingFile as { usage: number }).usage).toBe(1);
});
it('should handle empty files array', async () => {
const result = await fileMethods.updateFilesUsage([]);
expect(result).toEqual([]);
});
it('should handle fileIds parameter', async () => {
const userId = new mongoose.Types.ObjectId();
const fileIds = [uuidv4(), uuidv4()];
for (const fileId of fileIds) {
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: `file-${fileId}.txt`,
filepath: `/uploads/${fileId}.txt`,
type: 'text/plain',
bytes: 100,
usage: 0,
});
}
const files = [{ file_id: fileIds[0] }];
const updated = await fileMethods.updateFilesUsage(files, [fileIds[1]]);
expect(updated).toHaveLength(2);
const file1 = updated.find((f) => (f as { file_id: string }).file_id === fileIds[0]);
const file2 = updated.find((f) => (f as { file_id: string }).file_id === fileIds[1]);
expect(file1).toBeDefined();
expect(file2).toBeDefined();
expect((file1 as { usage: number }).usage).toBe(1);
expect((file2 as { usage: number }).usage).toBe(1);
});
it('should deduplicate between files and fileIds parameters', async () => {
const userId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'test.txt',
filepath: '/uploads/test.txt',
type: 'text/plain',
bytes: 100,
usage: 0,
});
const files = [{ file_id: fileId }];
const updated = await fileMethods.updateFilesUsage(files, [fileId]);
expect(updated).toHaveLength(1);
expect((updated[0] as { usage: number }).usage).toBe(1);
});
it('should only return and mutate files owned by the scoped user', async () => {
const ownerId = new mongoose.Types.ObjectId();
const otherUserId = new mongoose.Types.ObjectId();
const ownerFileId = uuidv4();
const otherFileId = uuidv4();
await fileMethods.createFile({
file_id: ownerFileId,
user: ownerId,
filename: 'owner.txt',
filepath: '/uploads/owner.txt',
type: 'text/plain',
bytes: 100,
usage: 0,
});
await fileMethods.createFile({
file_id: otherFileId,
temp_file_id: 'tmp-other',
user: otherUserId,
filename: 'other.txt',
filepath: '/uploads/other.txt',
type: 'text/plain',
bytes: 100,
usage: 0,
text: 'private extracted text',
});
const updated = await fileMethods.updateFilesUsage(
[{ file_id: ownerFileId }, { file_id: otherFileId }],
undefined,
{ user: ownerId.toString() },
);
const otherFile = await fileMethods.findFileById(otherFileId);
expect(updated).toHaveLength(1);
expect(updated[0].file_id).toBe(ownerFileId);
expect(updated[0].usage).toBe(1);
expect(otherFile?.usage).toBe(0);
expect(otherFile?.temp_file_id).toBe('tmp-other');
expect(otherFile?.expiresAt).toBeDefined();
});
});
describe('extendFilesTTL', () => {
const HOUR = 3_600_000;
const HOLD = { renewMs: 24 * HOUR, maxLifetimeMs: 48 * HOUR };
const seedTempFile = async (
userId: mongoose.Types.ObjectId,
expiresAt: Date,
createdAt?: Date,
) => {
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: `${fileId}.txt`,
filepath: `/uploads/${fileId}.txt`,
type: 'text/plain',
bytes: 100,
});
await mongoose.models.File.updateOne(
{ file_id: fileId },
{ $set: { expiresAt } },
{ timestamps: false },
);
/** Mongoose strips the immutable `createdAt` from updates, so backdating
* must go through the raw driver to actually land. */
if (createdAt) {
await mongoose.models.File.collection.updateOne(
{ file_id: fileId },
{ $set: { createdAt } },
);
}
return fileId;
};
const readFile = async (fileId: string) =>
(await mongoose.models.File.findOne({ file_id: fileId })
.lean<{ createdAt: Date; expiresAt?: Date }>()
.exec())!;
it('widens the TTL toward the renewal window without unsetting it', async () => {
const userId = new mongoose.Types.ObjectId();
const fileId = await seedTempFile(userId, new Date(Date.now() + 60_000));
const count = await fileMethods.extendFilesTTL([fileId], HOLD, { user: String(userId) });
expect(count).toBe(1);
const file = await readFile(fileId);
expect(file.expiresAt).toBeDefined();
expect(file.expiresAt!.getTime()).toBeGreaterThan(Date.now() + 23 * HOUR);
expect(file.expiresAt!.getTime()).toBeLessThanOrEqual(
file.createdAt.getTime() + HOLD.maxLifetimeMs,
);
});
/** The bound that makes the endpoint safe to expose: every renewal is
* clamped to createdAt + maxLifetimeMs, so replaying the call converges
* on a ceiling instead of advancing a window at a time. */
it('clamps every renewal to the ceiling, however often it is replayed', async () => {
const userId = new mongoose.Types.ObjectId();
const fileId = await seedTempFile(userId, new Date(Date.now() + 60_000));
const ceilingHold = { renewMs: 24 * HOUR, maxLifetimeMs: 10 * 60_000 };
const { createdAt } = await readFile(fileId);
const first = await fileMethods.extendFilesTTL([fileId], ceilingHold, {
user: String(userId),
});
expect(first).toBe(1);
for (let i = 0; i < 5; i++) {
expect(
await fileMethods.extendFilesTTL([fileId], ceilingHold, { user: String(userId) }),
).toBe(0);
}
const file = await readFile(fileId);
expect(file.expiresAt!.getTime()).toBe(createdAt.getTime() + ceilingHold.maxLifetimeMs);
/* The renewal window alone would have granted a full day. */
expect(file.expiresAt!.getTime()).toBeLessThan(Date.now() + HOUR);
});
/** Renewal is measured from now, so a queue still draining across
* successive runs keeps its attachments past the first hold. */
it('renews from now while the ceiling still allows it', async () => {
const userId = new mongoose.Types.ObjectId();
const twoHoursAgo = new Date(Date.now() - 2 * HOUR);
const fileId = await seedTempFile(userId, new Date(Date.now() + 60_000), twoHoursAgo);
const count = await fileMethods.extendFilesTTL(
[fileId],
{ renewMs: HOUR, maxLifetimeMs: 24 * HOUR },
{ user: String(userId) },
);
expect(count).toBe(1);
const file = await readFile(fileId);
/* Anchoring to createdAt alone would have expired this an hour ago. */
expect(file.expiresAt!.getTime()).toBeGreaterThan(Date.now() + 50 * 60_000);
});
it("applies each file's own ceiling within a single batch", async () => {
const userId = new mongoose.Types.ObjectId();
const soon = new Date(Date.now() + 60_000);
const freshId = await seedTempFile(userId, soon);
const agedId = await seedTempFile(userId, soon, new Date(Date.now() - 47 * HOUR));
const releasedId = await seedTempFile(userId, soon);
await fileMethods.updateFileUsage({ file_id: releasedId, user: String(userId) });
const count = await fileMethods.extendFilesTTL([freshId, agedId, releasedId], HOLD, {
user: String(userId),
});
expect(count).toBe(2);
const fresh = await readFile(freshId);
expect(fresh.expiresAt!.getTime()).toBeGreaterThan(Date.now() + 23 * HOUR);
const aged = await readFile(agedId);
expect(aged.expiresAt!.getTime()).toBe(aged.createdAt.getTime() + HOLD.maxLifetimeMs);
expect(aged.expiresAt!.getTime()).toBeLessThan(Date.now() + 2 * HOUR);
const released = await readFile(releasedId);
expect(released.expiresAt).toBeUndefined();
});
it('does not resurrect a TTL on an already-released file', async () => {
const userId = new mongoose.Types.ObjectId();
const fileId = await seedTempFile(userId, new Date(Date.now() + 60_000));
await fileMethods.updateFileUsage({ file_id: fileId, user: String(userId) });
const count = await fileMethods.extendFilesTTL([fileId], HOLD, { user: String(userId) });
expect(count).toBe(0);
const file = await readFile(fileId);
expect(file.expiresAt).toBeUndefined();
});
it('never moves an expiry earlier', async () => {
const userId = new mongoose.Types.ObjectId();
const farOut = new Date(Date.now() + 7 * 24 * HOUR);
const fileId = await seedTempFile(userId, farOut);
const count = await fileMethods.extendFilesTTL([fileId], HOLD, { user: String(userId) });
expect(count).toBe(0);
const file = await readFile(fileId);
expect(file.expiresAt!.getTime()).toBe(farOut.getTime());
});
it("leaves another user's file untouched", async () => {
const ownerId = new mongoose.Types.ObjectId();
const attackerId = new mongoose.Types.ObjectId();
const soon = new Date(Date.now() + 60_000);
const fileId = await seedTempFile(ownerId, soon);
const count = await fileMethods.extendFilesTTL([fileId], HOLD, {
user: String(attackerId),
});
expect(count).toBe(0);
const file = await readFile(fileId);
expect(file.expiresAt!.getTime()).toBe(soon.getTime());
});
it('is a no-op without an owner scope rather than a cross-user update', async () => {
const userId = new mongoose.Types.ObjectId();
const soon = new Date(Date.now() + 60_000);
const fileId = await seedTempFile(userId, soon);
const count = await fileMethods.extendFilesTTL([fileId], HOLD, { user: '' } as {
user: string;
});
expect(count).toBe(0);
const file = await readFile(fileId);
expect(file.expiresAt!.getTime()).toBe(soon.getTime());
});
it('is a no-op for a non-positive hold', async () => {
const userId = new mongoose.Types.ObjectId();
const soon = new Date(Date.now() + 60_000);
const fileId = await seedTempFile(userId, soon);
const owner = { user: String(userId) };
expect(
await fileMethods.extendFilesTTL([fileId], { renewMs: 0, maxLifetimeMs: 0 }, owner),
).toBe(0);
expect(
await fileMethods.extendFilesTTL([fileId], { renewMs: -1, maxLifetimeMs: -1 }, owner),
).toBe(0);
const file = await readFile(fileId);
expect(file.expiresAt!.getTime()).toBe(soon.getTime());
});
});
describe('deleteFile', () => {
it('should delete a file by file_id', async () => {
const fileId = uuidv4();
const userId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'delete-me.txt',
filepath: '/uploads/delete-me.txt',
type: 'text/plain',
bytes: 100,
});
const deleted = await fileMethods.deleteFile(fileId);
expect(deleted).not.toBeNull();
expect(deleted?.file_id).toBe(fileId);
const found = await fileMethods.findFileById(fileId);
expect(found).toBeNull();
});
});
describe('project reference cleanup on delete', () => {
async function seed() {
const userId = new mongoose.Types.ObjectId();
const ChatProject = mongoose.models.ChatProject as mongoose.Model<IChatProject>;
const ids = [uuidv4(), uuidv4()];
for (const fileId of ids) {
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: `${fileId}.txt`,
filepath: `/uploads/${fileId}.txt`,
type: 'text/plain',
bytes: 1,
});
}
const project = await ChatProject.create({
user: userId.toString(),
name: 'P',
file_ids: [...ids, 'other'],
contextRevision: 4,
});
const untouched = await ChatProject.create({
user: new mongoose.Types.ObjectId().toString(),
name: 'Q',
file_ids: [ids[0]],
contextRevision: 1,
});
return { ids, project, untouched, ChatProject };
}
it('pulls a deleted file from the owner projects and bumps the revision', async () => {
const { ids, project, untouched, ChatProject } = await seed();
await fileMethods.deleteFile(ids[0]);
const after = await ChatProject.findById(project._id).lean();
expect(after?.file_ids).toEqual([ids[1], 'other']);
expect(after?.contextRevision).toBe(5);
const other = await ChatProject.findById(untouched._id).lean();
expect(other?.file_ids).toEqual([ids[0]]);
expect(other?.contextRevision).toBe(1);
});
it('pulls every id removed by deleteFiles', async () => {
const { ids, project, ChatProject } = await seed();
await fileMethods.deleteFiles(ids);
const after = await ChatProject.findById(project._id).lean();
expect(after?.file_ids).toEqual(['other']);
expect(after?.contextRevision).toBe(5);
});
it('pulls a file removed through deleteFileByFilter', async () => {
const { ids, project, ChatProject } = await seed();
await fileMethods.deleteFileByFilter({ file_id: ids[1] });
const after = await ChatProject.findById(project._id).lean();
expect(after?.file_ids).toEqual([ids[0], 'other']);
});
it('clears the user projects on a user-wide delete without reading the files', async () => {
const { project, untouched, ChatProject } = await seed();
const File = mongoose.models.File as mongoose.Model<IMongoFile>;
const findSpy = jest.spyOn(File, 'find');
await fileMethods.deleteFiles([], project.user);
expect(findSpy).not.toHaveBeenCalled();
findSpy.mockRestore();
const after = await ChatProject.findById(project._id).lean();
expect(after?.file_ids).toEqual([]);
expect(after?.contextRevision).toBe(5);
expect((await ChatProject.findById(untouched._id).lean())?.file_ids).toHaveLength(1);
});
it('still reports a completed delete when the project cleanup fails', async () => {
const { ids, ChatProject } = await seed();
const spy = jest.spyOn(ChatProject, 'updateMany').mockImplementationOnce(() => {
throw new Error('cleanup failed');
});
const deleted = await fileMethods.deleteFile(ids[0]);
spy.mockRestore();
expect(deleted?.file_id).toBe(ids[0]);
});
});
describe('deleteFiles', () => {
it('should delete multiple files by file_ids', async () => {
const userId = new mongoose.Types.ObjectId();
const fileIds = [uuidv4(), uuidv4(), uuidv4()];
for (const fileId of fileIds) {
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: `file-${fileId}.txt`,
filepath: `/uploads/${fileId}.txt`,
type: 'text/plain',
bytes: 100,
});
}
const result = await fileMethods.deleteFiles(fileIds);
expect(result.deletedCount).toBe(3);
const remaining = await fileMethods.getFiles({ file_id: { $in: fileIds } });
expect(remaining).toHaveLength(0);
});
it('should delete all files for a user', async () => {
const userId = new mongoose.Types.ObjectId();
const otherUserId = new mongoose.Types.ObjectId();
await fileMethods.createFile({
file_id: uuidv4(),
user: userId,
filename: 'user-file-1.txt',
filepath: '/uploads/user-file-1.txt',
type: 'text/plain',
bytes: 100,
});
await fileMethods.createFile({
file_id: uuidv4(),
user: userId,
filename: 'user-file-2.txt',
filepath: '/uploads/user-file-2.txt',
type: 'text/plain',
bytes: 100,
});
await fileMethods.createFile({
file_id: uuidv4(),
user: otherUserId,
filename: 'other-user-file.txt',
filepath: '/uploads/other-user-file.txt',
type: 'text/plain',
bytes: 100,
});
const result = await fileMethods.deleteFiles([], userId.toString());
expect(result.deletedCount).toBe(2);
const remaining = await fileMethods.getFiles({});
expect(remaining).toHaveLength(1);
expect(remaining![0].user?.toString()).toBe(otherUserId.toString());
});
});
describe('batchUpdateFiles', () => {
it('should update multiple file paths', async () => {
const userId = new mongoose.Types.ObjectId();
const fileIds = [uuidv4(), uuidv4()];
for (const fileId of fileIds) {
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: `file-${fileId}.txt`,
filepath: `/old-path/${fileId}.txt`,
type: 'text/plain',
bytes: 100,
});
}
const updates = fileIds.map((file_id) => ({
file_id,
filepath: `/new-path/${file_id}.txt`,
}));
await fileMethods.batchUpdateFiles(updates);
for (const fileId of fileIds) {
const file = await fileMethods.findFileById(fileId);
expect(file?.filepath).toBe(`/new-path/${fileId}.txt`);
}
});
it('should persist storage metadata when provided', async () => {
const userId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'region-file.txt',
filepath: '/old-path/file.txt',
type: 'text/plain',
bytes: 100,
});
await fileMethods.batchUpdateFiles([
{
file_id: fileId,
filepath: '/new-path/file.txt',
storageKey: 'i/r/us-east-2/images/user123/file.txt',
storageRegion: 'us-east-2',
},
]);
const file = await fileMethods.findFileById(fileId);
expect(file?.filepath).toBe('/new-path/file.txt');
expect(file?.storageKey).toBe('i/r/us-east-2/images/user123/file.txt');
expect(file?.storageRegion).toBe('us-east-2');
});
it('should not overwrite existing storage metadata when omitted', async () => {
const userId = new mongoose.Types.ObjectId();
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: 'existing-metadata.txt',
filepath: '/old-path/file.txt',
storageKey: 'r/eu-central-1/uploads/user123/file.txt',
storageRegion: 'eu-central-1',
type: 'text/plain',
bytes: 100,
});
await fileMethods.batchUpdateFiles([
{
file_id: fileId,
filepath: '/new-path/file.txt',
},
]);
const file = await fileMethods.findFileById(fileId);
expect(file?.filepath).toBe('/new-path/file.txt');
expect(file?.storageKey).toBe('r/eu-central-1/uploads/user123/file.txt');
expect(file?.storageRegion).toBe('eu-central-1');
});
});
describe('sweepOrphanedPreviews', () => {
/* The deferred-preview flow runs the deferred render in-process. If the
* backend restarts mid-extraction, records stay at `status: 'pending'`
* forever. The boot-time sweep transitions stale ones to 'failed'
* with `previewError: 'orphaned'` so the frontend stops polling. */
const userId = new mongoose.Types.ObjectId();
/**
* Stamp a precise `updatedAt` on a file record. Mongoose timestamps
* insist on the current time during create, so we backdate via a
* direct collection write afterwards.
*/
async function makeFile(opts: {
ageMs: number;
status?: 'pending' | 'ready' | 'failed';
}): Promise<string> {
const fileId = uuidv4();
await fileMethods.createFile({
file_id: fileId,
user: userId,
filename: `${fileId}.xlsx`,
filepath: `/uploads/${fileId}.xlsx`,
type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
bytes: 1024,
...(opts.status ? { status: opts.status } : {}),
});
const backdated = new Date(Date.now() - opts.ageMs);
await File.collection.updateOne({ file_id: fileId }, { $set: { updatedAt: backdated } });
return fileId;
}
it('marks stale pending records as failed with previewError:orphaned', async () => {
const stale = await makeFile({ ageMs: 10 * 60 * 1000, status: 'pending' });
const fresh = await makeFile({ ageMs: 30 * 1000, status: 'pending' });
const count = await fileMethods.sweepOrphanedPreviews();
expect(count).toBe(1);
const staleAfter = (await fileMethods.findFileById(stale)) as {
status?: string;
previewError?: string;
} | null;
expect(staleAfter?.status).toBe('failed');
expect(staleAfter?.previewError).toBe('orphaned');
const freshAfter = (await fileMethods.findFileById(fresh)) as {
status?: string;
} | null;
expect(freshAfter?.status).toBe('pending');
});
it('does not touch records that are already ready or failed (idempotent)', async () => {
const ready = await makeFile({ ageMs: 60 * 60 * 1000, status: 'ready' });
const failed = await makeFile({ ageMs: 60 * 60 * 1000, status: 'failed' });
const count = await fileMethods.sweepOrphanedPreviews();
expect(count).toBe(0);
const readyAfter = (await fileMethods.findFileById(ready)) as { status?: string } | null;
const failedAfter = (await fileMethods.findFileById(failed)) as { status?: string } | null;
expect(readyAfter?.status).toBe('ready');
expect(failedAfter?.status).toBe('failed');
});
it('does not touch legacy records with no status field (back-compat)', async () => {
const legacy = await makeFile({ ageMs: 60 * 60 * 1000 }); // no status set
const count = await fileMethods.sweepOrphanedPreviews();
expect(count).toBe(0);
const after = (await fileMethods.findFileById(legacy)) as { status?: string } | null;
expect(after?.status).toBeUndefined();
});
it('respects a custom maxAgeMs cutoff', async () => {
const old10s = await makeFile({ ageMs: 10 * 1000, status: 'pending' });
const old1m = await makeFile({ ageMs: 60 * 1000, status: 'pending' });
// Cutoff = 30s — only the 60s-old record should be swept.
const count = await fileMethods.sweepOrphanedPreviews(30 * 1000);
expect(count).toBe(1);
const tenSecAfter = (await fileMethods.findFileById(old10s)) as { status?: string } | null;
const oneMinAfter = (await fileMethods.findFileById(old1m)) as {
status?: string;
previewError?: string;
} | null;
expect(tenSecAfter?.status).toBe('pending');
expect(oneMinAfter?.status).toBe('failed');
expect(oneMinAfter?.previewError).toBe('orphaned');
});
it('returns 0 when there are no stale pending records', async () => {
await makeFile({ ageMs: 30 * 1000, status: 'pending' });
const count = await fileMethods.sweepOrphanedPreviews();
expect(count).toBe(0);
});
describe('strict tenant isolation (boot-time recovery)', () => {
afterEach(() => {
delete process.env.TENANT_ISOLATION_STRICT;
_resetStrictCache();
});
it('throws under strict mode without runAsSystem', async () => {
await runAsSystem(() => makeFile({ ageMs: 10 * 60 * 1000, status: 'pending' }));
process.env.TENANT_ISOLATION_STRICT = 'true';
_resetStrictCache();
await expect(fileMethods.sweepOrphanedPreviews()).rejects.toThrow(
/Query attempted without tenant context in strict mode/,
);
});
it('succeeds under strict mode when wrapped in runAsSystem', async () => {
const stale = await runAsSystem(() =>
makeFile({ ageMs: 10 * 60 * 1000, status: 'pending' }),
);
process.env.TENANT_ISOLATION_STRICT = 'true';
_resetStrictCache();
const count = await runAsSystem(() => fileMethods.sweepOrphanedPreviews());
expect(count).toBe(1);
const after = (await runAsSystem(() => fileMethods.findFileById(stale))) as {
status?: string;
previewError?: string;
} | null;
expect(after?.status).toBe('failed');
expect(after?.previewError).toBe('orphaned');
});
});
});
});