seaweedfs/weed/mq/kafka/API_VERSION_MATRIX.md

Kafka API Version Matrix Audit

Summary

This document audits the advertised API versions in handleApiVersions() against actual implementation support in validateAPIVersion() and handlers.

Current Status: ALL VERIFIED ✅

API Version Matrix

API Key	API Name	Advertised	Validated	Handler Implemented	Status
18	ApiVersions	v0-v4	v0-v4	v0-v4	✅ Match
3	Metadata	v0-v7	v0-v7	v0-v7	✅ Match
0	Produce	v0-v7	v0-v7	v0-v7	✅ Match
1	Fetch	v0-v7	v0-v7	v0-v7	✅ Match
2	ListOffsets	v0-v2	v0-v2	v0-v2	✅ Match
19	CreateTopics	v0-v5	v0-v5	v0-v5	✅ Match
20	DeleteTopics	v0-v4	v0-v4	v0-v4	✅ Match
10	FindCoordinator	v0-v3	v0-v3	v0-v3	✅ Match
11	JoinGroup	v0-v6	v0-v6	v0-v6	✅ Match
14	SyncGroup	v0-v5	v0-v5	v0-v5	✅ Match
8	OffsetCommit	v0-v2	v0-v2	v0-v2	✅ Match
9	OffsetFetch	v0-v5	v0-v5	v0-v5	✅ Match
12	Heartbeat	v0-v4	v0-v4	v0-v4	✅ Match
13	LeaveGroup	v0-v4	v0-v4	v0-v4	✅ Match
15	DescribeGroups	v0-v5	v0-v5	v0-v5	✅ Match
16	ListGroups	v0-v4	v0-v4	v0-v4	✅ Match
32	DescribeConfigs	v0-v4	v0-v4	v0-v4	✅ Match
22	InitProducerId	v0-v4	v0-v4	v0-v4	✅ Match
60	DescribeCluster	v0-v1	v0-v1	v0-v1	✅ Match

Implementation Details

Core APIs

• ApiVersions (v0-v4): Supports both flexible (v3+) and non-flexible formats. v4 added for Kafka 8.0.0 compatibility.
• Metadata (v0-v7): Full version support with flexible format in v7+
• Produce (v0-v7): Supports transactional writes and idempotent producers
• Fetch (v0-v7): Includes schema-aware fetching and multi-batch support

Consumer Group Coordination

• FindCoordinator (v0-v3): v3+ supports flexible format
• JoinGroup (v0-v6): Capped at v6 (first flexible version)
• SyncGroup (v0-v5): Full consumer group protocol support
• Heartbeat (v0-v4): Consumer group session management
• LeaveGroup (v0-v4): Clean consumer group exit
• OffsetCommit (v0-v2): Consumer offset persistence
• OffsetFetch (v0-v5): v3+ includes throttle_time_ms, v5+ includes leader_epoch

Topic Management

• CreateTopics (v0-v5): v2+ uses compact arrays and tagged fields
• DeleteTopics (v0-v4): Full topic deletion support
• ListOffsets (v0-v2): Offset listing for partitions

Admin & Discovery

• DescribeCluster (v0-v1): AdminClient compatibility (KIP-919)
• DescribeGroups (v0-v5): Consumer group introspection
• ListGroups (v0-v4): List all consumer groups
• DescribeConfigs (v0-v4): Configuration inspection
• InitProducerId (v0-v4): Transactional producer initialization

Verification Source

All version ranges verified from handler.go:

• SupportedApiKeys array (line 1196): Advertised versions
• validateAPIVersion() function (line 2903): Validation ranges
• Individual handler implementations: Actual version support

Last verified: 2025-10-13

Maintenance Notes

1. After adding new API handlers, update all three locations:
   • SupportedApiKeys array
   • validateAPIVersion() map
   • This documentation
2. Test new versions with kafka-go and Sarama clients
3. Ensure flexible format support for v3+ APIs where applicable