smartstorage/readme.hints.md

Project Hints for smartstorage

Current State (v6.0.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

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
• 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
getStorageStats	{}	Return cached bucket/global runtime stats + storage location capacity snapshots
listBucketSummaries	{}	Return cached per-bucket runtime summaries
listCredentials	{}	Return 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

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

Build

• pnpm build runs tsrust && tsbuild tsfolders --allowimplicitany
• 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 coverage (19 tests, auth disabled, port 3337)
• test/test.credentials.node.ts - runtime credential rotation coverage (10 tests, auth enabled, port 3349)
• 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