Skip to main content
Version: 0.5.0 (Previous)

💾 File Storage Drivers

File storage drivers provide a consistent interface for secure file operations in NodeBlocks applications. They abstract cloud storage provider configurations and operations, allowing you to use different storage services without changing your business logic.

🎯 Overview​

File storage drivers in NodeBlocks are factory functions that create configured storage instances with signed URL capabilities. They provide:

  • Secure file operations with signed URLs for upload, download, and deletion
  • Consistent interface across different cloud storage providers
  • Simple configuration with project IDs and bucket names
  • Testing support with mock implementations

📋 Available File Storage Drivers​

Google Cloud Storage Driver​

The Google Cloud Storage driver creates a configured file storage instance with signed URL generation capabilities.

Prerequisites​

To use this driver, authenticate the Google Cloud SDK client by providing Application Default Credentials:

  • Create a Google Cloud service account with permissions to access your bucket
  • Download a service account JSON key file.
  • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the absolute path of the JSON key file.

The driver relies on Google Cloud Application Default Credentials; no credentials are passed directly to createFileStorageDriver.

createFileStorageDriver​

Creates a Google Cloud Storage file storage driver with signed URL capabilities.

Parameters:

  • projectId: string - Google Cloud project identifier
  • bucketName: string - Storage bucket name for file operations
  • options?: object - Optional configuration
    • signedUrlExpiresInSeconds?: number - Default URL validity duration in seconds (default: 900)

Returns: FileStorageDriver - File storage driver with signed URL generation methods

Usage:

import { createFileStorageDriver } from '@nodeblocks/backend-sdk/drivers';

const fileStorage = await createFileStorageDriver(
  'my-project-id',
  'my-storage-bucket'
);

Example with Custom Expiry:

import { createFileStorageDriver } from '@nodeblocks/backend-sdk/drivers';

const fileStorage = await createFileStorageDriver(
  'my-project-id',
  'my-storage-bucket',
  { signedUrlExpiresInSeconds: 1800 } // 30 minutes
);

🔧 File Storage Driver Methods​

generateSignedUploadUrl​

Generates a signed URL for secure file uploads to cloud storage.

Parameters:

  • contentType: string - MIME type of file to upload
  • contentLength: number - Maximum file size in bytes
  • objectName: string - Storage object name/path for upload

Returns: Promise<string> - Signed URL for file upload

Usage:

const uploadUrl = await fileStorage.generateSignedUploadUrl(
  'image/jpeg',
  5 * 1024 * 1024, // 5MB limit
  'uploads/profile-avatar.jpg'
);

cURL Example:

# Upload file using signed URL
curl -X PUT \
  -H "Content-Type: image/jpeg" \
  -H "Content-Length: 5242880" \
  --upload-file ./avatar.jpg \
  "https://storage.googleapis.com/my-bucket/uploads/profile-avatar.jpg?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"

generateSignedDownloadUrl​

Generates a signed URL for secure file downloads from cloud storage.

Parameters:

  • objectName: string - Storage object name/path to download

Returns: Promise<string> - Signed URL for file download

Usage:

const downloadUrl = await fileStorage.generateSignedDownloadUrl(
  'uploads/document.pdf'
);

cURL Example:

# Download file using signed URL
curl -O \
  "https://storage.googleapis.com/my-bucket/uploads/document.pdf?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"

generateSignedDeleteUrl​

Generates a signed URL for secure file deletion from cloud storage.

Parameters:

  • objectName: string - Storage object name/path to delete

Returns: Promise<string> - Signed URL for file deletion

Usage:

const deleteUrl = await fileStorage.generateSignedDeleteUrl(
  'uploads/temp-file.jpg'
);

cURL Example:

# Delete file using signed URL
curl -X DELETE \
  "https://storage.googleapis.com/my-bucket/uploads/temp-file.jpg?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"

🔗 Related Documentation​