e08988f7f3
Add development plan and Oracle-validated weekly plans (Weeks 1-3)
...
development-plan.md (master plan):
- 11-week implementation broken into 4 phases
- 11 Rust crates with dependency graph
- Per-week deliverables, tests, exit criteria
- Deferred requirements (FR-21, FR-22) with rationale
plans/week-01-foundation.md:
- Workspace setup, core types, FUSE skeleton, local origin
- Origin trait with watch() method (arch 4.3.4)
- EventBus with FileAccessed event (FR-18.1)
- All EROFS handlers for read-only enforcement (FR-4.1-4.5)
plans/week-02-metadata.md:
- symphonia metadata extraction (FR-6.1-6.5)
- SQLite schema matching architecture 4.3.6 exactly
- Column names: track/disc (not track_number/disc_number)
- Hash columns as TEXT (hex-encoded, not BLOB)
- Added idx_files_real index (FR-7.3)
plans/week-03-virtual-tree.md:
- Path resolver with $var syntax (arch 4.3.1)
- Template vars: $artist, $album, $title, $track, $year, $disc, $genre, $format, $format_upper
- RefreshPolicy struct for FR-9.3 (TTL-based refresh)
- force_refresh() method for FR-9.4 (signal/API refresh)
All plans Oracle-validated against architecture.md and requirements.md
2026-05-12 17:52:33 +02:00
dac9f3dd02
Replace JSON-RPC with gRPC for Control API
...
Update Control API specification to use gRPC over Unix socket instead of
JSON-RPC 2.0. gRPC provides better type safety, native streaming for events,
and auto-generated clients for multi-language integration.
architecture.md:
- Add decision rationale table (JSON-RPC vs gRPC comparison)
- Add full .proto definitions (~200 lines) for musicfs.v1 package
- Define MusicFS service with 9 RPC methods:
- Daemon: GetStatus, Shutdown
- Cache: GetCacheStats, ClearCache, Prefetch (streaming)
- Origins: ListOrigins, GetOriginHealth, RescanOrigin (streaming)
- Search: Search, SearchStream
- Events: SubscribeEvents (server-streaming)
- Add grpcurl debugging examples
requirements.md:
- FR-17.1: Clarify Unix socket uses gRPC
- FR-17.2: Upgrade from SHOULD to SHALL for gRPC requirement
2026-05-12 16:51:35 +02:00
1374084135
Reorganize docs into v1 (beetfs) and v2 (new architecture)
...
docs/v1/ - Original beetfs documentation:
- analysis.md, components.md, data-flow.md, drawbacks.md
- features.md, modernization.md, rust-migration.md
- benchmark-plan.md, benchmark-results.md, e2e-test-plan.md
- README.md
docs/v2/ - New MusicFS architecture:
- requirements.md: Full requirements spec (FR-1 to FR-25, NFR-1 to NFR-14)
- P0: Multi-origin, plugins, CAS, control API
- P1: Search, album art, prefetch, metadata sources
- P3: HA, 10M+ files scalability
- architecture.md: Google BlueDoc style design document
- PlantUML diagrams for all components
- Design requirements with quantitative targets
- Alternatives considered, implementation plan
2026-05-12 16:46:37 +02:00
3a6115cbab
Add benchmark suite and results
...
Benchmark harness (benchmarks/run_benchmarks.py):
- Mount time, readdir, stat latency, file open/read, memory usage
- ENOENT lookup (missing file) benchmark per Oracle review
- Uses synthetic FLAC files from test infrastructure
Results: ALL BENCHMARKS BLOCKED BY BUGS
- Bug #2 (directory tree building) crashes mount with any content
- FSNode.adddir() assumes parent dirs exist, fails with KeyError
- Bug #1 (nested methods) would block FUSE ops even if mount worked
beetfs is non-functional for real-world use until both bugs fixed.
2026-05-12 14:44:02 +02:00
dacd3a7c1f
Add benchmark plan for beetfs performance measurement
...
Covers:
- Mount time scaling (100 to 100K items)
- Metadata operations (stat, readdir throughput)
- File I/O (open latency, read throughput)
- Memory usage (idle, per-file, leak detection)
- Concurrent access (GIL impact)
- Realistic workloads (library scan, album playback)
Tools: fio, mdtest, hyperfine
Baselines: ext4, fuse-passthrough, sshfs
Key bottlenecks identified:
- FileHandler loads entire file into RAM on open
- Mount-time bulk load of all library items
- Python GIL limits parallelism
2026-05-12 14:36:24 +02:00
f8666ae8c6
Document test findings and fix mount script
...
Test Results (74 tests):
- 12 passed, 56 failures, 3 errors, 3 skipped
Bugs Detected:
1. Nested methods bug: lines 758-1144 indented inside access()
- FUSE operations (readdir, open, read, write) unreachable
- os.listdir() returns ENOSYS (Function not implemented)
2. Directory tree building: KeyError in FSNode.getnode()
- Mount fails when library contains tracks
3. Unmount not clean: filesystem not releasing properly
Changes:
- Fix conftest.py: inline sanitization (no module-level sanitize fn)
- Add test findings to e2e-test-plan.md
- Add .gitignore for .pyc and test artifacts
2026-05-12 14:29:05 +02:00
81df4790bf
Add e2e test suite for beetfs
...
Tests use real FUSE operations against mounted beetfs filesystem:
- test_smoke: mount/unmount lifecycle
- test_nested_bug: detects critical indentation bug (13 failures)
- test_readdir: directory listing
- test_read: metadata overlay verification
- test_stat: file/directory attributes
- test_write: metadata modification
- test_error_handling: ENOENT, EOPNOTSUPP
Also includes:
- conftest.py with BeetFSTestCase base class and synthetic FLAC generator
- e2e-test-plan.md with Oracle-reviewed test strategy
- flake.nix updated with ffmpeg/flac for test fixtures
Run: cd tests && nix develop ../ --command python -m unittest discover
2026-05-12 14:02:55 +02:00
f0a83df190
Add reverse-engineered documentation
...
- README.md: Overview, core concept diagram, component summary
- architecture.md: System design, initialization flow, memory model
- components.md: Deep dive on all classes and functions
- data-flow.md: Complete read/write operation flows with diagrams
- analysis.md: Performance analysis (latency, memory footprint, I/O)
- drawbacks.md: 27 identified issues and limitations catalog
- modernization.md: Python 3 migration guide with effort estimates
2026-05-12 11:52:48 +02:00
Alexander