Skip to content

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

🧾 feat: Add Skill Upload Reservation Helpers (#17041)

Dustin Healy6279dd3ccf86
diff --git a/.github/workflows/docker-smoke.yml b/.github/workflows/docker-smoke.yml
index 811d500a13..dccc8c80c4 100644
--- a/.github/workflows/docker-smoke.yml
+++ b/.github/workflows/docker-smoke.yml
@@ -208,7 +208,7 @@ jobs:
- name: Verify production image resolves all runtime modules
run: |
docker run --rm librechat-api-smoke:ci \
- node -e "require('@librechat/api'); require('@librechat/api/telemetry'); console.log('module resolution OK')"
+ node -e "const api = require('@librechat/api'); require('@librechat/api/telemetry'); for (const name of ['withSkillUploadIntent', 'reserveSkillBlob', 'createSkillBlobReserver', 'createSkillStorageResolver', 'createSkillBufferWriter']) { if (typeof api[name] !== 'function') throw new Error('Missing Skill upload helper: ' + name); } console.log('module resolution and Skill exports OK')"
# Boot the real entrypoint against a real MongoDB so the *entire* server
# require graph loads (api/db throws at module scope without MONGO_URI, and
diff --git a/packages/api/src/skills/index.ts b/packages/api/src/skills/index.ts
index 4de0b7c6ab..1d7ad05a4e 100644
--- a/packages/api/src/skills/index.ts
+++ b/packages/api/src/skills/index.ts
@@ -11,3 +11,5 @@ export * from './sync';
export * from './management';
export * from './upload';
export * from './save';
+export * from './intent';
+export * from './reservation';
diff --git a/packages/api/src/skills/intent.spec.ts b/packages/api/src/skills/intent.spec.ts
new file mode 100644
index 0000000000..0b46a2b68a
--- /dev/null
+++ b/packages/api/src/skills/intent.spec.ts
@@ -0,0 +1,307 @@
+import { FileSources } from 'librechat-data-provider';
+import type { SkillUploadIntentDeps, SkillUploadOperation } from './intent';
+import { withSkillUploadIntent } from './intent';
+import { reserveSkillBlob } from './reservation';
+
+function makeDeps(): jest.Mocked<SkillUploadIntentDeps> {
+ return {
+ reserveSkillUploadIntent: jest.fn(async (input) => ({ fileId: input.fileId })),
+ transitionSkillUploadIntent: jest.fn(async (_fileId, _writerId, _from, _to) => true),
+ };
+}
+
+function makeOperation(): SkillUploadOperation<string> {
+ return {
+ skillId: '507f1f77bcf86cd799439011',
+ author: '507f1f77bcf86cd799439012',
+ fileId: 'file-1',
+ source: 'local',
+ reservation: {
+ source: 'local',
+ filepath: '/uploads/owner/file-1',
+ writeLocation: { userId: 'owner', fileName: 'file-1', basePath: 'uploads' },
+ },
+ save: jest.fn(async () => '/uploads/owner/file-1'),
+ persist: jest.fn(async () => 'saved'),
+ readPersisted: jest.fn(async () => null),
+ deleteReserved: jest.fn(async () => undefined),
+ };
+}
+
+it('persists intent before writing bytes and acknowledges only after row commit', async () => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ await expect(withSkillUploadIntent(deps, operation)).resolves.toBe('saved');
+ expect(deps.reserveSkillUploadIntent.mock.invocationCallOrder[0]).toBeLessThan(
+ (operation.save as jest.Mock).mock.invocationCallOrder[0],
+ );
+ expect(deps.transitionSkillUploadIntent.mock.invocationCallOrder[1]).toBeGreaterThan(
+ (operation.persist as jest.Mock).mock.invocationCallOrder[0],
+ );
+});
+
+it('rejects a provider mismatch before journaling or writing bytes', async () => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.source = FileSources.s3;
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow(
+ 'Skill upload source differs from its reserved provider',
+ );
+ expect(deps.reserveSkillUploadIntent).not.toHaveBeenCalled();
+ expect(operation.save).not.toHaveBeenCalled();
+});
+
+it('persists the canonical provider key instead of a public URL', async () => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.reservation = {
+ source: 's3',
+ filepath: 'https://cdn.example.test/uploads/owner/file-1?signature=old',
+ storageKey: 'uploads/owner/file-1',
+ writeLocation: { userId: 'owner', fileName: 'file-1', basePath: 'uploads' },
+ };
+ operation.source = FileSources.s3;
+ operation.save = jest.fn(
+ async () => 'https://cdn.example.test/uploads/owner/file-1?signature=new',
+ );
+ await withSkillUploadIntent(deps, operation);
+ expect(deps.reserveSkillUploadIntent).toHaveBeenCalledWith(
+ expect.objectContaining({ storageKey: 'uploads/owner/file-1' }),
+ );
+});
+
+it('journals the regional object key and compensates a mismatched provider result before persistence', async () => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.reservation = await reserveSkillBlob({
+ source: FileSources.s3,
+ userId: 'owner',
+ fileName: 'file-1',
+ tenantId: 'tenant-a',
+ storageRegion: 'us-east-1',
+ includeRegionInPath: true,
+ getFileURL: async () =>
+ 'https://cdn.example.test/r/us-east-1/t/tenant-a/uploads/owner/file-1?old=signature',
+ });
+ operation.source = FileSources.s3;
+ operation.save = jest.fn(
+ async () =>
+ 'https://cdn.example.test/r/eu-west-1/t/tenant-a/uploads/owner/file-1?new=signature',
+ );
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow(
+ 'Skill storage wrote outside its reserved location',
+ );
+ expect(deps.reserveSkillUploadIntent).toHaveBeenCalledWith(
+ expect.objectContaining({ storageKey: operation.reservation.storageKey }),
+ );
+ expect(operation.persist).not.toHaveBeenCalled();
+ expect(operation.deleteReserved).toHaveBeenCalledWith(
+ operation.reservation,
+ 'https://cdn.example.test/r/eu-west-1/t/tenant-a/uploads/owner/file-1?new=signature',
+ );
+});
+
+it('retains the actual regional key for stopped-writer cleanup after bytes were written', async () => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.reservation = await reserveSkillBlob({
+ source: FileSources.cloudfront,
+ userId: 'owner',
+ fileName: 'file-1',
+ tenantId: 'tenant-a',
+ storageRegion: 'us-east-1',
+ includeRegionInPath: true,
+ getFileURL: async () => 'https://cdn.example.test/r/us-east-1/t/tenant-a/uploads/owner/file-1',
+ });
+ operation.source = FileSources.cloudfront;
+ operation.save = jest.fn(
+ async () =>
+ 'https://cdn.example.test/r/us-east-1/t/tenant-a/uploads/owner/file-1?signature=refreshed',
+ );
+ operation.persist = jest.fn(async () => {
+ throw new Error('database unavailable');
+ });
+ operation.deleteReserved = jest.fn(async () => {
+ throw new Error('storage unavailable');
+ });
+
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow('database unavailable');
+ expect(deps.reserveSkillUploadIntent).toHaveBeenCalledWith(
+ expect.objectContaining({
+ storageKey: 'r/us-east-1/t/tenant-a/uploads/owner/file-1',
+ }),
+ );
+ expect(operation.deleteReserved).toHaveBeenCalledWith(
+ operation.reservation,
+ expect.stringContaining('/r/us-east-1/t/tenant-a/uploads/owner/file-1'),
+ );
+ // A stopped writer leaves the pre-written canonical key in the durable intent.
+ expect(deps.reserveSkillUploadIntent).toHaveBeenCalledTimes(1);
+});
+
+it('keeps an abandoned intent even when immediate compensation succeeds', async () => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.save = jest.fn(async () => {
+ throw new Error('provider timeout');
+ });
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow('provider timeout');
+ expect(deps.transitionSkillUploadIntent).toHaveBeenCalledWith(
+ 'file-1',
+ expect.any(String),
+ 'uploading',
+ 'abandoned',
+ );
+ expect(operation.deleteReserved).toHaveBeenCalled();
+});
+
+it.each([null, '', ' '])('compensates a storage write with no usable path (%p)', async (path) => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.save = jest.fn(async () => path as string);
+
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow(
+ 'Skill storage returned no saved object path',
+ );
+ expect(operation.persist).not.toHaveBeenCalled();
+ expect(operation.deleteReserved).toHaveBeenCalledWith(operation.reservation, undefined);
+});
+
+it.each(['uploading', 'committing'] as const)(
+ 'compensates the reserved blob even when the %s abandonment update throws',
+ async (failedState) => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.save = jest.fn(async () => {
+ throw new Error('provider timeout');
+ });
+ deps.transitionSkillUploadIntent.mockImplementation(async (_fileId, _writerId, from, to) => {
+ if (from === failedState && to === 'abandoned') throw new Error('database unavailable');
+ return true;
+ });
+
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow('provider timeout');
+ expect(deps.transitionSkillUploadIntent).toHaveBeenCalledWith(
+ 'file-1',
+ expect.any(String),
+ 'uploading',
+ 'abandoned',
+ );
+ expect(deps.transitionSkillUploadIntent).toHaveBeenCalledWith(
+ 'file-1',
+ expect.any(String),
+ 'committing',
+ 'abandoned',
+ );
+ expect(operation.deleteReserved).toHaveBeenCalledWith(operation.reservation, undefined);
+ },
+);
+
+it('preserves the original failure for stopped-writer recovery if journal and cleanup both fail', async () => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.save = jest.fn(async () => {
+ throw new Error('provider timeout');
+ });
+ deps.transitionSkillUploadIntent.mockRejectedValue(new Error('database unavailable'));
+ operation.deleteReserved = jest.fn(async () => {
+ throw new Error('storage unavailable');
+ });
+
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow('provider timeout');
+ expect(deps.reserveSkillUploadIntent).toHaveBeenCalledTimes(1);
+ expect(deps.transitionSkillUploadIntent).toHaveBeenCalledTimes(3);
+ expect(operation.deleteReserved).toHaveBeenCalledTimes(1);
+ // The intent is intentionally retained. If both stores stay unavailable,
+ // an operator must recover the stopped writer before background cleanup.
+});
+
+it.each(['save', 'first transition'] as const)(
+ 'compensates a %s failure without reading persistence that was never attempted',
+ async (failurePoint) => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.readPersisted = jest.fn(async () => {
+ throw new Error('database unavailable');
+ });
+ if (failurePoint === 'save') {
+ operation.save = jest.fn(async () => {
+ throw new Error('provider timeout');
+ });
+ } else {
+ deps.transitionSkillUploadIntent.mockRejectedValueOnce(new Error('database unavailable'));
+ }
+
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow(
+ failurePoint === 'save' ? 'provider timeout' : 'database unavailable',
+ );
+ expect(operation.persist).not.toHaveBeenCalled();
+ expect(operation.readPersisted).not.toHaveBeenCalled();
+ expect(operation.deleteReserved).toHaveBeenCalledTimes(1);
+ },
+);
+
+it.each(['missing', 'replaced'] as const)(
+ 'abandons an acknowledged commit after the original row is %s and cleanup fails',
+ async (rowState) => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ let intentState = 'uploading';
+ deps.transitionSkillUploadIntent.mockImplementation(async (_fileId, _writerId, from, to) => {
+ if (intentState !== from) return intentState === to;
+ intentState = to;
+ if (from === 'committing' && to === 'committed') {
+ throw new Error('commit reply lost');
+ }
+ return true;
+ });
+ operation.readPersisted = jest.fn(async () => {
+ const row = rowState === 'replaced' ? { fileId: 'replacement' } : null;
+ return row?.fileId === operation.fileId ? 'saved' : null;
+ });
+ operation.deleteReserved = jest.fn(async () => {
+ throw new Error('storage unavailable');
+ });
+
+ await expect(withSkillUploadIntent(deps, operation)).rejects.toThrow('commit reply lost');
+ expect(intentState).toBe('abandoned');
+ expect(deps.transitionSkillUploadIntent).toHaveBeenCalledWith(
+ operation.fileId,
+ expect.any(String),
+ 'committed',
+ 'abandoned',
+ );
+ expect(operation.deleteReserved).toHaveBeenCalledTimes(1);
+ },
+);
+
+it('returns the persisted row after an ambiguous database commit', async () => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.persist = jest.fn(async () => {
+ throw new Error('lost database reply');
+ });
+ operation.readPersisted = jest.fn(async () => 'recovered');
+ await expect(withSkillUploadIntent(deps, operation)).resolves.toBe('recovered');
+ expect(operation.deleteReserved).not.toHaveBeenCalled();
+});
+
+it.each(['acknowledgement rejected', 'reply lost'] as const)(
+ 'returns a persisted upload after recovering %s',
+ async (scenario) => {
+ const deps = makeDeps();
+ const operation = makeOperation();
+ operation.readPersisted = jest.fn(async () => 'saved');
+ deps.transitionSkillUploadIntent.mockResolvedValueOnce(true);
+ if (scenario === 'reply lost') {
+ deps.transitionSkillUploadIntent.mockRejectedValueOnce(new Error('lost acknowledgement'));
+ } else {
+ deps.transitionSkillUploadIntent.mockResolvedValueOnce(false);
+ }
+ deps.transitionSkillUploadIntent.mockResolvedValueOnce(true);
+
+ await expect(withSkillUploadIntent(deps, operation)).resolves.toBe('saved');
+ expect(deps.transitionSkillUploadIntent).toHaveBeenCalledTimes(3);
+ expect(operation.deleteReserved).not.toHaveBeenCalled();
+ },
+);
diff --git a/packages/api/src/skills/intent.ts b/packages/api/src/skills/intent.ts
new file mode 100644
index 0000000000..5726c3391a
--- /dev/null
+++ b/packages/api/src/skills/intent.ts
@@ -0,0 +1,125 @@
+import { randomUUID } from 'node:crypto';
+import type { SkillBlobReservation } from './reservation';
+import { assertSavedSkillBlobMatchesReservation } from './reservation';
+
+type ReserveInput = {
+ skillId: string;
+ author: string;
+ fileId: string;
+ source: string;
+ storageKey: string;
+ tenantId?: string;
+ writerId: string;
+};
+
+export interface SkillUploadIntentDeps {
+ reserveSkillUploadIntent: (input: ReserveInput) => Promise<{ fileId: string }>;
+ transitionSkillUploadIntent: (
+ fileId: string,
+ writerId: string,
+ from: 'uploading' | 'committing' | 'committed' | 'abandoned',
+ to: 'uploading' | 'committing' | 'committed' | 'abandoned',
+ ) => Promise<boolean>;
+}
+
+export interface SkillUploadOperation<T> {
+ skillId: string;
+ author: string;
+ tenantId?: string;
+ fileId: string;
+ source: string;
+ reservation: SkillBlobReservation;
+ save: () => Promise<string>;
+ persist: (filepath: string) => Promise<T>;
+ readPersisted: () => Promise<T | null>;
+ deleteReserved: (reservation: SkillBlobReservation, savedPath?: string) => Promise<void>;
+}
+
+/** Persist the future object location before bytes can reach external storage. */
+export async function withSkillUploadIntent<T>(
+ deps: SkillUploadIntentDeps,
+ operation: SkillUploadOperation<T>,
+): Promise<T> {
+ if (operation.source !== operation.reservation.source) {
+ throw new Error('Skill upload source differs from its reserved provider');
+ }
+ const writerId = randomUUID();
+ await deps.reserveSkillUploadIntent({
+ skillId: operation.skillId,
+ author: operation.author,
+ tenantId: operation.tenantId,
+ fileId: operation.fileId,
+ source: operation.source,
+ storageKey: operation.reservation.storageKey ?? operation.reservation.filepath,
+ writerId,
+ });
+ let savedPath: string | undefined;
+ let persistedResult: { value: T } | undefined;
+ let persistStarted = false;
+ try {
+ const filepath = await operation.save();
+ if (typeof filepath !== 'string' || filepath.trim().length === 0) {
+ throw new Error('Skill storage returned no saved object path');
+ }
+ savedPath = filepath;
+ assertSavedSkillBlobMatchesReservation(operation.reservation, filepath);
+ const claimed = await deps.transitionSkillUploadIntent(
+ operation.fileId,
+ writerId,
+ 'uploading',
+ 'committing',
+ );
+ if (!claimed) {
+ throw Object.assign(new Error('Skill upload was cancelled'), { code: 'SKILL_DELETING' });
+ }
+ persistStarted = true;
+ persistedResult = { value: await operation.persist(filepath) };
+ const committed = await deps.transitionSkillUploadIntent(
+ operation.fileId,
+ writerId,
+ 'committing',
+ 'committed',
+ );
+ if (!committed) throw new Error('Skill upload commit acknowledgement failed');
+ return persistedResult.value;
+ } catch (error) {
+ let persisted: T | null = null;
+ if (persistStarted) {
+ try {
+ persisted = await operation.readPersisted();
+ } catch {
+ // An attempted database write may have succeeded despite its error.
+ // Do not delete a blob that may now belong to a live file row.
+ throw error;
+ }
+ }
+ if (persisted !== null) {
+ const committed = await deps.transitionSkillUploadIntent(
+ operation.fileId,
+ writerId,
+ 'committing',
+ 'committed',
+ );
+ if (committed) return persistedResult ? persistedResult.value : persisted;
+ throw error;
+ }
+ // A transient journal error must not skip immediate blob compensation.
+ // The final commit acknowledgement may have succeeded in Mongo before
+ // its reply was lost, so include that state once the row is known absent.
+ // If both journal updates and compensation fail, the reserved intent still
+ // supports explicit stopped-writer recovery once the database is healthy.
+ for (const from of ['uploading', 'committing', 'committed'] as const) {
+ try {
+ await deps.transitionSkillUploadIntent(operation.fileId, writerId, from, 'abandoned');
+ } catch {
+ // Preserve the original upload failure after attempting both states.
+ }
+ }
+ try {
+ await operation.deleteReserved(operation.reservation, savedPath);
+ } catch {
+ // The abandoned intent remains durable for the reconciler.
+ }
+ throw error;
+ }
+}
diff --git a/packages/api/src/skills/publicExports.spec.ts b/packages/api/src/skills/publicExports.spec.ts
new file mode 100644
index 0000000000..de13f26af4
--- /dev/null
+++ b/packages/api/src/skills/publicExports.spec.ts
@@ -0,0 +1,9 @@
+import * as skillExports from './index';
+
+it('exports Skill upload helpers from the source barrel without a package build', () => {
+ expect(typeof skillExports.withSkillUploadIntent).toBe('function');
+ expect(typeof skillExports.reserveSkillBlob).toBe('function');
+ expect(typeof skillExports.createSkillBlobReserver).toBe('function');
+ expect(typeof skillExports.createSkillStorageResolver).toBe('function');
+ expect(typeof skillExports.createSkillBufferWriter).toBe('function');
+});
diff --git a/packages/api/src/skills/reservation.spec.ts b/packages/api/src/skills/reservation.spec.ts
new file mode 100644
index 0000000000..ea09f71f22
--- /dev/null
+++ b/packages/api/src/skills/reservation.spec.ts
@@ -0,0 +1,311 @@
+import { FileContext, FileSources } from 'librechat-data-provider';
+import {
+ assertSavedSkillBlobMatchesReservation,
+ createSkillBlobReserver,
+ createSkillBufferWriter,
+ createSkillStorageResolver,
+ reserveSkillBlob,
+} from './reservation';
+import { extractFirebaseBlobPath } from '~/storage/ownedBlobDelete';
+import { getS3Key } from '~/storage/s3/crud';
+
+describe('Skill blob reservation', () => {
+ it('reserves local and Firebase owner-scoped paths before upload', async () => {
+ await expect(
+ reserveSkillBlob({ source: FileSources.local, userId: 'owner', fileName: 'id__note.md' }),
+ ).resolves.toMatchObject({ filepath: '/uploads/owner/id__note.md' });
+ const firebase = await reserveSkillBlob({
+ source: FileSources.firebase,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ });
+ expect(extractFirebaseBlobPath(firebase.filepath)).toBe('uploads/owner/id__note.md');
+ });
+
+ it.each([FileSources.s3, FileSources.cloudfront, FileSources.azure_blob])(
+ 'uses the provider future-URL resolver for %s',
+ async (source) => {
+ const getFileURL = jest.fn(async () =>
+ source === FileSources.azure_blob
+ ? 'https://example.invalid/container/uploads/owner/id__note.md'
+ : 'https://example.invalid/t/tenant-a/uploads/owner/id__note.md',
+ );
+ const reserved = await reserveSkillBlob({
+ source,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ tenantId: 'tenant-a',
+ getFileURL,
+ });
+ expect(getFileURL).toHaveBeenCalledWith({
+ userId: 'owner',
+ fileName: 'id__note.md',
+ basePath: 'uploads',
+ tenantId: 'tenant-a',
+ storageRegion: undefined,
+ includeRegionInPath: undefined,
+ useInlinePath: undefined,
+ });
+ expect(reserved.filepath).toContain('/uploads/owner/id__note.md');
+ },
+ );
+
+ it('fails closed for unsupported storage', async () => {
+ await expect(
+ reserveSkillBlob({ source: FileSources.openai, userId: 'owner', fileName: 'id__note.md' }),
+ ).rejects.toThrow('Unsupported Skill storage strategy');
+ });
+
+ it('selects a Skill provider from config and requires save and delete capabilities', async () => {
+ const getFileStrategy = jest.fn(() => FileSources.local);
+ let canDelete = true;
+ const getStrategyFunctions = jest.fn(() => ({
+ saveBuffer: jest.fn(),
+ deleteFile: canDelete ? jest.fn() : undefined,
+ }));
+ const reserve = createSkillBlobReserver({ getFileStrategy, getStrategyFunctions });
+ await expect(
+ reserve(Promise.resolve({ fileStrategy: FileSources.local }), {
+ userId: 'owner',
+ fileName: 'id__note.md',
+ isImage: false,
+ }),
+ ).resolves.toMatchObject({ source: FileSources.local, filepath: '/uploads/owner/id__note.md' });
+ expect(getFileStrategy).toHaveBeenCalledWith(
+ { fileStrategy: FileSources.local },
+ { context: FileContext.skill_file, isImage: false },
+ );
+ canDelete = false;
+ await expect(
+ reserve(
+ { fileStrategy: FileSources.local },
+ {
+ userId: 'owner',
+ fileName: 'id__note.md',
+ isImage: false,
+ },
+ ),
+ ).rejects.toThrow('Skill storage cannot guarantee cleanup');
+ });
+
+ it('rejects truthy non-function cleanup capabilities before reserving or writing', async () => {
+ const getStrategyFunctions = () => ({
+ saveBuffer: jest.fn(async () => '/uploads/owner/file-1'),
+ deleteFile: true,
+ });
+ const resolve = createSkillStorageResolver({
+ getFileStrategy: () => FileSources.local,
+ getStrategyFunctions,
+ });
+ expect(() => resolve({}, { isImage: false })).toThrow('Skill storage cannot guarantee cleanup');
+
+ const write = createSkillBufferWriter({ getStrategyFunctions });
+ const reservation = await reserveSkillBlob({
+ source: FileSources.local,
+ userId: 'owner',
+ fileName: 'file-1',
+ });
+ await expect(
+ write({
+ reservation,
+ buffer: Buffer.from('content'),
+ }),
+ ).rejects.toThrow('Skill storage cannot guarantee cleanup');
+ });
+
+ it('writes to the reserved provider when live config changes before upload', async () => {
+ const localSave = jest.fn(async () => '/uploads/owner/id__note.md');
+ const firebaseSave = jest.fn(async () => 'https://firebase.invalid/o/other');
+ const getFileStrategy = jest.fn(() => FileSources.local);
+ const getStrategyFunctions = jest.fn((source: string) => ({
+ saveBuffer: source === FileSources.local ? localSave : firebaseSave,
+ deleteFile: jest.fn(),
+ }));
+ const resolve = createSkillStorageResolver({ getFileStrategy, getStrategyFunctions });
+ const selected = resolve({}, { isImage: false });
+ getFileStrategy.mockReturnValue(FileSources.firebase);
+ const write = createSkillBufferWriter({ getStrategyFunctions });
+ const reservation = await reserveSkillBlob({
+ source: selected.source,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ });
+
+ await expect(
+ write({
+ reservation,
+ buffer: Buffer.from('note'),
+ }),
+ ).resolves.toMatchObject({
+ source: FileSources.local,
+ filepath: '/uploads/owner/id__note.md',
+ });
+ expect(localSave).toHaveBeenCalledTimes(1);
+ expect(firebaseSave).not.toHaveBeenCalled();
+ expect(getFileStrategy).toHaveBeenCalledTimes(1);
+ });
+
+ it('writes to the reserved uploads path without accepting a second location', async () => {
+ const saveBuffer = jest.fn(async () => '/uploads/owner/id__note.md');
+ const write = createSkillBufferWriter({
+ getStrategyFunctions: () => ({ saveBuffer, deleteFile: jest.fn() }),
+ });
+ const reservation = await reserveSkillBlob({
+ source: FileSources.local,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ });
+ await write({
+ reservation,
+ buffer: Buffer.from('note'),
+ });
+ expect(saveBuffer).toHaveBeenCalledWith(
+ expect.objectContaining({ basePath: 'uploads', userId: 'owner', fileName: 'id__note.md' }),
+ );
+ });
+
+ it.each([FileSources.s3, FileSources.cloudfront])(
+ 'freezes the %s provider key across region-config changes',
+ async (source) => {
+ let configRegion = 'us-east-1';
+ let includeRegion = true;
+ const getFileURL = jest.fn(async (params) => {
+ const key = getS3Key({
+ ...params,
+ storageRegion: params.storageRegion ?? configRegion,
+ includeRegionInPath: params.includeRegionInPath ?? includeRegion,
+ useInlinePath: params.useInlinePath ?? false,
+ });
+ return `https://cdn.example.test/${key}?signature=reserved`;
+ });
+ const saveBuffer = jest.fn(async (params) => {
+ const key = getS3Key({
+ ...params,
+ storageRegion: params.storageRegion ?? configRegion,
+ includeRegionInPath: params.includeRegionInPath ?? includeRegion,
+ useInlinePath: params.useInlinePath ?? false,
+ });
+ return `https://cdn.example.test/${key}?signature=saved`;
+ });
+ const reservation = await reserveSkillBlob({
+ source,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ tenantId: 'tenant-a',
+ getFileURL,
+ });
+ expect(reservation.storageKey).toBe('r/us-east-1/t/tenant-a/uploads/owner/id__note.md');
+ expect(Object.isFrozen(reservation.writeLocation)).toBe(true);
+ configRegion = 'eu-west-1';
+ includeRegion = false;
+ const write = createSkillBufferWriter({
+ getStrategyFunctions: () => ({ saveBuffer, deleteFile: jest.fn() }),
+ });
+ const saved = await write({ reservation, buffer: Buffer.from('note') });
+ assertSavedSkillBlobMatchesReservation(reservation, saved.filepath);
+ expect(saved.storageKey).toBe(reservation.storageKey);
+ expect(saveBuffer).toHaveBeenCalledWith(
+ expect.objectContaining({
+ basePath: 'uploads',
+ tenantId: 'tenant-a',
+ storageRegion: 'us-east-1',
+ includeRegionInPath: true,
+ useInlinePath: false,
+ }),
+ );
+ },
+ );
+
+ it('keeps the default S3 key unprefixed despite a later regional default', async () => {
+ const reservation = await reserveSkillBlob({
+ source: FileSources.s3,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ getFileURL: async () => 'https://s3.example.test/uploads/owner/id__note.md',
+ });
+ expect(reservation.writeLocation).toMatchObject({
+ includeRegionInPath: false,
+ useInlinePath: false,
+ });
+ expect(reservation.storageKey).toBe('uploads/owner/id__note.md');
+ });
+
+ it.each([FileSources.local, FileSources.firebase, FileSources.azure_blob])(
+ 'matches the reserved %s object after a provider write',
+ async (source) => {
+ const reservation = await reserveSkillBlob({
+ source,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ getFileURL: async () => 'https://azure.example.test/files/uploads/owner/id__note.md',
+ });
+ const saveBuffer = jest.fn(async ({ userId, fileName, basePath }) => {
+ if (source === FileSources.local) return `/${basePath}/${userId}/${fileName}`;
+ if (source === FileSources.firebase) {
+ return `https://firebase.example.test/o/${encodeURIComponent(`${basePath}/${userId}/${fileName}`)}?token=new`;
+ }
+ return `https://azure.example.test/files/${basePath}/${userId}/${fileName}`;
+ });
+ const write = createSkillBufferWriter({
+ getStrategyFunctions: () => ({ saveBuffer, deleteFile: jest.fn() }),
+ });
+ const saved = await write({ reservation, buffer: Buffer.from('note') });
+ expect(() =>
+ assertSavedSkillBlobMatchesReservation(reservation, saved.filepath),
+ ).not.toThrow();
+ expect(saveBuffer).toHaveBeenCalledWith(expect.objectContaining(reservation.writeLocation));
+ },
+ );
+
+ it('rejects unsupported inline uploads and ambiguous provider keys before writing bytes', async () => {
+ const getFileURL = jest.fn(async (params) => {
+ const key = getS3Key({ ...params, useInlinePath: params.useInlinePath });
+ return `https://cdn.example.test/${key}`;
+ });
+ await expect(
+ reserveSkillBlob({
+ source: FileSources.cloudfront,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ useInlinePath: true,
+ getFileURL,
+ }),
+ ).rejects.toThrow('inline path is not supported');
+ await expect(
+ reserveSkillBlob({
+ source: FileSources.s3,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ getFileURL: async () => 'https://cdn.example.test/t/wrong/uploads/owner/id__note.md',
+ }),
+ ).rejects.toThrow('different reserved object');
+ });
+
+ it('rejects an Azure write to another account or container with the same relative path', async () => {
+ const reservation = await reserveSkillBlob({
+ source: FileSources.azure_blob,
+ userId: 'owner',
+ fileName: 'id__note.md',
+ getFileURL: async () =>
+ 'https://account-a.example.test/files/uploads/owner/id__note.md?reserved=signature',
+ });
+ expect(() =>
+ assertSavedSkillBlobMatchesReservation(
+ reservation,
+ 'https://account-b.example.test/files/uploads/owner/id__note.md',
+ ),
+ ).toThrow('outside its reserved location');
+ expect(() =>
+ assertSavedSkillBlobMatchesReservation(
+ reservation,
+ 'https://account-a.example.test/other/uploads/owner/id__note.md',
+ ),
+ ).toThrow('outside its reserved location');
+ expect(() =>
+ assertSavedSkillBlobMatchesReservation(
+ reservation,
+ 'https://account-a.example.test/files/uploads/owner/id__note.md?saved=signature',
+ ),
+ ).not.toThrow();
+ });
+});
diff --git a/packages/api/src/skills/reservation.ts b/packages/api/src/skills/reservation.ts
new file mode 100644
index 0000000000..d5f612291e
--- /dev/null
+++ b/packages/api/src/skills/reservation.ts
@@ -0,0 +1,238 @@
+import { FileContext, FileSources } from 'librechat-data-provider';
+import type { SaveBufferParams } from '~/storage/types';
+import { extractKeyFromS3Url, getS3Key, parseS3Key } from '~/storage/s3/crud';
+import { extractFirebaseBlobPath } from '~/storage/ownedBlobDelete';
+import { getStorageMetadata } from '~/storage/metadata';
+
+type FutureURL = (params: {
+ userId: string;
+ fileName: string;
+ basePath: 'uploads';
+ tenantId?: string;
+ storageRegion?: string | null;
+ includeRegionInPath?: boolean;
+ useInlinePath?: boolean;
+}) => Promise<string>;
+type WriteLocation = Omit<SaveBufferParams, 'buffer'> & { basePath: 'uploads' };
+
+export interface SkillBlobReservation {
+ readonly source: string;
+ readonly filepath: string;
+ readonly storageKey?: string;
+ readonly storageRegion?: string;
+ readonly writeLocation: Readonly<WriteLocation>;
+}
+
+type SkillStorageStrategy = {
+ saveBuffer?: (params: SaveBufferParams) => Promise<string>;
+ deleteFile?: unknown;
+ getFileURL?: FutureURL | null;
+};
+
+type ResolvedSkillStorage = {
+ source: string;
+ saveBuffer: (params: SaveBufferParams) => Promise<string>;
+ getFileURL?: FutureURL | null;
+};
+
+type SavedSkillBuffer = {
+ filepath: string;
+ source: string;
+ storageKey?: string;
+ storageRegion?: string;
+};
+
+function freezeReservation(reservation: SkillBlobReservation): SkillBlobReservation {
+ return Object.freeze({
+ ...reservation,
+ writeLocation: Object.freeze({ ...reservation.writeLocation }),
+ });
+}
+
+/** Select and validate one Skill store; callers keep its writer for this upload. */
+export function createSkillStorageResolver<TConfig>(deps: {
+ getFileStrategy: (config: TConfig, options: { context: FileContext; isImage: boolean }) => string;
+ getStrategyFunctions: (source: string) => SkillStorageStrategy;
+}): (config: TConfig, options: { isImage: boolean }) => ResolvedSkillStorage {
+ return (config: TConfig, options: { isImage: boolean }) => {
+ const source = deps.getFileStrategy(config, {
+ context: FileContext.skill_file,
+ isImage: options.isImage,
+ });
+ const strategy = deps.getStrategyFunctions(source);
+ if (typeof strategy.saveBuffer !== 'function' || typeof strategy.deleteFile !== 'function') {
+ throw new Error('Skill storage cannot guarantee cleanup');
+ }
+ return { source, saveBuffer: strategy.saveBuffer, getFileURL: strategy.getFileURL };
+ };
+}
+
+/** Write with the already-reserved provider, even if live configuration changes. */
+export function createSkillBufferWriter(deps: {
+ getStrategyFunctions: (source: string) => SkillStorageStrategy;
+}): (params: { reservation: SkillBlobReservation; buffer: Buffer }) => Promise<SavedSkillBuffer> {
+ return async ({ reservation, buffer }) => {
+ const strategy = deps.getStrategyFunctions(reservation.source);
+ if (typeof strategy.saveBuffer !== 'function' || typeof strategy.deleteFile !== 'function') {
+ throw new Error('Skill storage cannot guarantee cleanup');
+ }
+ const filepath = await strategy.saveBuffer({ ...reservation.writeLocation, buffer });
+ return {
+ filepath,
+ source: reservation.source,
+ ...getStorageMetadata({ filepath, source: reservation.source }),
+ };
+ };
+}
+
+/** Compare provider object identities while ignoring expiring URL signatures. */
+export function assertSavedSkillBlobMatchesReservation(
+ reservation: SkillBlobReservation,
+ savedPath: string,
+): void {
+ let matches = false;
+ try {
+ if (reservation.source === FileSources.s3 || reservation.source === FileSources.cloudfront) {
+ matches = extractKeyFromS3Url(savedPath) === reservation.storageKey;
+ } else if (reservation.source === FileSources.firebase) {
+ matches =
+ extractFirebaseBlobPath(savedPath) === extractFirebaseBlobPath(reservation.filepath);
+ } else if (reservation.source === FileSources.azure_blob) {
+ const savedURL = new URL(savedPath);
+ const reservedURL = new URL(reservation.filepath);
+ matches =
+ savedURL.origin === reservedURL.origin && savedURL.pathname === reservedURL.pathname;
+ } else {
+ matches = savedPath === reservation.filepath;
+ }
+ } catch {
+ // A malformed provider result is not proof that the journal names its object.
+ }
+ if (!matches) throw new Error('Skill storage wrote outside its reserved location');
+}
+
+/**
+ * All supported Skill stores can name the future object before writing it.
+ * This reference goes into Mongo first, closing the upload-before-row gap.
+ */
+export async function reserveSkillBlob(params: {
+ source: string;
+ userId: string;
+ fileName: string;
+ tenantId?: string;
+ storageRegion?: string | null;
+ includeRegionInPath?: boolean;
+ useInlinePath?: boolean;
+ getFileURL?: FutureURL | null;
+}): Promise<SkillBlobReservation> {
+ const {
+ source,
+ userId,
+ fileName,
+ tenantId,
+ storageRegion,
+ includeRegionInPath,
+ useInlinePath,
+ getFileURL,
+ } = params;
+ if (!userId || !fileName || fileName.includes('/') || fileName.includes('\\')) {
+ throw new Error('Invalid Skill storage identity');
+ }
+ const writeLocation: WriteLocation = { userId, fileName, basePath: 'uploads', tenantId };
+ if (source === FileSources.local) {
+ return freezeReservation({ source, filepath: `/uploads/${userId}/${fileName}`, writeLocation });
+ }
+ if (source === FileSources.firebase) {
+ const key = `uploads/${userId}/${fileName}`;
+ return freezeReservation({
+ source,
+ filepath: `https://firebase.invalid/o/${encodeURIComponent(key)}`,
+ writeLocation,
+ });
+ }
+ if (
+ source !== FileSources.s3 &&
+ source !== FileSources.cloudfront &&
+ source !== FileSources.azure_blob
+ ) {
+ throw new Error('Unsupported Skill storage strategy');
+ }
+ if (!getFileURL) throw new Error('Skill storage strategy cannot reserve an object');
+ const filepath = await getFileURL({
+ userId,
+ fileName,
+ basePath: 'uploads',
+ tenantId,
+ storageRegion,
+ includeRegionInPath,
+ useInlinePath,
+ });
+ if (!filepath) throw new Error('Skill storage strategy returned no reserved object');
+ if (source === FileSources.azure_blob) {
+ const path = new URL(filepath).pathname.split('/').map(decodeURIComponent);
+ if (path.slice(-3).join('/') !== `uploads/${userId}/${fileName}`) {
+ throw new Error('Skill storage strategy returned a different reserved object');
+ }
+ return freezeReservation({ source, filepath, writeLocation });
+ }
+ const key = extractKeyFromS3Url(filepath);
+ const parsed = parseS3Key(key);
+ if (
+ !parsed ||
+ parsed.basePath !== 'uploads' ||
+ parsed.userId !== userId ||
+ parsed.fileName !== fileName ||
+ (parsed.tenantId ?? undefined) !== tenantId ||
+ parsed.useInlinePath
+ ) {
+ throw new Error('Skill storage strategy returned a different reserved object');
+ }
+ const plannedLocation: WriteLocation = {
+ ...writeLocation,
+ storageRegion: parsed.storageRegion,
+ includeRegionInPath: Boolean(parsed.storageRegion),
+ useInlinePath: false,
+ };
+ if (getS3Key(plannedLocation) !== key) {
+ throw new Error('Skill storage strategy returned an ambiguous reserved object');
+ }
+ return freezeReservation({
+ source,
+ filepath,
+ storageKey: key,
+ storageRegion: parsed.storageRegion,
+ writeLocation: plannedLocation,
+ });
+}
+
+/** Selects and validates the provider before reserving a future Skill object. */
+export function createSkillBlobReserver<TConfig>(deps: {
+ getFileStrategy: (config: TConfig, options: { context: FileContext; isImage: boolean }) => string;
+ getStrategyFunctions: (source: string) => SkillStorageStrategy;
+}) {
+ const resolveStorage = createSkillStorageResolver(deps);
+ return async (
+ config: TConfig | Promise<TConfig>,
+ params: {
+ userId: string;
+ fileName: string;
+ isImage: boolean;
+ tenantId?: string;
+ storageRegion?: string | null;
+ includeRegionInPath?: boolean;
+ useInlinePath?: boolean;
+ },
+ ): Promise<SkillBlobReservation> => {
+ const { source, getFileURL } = resolveStorage(await config, params);
+ return reserveSkillBlob({
+ source,
+ userId: params.userId,
+ fileName: params.fileName,
+ tenantId: params.tenantId,
+ storageRegion: params.storageRegion,
+ includeRegionInPath: params.includeRegionInPath,
+ useInlinePath: params.useInlinePath,
+ getFileURL,
+ });
+ };
+}