docs: new capability to advertise session IDs
In future patches, we will add the ability for Git servers and clients to advertise unique session IDs via protocol capabilities. This allows for easier debugging when both client and server logs are available. Signed-off-by: Josh Steadmon <steadmon@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Josh Steadmon committed
Nov 11, 2020 at 15:29 UTC
f5cdbe485f5c560eb53734a2b25309409786b636
2 files changed
+28
-2
Documentation/technical/protocol-capabilities.txt
+15
-2
@@ -27,8 +27,8 @@ and 'push-cert' capabilities are sent and recognized by the receive-pack
27
(push to server) process.
28
29
The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
30
-by both upload-pack and receive-pack protocols. The 'agent' capability
31
-may optionally be sent in both protocols.
30
+by both upload-pack and receive-pack protocols. The 'agent' and 'session-id'
31
+capabilities may optionally be sent in both protocols.
32
33
All other capabilities are only recognized by the upload-pack (fetch
34
from server) process.
@@ -365,3 +365,16 @@ If the upload-pack server advertises the 'filter' capability,
365
fetch-pack may send "filter" commands to request a partial clone
366
or partial fetch and request that the server omit various objects
367
from the packfile.
368
+
369
+session-id=<session id>
370
+-----------------------
371
+
372
+The server may advertise a session ID that can be used to identify this process
373
+across multiple requests. The client may advertise its own session ID back to
374
+the server as well.
375
+
376
+Session IDs should be unique to a given process. They must fit within a
377
+packet-line, and must not contain non-printable or whitespace characters. The
378
+current implementation uses trace2 session IDs (see
379
+link:api-trace2.html[api-trace2] for details), but this may change and users of
380
+the session ID should not rely on this fact.
Documentation/technical/protocol-v2.txt
+13
@@ -492,3 +492,16 @@ form `object-format=X`) to notify the client that the server is able to deal
492
with objects using hash algorithm X. If not specified, the server is assumed to
493
only handle SHA-1. If the client would like to use a hash algorithm other than
494
SHA-1, it should specify its object-format string.
495
+
496
+session-id=<session id>
497
+~~~~~~~~~~~~~~~~~~~~~~~
498
+
499
+The server may advertise a session ID that can be used to identify this process
500
+across multiple requests. The client may advertise its own session ID back to
501
+the server as well.
502
+
503
+Session IDs should be unique to a given process. They must fit within a
504
+packet-line, and must not contain non-printable or whitespace characters. The
505
+current implementation uses trace2 session IDs (see
506
+link:api-trace2.html[api-trace2] for details), but this may change and users of
507
+the session ID should not rely on this fact.