smarts3/readme.hints.md

Project Hints for smarts3

Current State (v3.0.0)

• Native custom S3 server implementation (Smarts3Server)
• No longer uses legacy s3rver backend (removed in v3.0.0)
• Core S3 operations working: PUT, GET, HEAD, DELETE for objects and buckets
• Multipart upload NOT yet implemented (critical gap for production)
• Authentication is hardcoded ('S3RVER'/'S3RVER') - not production-ready
• No CORS support yet
• No SSL/TLS support yet

Production Readiness

See production-readiness.md for the complete gap analysis and implementation plan.

Key Missing Features for Production:

1. Multipart upload support (HIGHEST PRIORITY)
2. Configurable authentication
3. CORS middleware
4. SSL/TLS support
5. Production configuration system
6. Production logging

Architecture Notes

File Structure

• ts/classes/smarts3-server.ts - Main server class
• ts/classes/filesystem-store.ts - Storage layer (filesystem-backed)
• ts/classes/router.ts - URL routing with pattern matching
• ts/classes/middleware-stack.ts - Middleware execution
• ts/classes/context.ts - Request/response context
• ts/classes/s3-error.ts - S3-compatible error handling
• ts/controllers/ - Service, bucket, and object controllers
• ts/index.ts - Main export (Smarts3 class)

Storage Layout

• Objects stored as: {bucket}/{encodedKey}._S3_object
• Metadata stored as: {bucket}/{encodedKey}._S3_object.metadata.json
• MD5 stored as: {bucket}/{encodedKey}._S3_object.md5
• Keys are encoded for Windows compatibility (hex encoding for invalid chars)

Current Limitations

• Max file size limited by available memory (no streaming multipart)
• Single server instance only (no clustering)
• No versioning support
• No access control beyond basic auth

Testing

• Main test: test/test.aws-sdk.node.ts - Tests AWS SDK v3 compatibility
• Run with: pnpm test
• Tests run with cleanSlate mode enabled

Dependencies

• @push.rocks/smartbucket - S3 abstraction layer
• @push.rocks/smartfs - Modern filesystem operations with Web Streams API (replaced smartfile)
• @push.rocks/smartxml - XML generation/parsing
• @push.rocks/smartpath - Path utilities
• @tsclass/tsclass - TypeScript utilities

Migration Notes (2025-11-23)

Successfully migrated from @push.rocks/smartfile + native fs to @push.rocks/smartfs:

• All file/directory operations now use smartfs fluent API
• Web Streams → Node.js Streams conversion for HTTP compatibility
• All tests passing ✅
• Build successful ✅

Next Steps

Waiting for approval to proceed with production-readiness implementation. Priority 1 is implementing multipart uploads.