kafka-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ewe...@apache.org
Subject kafka git commit: KAFKA-3699: Update protocol page on website to explain how KIP-35 should be used
Date Tue, 14 Jun 2016 16:50:39 GMT
Repository: kafka
Updated Branches:
  refs/heads/trunk b8ea094b4 -> b1ba54025


KAFKA-3699: Update protocol page on website to explain how KIP-35 should be used

…uld be used

Author: Ashish Singh <asingh@cloudera.com>

Reviewers: Oleksiy Krivoshey <oleksiy@luckyteam.co.uk>, Gwen Shapira <cshapi@gmail.com>,
Magnus Edenhill <magnus@edenhill.se>, Dana Powers <dana.powers@gmail.com>, Ewen
Cheslack-Postava <ewen@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 <asingh@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>


Mime
View raw message