@xenterprises/fastify-xstorage 1.0.0

package/server/app.js

@@ -0,0 +1,136 @@
+// server/app.js
+import Fastify from "fastify";
+import multipart from "@fastify/multipart";
+import xStorage from "../src/xStorage.js";
+
+const fastify = Fastify({
+  logger: true,
+});
+
+// xStorage is a library of methods, not a server with routes
+// The routes below are EXAMPLES of how to use the fastify.xStorage methods
+// You can implement your own routes or use xStorage methods directly in your application
+
+// Register multipart for file uploads
+await fastify.register(multipart, {
+  limits: {
+    fileSize: 10 * 1024 * 1024, // 10MB
+  },
+});
+
+// Register xStorage
+await fastify.register(xStorage, {
+  endpoint: process.env.STORAGE_ENDPOINT,
+  region: process.env.STORAGE_REGION,
+  accessKeyId: process.env.STORAGE_ACCESS_KEY_ID,
+  secretAccessKey: process.env.STORAGE_SECRET_ACCESS_KEY,
+  bucket: process.env.STORAGE_BUCKET,
+  publicUrl: process.env.STORAGE_PUBLIC_URL,
+  forcePathStyle: true,
+  // Default ACL is "private" - use signed URLs for secure access
+  // acl: "private", // Uncomment to override default
+});
+
+// Basic file upload endpoint
+fastify.post("/upload", async (request, reply) => {
+  const data = await request.file();
+
+  if (!data) {
+    return reply.code(400).send({ error: "No file uploaded" });
+  }
+
+  const buffer = await data.toBuffer();
+
+  const result = await fastify.xStorage.upload(buffer, data.filename, {
+    folder: "uploads",
+  });
+
+  return {
+    success: true,
+    file: result,
+  };
+});
+
+// For image processing, use @xenterprises/fastify-ximagepipeline
+// Example:
+// import xImagePipeline from "@xenterprises/fastify-ximagepipeline";
+// await fastify.register(xImagePipeline, { r2, db, ... });
+
+// Multiple file upload
+fastify.post("/upload/multiple", async (request, reply) => {
+  const parts = request.parts();
+  const files = [];
+
+  for await (const part of parts) {
+    if (part.type === "file") {
+      const buffer = await part.toBuffer();
+      files.push({
+        file: buffer,
+        filename: part.filename,
+      });
+    }
+  }
+
+  const results = await fastify.xStorage.uploadMultiple(files, {
+    folder: "uploads",
+  });
+
+  return {
+    success: true,
+    files: results,
+  };
+});
+
+// List files
+fastify.get("/files", async (request, reply) => {
+  const { folder = "" } = request.query;
+
+  const files = await fastify.xStorage.list(folder);
+
+  return {
+    success: true,
+    files,
+  };
+});
+
+// Delete file
+fastify.delete("/files/:key", async (request, reply) => {
+  const { key } = request.params;
+
+  await fastify.xStorage.delete(key);
+
+  return {
+    success: true,
+    message: "File deleted successfully",
+  };
+});
+
+// Get signed URL
+fastify.get("/files/:key/signed-url", async (request, reply) => {
+  const { key } = request.params;
+  const { expires = 3600 } = request.query;
+
+  const url = await fastify.xStorage.getSignedUrl(key, Number(expires));
+
+  return {
+    success: true,
+    url,
+  };
+});
+
+// Health check
+fastify.get("/health", async () => {
+  return { status: "ok", timestamp: new Date().toISOString() };
+});
+
+// Start server
+const start = async () => {
+  try {
+    await fastify.listen({ port: process.env.PORT || 3000, host: "0.0.0.0" });
+  } catch (err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+};
+
+start();

package/src/index.js

@@ -0,0 +1,9 @@
+// src/index.js
+
+/**
+ * Main exports for xStorage plugin
+ */
+
+export { default } from "./xStorage.js";
+export { default as xStorage } from "./xStorage.js";
+export * as helpers from "./utils/helpers.js";

package/src/services/storage.js

@@ -0,0 +1,352 @@
+// src/services/storage.js
+import {
+  PutObjectCommand,
+  GetObjectCommand,
+  DeleteObjectCommand,
+  ListObjectsV2Command,
+  CopyObjectCommand,
+  HeadObjectCommand,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { lookup } from "mime-types";
+import { randomBytes } from "crypto";
+import path from "path";
+
+export function getStorageMethods(fastify, config) {
+  const { s3Client, bucket, publicUrl, acl } = config;
+
+  return {
+    /**
+     * Upload a file to S3-compatible storage
+     * @param {Buffer|Stream} file - File buffer or stream
+     * @param {string} filename - Original filename
+     * @param {object} options - Upload options
+     * @returns {Promise<{key: string, url: string, size: number, contentType: string}>}
+     */
+    upload: async (file, filename, options = {}) => {
+      try {
+        const {
+          folder = "",
+          key = null,
+          contentType = null,
+          metadata = {},
+          useRandomName = true,
+          acl: fileAcl = acl, // Allow per-file ACL override
+        } = options;
+
+        // Generate file key
+        let fileKey;
+        if (key) {
+          fileKey = key;
+        } else {
+          const ext = path.extname(filename);
+          const baseName = path.basename(filename, ext);
+          const randomName = useRandomName
+            ? `${baseName}-${randomBytes(8).toString("hex")}${ext}`
+            : filename;
+          fileKey = folder ? `${folder}/${randomName}` : randomName;
+        }
+
+        // Determine content type
+        const mimeType = contentType || lookup(filename) || "application/octet-stream";
+
+        // Upload to S3 with per-file ACL
+        const command = new PutObjectCommand({
+          Bucket: bucket,
+          Key: fileKey,
+          Body: file,
+          ContentType: mimeType,
+          ACL: fileAcl,
+          Metadata: metadata,
+        });
+
+        await s3Client.send(command);
+
+        // Get file size
+        const fileSize = Buffer.isBuffer(file) ? file.length : null;
+
+        const result = {
+          key: fileKey,
+          url: `${publicUrl}/${fileKey}`,
+          size: fileSize,
+          contentType: mimeType,
+          bucket,
+        };
+
+        fastify.log.info(`File uploaded: ${fileKey}`);
+        return result;
+      } catch (error) {
+        fastify.log.error("Storage upload failed:", error);
+        throw new Error(`Failed to upload file: ${error.message}`);
+      }
+    },
+
+    /**
+     * Upload multiple files
+     * @param {Array<{file: Buffer, filename: string}>} files - Array of files
+     * @param {object} options - Upload options
+     * @returns {Promise<Array>}
+     */
+    uploadMultiple: async (files, options = {}) => {
+      try {
+        const {
+          folder = "",
+          key = null,
+          contentType = null,
+          metadata = {},
+          useRandomName = true,
+          acl: batchAcl = acl, // Allow batch ACL override
+        } = options;
+
+        const uploadPromises = files.map((fileData) => {
+          // Determine per-file ACL (file can override batch ACL)
+          const fileAcl = fileData.acl || batchAcl;
+
+          // Generate file key
+          let fileKey;
+          if (key) {
+            fileKey = key;
+          } else {
+            const ext = path.extname(fileData.filename);
+            const baseName = path.basename(fileData.filename, ext);
+            const randomName = useRandomName
+              ? `${baseName}-${randomBytes(8).toString("hex")}${ext}`
+              : fileData.filename;
+            fileKey = folder ? `${folder}/${randomName}` : randomName;
+          }
+
+          // Determine content type
+          const mimeType = contentType || lookup(fileData.filename) || "application/octet-stream";
+
+          // Upload to S3 with per-file ACL support
+          const command = new PutObjectCommand({
+            Bucket: bucket,
+            Key: fileKey,
+            Body: fileData.file,
+            ContentType: mimeType,
+            ACL: fileAcl,
+            Metadata: metadata,
+          });
+
+          return s3Client.send(command).then(() => {
+            const fileSize = Buffer.isBuffer(fileData.file) ? fileData.file.length : null;
+            return {
+              key: fileKey,
+              url: `${publicUrl}/${fileKey}`,
+              size: fileSize,
+              contentType: mimeType,
+              bucket,
+            };
+          });
+        });
+
+        const results = await Promise.all(uploadPromises);
+        fastify.log.info(`${results.length} files uploaded successfully`);
+        return results;
+      } catch (error) {
+        fastify.log.error("Multiple upload failed:", error);
+        throw new Error(`Failed to upload multiple files: ${error.message}`);
+      }
+    },
+
+    /**
+     * Download a file from storage
+     * @param {string} key - File key
+     * @returns {Promise<Buffer>}
+     */
+    download: async (key) => {
+      try {
+        const command = new GetObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+
+        const response = await s3Client.send(command);
+        const chunks = [];
+
+        for await (const chunk of response.Body) {
+          chunks.push(chunk);
+        }
+
+        return Buffer.concat(chunks);
+      } catch (error) {
+        fastify.log.error("Storage download failed:", error);
+        throw new Error(`Failed to download file: ${error.message}`);
+      }
+    },
+
+    /**
+     * Delete a file from storage
+     * @param {string} key - File key
+     * @returns {Promise<boolean>}
+     */
+    delete: async (key) => {
+      try {
+        const command = new DeleteObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+
+        await s3Client.send(command);
+        fastify.log.info(`File deleted: ${key}`);
+        return true;
+      } catch (error) {
+        fastify.log.error("Storage delete failed:", error);
+        throw new Error(`Failed to delete file: ${error.message}`);
+      }
+    },
+
+    /**
+     * Delete multiple files
+     * @param {Array<string>} keys - Array of file keys
+     * @returns {Promise<boolean>}
+     */
+    deleteMultiple: async (keys) => {
+      try {
+        const deletePromises = keys.map((key) => fastify.storage.delete(key));
+        await Promise.all(deletePromises);
+        return true;
+      } catch (error) {
+        fastify.log.error("Multiple delete failed:", error);
+        throw new Error(`Failed to delete multiple files: ${error.message}`);
+      }
+    },
+
+    /**
+     * Copy a file within storage
+     * @param {string} sourceKey - Source file key
+     * @param {string} destinationKey - Destination file key
+     * @returns {Promise<{key: string, url: string}>}
+     */
+    copy: async (sourceKey, destinationKey) => {
+      try {
+        const command = new CopyObjectCommand({
+          Bucket: bucket,
+          CopySource: `${bucket}/${sourceKey}`,
+          Key: destinationKey,
+          ACL: acl,
+        });
+
+        await s3Client.send(command);
+
+        return {
+          key: destinationKey,
+          url: `${publicUrl}/${destinationKey}`,
+        };
+      } catch (error) {
+        fastify.log.error("Storage copy failed:", error);
+        throw new Error(`Failed to copy file: ${error.message}`);
+      }
+    },
+
+    /**
+     * Check if a file exists
+     * @param {string} key - File key
+     * @returns {Promise<boolean>}
+     */
+    exists: async (key) => {
+      try {
+        const command = new HeadObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+
+        await s3Client.send(command);
+        return true;
+      } catch (error) {
+        if (error.name === "NotFound") {
+          return false;
+        }
+        throw error;
+      }
+    },
+
+    /**
+     * Get file metadata
+     * @param {string} key - File key
+     * @returns {Promise<object>}
+     */
+    getMetadata: async (key) => {
+      try {
+        const command = new HeadObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+
+        const response = await s3Client.send(command);
+
+        return {
+          contentType: response.ContentType,
+          contentLength: response.ContentLength,
+          lastModified: response.LastModified,
+          etag: response.ETag,
+          metadata: response.Metadata,
+        };
+      } catch (error) {
+        fastify.log.error("Get metadata failed:", error);
+        throw new Error(`Failed to get file metadata: ${error.message}`);
+      }
+    },
+
+    /**
+     * List files in a folder
+     * @param {string} prefix - Folder prefix
+     * @param {number} maxKeys - Maximum number of keys to return
+     * @returns {Promise<Array>}
+     */
+    list: async (prefix = "", maxKeys = 1000) => {
+      try {
+        const command = new ListObjectsV2Command({
+          Bucket: bucket,
+          Prefix: prefix,
+          MaxKeys: maxKeys,
+        });
+
+        const response = await s3Client.send(command);
+
+        return (
+          response.Contents?.map((item) => ({
+            key: item.Key,
+            url: `${publicUrl}/${item.Key}`,
+            size: item.Size,
+            lastModified: item.LastModified,
+            etag: item.ETag,
+          })) || []
+        );
+      } catch (error) {
+        fastify.log.error("Storage list failed:", error);
+        throw new Error(`Failed to list files: ${error.message}`);
+      }
+    },
+
+    /**
+     * Generate a pre-signed URL for temporary access
+     * @param {string} key - File key
+     * @param {number} expiresIn - Expiration time in seconds (default: 1 hour)
+     * @returns {Promise<string>}
+     */
+    getSignedUrl: async (key, expiresIn = 3600) => {
+      try {
+        const command = new GetObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+
+        const url = await getSignedUrl(s3Client, command, { expiresIn });
+        return url;
+      } catch (error) {
+        fastify.log.error("Generate signed URL failed:", error);
+        throw new Error(`Failed to generate signed URL: ${error.message}`);
+      }
+    },
+
+    /**
+     * Get public URL for a file
+     * @param {string} key - File key
+     * @returns {string}
+     */
+    getPublicUrl: (key) => {
+      return `${publicUrl}/${key}`;
+    },
+  };
+}