🚀 feat: S3 Integration for File handling and Image uploads (#6142)

* French Translation Update

* French Translation Update

* test

* Add fileStrategy S3 Config

* update s3 crud.js

* 🔧 chore: downgrade dotenv to version 16.0.3 and add aws-sdk to package-lock.json

* 🔧 chore: remove aws-sdk from package.json

* 🚀 feat: Integrate AWS SDK for S3 with enhanced upload and retrieval functionalities

* 🚀 feat: Implement S3 integration for file upload and retrieval functionalities

* 🚀 feat: Enhance S3 initialization to support default credentials and improved error handling

---------

Co-authored-by: Gael Martins <gael.martins@acolad.com>

.env.example

@@ -473,6 +473,15 @@ FIREBASE_STORAGE_BUCKET=
 FIREBASE_MESSAGING_SENDER_ID=
 FIREBASE_APP_ID=
 
+#========================#
+# S3 AWS Bucket          #
+#========================#
+
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION=
+AWS_BUCKET_NAME=
+
 #========================#
 # Shared Links           #
 #========================#

api/package.json

@@ -35,6 +35,8 @@
   "homepage": "https://librechat.ai",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.37.0",
+    "@aws-sdk/client-s3": "^3.758.0",
+    "@aws-sdk/s3-request-presigner": "^3.758.0",
     "@azure/search-documents": "^12.0.0",
     "@google/generative-ai": "^0.23.0",
     "@googleapis/youtube": "^20.0.0",

api/server/services/AppService.js

@@ -8,6 +8,7 @@ const {
 const { checkVariables, checkHealth, checkConfig, checkAzureVariables } = require('./start/checks');
 const { azureAssistantsDefaults, assistantsConfigSetup } = require('./start/assistants');
 const { initializeFirebase } = require('./Files/Firebase/initialize');
+const { initializeS3 } = require('./Files/S3/initialize');
 const loadCustomConfig = require('./Config/loadCustomConfig');
 const handleRateLimits = require('./Config/handleRateLimits');
 const { loadDefaultInterface } = require('./start/interface');
@@ -44,6 +45,8 @@ const AppService = async (app) => {
 
   if (fileStrategy === FileSources.firebase) {
     initializeFirebase();
+  } else if (fileStrategy === FileSources.s3) {
+    initializeS3();
   }
 
   /** @type {Record<string, FunctionTool} */

api/server/services/Files/S3/crud.js

@@ -0,0 +1,162 @@
+const fs = require('fs');
+const path = require('path');
+const axios = require('axios');
+const fetch = require('node-fetch');
+const { getBufferMetadata } = require('~/server/utils');
+const { initializeS3 } = require('./initialize');
+const { logger } = require('~/config');
+const { PutObjectCommand, GetObjectCommand, DeleteObjectCommand } = require('@aws-sdk/client-s3');
+const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
+
+const bucketName = process.env.AWS_BUCKET_NAME;
+const s3 = initializeS3();
+const defaultBasePath = 'images';
+
+/**
+ * Constructs the S3 key based on the base path, user ID, and file name.
+ */
+const getS3Key = (basePath, userId, fileName) => `${basePath}/${userId}/${fileName}`;
+
+/**
+ * Uploads a buffer to S3 and returns a signed URL.
+ *
+ * @param {Object} params
+ * @param {string} params.userId - The user's unique identifier.
+ * @param {Buffer} params.buffer - The buffer containing file data.
+ * @param {string} params.fileName - The file name to use in S3.
+ * @param {string} [params.basePath='images'] - The base path in the bucket.
+ * @returns {Promise<string>} Signed URL of the uploaded file.
+ */
+async function saveBufferToS3({ userId, buffer, fileName, basePath = defaultBasePath }) {
+  const key = getS3Key(basePath, userId, fileName);
+  const params = { Bucket: bucketName, Key: key, Body: buffer };
+
+  try {
+    await s3.send(new PutObjectCommand(params));
+    return await getS3URL({ userId, fileName, basePath });
+  } catch (error) {
+    logger.error('[saveBufferToS3] Error uploading buffer to S3:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Retrieves a signed URL for a file stored in S3.
+ *
+ * @param {Object} params
+ * @param {string} params.userId - The user's unique identifier.
+ * @param {string} params.fileName - The file name in S3.
+ * @param {string} [params.basePath='images'] - The base path in the bucket.
+ * @returns {Promise<string>} A signed URL valid for 24 hours.
+ */
+async function getS3URL({ userId, fileName, basePath = defaultBasePath }) {
+  const key = getS3Key(basePath, userId, fileName);
+  const params = { Bucket: bucketName, Key: key };
+
+  try {
+    return await getSignedUrl(s3, new GetObjectCommand(params), { expiresIn: 86400 });
+  } catch (error) {
+    logger.error('[getS3URL] Error getting signed URL from S3:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Saves a file from a given URL to S3.
+ *
+ * @param {Object} params
+ * @param {string} params.userId - The user's unique identifier.
+ * @param {string} params.URL - The source URL of the file.
+ * @param {string} params.fileName - The file name to use in S3.
+ * @param {string} [params.basePath='images'] - The base path in the bucket.
+ * @returns {Promise<string>} Signed URL of the uploaded file.
+ */
+async function saveURLToS3({ userId, URL, fileName, basePath = defaultBasePath }) {
+  try {
+    const response = await fetch(URL);
+    const buffer = await response.buffer();
+    // Optionally you can call getBufferMetadata(buffer) if needed.
+    return await saveBufferToS3({ userId, buffer, fileName, basePath });
+  } catch (error) {
+    logger.error('[saveURLToS3] Error uploading file from URL to S3:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Deletes a file from S3.
+ *
+ * @param {Object} params
+ * @param {string} params.userId - The user's unique identifier.
+ * @param {string} params.fileName - The file name in S3.
+ * @param {string} [params.basePath='images'] - The base path in the bucket.
+ * @returns {Promise<void>}
+ */
+async function deleteFileFromS3({ userId, fileName, basePath = defaultBasePath }) {
+  const key = getS3Key(basePath, userId, fileName);
+  const params = { Bucket: bucketName, Key: key };
+
+  try {
+    await s3.send(new DeleteObjectCommand(params));
+    logger.debug('[deleteFileFromS3] File deleted successfully from S3');
+  } catch (error) {
+    logger.error('[deleteFileFromS3] Error deleting file from S3:', error.message);
+    // If the file is not found, we can safely return.
+    if (error.code === 'NoSuchKey') {
+      return;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Uploads a local file to S3.
+ *
+ * @param {Object} params
+ * @param {import('express').Request} params.req - The Express request (must include user).
+ * @param {Express.Multer.File} params.file - The file object from Multer.
+ * @param {string} params.file_id - Unique file identifier.
+ * @param {string} [params.basePath='images'] - The base path in the bucket.
+ * @returns {Promise<{ filepath: string, bytes: number }>}
+ */
+async function uploadFileToS3({ req, file, file_id, basePath = defaultBasePath }) {
+  try {
+    const inputFilePath = file.path;
+    const inputBuffer = await fs.promises.readFile(inputFilePath);
+    const bytes = Buffer.byteLength(inputBuffer);
+    const userId = req.user.id;
+    const fileName = `${file_id}__${path.basename(inputFilePath)}`;
+    const fileURL = await saveBufferToS3({ userId, buffer: inputBuffer, fileName, basePath });
+    await fs.promises.unlink(inputFilePath);
+    return { filepath: fileURL, bytes };
+  } catch (error) {
+    logger.error('[uploadFileToS3] Error uploading file to S3:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Retrieves a readable stream for a file stored in S3.
+ *
+ * @param {string} filePath - The S3 key of the file.
+ * @returns {Promise<NodeJS.ReadableStream>}
+ */
+async function getS3FileStream(filePath) {
+  const params = { Bucket: bucketName, Key: filePath };
+  try {
+    const data = await s3.send(new GetObjectCommand(params));
+    return data.Body; // Returns a Node.js ReadableStream.
+  } catch (error) {
+    logger.error('[getS3FileStream] Error retrieving S3 file stream:', error.message);
+    throw error;
+  }
+}
+
+module.exports = {
+  saveBufferToS3,
+  saveURLToS3,
+  getS3URL,
+  deleteFileFromS3,
+  uploadFileToS3,
+  getS3FileStream,
+};

api/server/services/Files/S3/images.js

@@ -0,0 +1,118 @@
+const fs = require('fs');
+const path = require('path');
+const sharp = require('sharp');
+const { resizeImageBuffer } = require('../images/resize');
+const { updateUser } = require('~/models/userMethods');
+const { saveBufferToS3 } = require('./crud');
+const { updateFile } = require('~/models/File');
+const { logger } = require('~/config');
+
+const defaultBasePath = 'images';
+
+/**
+ * Resizes, converts, and uploads an image file to S3.
+ *
+ * @param {Object} params
+ * @param {import('express').Request} params.req - Express request (expects user and app.locals.imageOutputType).
+ * @param {Express.Multer.File} params.file - File object from Multer.
+ * @param {string} params.file_id - Unique file identifier.
+ * @param {any} params.endpoint - Endpoint identifier used in image processing.
+ * @param {string} [params.resolution='high'] - Desired image resolution.
+ * @param {string} [params.basePath='images'] - Base path in the bucket.
+ * @returns {Promise<{ filepath: string, bytes: number, width: number, height: number }>}
+ */
+async function uploadImageToS3({
+  req,
+  file,
+  file_id,
+  endpoint,
+  resolution = 'high',
+  basePath = defaultBasePath,
+}) {
+  try {
+    const inputFilePath = file.path;
+    const inputBuffer = await fs.promises.readFile(inputFilePath);
+    const {
+      buffer: resizedBuffer,
+      width,
+      height,
+    } = await resizeImageBuffer(inputBuffer, resolution, endpoint);
+    const extension = path.extname(inputFilePath);
+    const userId = req.user.id;
+
+    let processedBuffer;
+    let fileName = `${file_id}__${path.basename(inputFilePath)}`;
+    const targetExtension = `.${req.app.locals.imageOutputType}`;
+
+    if (extension.toLowerCase() === targetExtension) {
+      processedBuffer = resizedBuffer;
+    } else {
+      processedBuffer = await sharp(resizedBuffer)
+        .toFormat(req.app.locals.imageOutputType)
+        .toBuffer();
+      fileName = fileName.replace(new RegExp(path.extname(fileName) + '$'), targetExtension);
+      if (!path.extname(fileName)) {
+        fileName += targetExtension;
+      }
+    }
+
+    const downloadURL = await saveBufferToS3({
+      userId,
+      buffer: processedBuffer,
+      fileName,
+      basePath,
+    });
+    await fs.promises.unlink(inputFilePath);
+    const bytes = Buffer.byteLength(processedBuffer);
+    return { filepath: downloadURL, bytes, width, height };
+  } catch (error) {
+    logger.error('[uploadImageToS3] Error uploading image to S3:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Updates a file record and returns its signed URL.
+ *
+ * @param {import('express').Request} req - Express request.
+ * @param {Object} file - File metadata.
+ * @returns {Promise<[Promise<any>, string]>}
+ */
+async function prepareImageURLS3(req, file) {
+  try {
+    const updatePromise = updateFile({ file_id: file.file_id });
+    return Promise.all([updatePromise, file.filepath]);
+  } catch (error) {
+    logger.error('[prepareImageURLS3] Error preparing image URL:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Processes a user's avatar image by uploading it to S3 and updating the user's avatar URL if required.
+ *
+ * @param {Object} params
+ * @param {Buffer} params.buffer - Avatar image buffer.
+ * @param {string} params.userId - User's unique identifier.
+ * @param {string} params.manual - 'true' or 'false' flag for manual update.
+ * @param {string} [params.basePath='images'] - Base path in the bucket.
+ * @returns {Promise<string>} Signed URL of the uploaded avatar.
+ */
+async function processS3Avatar({ buffer, userId, manual, basePath = defaultBasePath }) {
+  try {
+    const downloadURL = await saveBufferToS3({ userId, buffer, fileName: 'avatar.png', basePath });
+    if (manual === 'true') {
+      await updateUser(userId, { avatar: downloadURL });
+    }
+    return downloadURL;
+  } catch (error) {
+    logger.error('[processS3Avatar] Error processing S3 avatar:', error.message);
+    throw error;
+  }
+}
+
+module.exports = {
+  uploadImageToS3,
+  prepareImageURLS3,
+  processS3Avatar,
+};

api/server/services/Files/S3/index.js

@@ -0,0 +1,9 @@
+const crud = require('./crud');
+const images = require('./images');
+const initialize = require('./initialize');
+
+module.exports = {
+  ...crud,
+  ...images,
+  ...initialize,
+};

api/server/services/Files/S3/initialize.js

@@ -0,0 +1,43 @@
+const { S3Client } = require('@aws-sdk/client-s3');
+const { logger } = require('~/config');
+
+let s3 = null;
+
+/**
+ * Initializes and returns an instance of the AWS S3 client.
+ *
+ * If AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are provided, they will be used.
+ * Otherwise, the AWS SDK's default credentials chain (including IRSA) is used.
+ *
+ * @returns {S3Client|null} An instance of S3Client if the region is provided; otherwise, null.
+ */
+const initializeS3 = () => {
+  if (s3) {
+    return s3;
+  }
+
+  const region = process.env.AWS_REGION;
+  if (!region) {
+    logger.error('[initializeS3] AWS_REGION is not set. Cannot initialize S3.');
+    return null;
+  }
+
+  const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+
+  if (accessKeyId && secretAccessKey) {
+    s3 = new S3Client({
+      region,
+      credentials: { accessKeyId, secretAccessKey },
+    });
+    logger.info('[initializeS3] S3 initialized with provided credentials.');
+  } else {
+    // When using IRSA, credentials are automatically provided via the IAM Role attached to the ServiceAccount.
+    s3 = new S3Client({ region });
+    logger.info('[initializeS3] S3 initialized using default credentials (IRSA).');
+  }
+
+  return s3;
+};
+
+module.exports = { initializeS3 };

api/server/services/Files/strategies.js

@@ -21,6 +21,17 @@ const {
   processLocalAvatar,
   getLocalFileStream,
 } = require('./Local');
+const {
+  getS3URL,
+  saveURLToS3,
+  saveBufferToS3,
+  getS3FileStream,
+  uploadImageToS3,
+  prepareImageURLS3,
+  deleteFileFromS3,
+  processS3Avatar,
+  uploadFileToS3,
+} = require('./S3');
 const { uploadOpenAIFile, deleteOpenAIFile, getOpenAIFileStream } = require('./OpenAI');
 const { getCodeOutputDownloadStream, uploadCodeEnvFile } = require('./Code');
 const { uploadVectors, deleteVectors } = require('./VectorDB');
@@ -58,6 +69,22 @@ const localStrategy = () => ({
   getDownloadStream: getLocalFileStream,
 });
 
+/**
+ * S3 Storage Strategy Functions
+ *
+ * */
+const s3Strategy = () => ({
+  handleFileUpload: uploadFileToS3,
+  saveURL: saveURLToS3,
+  getFileURL: getS3URL,
+  deleteFile: deleteFileFromS3,
+  saveBuffer: saveBufferToS3,
+  prepareImagePayload: prepareImageURLS3,
+  processAvatar: processS3Avatar,
+  handleImageUpload: uploadImageToS3,
+  getDownloadStream: getS3FileStream,
+});
+
 /**
  * VectorDB Storage Strategy Functions
  *
@@ -160,6 +187,8 @@ const getStrategyFunctions = (fileSource) => {
     return openAIStrategy();
   } else if (fileSource === FileSources.vectordb) {
     return vectorStrategy();
+  } else if (fileSource === FileSources.s3) {
+    return s3Strategy();
   } else if (fileSource === FileSources.execute_code) {
     return codeOutputStrategy();
   } else if (fileSource === FileSources.mistral_ocr) {

librechat.example.yaml

@@ -7,6 +7,9 @@ version: 1.2.1
 # Cache settings: Set to true to enable caching
 cache: true
 
+# File strategy s3/firebase
+# fileStrategy: "s3"
+
 # Custom interface configuration
 interface:
   customWelcome: "Welcome to LibreChat! Enjoy your experience."