root
/
kafka
mirror of https://github.com/apache/kafka.git
1
0
Fork 0
Code Issues Actions 2 Packages Projects Releases Wiki Activity

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
This commit is contained in:
Ashish Singh 2016-06-14 09:49:54 -07:00 committed by Ewen Cheslack-Postava
parent b8ea094b42
commit b1ba54025f
1 changed files with 26 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/protocol.html
View File

@ -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> <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> <h5><a id="sasl_handshake" href="#sasl_handshake">SASL Authentication Sequence</a></h5>
<p>The following sequence is used for SASL authentication: <p>The following sequence is used for SASL authentication:
<ol> <ol>