You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kafka.apache.org by ew...@apache.org on 2016/06/14 16:50:39 UTC
kafka git commit: KAFKA-3699: Update protocol page on website to
explain how KIP-35 should be used
Repository: kafka
Updated Branches:
refs/heads/trunk b8ea094b4 -> b1ba54025
KAFKA-3699: Update protocol page on website to explain how KIP-35 should be used
\u2026uld be used
Author: Ashish Singh <as...@cloudera.com>
Reviewers: Oleksiy Krivoshey <ol...@luckyteam.co.uk>, Gwen Shapira <cs...@gmail.com>, Magnus Edenhill <ma...@edenhill.se>, Dana Powers <da...@gmail.com>, Ewen Cheslack-Postava <ew...@confluent.io>
Closes #1395 from SinghAsDev/KAFKA-3699
Project: http://git-wip-us.apache.org/repos/asf/kafka/repo
Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/b1ba5402
Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/b1ba5402
Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/b1ba5402
Branch: refs/heads/trunk
Commit: b1ba54025fc872e14e1ff97fde018637826a3a5e
Parents: b8ea094
Author: Ashish Singh <as...@cloudera.com>
Authored: Tue Jun 14 09:49:54 2016 -0700
Committer: Ewen Cheslack-Postava <me...@ewencp.org>
Committed: Tue Jun 14 09:50:30 2016 -0700
----------------------------------------------------------------------
docs/protocol.html | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/kafka/blob/b1ba5402/docs/protocol.html
----------------------------------------------------------------------
diff --git a/docs/protocol.html b/docs/protocol.html
index c26f16b..e28b0a8 100644
--- a/docs/protocol.html
+++ b/docs/protocol.html
@@ -114,6 +114,32 @@
<p>Currently all versions are baselined at 0, as we evolve these APIs we will indicate the format for each version individually.</p>
+<h5><a id="api_versions" href="#api_versions">Retrieving Supported API versions</a></h5>
+<p>In order for a client to successfully talk to a broker, it must use request versions supported by the broker. Clients
+ may work against multiple broker versions, however to do so the clients need to know what versions of various APIs a
+ broker supports. Starting from 0.10.0.0, brokers provide information on various versions of APIs they support. Details
+ of this new capability can be found <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-35+-+Retrieving+protocol+version">here</a>.
+ Clients may use the supported API versions information to take appropriate actions such as propagating an unsupported
+ API version error to application or choose an API request/response version supported by both the client and broker.
+ The following sequence maybe used by a client to obtain supported API versions from a broker.</p>
+<ol>
+ <li>Client sends <code>ApiVersionsRequest</code> to a broker after connection has been established with the broker. If SSL is enabled,
+ this happens after SSL connection has been established.</li>
+ <li>On receiving <code>ApiVersionsRequest</code>, a broker returns its full list of supported ApiKeys and
+ versions regardless of current authentication state (e.g., before SASL authentication on an SASL listener, do note that no
+ Kafka protocol requests may take place on a SSL listener before the SSL handshake is finished). If this is considered to
+ leak information about the broker version a workaround is to use SSL with client authentication which is performed at an
+ earlier stage of the connection where the <code>ApiVersionRequest</code> is not available. Also, note that broker versions older
+ than 0.10.0.0 do not support this API and will either ignore the request or close connection in response to the request.</li>
+ <li>If multiple versions of an API are supported by broker and client, clients are recommended to use the latest version supported
+ by the broker and itself.</li>
+ <li>Deprecation of a protocol version is done by marking an API version as deprecated in protocol documentation.</li>
+ <li>Supported API versions obtained from a broker, is valid only for current connection on which that information is obtained.
+ In the event of disconnection, the client should obtain the information from broker again, as the broker might have
+ upgraded/downgraded in the mean time.</li>
+</ol>
+
+
<h5><a id="sasl_handshake" href="#sasl_handshake">SASL Authentication Sequence</a></h5>
<p>The following sequence is used for SASL authentication:
<ol>