Configuration

Overview

Tusflow's configuration is managed through:

Environment variables in wrangler.toml
TypeScript configuration modules in config/

All configuration changes require worker redeployment to take effect.

Environment Configuration

Configure your environment in wrangler.toml:

name = "Tusflow-api"
main = "src/index.ts"
compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"
 
[vars]
AWS_REGION = ""
AWS_ACCESS_KEY_ID = ""
AWS_SECRET_ACCESS_KEY = ""
AWS_ENDPOINT = ""
AWS_BUCKET_NAME = ""
UPSTASH_REDIS_REST_URL = ""
UPSTASH_REDIS_REST_TOKEN = ""
UNKEY_API_ID = ""
UNKEY_ROOT_KEY = ""
 
[observability]
enabled = true
 
[triggers]
crons = ["0 0 * * *"]  # Daily cleanup at midnight UTC

Upload Configuration

Configure upload behavior in upload-config.ts:

export const UPLOAD_CONFIG = {
  DOMAIN: '',
  CHUNK_SIZE: {
    MIN: 5 * 1024 * 1024, // 5MB
    MAX: 50 * 1024 * 1024, // 50MB
    TARGET_UPLOAD_TIME: 1, // 1 second
  },
  RETRY: {
    MAX_ATTEMPTS: 3,
    DELAY: 500, // 500ms
  },
  CIRCUIT_BREAKER: {
    TIMEOUT: 25000, // 25 seconds
    FAILURE_THRESHOLD: 3,
    RESET_TIMEOUT: 5000, // 5 seconds
  },
  UPLOAD: {
    INCOMPLETE_TTL: 24 * 60 * 60, // 24 hours
    MAX_PARTS: 10000,
    TIMEOUT: 25000, // 25 seconds
  },
  PARALLEL_UPLOADS: {
    MAX_CONCURRENT: 10,
    BATCH_SIZE: 5,
  },
};

Worker Constraints

Set worker limits in workers-config.ts:

export const WORKER_CONSTRAINTS = {
  MAX_EXECUTION_TIME: 25000, // 25 seconds
  MEMORY_LIMIT: 128 * 1024 * 1024, // 128MB
  CHUNK_MEMORY_LIMIT: 50 * 1024 * 1024, // 50MB
  NETWORK_OVERHEAD: 1.2, // 20% overhead
  CONCURRENT_UPLOADS: 5,
};

TUS Protocol Settings

Configure TUS protocol in tus-config.ts:

export const TUS_CONFIG = {
  VERSION: '1.0.0',
  SUPPORTED_VERSIONS: ['1.0.0', '1.0.0'],
  MAX_SIZE: 1024 * 1024 * 1024, // 1GB
  EXTENSIONS: [
    'creation',
    'creation-with-upload',
    'termination',
    'concatenation',
    'checksum',
    'expiration',
  ],
  CHECKSUM_ALGORITHMS: ['sha1', 'md5'],
  HEADERS: {
    RESUMABLE: 'Tus-Resumable',
    VERSION: 'Tus-Version',
    // ... other headers
  },
};

Rate Limiting

Configure rate limits in ratelimit-config.ts:

export const RATE_LIMIT = {
  ENABLE: true,
  NAMESPACE: 'tusflow-api',
  BLOCK_DURATION: 60 * 60, // 1 hour
  // Different limits for different endpoints
  LIMITS: {
    // For initiating new uploads
    POST: {
      tokens: 50, // Number of requests
      interval: 3600, // Time window in seconds (1 hour)
    },
    // For upload chunks
    PATCH: {
      tokens: 500, // More tokens for chunk uploads
      interval: 3600,
    },
    // For other operations (HEAD, DELETE)
    DEFAULT: {
      tokens: 100,
      interval: 3600,
    },
  },
};

Security Configuration

Manage security in security-config.ts:

export const SECURITY_CONFIG = {
  ALLOWED_ORIGINS: ['*'],
  ALLOWED_METHODS: ['GET', 'POST', 'PATCH', 'HEAD', 'DELETE', 'OPTIONS'],
  ALLOWED_HEADERS: [
    'Content-Type',
    'Upload-Length',
    'Upload-Metadata',
    // ... other headers
  ],
  EXPOSE_HEADERS: [
    'Location',
    'Upload-Offset',
    // ... other headers
  ],
  CREDENTIALS: true,
};

File Validation

Set file validation rules in fileValidation-config.ts:

export const FILE_VALIDATION = {
  ENABLE_TYPE_VALIDATION: true,
  ALLOWED_FILE_TYPES: [
    '.pdf',
    '.doc',
    '.docx',
    '.txt',
    '.jpg',
    '.jpeg',
    '.png',
    '.mp4',
  ],
  MAX_FILE_SIZE: 100 * 1024 * 1024, // 100MB
  MIN_FILE_SIZE: 1024, // 1KB
};

Error Configuration

Define error messages in error-config.ts:

export const ERROR_MESSAGES = {
  UPLOAD: {
    LENGTH_REQUIRED: 'Upload-Length or Upload-Defer-Length header required',
    INVALID_OFFSET: 'Invalid Upload-Offset header',
    // ... other upload errors
  },
  S3: {
    MULTIPART_INIT_FAILED: 'Failed to initialize multipart upload',
    // ... other S3 errors
  },
  RATE_LIMIT: {
    LIMIT_EXCEEDED: 'Rate limit exceeded. Please try again later.',
    // ... other rate limit errors
  },
};

Cache Configuration

Configure caching in cache-config.ts:

export const CACHE_CONFIG = {
  CACHE_NAME: 'Tusflow-api-cache',
  MAX_AGE: UPLOAD_CONFIG.UPLOAD.INCOMPLETE_TTL,
  VARY_HEADERS: ['Accept', 'Accept-Encoding', 'Authorization'],
};

Best Practices

Security Settings

Use restrictive CORS origins in production
Enable rate limiting
Set appropriate file size limits
Configure authentication

Performance Tuning

Adjust chunk sizes based on network conditions
Configure parallel upload limits
Set appropriate timeouts
Enable caching where possible

Error Handling

Configure meaningful error messages
Set up proper logging
Implement retry strategies
Monitor error rates

Always test configuration changes in a staging environment before deploying to production.

Configuration Import

Import and use configurations in your application:

import {
  CACHE_CONFIG,
  ERROR_MESSAGES,
  FILE_VALIDATION,
  RATE_LIMIT,
  SECURITY_CONFIG,
  TUS_CONFIG,
  UPLOAD_CONFIG,
  WORKER_CONSTRAINTS,
} from '@/config';
 
// Example usage
const maxChunkSize = UPLOAD_CONFIG.CHUNK_SIZE.MAX;
const allowedTypes = FILE_VALIDATION.ALLOWED_FILE_TYPES;
const corsOrigins = SECURITY_CONFIG.ALLOWED_ORIGINS;

On this page