Return X-Gerrit-UpdatedRef in the response headers of WRITE requests
For each REST-API request, we can track which refs were changed via
GitReferenceUpdatedListener which is already used and tested by the
plugins, caches, and indices.
Using the information of which refs were changed, for each request that
changed any of the refs, we return the changed refs in the response
header of `X-Gerrit-UpdatedRef` in the format:
REPONAME~REFNAME~OLD_SHA-1~NEW_SHA-1.
This is useful because:
1. Successful operations on changes are signaled by an update on the
meta ref (and similarly for other operations such as updating accounts
signaled by update to the account ref).
2. Returning the SHA-1s generically in the response headers can reduce
load on Gerrit: users will not have to call Gerrit to get this
information since Gerrit already always returns it. For example, some
users need the new SHA-1 of the destination branch, which we don't
return on submission, and right now they are forced to call Gerrit again
after submission to retrieve the SHA-1.
3. Because of (2), for multi-site setups, we are not impacted by
replication lags that could be caused by the users calling Gerrit more
times than they really need.
While at it, we change WebSession to be an abstract class instead of an
interface to have ref updates as part of the class.
Change-Id: Iaac3bf1036408c7f0b2d48494b544032c76c5462
diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt
index eabcaa9..8709843 100644
--- a/Documentation/rest-api.txt
+++ b/Documentation/rest-api.txt
@@ -244,6 +244,38 @@
Given the trace ID an administrator can find the corresponding logs and
investigate issues more easily.
+[[updated-refs]]
+=== X-Gerrit-UpdatedRef
+For each write REST request, we return X-Gerrit-UpdatedRef headers as the refs
+that were updated in the current request (involved in a ref transaction in the
+current request).
+
+The format of those headers is `PROJECT_NAME~REF_NAME~OLD_SHA-1~NEW_SHA-1`. The
+project and ref names are URL-encoded, and must use %7E for '~'.
+
+A new SHA-1 of `0000000000000000000000000000000000000000` is treated as a
+deleted ref.
+If the new SHA-1 is not `0000000000000000000000000000000000000000`, the ref was
+either updated or created.
+If the old SHA-1 is `0000000000000000000000000000000000000000`, the ref was
+created.
+
+.Example Request
+----
+ DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940
+----
+
+.Example Response
+----
+HTTP/1.1 204 NO CONTENT
+ Content-Disposition: attachment
+ Content-Type: application/json; charset=UTF-8
+ X-Gerrit-UpdatedRef: myProject~refs%2Fchanges%2F01%2F1%2F1~deadbeefdeadbeefdeadbeefdeadbeefdeadbeef~0000000000000000000000000000000000000000
+ X-Gerrit-UpdatedRef: myProject~refs%2Fchanges%2F01%2F1%2Fmeta~deadbeefdeadbeefdeadbeefdeadbeefdeadbeef~0000000000000000000000000000000000000000
+
+ )]}'
+----
+
GERRIT
------
Part of link:index.html[Gerrit Code Review]
