61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
# Project Hints for smarts3
|
|
|
|
## Current State (v6.0.0-dev)
|
|
|
|
- **Rust-powered S3 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 `rusts3`
|
|
- Full S3 compatibility: PUT, GET, HEAD, DELETE for objects and buckets
|
|
- Multipart upload support (streaming, no OOM)
|
|
- Authentication (AWS v2/v4 signature key extraction)
|
|
- CORS support
|
|
- ListBuckets, ListObjects (v1/v2), CopyObject
|
|
|
|
## Architecture
|
|
|
|
### Rust Binary (`rust/src/`)
|
|
- `main.rs` - Clap CLI, management mode entry
|
|
- `config.rs` - Serde config structs matching TS interfaces
|
|
- `management.rs` - IPC loop (newline-delimited JSON over stdin/stdout)
|
|
- `server.rs` - hyper 1.x HTTP server, routing, CORS, auth, all S3 handlers
|
|
- `storage.rs` - FileStore: filesystem-backed storage, multipart manager
|
|
- `xml_response.rs` - S3 XML response builders
|
|
- `s3_error.rs` - S3 error codes with HTTP status mapping
|
|
|
|
### TypeScript Bridge (`ts/`)
|
|
- `ts/index.ts` - Smarts3 class with RustBridge<TRustS3Commands>
|
|
- `ts/plugins.ts` - path, smartpath, RustBridge, tsclass
|
|
- `ts/paths.ts` - packageDir, bucketsDir defaults
|
|
|
|
### IPC Commands
|
|
| Command | Params | Action |
|
|
|---------|--------|--------|
|
|
| `start` | `{ config: ISmarts3Config }` | Init storage + HTTP server |
|
|
| `stop` | `{}` | Graceful shutdown |
|
|
| `createBucket` | `{ name: string }` | Create bucket directory |
|
|
|
|
### Storage Layout (backward-compatible)
|
|
- Objects: `{root}/{bucket}/{key}._S3_object`
|
|
- Metadata: `{root}/{bucket}/{key}._S3_object.metadata.json`
|
|
- MD5: `{root}/{bucket}/{key}._S3_object.md5`
|
|
- Multipart: `{root}/.multipart/{upload_id}/part-{N}`
|
|
|
|
## Build
|
|
|
|
- `pnpm build` runs `tsrust && tsbuild --web --allowimplicitany`
|
|
- `tsrust` compiles Rust to `dist_rust/rusts3`
|
|
- Targets: linux_amd64, linux_arm64 (configured in npmextra.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 (10 tests)
|
|
- `test/test.ts` - SmartBucket integration (3 tests)
|
|
- Run: `pnpm test` or `tstest test/test.aws-sdk.node.ts --verbose`
|