commit 63b81f2bde703ae07787a940e8fdf9a1828605b1
author Han-Wen Nienhuys <hanwen@google.com> Wed Feb 17 10:31:01 2021 +0100
committer Han-Wen Nienhuys <hanwen@google.com> Thu Feb 18 08:01:04 2021 +0100
tree 5a9851755ecb9e32f7871e6960bd0a4f940c7d24
parent a29ad29bc365e1aad78b1944e27ba4f54f77703d

GetChange: provide meta=SHA1 option

This change lets callers inspect a change at a given NoteDb commit.

    $ curl -u admin:secret http://localhost:8080/a/changes/101/'?pp=1&O=22'
    ..
      "current_revision": "f3cccef96155ed3f9de2aaed44d8cf00960a21ca",
      "revisions": {
        "f3cccef96155ed3f9de2aaed44d8cf00960a21ca": {
          "kind": "REWORK",
          "_number": 5,

    $ curl -u admin:secret http://localhost:8080/a/changes/101/'?pp=1&O=22&meta=8ebdac0e8a2047ee2d2433a09f05de230d3050f2'
    ..
      "current_revision": "e24af8d95295181064078a99a3bde31cf9b643a2",
      "revisions": {
        "e24af8d95295181064078a99a3bde31cf9b643a2": {
          "kind": "NO_CODE_CHANGE",
          "_number": 3,

This is part of an alternate approach to event notifications, where
notification is split into two parts:

1) notifying a client that *something* changed

2) letting the client discover precisely *what* changed.

This change provides a way for clients to get 2): A subscriber, when
receiving a notification, can use /changes/ID?meta=XXX to get the old
and new states of the ChangeInfo. By analyzing the difference between
both ChangeInfos, subscribers can tell what happened.

As a follow-up, we plan to provide a diffing functionality as a
built-in REST endpoint.

If the server hasn't seen the NoteDb meta SHA1 yet, it replies with
412. This is useful in a distributed setting: notifications can be
delivered ahead of the underlying Git data. If this happens, this also
results in a 412 error code. The client can respond by waiting and
retrying.

For 1), the minimal amount of information required is a list of opaque
identifiers (change number, old meta SHA1, new meta SHA1).

The opaque identifiers could be discovered through several means

* By finding recently modified changes, through a query such as
  "age:1h status:open", and comparing the meta SHA1s with output of an
  earlier query

* By executing ls-remote, and comparing its output with an earlier
  run.

* By hooking into ref updates at the storage level, and exposing the
  result over SSH. For vanilla JGit, this will need JGit changes,
  because RefChangedEvent in JGit doesn't provide per-Ref data.

  At Google, the plan is to generate these notifications at the storage
  level in the global ref database.

This approach to notifications has several advantages over the
existing stream-events mechanism:

* The event notification only contains opaque data, and can be sent to
  any subscriber without leaking data. The GetChange endpoint enforces
  visibility.

* It uses the same endpoint as the UI, so there is no chance of new
  features being forgotten for stream-events (for example, stream-events
  does not support attention set updates).

* It doesn't rely on having a stream. Without streaming, the
  change index (query "status:open age:INTERVAL") or the output of ls-remote
  can still provide data on for polling clients.

* A subscriber can protect against missed notifications, by keeping
  track of the meta SHA1s locally. If the connection breaks, they can
  resynchronize using the mechanism for polling clients.

Change-Id: Ia54acb37e1187bc64e190d5694de0b17674595f8