smarts3/readme.hints.md

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)
• Real AWS SigV4 authentication (cryptographic signature verification)
• Bucket policies (AWS/MinIO-compatible JSON policies, public access support)
• 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 (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 handlers
• storage.rs - FileStore: filesystem-backed storage, multipart manager, .policies/ dir
• xml_response.rs - S3 XML response builders
• s3_error.rs - S3 error codes with HTTP status mapping
• auth.rs - AWS SigV4 signature verification (HMAC-SHA256, clock skew, constant-time compare)
• action.rs - S3Action 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 - Smarts3 class with RustBridge
• 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}
• Policies: {root}/.policies/{bucket}.policy.json

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, auth disabled, port 3337)
• 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