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)
• 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
• 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