Skip to main content
Version: 🚧 Canary

💾 File Storage Drivers

File storage drivers provide a consistent interface for secure file operations in NodeBlocks applications. They abstract cloud storage configurations and signed URL generation for use with SDK services and blocks.

🎯 Overview​

File storage drivers in NodeBlocks are factory functions that create configured Google Cloud Storage instances with signed URL capabilities. The SDK ships one GCS driver today.

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

const { createFileStorageDriver } = drivers;

📋 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 with Application Default Credentials. For local development, one option is:

  • 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 Application Default Credentials; no credentials are passed directly to createFileStorageDriver. The environment-variable setup above is only one way to provide ADC.

createFileStorageDriver​

Creates a Google Cloud Storage file storage driver with signed URL capabilities. This is a synchronous factory — no await is required.

Parameters:

ParameterTypeDescription
projectIdstringGoogle Cloud project identifier
bucketNamestringStorage bucket name for file operations
options?{ signedUrlExpiresInSeconds: number }Optional configuration (default expiry: 900 seconds)

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

Usage:

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

const { createFileStorageDriver } = drivers;

const fileStorage = createFileStorageDriver(
  process.env.GCP_PROJECT_ID!,
  process.env.GCP_BUCKET_NAME!
);

Example with Custom Expiry:

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

const { createFileStorageDriver } = drivers;

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

FileStorageDriver​

Type alias exported from the drivers namespace (Awaited<ReturnType<typeof createFileStorageDriver>> in src/drivers/file-storage.ts). It exposes deleteFile, generateSignedDeleteUrl, generateSignedDownloadUrl, and generateSignedUploadUrl — see File Storage Driver Methods below for parameters and behavior.

The type is used as the service injection type in SDK primitives.

Signed URL implementation​

All signed URL methods use GCS v4 signing (version: 'v4'). Expiry is computed as:

Date.now() + signedUrlExpiresInSeconds * 1000
MethodGCS actionNotes
generateSignedUploadUrl'write'Includes contentType and extensionHeaders: { 'Content-Length': contentLength }
generateSignedDownloadUrl'read'—
generateSignedDeleteUrl'delete'—

🔧 File Storage Driver Methods​

deleteFile​

Deletes a file from the Google Cloud Storage bucket.

ParameterTypeDescription
objectNamestringStorage object name/path to delete from bucket

Returns: Promise<void>

await fileStorage.deleteFile('uploads/temp-file.jpg');

generateSignedDeleteUrl​

Generates a signed URL for file deletion operations.

ParameterTypeDescription
objectNamestringStorage object name/path to delete

Returns: Promise<string>

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

generateSignedDownloadUrl​

Generates a signed URL for file download operations.

ParameterTypeDescription
objectNamestringStorage object name/path to download

Returns: Promise<string>

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

generateSignedUploadUrl​

Generates a signed URL for file upload operations.

ParameterTypeDescription
contentTypestringMIME type of file to upload
contentLengthnumberExact request body size in bytes; it is signed as the Content-Length header
objectNamestringStorage object name/path for upload

Returns: Promise<string>

const uploadUrl = await fileStorage.generateSignedUploadUrl(
  'image/jpeg',
  5 * 1024 * 1024, // exact request body size
  'uploads/profile-avatar.jpg'
);

Upload client requirements:

RequirementDetail
HTTP methodPUT
Content-Type headerMust match the contentType passed to generateSignedUploadUrl — mismatch returns 403
Body sizeMust equal the declared contentLength — a different size can cause the upload request to fail

Error behavior:

OutcomeBehavior
Missing credentials or signing failureSigned URL methods reject; generating a URL does not check bucket or object access
Bucket/object access failuredeleteFile rejects, or the subsequent signed URL request fails
deleteFile on missing objectThrows (object does not exist)
Upload with headers/body that do not match the signed requestThe signed URL request can fail; the driver does not validate the upload itself

🔧 Using File Storage Drivers​

With Services​

Inject the driver via the third-argument options on services that accept fileStorageDriver:

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

const { organizationService } = services;
const { createFileStorageDriver } = drivers;

const fileStorageDriver = createFileStorageDriver(
  process.env.GCP_PROJECT_ID!,
  process.env.GCP_BUCKET_NAME!
);

organizationService(
  dataStores, // identities, organizations, profiles required for org service
  {
    authSecrets: {
      authEncSecret: process.env.AUTH_ENC_SECRET!,
      authSignSecret: process.env.AUTH_SIGN_SECRET!,
    },
  },
  { fileStorageDriver }
);

See Organization Service for full Express wiring and required data stores (identities, organizations, profiles). The same fileStorageDriver injection pattern applies to Profile Service, Product Service, and Chat Service.

🔗 Related Documentation​