106 lines
6.4 KiB
Markdown
106 lines
6.4 KiB
Markdown
# Project Hints for smartstorage
|
|
|
|
## Current State (v6.5.0)
|
|
|
|
- **Rust-powered S3-compatible storage server** via `@push.rocks/smartrust` IPC bridge
|
|
- High-performance: streaming I/O, zero-copy, backpressure, range seek
|
|
- TypeScript is thin IPC wrapper; all HTTP/storage/routing in Rust binary `ruststorage`
|
|
- Full S3 compatibility: PUT, GET, HEAD, DELETE for objects and buckets
|
|
- Multipart upload support (streaming, no OOM)
|
|
- **Real AWS SigV4 authentication** (cryptographic signature verification)
|
|
- **Bucket policies** (AWS/MinIO-compatible JSON policies, public access support)
|
|
- CORS support
|
|
- ListBuckets, ListObjects (v1/v2), CopyObject
|
|
- Runtime bucket summaries and storage stats via the Rust bridge (no S3 list scans)
|
|
- Cluster health introspection via the Rust bridge (node membership, local drive probes, quorum, healing state)
|
|
- Runtime credential listing and atomic replacement via the Rust bridge
|
|
- Runtime credentials persist under `{storage}/.smartstorage/credentials.json`
|
|
- Bucket tenant APIs provision scoped per-bucket credentials and enforce the scope before bucket-policy/default-auth authorization
|
|
- Per-bucket export/import uses `smartstorage.bucket.v1` JSON with object payloads encoded per object and size/MD5 validation on import
|
|
- Cluster identity and topology snapshots persist under `{storage}/.smartstorage/cluster/`
|
|
- S3-side operational endpoints are available at `/-/live`, `/-/ready`, `/-/health`, and `/-/metrics`
|
|
- Runtime credential listing returns access-key metadata only; secrets are write-only
|
|
|
|
## Architecture
|
|
|
|
### Rust Binary (`rust/src/`)
|
|
- `main.rs` - Clap CLI, management mode entry
|
|
- `config.rs` - Serde config structs matching TS interfaces (includes `region`)
|
|
- `management.rs` - IPC loop (newline-delimited JSON over stdin/stdout)
|
|
- `server.rs` - hyper 1.x HTTP server, routing, CORS, auth+policy pipeline, all S3-compatible handlers
|
|
- `storage.rs` - FileStore: filesystem-backed storage, multipart manager, `.policies/` dir
|
|
- `storage.rs` also owns the runtime stats cache and standalone storage scans used by the bridge stats API
|
|
- `xml_response.rs` - S3-compatible XML response builders
|
|
- `error.rs` - StorageError codes with HTTP status mapping
|
|
- `auth.rs` - AWS SigV4 signature verification (HMAC-SHA256, clock skew, constant-time compare)
|
|
- `action.rs` - StorageAction enum + request-to-IAM-action resolver + RequestContext
|
|
- `policy.rs` - BucketPolicy model, evaluation engine (Deny > Allow > NoOpinion), PolicyStore (RwLock cache + disk)
|
|
|
|
### TypeScript Bridge (`ts/`)
|
|
- `ts/index.ts` - SmartStorage class with RustBridge<TRustStorageCommands>
|
|
- `ts/plugins.ts` - path, smartpath, RustBridge, tsclass
|
|
- `ts/paths.ts` - packageDir, bucketsDir defaults
|
|
|
|
### IPC Commands
|
|
| Command | Params | Action |
|
|
|---------|--------|--------|
|
|
| `start` | `{ config: ISmartStorageConfig }` | Init storage + HTTP server |
|
|
| `stop` | `{}` | Graceful shutdown |
|
|
| `createBucket` | `{ name: string }` | Create bucket directory |
|
|
| `createBucketTenant` | `{ bucketName, accessKeyId, secretAccessKey, region? }` | Create bucket and scoped persisted credential |
|
|
| `deleteBucketTenant` | `{ bucketName, accessKeyId? }` | Revoke scoped credential or delete a verified tenant bucket recursively |
|
|
| `rotateBucketTenantCredentials` | `{ bucketName, accessKeyId, secretAccessKey, region? }` | Replace scoped credential for one bucket |
|
|
| `listBucketTenants` | `{}` | Return scoped credential metadata |
|
|
| `getBucketTenantCredential` | `{ bucketName }` | Return one scoped credential including secret for descriptor generation |
|
|
| `exportBucket` | `{ bucketName }` | Export one bucket's objects and metadata |
|
|
| `importBucket` | `{ bucketName, source }` | Import a `smartstorage.bucket.v1` bucket export |
|
|
| `getStorageStats` | `{}` | Return cached bucket/global runtime stats + storage location capacity snapshots |
|
|
| `listBucketSummaries` | `{}` | Return cached per-bucket runtime summaries |
|
|
| `listCredentials` | `{}` | Return metadata for the active runtime auth credential set |
|
|
| `replaceCredentials` | `{ credentials: IStorageCredential[] }` | Atomically replace the runtime auth credential set |
|
|
| `getClusterHealth` | `{}` | Return runtime cluster health or `{ enabled: false }` in standalone mode |
|
|
|
|
### Operational HTTP Endpoints
|
|
|
|
| Endpoint | Purpose |
|
|
|----------|---------|
|
|
| `GET /-/live` | Process liveness |
|
|
| `GET /-/ready` | S3 readiness and cluster quorum readiness |
|
|
| `GET /-/health` | JSON storage, cluster, and runtime health |
|
|
| `GET /-/metrics` | Prometheus text metrics |
|
|
|
|
### Storage Layout
|
|
- Objects: `{root}/{bucket}/{key}._storage_object`
|
|
- Metadata: `{root}/{bucket}/{key}._storage_object.metadata.json`
|
|
- MD5: `{root}/{bucket}/{key}._storage_object.md5`
|
|
- Multipart: `{root}/.multipart/{upload_id}/part-{N}`
|
|
- Policies: `{root}/.policies/{bucket}.policy.json`
|
|
- Runtime credentials: `{root}/.smartstorage/credentials.json`
|
|
|
|
## Build
|
|
|
|
- `pnpm build` runs `tsrust && tsbuild tsfolders`
|
|
- `tsrust` compiles Rust to `dist_rust/ruststorage`
|
|
- Targets: linux_amd64, linux_arm64 (configured in .smartconfig.json)
|
|
|
|
## Dependencies
|
|
|
|
- `@push.rocks/smartrust` - RustBridge IPC bridge
|
|
- `@push.rocks/smartpath` - Path utilities
|
|
- `@tsclass/tsclass` - IS3Descriptor type
|
|
- `@git.zone/tsrust` (devDep) - Rust cross-compilation
|
|
|
|
## Testing
|
|
|
|
- `test/test.aws-sdk.node.ts` - AWS SDK v3 compatibility + runtime stats + standalone cluster health/metrics coverage (20 tests, auth disabled, port 3337)
|
|
- `test/test.bucket-tenants.node.ts` - bucket tenant provisioning, per-bucket isolation, restart persistence, export/import integrity, policy persistence, rotation, revoke/delete safeguards, AWS SDK v3 compatibility (15 tests, port 3361)
|
|
- `test/test.credentials.node.ts` - runtime credential rotation coverage (10 tests, auth enabled, port 3349)
|
|
- `test/test.health-http.node.ts` - unauthenticated operational endpoint coverage (3 tests, port 3353)
|
|
- `test/test.cluster-health.node.ts` - single-node cluster health coverage (4 tests, S3 port 3348, QUIC port 4348)
|
|
- `test/test.auth.node.ts` - Auth + bucket policy integration (20 tests, auth enabled, port 3344)
|
|
- `test/test.policy-crud.node.ts` - Policy API CRUD + validation edge cases (17 tests, port 3345)
|
|
- `test/test.policy-eval.node.ts` - Policy evaluation: principals, actions, resources, deny-vs-allow (22 tests, port 3346)
|
|
- `test/test.policy-actions.node.ts` - Per-action policy enforcement (15 tests, port 3347)
|
|
- `test/test.ts` - SmartBucket integration (3 tests)
|
|
- Run: `pnpm test` or `tstest test/test.aws-sdk.node.ts --verbose`
|