2025-11-23 22:12:29 +00:00
|
|
|
# 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.
|
