[PATCH v3 0/1] refs: add 'preparing' phase to the reference-transaction hook

[Eric Ju <eric.peijian@gmail.com>]

The "reference-transaction" hook currently exposes three phases to callers:
"prepared", "committed", and "aborted". The earliest of these, "prepared",
fires after Git has already acquired exclusive locks on every affected
reference. This is well-suited for last-chance validation, but it arrives
too late for any use case that requires coordination before locking, such
as serializing concurrent transactions across distributed storage nodes.

This series introduces a new "preparing" phase that fires before
refs->be->transaction_prepare() is called, that is, before Git takes any
reference lock on disk. Hook scripts that handle this phase receive the full
list of proposed updates and may reject the transaction by returning a
non-zero exit status, causing Git to abort cleanly before any locks are
acquired.

The motivating use case is Gitaly/Praefect, GitLab's distributed Git storage
layer. Praefect must serialize concurrent writes that target the same
references across replicas. With only the "prepared" phase available, by the
time Praefect can observe a transaction the locks are already held, making
reordering impossible. The "preparing" phase provides the necessary
pre-lock window.

Compatibility note: this change is not strictly backwards compatible. Hook
scripts that do not expect unknown phase strings may return an error when
they encounter "preparing". We consider this acceptable for the same reasons
cited when symref support was added to the hook in a8ae923f85 (refs: support
symrefs in 'reference-transaction' hook, 2024-05-07): the hook is documented
as exposing internal implementation details, and its semantics have been
adjusted before. An alternative of introducing a "reference-transaction-v2"
hook was considered but rejected as unnecessarily heavyweight.

---
Changes since v2:

- Shorten and reorder die() message to highlight the phase name early
- Extract the error message into a file-scope static constant to avoid
  duplication across the "preparing" and "prepared" call sites
- Reflow the backwards compatibility paragraph in the commit message

Eric Ju (1):
  refs: add 'preparing' phase to the reference-transaction hook

 Documentation/githooks.adoc      | 19 ++++++++++++-------
 refs.c                           | 12 +++++++++++-
 t/t1416-ref-transaction-hooks.sh | 30 ++++++++++++++++++++++++++----
 t/t5510-fetch.sh                 |  7 ++++++-
 4 files changed, 55 insertions(+), 13 deletions(-)

Range-diff against v2:
1:  4fff10e694 ! 1:  39f7a2bc4b refs: add 'preparing' phase to the reference-transaction hook
    @@ Commit message
         interfering with the locking state.
     
         This change is strictly speaking not backwards compatible. Existing hook
    -    scripts that do not know how to handle unknown phases may treat
    -    'preparing' as an error and return non-zero.
    -    But the hook is considered to expose internal implementation details
    -    of how Git works, and as such we have been a bit more lenient with changing its
    -    exact semantics, like for example in a8ae923f85 (refs: support symrefs in
    -    'reference-transaction' hook, 2024-05-07).
    +    scripts that do not know how to handle unknown phases may treat 'preparing'
    +    as an error and return non-zero. But the hook is considered to expose
    +    internal implementation details of how Git works, and as such we have
    +    been a bit more lenient with changing its exact semantics, like for example
    +    in a8ae923f85 (refs: support symrefs in 'reference-transaction' hook, 2024-05-07).
     
         An alternative would be to introduce a "reference-transaction-v2" hook that
         knows about the new phase. This feels like a rather heavy-weight option though,
    @@ Commit message
     
         Helped-by: Patrick Steinhardt <ps@pks.im>
         Helped-by: Justin Tobler <jltobler@gmail.com>
    +    Helped-by: Karthik Nayak <karthik.188@gmail.com>
         Signed-off-by: Eric Ju <eric.peijian@gmail.com>
     
      ## Documentation/githooks.adoc ##
    @@ Documentation/githooks.adoc: ref and `<ref-name>` is the full name of the ref. W
      ~~~~~~~~~~~~~~~~
     
      ## refs.c ##
    +@@ refs.c: const char *ref_storage_format_to_name(enum ref_storage_format ref_storage_forma
    + 	return be->name;
    + }
    + 
    ++static const char *abort_by_ref_transaction_hook =
    ++	N_("in '%s' phase, update aborted by the reference-transaction hook");
    ++
    + /*
    +  * How to handle various characters in refnames:
    +  * 0: An acceptable character for refs
     @@ refs.c: int ref_transaction_prepare(struct ref_transaction *transaction,
      	if (ref_update_reject_duplicates(&transaction->refnames, err))
      		return REF_TRANSACTION_ERROR_GENERIC;
    @@ refs.c: int ref_transaction_prepare(struct ref_transaction *transaction,
     +	ret = run_transaction_hook(transaction, "preparing");
     +	if (ret) {
     +		ref_transaction_abort(transaction, err);
    -+		die(_("ref updates aborted by the reference-transaction hook at its %s state"), "preparing");
    ++		die(_(abort_by_ref_transaction_hook), "preparing");
     +	}
     +
      	ret = refs->be->transaction_prepare(refs, transaction, err);
    @@ refs.c: int ref_transaction_prepare(struct ref_transaction *transaction,
      	if (ret) {
      		ref_transaction_abort(transaction, err);
     -		die(_("ref updates aborted by hook"));
    -+		die(_("ref updates aborted by the reference-transaction hook at its %s state"), "prepared");
    ++		die(_(abort_by_ref_transaction_hook), "prepared");
      	}
      
      	return 0;
    @@ t/t1416-ref-transaction-hooks.sh: test_expect_success 'hook allows updating ref
     +		fi
     +	EOF
     +	test_must_fail git update-ref HEAD POST 2>err &&
    -+	test_grep "ref updates aborted by the reference-transaction hook at its preparing state" err
    ++	test_grep "in '\''preparing'\'' phase, update aborted by the reference-transaction hook" err
     +'
     +
      test_expect_success 'hook aborts updating ref in prepared state' '
    @@ t/t1416-ref-transaction-hooks.sh: test_expect_success 'hook aborts updating ref
      	EOF
      	test_must_fail git update-ref HEAD POST 2>err &&
     -	test_grep "ref updates aborted by hook" err
    -+	test_grep "ref updates aborted by the reference-transaction hook at its prepared state" err
    ++	test_grep "in '\''prepared'\'' phase, update aborted by the reference-transaction hook" err
      '
      
      test_expect_success 'hook gets all queued updates in prepared state' '
-- 
2.51.0