mirror of
https://github.com/rustfs/rustfs.git
synced 2026-08-25 13:36:50 +00:00
Senol Colak
b07383760f
Co-authored-by: houseme <housemecn@gmail.com> Co-authored-by: Copilot <noreply@github.com>
135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
# 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
|