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
🧾 feat: Add Skill Upload Reservation Helpers (#17041)
Dustin Healy6279dd3ccf86
diff --git a/.github/workflows/docker-smoke.yml b/.github/workflows/docker-smoke.ymlindex 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 modulesrun: |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, anddiff --git a/packages/api/src/skills/index.ts b/packages/api/src/skills/index.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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,+ });+ };+}