- Added flexible_versions.go with utilities for Kafka flexible versions (v3+)
- Implemented ParseRequestHeader for compact string parsing and tagged fields
- Added fallback mechanism in handler.go for backward compatibility
- Updated handleApiVersions to support flexible version responses
- Added comprehensive tests for flexible version utilities
- All protocol tests passing with robust error handling
Multi-batch Fetch support completed:
## Core Features
- **MaxBytes compliance**: Respects fetch request MaxBytes limits to prevent oversized responses
- **Multi-batch concatenation**: Properly concatenates multiple record batches in single response
- **Size estimation**: Pre-estimates batch sizes to optimize MaxBytes usage before construction
- **Kafka-compliant behavior**: Always returns at least one batch even if it exceeds MaxBytes (first batch rule)
## Implementation Details
- **MultiBatchFetcher**: New dedicated class for multi-batch operations
- **Intelligent batching**: Adapts record count per batch based on available space (10-50 records)
- **Proper concatenation format**: Each batch maintains independent headers and structure
- **Fallback support**: Graceful fallback to single batch if multi-batch fails
## Advanced Features
- **Compression ready**: Basic support for compressed record batches (GZIP placeholder)
- **Size tracking**: Tracks total response size and batch count across operations
- **Edge case handling**: Handles large single batches, empty responses, partial batches
## Integration & Testing
- **Fetch API integration**: Seamlessly integrated with existing handleFetch pipeline
- **17 comprehensive tests**: Multi-batch scenarios, size limits, concatenation format validation
- **E2E compatibility**: Sarama tests pass with no regressions
- **Performance validation**: Benchmarks for batch construction and multi-fetch operations
## Performance Improvements
- **Better bandwidth utilization**: Fills available MaxBytes space efficiently
- **Reduced round trips**: Multiple batches in single response
- **Adaptive sizing**: Smaller batches when space limited, larger when space available
Ready for Phase 6: Basic flexible versions support
ApiVersions Matrix Accuracy completed:
## Critical Fixes
- **OffsetFetch API**: Updated advertised from v0-v2 to v0-v5 (MAJOR fix)
- Implementation already supported v3+ throttle_time_ms and v5+ leader_epoch
- Clients can now use advanced OffsetFetch features
- **CreateTopics API**: Updated advertised from v0-v4 to v0-v5 (minor fix)
- Implementation already routed v5 requests to v2+ handler
- Better client compatibility for v5 CreateTopics requests
## Implementation
- **handleApiVersions()**: Corrected advertised max versions
- **validateAPIVersion()**: Updated validation ranges to match advertisements
- **Consistency**: Eliminated mismatch between advertised vs implemented versions
## Testing & Verification
- **Comprehensive test suite**: 6 new tests in api_versions_test.go
- **Version validation tests**: OffsetFetch v3-v5 and CreateTopics v5 now accepted
- **End-to-end verification**: E2E tests still pass, no regressions
- **API audit documentation**: Complete version matrix in API_VERSION_MATRIX.md
## Impact
- **Client compatibility**: Higher-version clients can now connect properly
- **Feature utilization**: Advanced features like leader epoch, throttle time accessible
- **Protocol compliance**: Advertised versions now match actual implementation
- **Future-proofing**: Clear process for managing API version accuracy
Ready for Phase 4: Consumer group protocol metadata parsing
CreateTopics Protocol Compliance completed:
## Implementation
- Implement handleCreateTopicsV0V1() with proper v0/v1 request parsing
- Support regular array/string format (not compact) for v0/v1
- Parse topic name, partitions, replication factor, assignments, configs
- Handle timeout_ms and validate_only fields correctly
- Maintain existing v2+ compact format support
- Wire to SeaweedMQ handler for actual topic creation
## Key Features
- Full v0-v5 CreateTopics API version support
- Proper error handling (TOPIC_ALREADY_EXISTS, INVALID_PARTITIONS, etc.)
- Partition count validation and enforcement
- Compatible with existing SeaweedMQ topic management
## Tests
- Comprehensive unit tests for v0/v1/v2+ parsing
- Error condition testing (duplicate topics, invalid partitions)
- Multi-topic creation support
- Integration tests across all API versions
- Performance benchmarks for CreateTopics operations
## Verification
- All protocol tests pass (v0-v5 CreateTopics)
- E2E Sarama tests continue to work
- Real topics created with specified partition counts
- Proper error responses for edge cases
Ready for Phase 3: ApiVersions matrix accuracy
Core SeaweedMQ Integration completed:
## Implementation
- Implement SeaweedMQHandler.GetStoredRecords() to retrieve actual records from SeaweedMQ
- Add SeaweedSMQRecord wrapper implementing offset.SMQRecord interface
- Wire Fetch API to use real SMQ records instead of synthetic batches
- Support both agent and broker client connections for record retrieval
## Key Features
- Proper Kafka offset mapping from SeaweedMQ records
- Respects maxRecords limit and batch size constraints
- Graceful error handling for missing topics/partitions
- High water mark boundary checking
## Tests
- Unit tests for SMQRecord interface compliance
- Edge case testing (empty topics, offset boundaries, limits)
- Integration with existing end-to-end Kafka tests
- Benchmark tests for record accessor performance
## Verification
- All integration tests pass
- E2E Sarama test shows 'Found X SMQ records' debug output
- GetStoredRecords now returns real data instead of TODO placeholder
Ready for Phase 2: CreateTopics protocol compliance
- Add end-to-end flow tests for Kafka OffsetCommit to SMQ storage
- Test multiple consumer groups with independent offset tracking
- Validate SMQ file path and format compatibility
- Test error handling and edge cases (negative, zero, max offsets)
- Verify offset encoding/decoding matches SMQ broker format
- Ensure consumer group isolation and proper key generation
- Update Kafka protocol handler to use SMQOffsetStorage for consumer offsets
- Modify OffsetCommit to save consumer offsets using SMQ's filer format
- Modify OffsetFetch to read consumer offsets from SMQ's filer location
- Add proper ConsumerOffsetKey creation with consumer group and instance ID
- Maintain backward compatibility with in-memory storage fallback
- Include comprehensive test coverage for offset handler integration
🎉 HISTORIC ACHIEVEMENT: 100% Consumer Group Protocol Working!
✅ Complete Protocol Implementation:
- FindCoordinator v2: Fixed response format with throttle_time, error_code, error_message
- JoinGroup v5: Fixed request parsing with client_id and GroupInstanceID fields
- SyncGroup v3: Fixed request parsing with client_id and response format with throttle_time
- OffsetFetch: Fixed complete parsing with client_id field and 1-byte offset correction
🔧 Technical Fixes:
- OffsetFetch uses 1-byte array counts instead of 4-byte (compact arrays)
- OffsetFetch topic name length uses 1-byte instead of 2-byte
- Fixed 1-byte off-by-one error in offset calculation
- All protocol version compatibility issues resolved
🚀 Consumer Group Functionality:
- Full consumer group coordination working end-to-end
- Partition assignment and consumer rebalancing functional
- Protocol compatibility with Sarama and other Kafka clients
- Consumer group state management and member coordination complete
This represents a MAJOR MILESTONE in Kafka protocol compatibility for SeaweedFS
- Created consumer group tests for basic functionality, offset management, and rebalancing
- Added debug test to isolate consumer group coordination issues
- Root cause identified: Sarama repeatedly calls FindCoordinator but never progresses to JoinGroup
- Issue: Connections closed after FindCoordinator, preventing coordinator protocol
- Consumer group implementation exists but not being reached by Sarama clients
Next: Fix coordinator connection handling to enable JoinGroup protocol
🎉 MAJOR SUCCESS: Both kafka-go and Sarama now fully working!
Root Cause:
- Individual message batches (from Sarama) had base offset 0 in binary data
- When Sarama requested offset 1, it received batch claiming offset 0
- Sarama ignored it as duplicate, never got actual message 1,2
Solution:
- Correct base offset in record batch header during StoreRecordBatch
- Update first 8 bytes (base_offset field) to match assigned offset
- Each batch now has correct internal offset matching storage key
Results:
✅ kafka-go: 3/3 produced, 3/3 consumed
✅ Sarama: 3/3 produced, 3/3 consumed
Both clients now have full produce-consume compatibility
- Removed debug hex dumps and API request logging
- kafka-go now fully functional: produces and consumes 3/3 messages
- Sarama partially working: produces 3/3, consumes 1/3 messages
- Issue identified: Sarama gets stuck after first message in record batch
Next: Debug Sarama record batch parsing to consume all messages
- Added missing error_code (2 bytes) and session_id (4 bytes) fields for Fetch v7+
- kafka-go now successfully produces and consumes all messages
- Fixed both ListOffsets v1 and Fetch v10 protocol compatibility
- Test shows: ✅ Consumed 3 messages successfully with correct keys/values/offsets
Major breakthrough: kafka-go client now fully functional for produce-consume workflows
- Fixed ListOffsets v1 to parse replica_id field (present in v1+, not v2+)
- Fixed ListOffsets v1 response format - now 55 bytes instead of 64
- kafka-go now successfully passes ListOffsets and makes Fetch requests
- Identified next issue: Fetch response format has incorrect topic count
Progress: kafka-go client now progresses to Fetch API but fails due to Fetch response format mismatch.
- Fixed throttle_time_ms field: only include in v2+, not v1
- Reduced kafka-go 'unread bytes' error from 60 to 56 bytes
- Added comprehensive API request debugging to identify format mismatches
- kafka-go now progresses further but still has 56 bytes format issue in some API response
Progress: kafka-go client can now parse ListOffsets v1 responses correctly but still fails before making Fetch requests due to remaining API format issues.
- Fixed Produce v2+ handler to properly store messages in ledger and update high water mark
- Added record batch storage system to cache actual Produce record batches
- Modified Fetch handler to return stored record batches instead of synthetic ones
- Consumers can now successfully fetch and decode messages with correct CRC validation
- Sarama consumer successfully consumes messages (1/3 working, investigating offset handling)
Key improvements:
- Produce handler now calls AssignOffsets() and AppendRecord() correctly
- High water mark properly updates from 0 → 1 → 2 → 3
- Record batches stored during Produce and retrieved during Fetch
- CRC validation passes because we return exact same record batch data
- Debug logging shows 'Using stored record batch for offset X'
TODO: Fix consumer offset handling when fetchOffset == highWaterMark
- Added comprehensive Fetch request parsing for different API versions
- Implemented constructRecordBatchFromLedger to return actual messages
- Added support for dynamic topic/partition handling in Fetch responses
- Enhanced record batch format with proper Kafka v2 structure
- Added varint encoding for record fields
- Improved error handling and validation
TODO: Debug consumer integration issues and test with actual message retrieval
- Removed connection establishment debug messages
- Removed API request/response logging that cluttered test output
- Removed metadata advertising debug messages
- Kept functional error handling and informational messages
- Tests still pass with cleaner output
The kafka-go writer test now shows much cleaner output while maintaining full functionality.
- Fixed kafka-go writer metadata loop by addressing protocol mismatches:
* ApiVersions v0: Removed throttle_time field that kafka-go doesn't expect
* Metadata v1: Removed correlation ID from response body (transport handles it)
* Metadata v0: Fixed broker ID consistency (node_id=1 matches leader_id=1)
* Metadata v4+: Implemented AllowAutoTopicCreation flag parsing and auto-creation
* Produce acks=0: Added minimal success response for kafka-go internal state updates
- Cleaned up debug messages while preserving core functionality
- Verified kafka-go writer works correctly with WriteMessages completing in ~0.15s
- Added comprehensive test coverage for kafka-go client compatibility
The kafka-go writer now works seamlessly with SeaweedFS Kafka Gateway.
- ApiVersions v0 response: remove unsupported throttle_time field
- Metadata v1: include correlation ID (kafka-go transport expects it after size)
- Metadata v1: ensure broker/partition IDs consistent and format correct
Validated:
- TestMetadataV6Debug passes (kafka-go ReadPartitions works)
- Sarama simple producer unaffected
Root cause: correlation ID handling differences and extra footer in ApiVersions.
chrislu