1// ListOffsetsRequest requests partition offsets from Kafka for use in
2// consuming records.
3//
4// Version 5, introduced in Kafka 2.2.0, is the same as version 4. Using
5// version 5 implies you support Kafka's OffsetNotAvailableException
6// See KIP-207 for details.
7//
8// Version 7, introduced in Kafka 3.0, supports -3 as a timestamp to return
9// the timestamp and offset for the record with the largest timestamp.
10//
11// Version 8, introduced in Kafka 3.4, supports -4 as a timestamp to return
12// the local log start offset (in the context of tiered storage, see KIP-405).
13ListOffsetsRequest => key 2, max version 8, flexible v6+
14 // ReplicaID is the broker ID to get offsets from. As a Kafka client, use -1.
15 // The consumer replica ID (-1) causes requests to only succeed if issued
16 // against the leader broker.
17 ReplicaID: int32(-1)
18 // IsolationLevel configures which record offsets are visible in the
19 // response. READ_UNCOMMITTED (0) makes all records visible. READ_COMMITTED
20 // (1) makes non-transactional and committed transactional records visible.
21 // READ_COMMITTED means all offsets smaller than the last stable offset and
22 // includes aborted transactions (allowing consumers to discard aborted
23 // records).
24 IsolationLevel: int8 // v2+
25 // Topics is an array of topics to get offsets for.
26 Topics: [=>]
27 // Topic is a topic to get offsets for.
28 Topic: string
29 // Partitions is an array of partitions in a topic to get offsets for.
30 Partitions: [=>]
31 // Partition is a partition of a topic to get offsets for.
32 Partition: int32
33 // CurrentLeaderEpoch, proposed in KIP-320 and introduced in Kafka 2.1.0,
34 // allows brokers to check if the client is fenced (has an out of date
35 // leader) or is using an unknown leader.
36 //
37 // The initial leader epoch can be determined from a MetadataResponse.
38 // To skip log truncation checking, use -1.
39 CurrentLeaderEpoch: int32(-1) // v4+
40 // Timestamp controls which offset to return in a response for this
41 // partition.
42 //
43 // The offset returned will be the one of the message whose timestamp is
44 // the first timestamp greater than or equal to this requested timestamp.
45 //
46 // If no such message is found, then no offset is returned (-1).
47 //
48 // There exist two special timestamps: -2 corresponds to the earliest
49 // timestamp, and -1 corresponds to the latest.
50 //
51 // If you are talking to Kafka 3.0+, there exists an additional special
52 // timestamp -3 that returns the latest timestamp produced so far and its
53 // corresponding offset. This is subtly different from the latest offset,
54 // because timestamps are client-side generated. More importantly though,
55 // because this returns the latest produced timestamp, this can be used
56 // to determine topic "liveness" (when was the last produce?).
57 // Previously, this was not easy to determine. See KIP-734 for more
58 // detail.
59 //
60 // If you are talking to Kafka 3.4+ and using request version 8+ (for
61 // KIP-405), the new special timestamp -4 returns the local log start
62 // offset. In the context of tiered storage, the earliest local log start
63 // offset is the offset actually available on disk on the broker.
64 Timestamp: int64
65 // MaxNumOffsets is the maximum number of offsets to report.
66 // This was removed after v0.
67 MaxNumOffsets: int32(1) // v0-v0
68
69// ListOffsetsResponse is returned from a ListOffsetsRequest.
70ListOffsetsResponse =>
71 ThrottleMillis(3) // v2+
72 // Topics is an array of topic / partition responses corresponding to
73 // the requested topics and partitions.
74 Topics: [=>]
75 // Topic is the topic this array slot is for.
76 Topic: string
77 // Partitions is an array of partition responses corresponding to
78 // the requested partitions for a topic.
79 Partitions: [=>]
80 // Partition is the partition this array slot is for.
81 Partition: int32
82 // ErrorCode is any error for a topic partition in a ListOffsets request.
83 //
84 // TOPIC_AUTHORIZATION_FAILED is returned if the client is not authorized
85 // to describe the topic.
86 //
87 // INVALID_REQUEST is returned if the requested topic partitions had
88 // contained duplicates.
89 //
90 // KAFKA_STORAGE_EXCEPTION is returned if the topic / partition is in
91 // an offline log directory.
92 //
93 // UNSUPPORTED_FOR_MESSAGE_FORMAT is returned if the broker is using
94 // Kafka 0.10.0 messages and the requested timestamp was not -1 nor -2.
95 //
96 // NOT_LEADER_FOR_PARTITION is returned if the broker is not a leader
97 // for this partition. This means that the client has stale metadata.
98 // If the request used the debug replica ID, the returned error will
99 // be REPLICA_NOT_AVAILABLE.
100 //
101 // UNKNOWN_TOPIC_OR_PARTITION is returned if the broker does not know
102 // of the requested topic or partition.
103 //
104 // FENCED_LEADER_EPOCH is returned if the broker has a higher leader
105 // epoch than what the request sent.
106 //
107 // UNKNOWN_LEADER_EPOCH is returned if the request used a leader epoch
108 // that the broker does not know about.
109 //
110 // OFFSET_NOT_AVAILABLE, introduced in Kafka 2.2.0 with produce request
111 // v5+, is returned when talking to a broker that is a new leader while
112 // that broker's high water mark catches up. This avoids situations where
113 // the old broker returned higher offsets than the new broker would. Note
114 // that if unclean leader election is allowed, you could still run into
115 // the situation where offsets returned from list offsets requests are
116 // not monotonically increasing. This error is only returned if the
117 // request used the consumer replica ID (-1). If the client did not use
118 // a v5+ list offsets request, LEADER_NOT_AVAILABLE is returned.
119 // See KIP-207 for more details.
120 ErrorCode: int16
121 // OldStyleOffsets is a list of offsets. This was removed after
122 // version 0 and, since it is so historic, is undocumented.
123 OldStyleOffsets: [int64] // v0-v0
124 // If the request was for the earliest or latest timestamp (-2 or -1), or
125 // if an offset could not be found after the requested one, this will be -1.
126 Timestamp: int64(-1) // v1+
127 // Offset is the offset corresponding to the record on or after the
128 // requested timestamp. If one could not be found, this will be -1.
129 Offset: int64(-1) // v1+
130 // LeaderEpoch is the leader epoch of the record at this offset,
131 // or -1 if there was no leader epoch.
132 LeaderEpoch: int32(-1) // v4+
View as plain text