rustfs/crates/protocols/src/swift

OpenStack Swift API for RustFS

Swift-compatible object storage API implementation for RustFS.

Features

This implementation provides Phase 1 Swift API support (~25% of full Swift API):

• ✅ Container CRUD operations (create, list, delete, metadata)
• ✅ Object CRUD with streaming downloads (upload, get, head, delete)
• ✅ Keystone token authentication
• ✅ Multi-tenant isolation with secure SHA256-based bucket prefixing
• ✅ Server-side object copy (COPY method)
• ✅ HTTP Range requests for partial downloads (206, 416 responses)
• ✅ Custom metadata support (X-Object-Meta-, X-Container-Meta-)

Not yet implemented:

• ⏳ Account-level operations (statistics, metadata)
• ⏳ Large object support (multi-part uploads >5GB)
• ⏳ Object versioning
• ⏳ Container ACLs and CORS
• ⏳ Temporary URLs (TempURL)
• ⏳ XML/plain-text response formats (JSON only)

Enable Feature

Swift API is opt-in and must be explicitly enabled.

Build with Swift support:

cargo build --features swift

Or enable all protocol features:

cargo build --features full

Note: Swift is NOT enabled by default to avoid unexpected API surface changes in existing deployments.

Configuration

Swift API uses Keystone for authentication. Configure the following environment variables:

Variable	Description
RUSTFS_KEYSTONE_URL	Keystone authentication endpoint URL
RUSTFS_KEYSTONE_ADMIN_TENANT	Admin tenant/project name
RUSTFS_KEYSTONE_ADMIN_USER	Admin username
RUSTFS_KEYSTONE_ADMIN_PASSWORD	Admin password

API Endpoints

Swift API endpoints follow the pattern: /v1/AUTH_{project_id}/...

Account Operations

• GET /v1/AUTH_{project} - List containers
• HEAD /v1/AUTH_{project} - Get account metadata (not yet implemented)
• POST /v1/AUTH_{project} - Update account metadata (not yet implemented)

Container Operations

• PUT /v1/AUTH_{project}/{container} - Create container
• GET /v1/AUTH_{project}/{container} - List objects
• HEAD /v1/AUTH_{project}/{container} - Get container metadata
• POST /v1/AUTH_{project}/{container} - Update container metadata
• DELETE /v1/AUTH_{project}/{container} - Delete container

Object Operations

• PUT /v1/AUTH_{project}/{container}/{object} - Upload object
• GET /v1/AUTH_{project}/{container}/{object} - Download object
• HEAD /v1/AUTH_{project}/{container}/{object} - Get object metadata
• POST /v1/AUTH_{project}/{container}/{object} - Update object metadata
• DELETE /v1/AUTH_{project}/{container}/{object} - Delete object
• COPY /v1/AUTH_{project}/{container}/{object} - Server-side copy

Architecture

The Swift API is implemented as a Tower service layer (SwiftService) that wraps the S3 service:

HTTP Request
    │
    ▼
┌───────────────┐
│ SwiftService  │ ← Routes /v1/AUTH_* requests
└───────┬───────┘
        │
   ┌────┴────┐
   │         │
   ▼         ▼
Swift     S3 Service
Handler   (fallback)

Key Components

• handler.rs - Main service implementing Tower's Service trait
• router.rs - URL routing and parsing for Swift paths
• container.rs - Container operations with tenant isolation
• object.rs - Object operations including copy and range requests
• account.rs - Account validation and tenant access control
• errors.rs - Swift-specific error types
• types.rs - Data structures for Swift API responses

Tenant Isolation

Swift containers are mapped to S3 buckets with a secure hash prefix:

Swift: /v1/AUTH_abc123/mycontainer
  ↓
S3 Bucket: {sha256(abc123)[0:16]}-mycontainer

This ensures:

• Complete tenant isolation at the storage layer
• No collision between tenants with similar container names
• S3-compatible bucket naming (lowercase alphanumeric + hyphen)

Documentation

See the docs/ directory for detailed documentation:

• SWIFT_API.md - Complete API reference
• TESTING_GUIDE.md - Manual testing procedures
• COMPLETION_ANALYSIS.md - Protocol coverage tracking
• COPY_IMPLEMENTATION.md - Server-side copy documentation
• RANGE_REQUESTS.md - Range request implementation details

License

Apache License 2.0