Refactor rebuf API, add comprehensive tests, and improve reliability

[stym06]

Summary

This PR significantly improves rebuf's API design, test coverage, and reliability. The main changes include:

1. API Redesign: Replaced the Init(RebufOptions) constructor with a modern New(ctx, dir, opts...) pattern using functional options, following Go conventions.

2. Comprehensive Test Suite: Added 1000+ lines of tests covering initialization, writes, batches, replay, segment rotation, concurrency, sync strategies, and edge cases.

3. Data Integrity: Implemented CRC32 checksums for every log entry to detect corruption during replay.

4. Concurrency Fixes: Protected the entire write path with mutex locks (previously only the final sync was protected), fixing race conditions in concurrent scenarios.

5. Graceful Shutdown: Added context-based cancellation for the background sync goroutine to prevent leaks.

Key Changes

• rebuf/rebuf.go:

  • Replaced RebufOptions struct with functional Option pattern (WithMaxLogSize, WithMaxSegments, etc.)
  • Renamed Init() to New() with signature New(ctx context.Context, logDir string, opts ...Option)
  • Added SyncStrategy enum (SyncEveryWrite, SyncPeriodic, SyncManual) for flexible durability control
  • Implemented CRC32 checksums: entries now stored as [8-byte size][4-byte crc32][data]
  • Fixed concurrency: entire Write() and WriteBatch() methods now protected by mutex
  • Added Sync() method for manual sync strategy
  • Implemented graceful goroutine shutdown using context.Context and done channel
  • Added state accessor methods: SegmentCount(), CurrentLogSize(), Dir()
  • Added ReplayFrom(segmentId) for selective replay starting from a specific segment

• rebuf/rebuf_test.go (new file):

  • 1046 lines of comprehensive tests including:
    • Initialization tests (fresh dir, existing segments, default options)
    • Write tests (single/multiple entries, zero-length, large data, segment rotation, max segments deletion)
    • CRC32 integrity verification
    • WriteBatch tests with rotation
    • Replay tests (empty dir, multiple segments, corrupt CRC, callback errors)
    • ReplayFrom tests
    • Purge and PurgeThrough tests
    • Sync strategy tests (EveryWrite, Periodic, Manual)
    • Close tests (flushing, graceful shutdown)
    • Concurrent write tests (10 goroutines × 20 writes each)
    • Concurrent WriteBatch tests

• utils/utils.go:

  • Added ParseSegmentId() to extract numeric ID from filenames
  • Added GetSortedSegmentFiles() to return segments sorted by ID with .tmp appended
  • Refactored GetLatestSegmentId() to use new helpers
  • Improved IsDirectoryEmpty() logic

• utils/utils_test.go:

  • Expanded from ~100 lines to ~370 lines with proper test structure
  • Added tests for IsDirectoryEmpty, ParseSegmentId, GetSortedSegmentFiles, GetLatestSegmentId, GetNumSegments, GetOldestSegmentFile, FileSize

• Documentation:

  • Added ROADMAP.md outlining planned improvements
  • Added CONTRIBUTING.md with development guidelines
  • Updated README.md with feature list and modern usage examples
  • Updated example.go to use new API

• CI/CD:

  • Added -race flag to test runs in GitHub Actions workflow
  • Added go vet step

Notable Implementation Details

• Entry Format: Each log entry is now [8-byte big-endian size][4-byte big-endian CRC32][data] for integrity checking
• Mutex Protection: The entire write path (including segment rotation and buffered I/O) is now protected by a single mutex
• **Context-Base

https://claude.ai/code/session_01VSZuYevFutSrFay5XmL1qh

[github-actions]

Merging this branch will not change overall coverage

Impacted Packages	Coverage Δ	🤖
github.com/stym06/rebuf	0.00% (ø)
github.com/stym06/rebuf/rebuf	80.83% (ø)
github.com/stym06/rebuf/utils	90.79% (ø)

---

Coverage by file

Changed files (no unit tests)

Changed File	Coverage Δ	Total	Covered	Missed	🤖
github.com/stym06/rebuf/example.go	0.00% (ø)	15	0	15
github.com/stym06/rebuf/rebuf/rebuf.go	80.83% (ø)	240	194	46
github.com/stym06/rebuf/utils/utils.go	90.79% (ø)	76	69	7

Please note that the "Total", "Covered", and "Missed" counts above refer to code statements instead of lines of code. The value in brackets refers to the test coverage of that file in the old version of the code.

Changed unit test files

• github.com/stym06/rebuf/rebuf/rebuf_test.go
• github.com/stym06/rebuf/utils/utils_test.go