Add OpenStack Swift API Support (#2066)

Co-authored-by: houseme <housemecn@gmail.com> Co-authored-by: Copilot <noreply@github.com>
2026-08-28 16:07:05 +00:00 · 2026-03-07 18:11:35 +01:00
parent 7c94be4e8c
commit b07383760f
41 changed files with 16973 additions and 7 deletions
@@ -0,0 +1,134 @@
+# 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:
+
+```bash
+cargo build --features swift
+```
+
+Or enable all protocol features:
+
+```bash
+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