@xenterprises/fastify-xstorage 1.0.0

package/TESTING.md

@@ -0,0 +1,567 @@
+# Testing Guide
+
+Complete guide for testing xStorage plugin locally and in production.
+
+## Local Development Setup
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Setup Storage Provider
+
+Choose one of the following:
+
+#### Digital Ocean Spaces
+
+1. Create a Space at https://cloud.digitalocean.com/spaces
+2. Create API keys at https://cloud.digitalocean.com/account/api/tokens
+3. Configure CORS (allow your domain)
+4. Set permissions to public-read
+
+#### AWS S3
+
+1. Create S3 bucket at https://console.aws.amazon.com/s3
+2. Create IAM user with S3 permissions
+3. Configure bucket policy for public access
+4. Enable CORS
+
+#### Cloudflare R2
+
+1. Create R2 bucket at https://dash.cloudflare.com/r2
+2. Create API token
+3. Set up custom domain
+4. Configure CORS
+
+### 3. Configure Environment
+
+Create `.env` file:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your credentials:
+
+```bash
+STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com
+STORAGE_REGION=us-east-1
+STORAGE_ACCESS_KEY_ID=your_key
+STORAGE_SECRET_ACCESS_KEY=your_secret
+STORAGE_BUCKET=your-bucket
+STORAGE_PUBLIC_URL=https://your-bucket.nyc3.digitaloceanspaces.com
+PORT=3000
+```
+
+### 4. Start Development Server
+
+```bash
+npm run dev
+```
+
+## Manual Testing
+
+### Test File Upload
+
+```bash
+# Upload a file
+curl -X POST http://localhost:3000/upload \
+  -F "file=@./test-image.jpg"
+
+# Response:
+{
+  "success": true,
+  "file": {
+    "key": "uploads/test-image-a1b2c3d4.jpg",
+    "url": "https://your-bucket.nyc3.digitaloceanspaces.com/uploads/test-image-a1b2c3d4.jpg",
+    "size": 245678,
+    "contentType": "image/jpeg"
+  }
+}
+```
+
+### Test Image Upload with Thumbnails
+
+```bash
+curl -X POST http://localhost:3000/upload/image \
+  -F "file=@./photo.jpg"
+
+# Response includes original + thumbnails
+{
+  "success": true,
+  "image": {
+    "original": {
+      "url": "https://.../images/photo.webp",
+      "width": 1920,
+      "height": 1080
+    },
+    "thumbnails": [
+      {
+        "size": "small",
+        "url": "https://.../thumbnails/photo-small.webp",
+        "width": 150,
+        "height": 150
+      }
+    ]
+  }
+}
+```
+
+### Test PDF Upload
+
+```bash
+curl -X POST http://localhost:3000/upload/pdf \
+  -F "file=@./document.pdf"
+
+# Response:
+{
+  "success": true,
+  "pdf": {
+    "key": "pdfs/document-a1b2c3d4.pdf",
+    "url": "https://.../pdfs/document-a1b2c3d4.pdf",
+    "size": 456789,
+    "pageCount": 12
+  }
+}
+```
+
+### Test Multiple Files
+
+```bash
+curl -X POST http://localhost:3000/upload/multiple \
+  -F "file1=@./photo1.jpg" \
+  -F "file2=@./photo2.jpg" \
+  -F "file3=@./photo3.jpg"
+```
+
+### List Files
+
+```bash
+curl http://localhost:3000/files?folder=uploads
+
+# Response:
+{
+  "success": true,
+  "files": [
+    {
+      "key": "uploads/photo1.jpg",
+      "url": "https://.../uploads/photo1.jpg",
+      "size": 123456,
+      "lastModified": "2024-01-15T10:30:00.000Z"
+    }
+  ]
+}
+```
+
+### Delete File
+
+```bash
+curl -X DELETE "http://localhost:3000/files/uploads%2Fphoto1.jpg"
+```
+
+### Get Signed URL
+
+```bash
+curl "http://localhost:3000/files/uploads%2Fphoto1.jpg/signed-url?expires=3600"
+
+# Response:
+{
+  "success": true,
+  "url": "https://...?X-Amz-Signature=..."
+}
+```
+
+## Unit Testing
+
+Create `test/storage.test.js`:
+
+```javascript
+import { test } from "node:test";
+import assert from "node:assert";
+import Fastify from "fastify";
+import xStorage from "../src/xStorage.js";
+import fs from "fs";
+
+test("Storage plugin registration", async () => {
+  const fastify = Fastify();
+
+  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,
+  });
+
+  assert.ok(fastify.storage);
+  assert.ok(fastify.images);
+  assert.ok(fastify.pdfs);
+});
+
+test("Upload file", async () => {
+  const fastify = Fastify();
+
+  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,
+  });
+
+  const buffer = Buffer.from("test content");
+  const result = await fastify.storage.upload(buffer, "test.txt", {
+    folder: "test",
+  });
+
+  assert.ok(result.key);
+  assert.ok(result.url);
+  assert.equal(result.contentType, "text/plain");
+
+  // Cleanup
+  await fastify.storage.delete(result.key);
+});
+
+test("Upload and generate thumbnails", async () => {
+  const fastify = Fastify();
+
+  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,
+  });
+
+  const imageBuffer = fs.readFileSync("./test-image.jpg");
+
+  const result = await fastify.images.uploadWithThumbnails(imageBuffer, "test.jpg", {
+    imageOptions: { folder: "test/images" },
+    thumbnailOptions: {
+      folder: "test/thumbnails",
+      sizes: [{ name: "small", width: 150, height: 150 }],
+    },
+  });
+
+  assert.ok(result.original.url);
+  assert.equal(result.thumbnails.length, 1);
+  assert.equal(result.thumbnails[0].size, "small");
+  assert.equal(result.thumbnails[0].width, 150);
+
+  // Cleanup
+  await fastify.storage.delete(result.original.key);
+  await fastify.storage.delete(result.thumbnails[0].key);
+});
+
+test("PDF upload and metadata", async () => {
+  const fastify = Fastify();
+
+  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,
+  });
+
+  const pdfBuffer = fs.readFileSync("./test-document.pdf");
+
+  const result = await fastify.pdfs.upload(pdfBuffer, "test.pdf", {
+    folder: "test/pdfs",
+  });
+
+  assert.ok(result.url);
+  assert.ok(result.pageCount > 0);
+
+  // Cleanup
+  await fastify.storage.delete(result.key);
+});
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+## Integration Testing
+
+Create `test/integration.test.js`:
+
+```javascript
+import { test } from "node:test";
+import assert from "node:assert";
+import Fastify from "fastify";
+import multipart from "@fastify/multipart";
+import xStorage from "../src/xStorage.js";
+import FormData from "form-data";
+import fs from "fs";
+
+test("End-to-end file upload", async () => {
+  const fastify = Fastify();
+
+  await fastify.register(multipart);
+  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,
+  });
+
+  fastify.post("/upload", async (request) => {
+    const data = await request.file();
+    const buffer = await data.toBuffer();
+
+    return await fastify.storage.upload(buffer, data.filename, {
+      folder: "test",
+    });
+  });
+
+  await fastify.listen({ port: 0 });
+
+  const form = new FormData();
+  form.append("file", fs.createReadStream("./test-image.jpg"));
+
+  const response = await fastify.inject({
+    method: "POST",
+    url: "/upload",
+    headers: form.getHeaders(),
+    payload: form,
+  });
+
+  assert.equal(response.statusCode, 200);
+
+  const result = JSON.parse(response.payload);
+  assert.ok(result.url);
+  assert.ok(result.key);
+
+  // Cleanup
+  await fastify.storage.delete(result.key);
+  await fastify.close();
+});
+```
+
+## Testing Helpers
+
+Create `test/helpers.test.js`:
+
+```javascript
+import { test } from "node:test";
+import assert from "node:assert";
+import { helpers } from "../src/index.js";
+
+test("formatFileSize", () => {
+  assert.equal(helpers.formatFileSize(0), "0 Bytes");
+  assert.equal(helpers.formatFileSize(1024), "1 KB");
+  assert.equal(helpers.formatFileSize(1048576), "1 MB");
+  assert.equal(helpers.formatFileSize(1073741824), "1 GB");
+});
+
+test("isImage", () => {
+  assert.equal(helpers.isImage("photo.jpg"), true);
+  assert.equal(helpers.isImage("photo.png"), true);
+  assert.equal(helpers.isImage("photo.webp"), true);
+  assert.equal(helpers.isImage("document.pdf"), false);
+});
+
+test("isPdf", () => {
+  assert.equal(helpers.isPdf("document.pdf"), true);
+  assert.equal(helpers.isPdf("photo.jpg"), false);
+});
+
+test("sanitizeFilename", () => {
+  assert.equal(helpers.sanitizeFilename("My File (2024).jpg"), "my_file_2024.jpg");
+  assert.equal(helpers.sanitizeFilename("Test@#$%.txt"), "test____.txt");
+});
+
+test("calculateFitDimensions", () => {
+  const result = helpers.calculateFitDimensions(4000, 3000, 1920, 1080);
+  assert.equal(result.width, 1440);
+  assert.equal(result.height, 1080);
+});
+```
+
+## Performance Testing
+
+Test upload performance with larger files:
+
+```javascript
+import { test } from "node:test";
+import Fastify from "fastify";
+import xStorage from "../src/xStorage.js";
+
+test("Upload large file performance", async () => {
+  const fastify = Fastify();
+
+  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,
+  });
+
+  // Create 10MB buffer
+  const largeBuffer = Buffer.alloc(10 * 1024 * 1024);
+
+  const start = Date.now();
+  const result = await fastify.storage.upload(largeBuffer, "large-file.bin", {
+    folder: "test",
+  });
+  const duration = Date.now() - start;
+
+  console.log(`Upload took ${duration}ms`);
+
+  // Cleanup
+  await fastify.storage.delete(result.key);
+});
+```
+
+## Production Testing
+
+### 1. Test in Staging Environment
+
+Deploy to staging with production-like configuration:
+
+```bash
+# staging.env
+STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com
+STORAGE_REGION=us-east-1
+STORAGE_ACCESS_KEY_ID=staging_key
+STORAGE_SECRET_ACCESS_KEY=staging_secret
+STORAGE_BUCKET=staging-bucket
+STORAGE_PUBLIC_URL=https://staging-bucket.nyc3.digitaloceanspaces.com
+```
+
+### 2. Monitor Uploads
+
+Check logs for errors:
+
+```bash
+# Check Fastify logs
+tail -f logs/app.log | grep "Storage"
+
+# Look for:
+# - Upload failures
+# - Slow uploads
+# - Invalid file types
+# - Permission errors
+```
+
+### 3. Verify Public URLs
+
+Test that uploaded files are accessible:
+
+```bash
+# Upload file
+curl -X POST https://staging.example.com/upload \
+  -F "file=@./test.jpg"
+
+# Get URL from response
+# Visit URL in browser to verify it works
+```
+
+### 4. Test CORS
+
+Verify CORS is configured correctly:
+
+```bash
+curl -H "Origin: https://your-domain.com" \
+  -H "Access-Control-Request-Method: GET" \
+  -H "Access-Control-Request-Headers: Content-Type" \
+  -X OPTIONS \
+  https://your-bucket.nyc3.digitaloceanspaces.com/test.jpg
+```
+
+### 5. Load Testing
+
+Use tools like `autocannon` for load testing:
+
+```bash
+npm install -g autocannon
+
+# Test upload endpoint
+autocannon -c 10 -d 30 \
+  -m POST \
+  -H "Content-Type: multipart/form-data" \
+  http://localhost:3000/upload
+```
+
+## Common Issues
+
+### Issue: Signature Mismatch
+
+**Cause**: Incorrect credentials or endpoint
+
+**Fix**:
+```bash
+# Verify credentials
+echo $STORAGE_ACCESS_KEY_ID
+echo $STORAGE_SECRET_ACCESS_KEY
+
+# Check endpoint format
+# Correct: https://nyc3.digitaloceanspaces.com
+# Wrong: https://nyc3.digitaloceanspaces.com/
+```
+
+### Issue: Access Denied
+
+**Cause**: Bucket permissions or ACL
+
+**Fix**:
+- Check bucket is public or has correct ACL
+- Verify IAM user has `s3:PutObject` permission
+- Check CORS configuration
+
+### Issue: File Not Found
+
+**Cause**: Incorrect public URL or key
+
+**Fix**:
+```javascript
+// Ensure publicUrl doesn't have trailing slash
+publicUrl: "https://bucket.nyc3.digitaloceanspaces.com" // ✓
+publicUrl: "https://bucket.nyc3.digitaloceanspaces.com/" // ✗
+
+// Verify key format
+const url = fastify.storage.getPublicUrl(key);
+console.log(url); // Should be valid URL
+```
+
+### Issue: Sharp Installation Error
+
+**Cause**: Platform-specific binary issues
+
+**Fix**:
+```bash
+# Rebuild sharp
+npm rebuild sharp
+
+# Or install with specific platform
+npm install --platform=linux --arch=x64 sharp
+```
+
+## Best Practices
+
+1. **Use test bucket** - Never test with production bucket
+2. **Clean up test files** - Delete uploaded files after tests
+3. **Test all file types** - Images, PDFs, documents, etc.
+4. **Test error cases** - Invalid files, large files, etc.
+5. **Monitor logs** - Check for warnings and errors
+6. **Test CORS** - Verify cross-origin access works
+7. **Load test** - Ensure performance under load
+8. **Test URLs** - Verify all generated URLs are accessible
+
+## Next Steps
+
+- See [README.md](./README.md) for API documentation
+- See [EXAMPLES.md](./EXAMPLES.md) for real-world examples

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@xenterprises/fastify-xstorage",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Fastify plugin for S3-compatible storage with simple, intuitive API. Supports AWS S3, Cloudflare R2, Digital Ocean Spaces and any S3-compatible provider.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./helpers": "./src/utils/helpers.js"
+  },
+  "scripts": {
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/storage.test.js"
+  },
+  "keywords": [
+    "fastify",
+    "s3",
+    "storage",
+    "upload",
+    "download",
+    "file",
+    "spaces",
+    "r2",
+    "cloudflare",
+    "digitalocean",
+    "aws"
+  ],
+  "author": "Tim Mushen",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.com:x-enterprises/fastify-plugins/fastify-x-storage.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-storage/-/issues"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "fastify-plugin": "^5.0.0",
+    "mime-types": "^2.1.35"
+  },
+  "devDependencies": {
+    "@fastify/multipart": "^9.0.0",
+    "fastify": "^5.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  }
+}