Skip to content

feat(runway): dlq reconciler for merge topics - #459

Merged
behinddwalls merged 1 commit into
mainfrom
preetam/runway-dlq-reconciler
Jul 30, 2026
Merged

feat(runway): dlq reconciler for merge topics#459
behinddwalls merged 1 commit into
mainfrom
preetam/runway-dlq-reconciler

Conversation

@behinddwalls

@behinddwalls behinddwalls commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Why?

SubmitQueue records in-flight merge work before publishing and then waits for exactly one MergeResult echoing its correlation id. Runway is stateless and the sole responder on that id, so every request must resolve to a result — or the client waits forever.

The primary controllers resolve what they can name: conflicts and invalid requests become a FAILED result, infrastructure faults are nacked for retry. But a fault that never recovers exhausts the retry budget and dead-letters. Nothing consumed those dead-letter topics, so the request produced no signal at all and the client's correlation id hung indefinitely.

What?

Adds runway/controller/dlq, a reconciler that subscribes to an inbound topic's _dlq queue and, for each dead-lettered MergeRequest, republishes a FAILED MergeResult echoing the correlation id to the corresponding signal topic. dlq.TopicKey derives the DLQ topic key from the primary one so the two stay in lockstep.

Unlike the SubmitQueue and Stovepipe DLQ reconcilers this one writes no entity state — Runway has none, and the signal is the resolution. A payload that cannot be decoded carries no correlation id and is dropped rather than retried forever.

Wires two instances in the server (one per inbound topic) on a dedicated consumer running under errs.AlwaysRetryableProcessor, so a transient publish failure retries indefinitely rather than dead-lettering the dead-letter. The DLQ consumer is started alongside the primary one and stopped with the same 30s drain on shutdown; both stop errors are joined into the exit status.

Test Plan

✅ bazel test //runway/... — 5/5 pass, including new //runway/controller/dlq coverage for republish-on-dead-letter, the drop-undecodable-payload path, and publish-failure propagation
✅ bazel build //service/runway/... — wiring compiles
✅ make gazelle, make fmt

Stack

  1. @ feat(runway): dlq reconciler for merge topics #459
  2. feat(runway): git-backed merger with REBASE #460
  3. feat(runway): git merger SQUASH_REBASE and MERGE #461
  4. feat(runway): git merger PROMOTE #462
  5. feat(runway): wire the git merger into the server #463
  6. feat(runway): reject changes that disagree on provider #476
  7. docs: define the URI as the unit of change #477

This was referenced Jul 29, 2026
Merged
Merged
Merged
Merged
Merged
Open
@behinddwalls
behinddwalls marked this pull request as ready for review July 30, 2026 14:47
@behinddwalls
behinddwalls requested review from a team and sbalabanov as code owners July 30, 2026 14:47
@behinddwalls
behinddwalls force-pushed the preetam/runway-terminal-errors branch from 24ac344 to 8878096 Compare July 30, 2026 16:12
@behinddwalls
behinddwalls force-pushed the preetam/runway-dlq-reconciler branch from 6c0f8d9 to 42a0cd1 Compare July 30, 2026 16:12
@behinddwalls
behinddwalls marked this pull request as draft July 30, 2026 16:14
@behinddwalls
behinddwalls force-pushed the preetam/runway-terminal-errors branch from 8878096 to 930df02 Compare July 30, 2026 16:15
@behinddwalls
behinddwalls force-pushed the preetam/runway-dlq-reconciler branch from 42a0cd1 to d8ee8ae Compare July 30, 2026 16:16
@behinddwalls
behinddwalls marked this pull request as ready for review July 30, 2026 17:06
@behinddwalls
behinddwalls force-pushed the preetam/runway-terminal-errors branch from 930df02 to 8ee23c0 Compare July 30, 2026 17:13
@behinddwalls
behinddwalls force-pushed the preetam/runway-dlq-reconciler branch from d8ee8ae to b358333 Compare July 30, 2026 17:13
@behinddwalls
behinddwalls force-pushed the preetam/runway-terminal-errors branch from 8ee23c0 to 133a045 Compare July 30, 2026 17:55
@behinddwalls
behinddwalls force-pushed the preetam/runway-dlq-reconciler branch from b358333 to d976bb9 Compare July 30, 2026 17:55
Base automatically changed from preetam/runway-terminal-errors to main July 30, 2026 17:58
@behinddwalls
feat(runway): dlq reconciler for merge topics
c766cf8 
## Summary

### Why?

SubmitQueue records in-flight merge work before publishing and then waits for exactly one `MergeResult` echoing its correlation id. Runway is stateless and the sole responder on that id, so every request must resolve to a result — or the client waits forever.

The primary controllers resolve what they can name: conflicts and invalid requests become a `FAILED` result, infrastructure faults are nacked for retry. But a fault that never recovers exhausts the retry budget and dead-letters. Nothing consumed those dead-letter topics, so the request produced no signal at all and the client's correlation id hung indefinitely.

### What?

Adds `runway/controller/dlq`, a reconciler that subscribes to an inbound topic's `_dlq` queue and, for each dead-lettered `MergeRequest`, republishes a `FAILED` `MergeResult` echoing the correlation id to the corresponding signal topic. `dlq.TopicKey` derives the DLQ topic key from the primary one so the two stay in lockstep.

Unlike the SubmitQueue and Stovepipe DLQ reconcilers this one writes no entity state — Runway has none, and the signal *is* the resolution. A payload that cannot be decoded carries no correlation id and is dropped rather than retried forever.

Wires two instances in the server (one per inbound topic) on a dedicated consumer running under `errs.AlwaysRetryableProcessor`, so a transient publish failure retries indefinitely rather than dead-lettering the dead-letter. The DLQ consumer is started alongside the primary one and stopped with the same 30s drain on shutdown; both stop errors are joined into the exit status.

## Test Plan

✅ `bazel test //runway/...` — 5/5 pass, including new `//runway/controller/dlq` coverage for republish-on-dead-letter, the drop-undecodable-payload path, and publish-failure propagation
✅ `bazel build //service/runway/...` — wiring compiles
✅ `make gazelle`, `make fmt`
@behinddwalls
behinddwalls force-pushed the preetam/runway-dlq-reconciler branch from d976bb9 to c766cf8 Compare July 30, 2026 18:05
This was referenced Jul 30, 2026
Open
Open
@behinddwalls
behinddwalls merged commit dfcf52f into main Jul 30, 2026
15 checks passed
@behinddwalls
behinddwalls deleted the preetam/runway-dlq-reconciler branch July 30, 2026 20:09
behinddwalls added a commit that referenced this pull request Jul 31, 2026
@behinddwalls
feat(runway): git-backed merger with REBASE (#460)
d57b36b 
## Summary

### Why?

Runway's `merger` extension has had exactly one implementation — `noop`,
which always succeeds. Nothing actually merges anything. This lands the
first real backend: a `Merger` driven by the `git` CLI against a local
checkout.

It ships REBASE only. The strategy-specific apply paths are small and
independent, but the machinery underneath them — the pinned git runtime,
object resolution, the reset/apply/push cycle, contention retry, dry-run
discard, conflict classification — is shared and is the bulk of what
needs review. Landing it with one strategy keeps that review separable
from the per-strategy mechanics that follow in this stack.

### What?

Adds `runway/extension/merger/git`.

**A change is a range of commits, not a commit.** A change URI pins a
pull request to a single head SHA, but a pull request is routinely
several commits. Applying the head alone applies only that commit's diff
against its own parent: it conflicts against context its predecessors
would have established, or — when the commits touch different files —
succeeds while silently dropping everything before the head. So the unit
replayed is the range from the change's merge base with the target up to
its head. A change already contained in the target has an empty range
and is a no-op, which is what keeps redelivery idempotent.

A range runs through git's sequencer, which changes the control flow
versus a single pick: the operation stops on a commit it declines and
`--skip` advances to the next rather than ending. Two kinds of commit
stop it harmlessly — one already present on the target, and one that was
empty to begin with — and both are skipped. Anything else is a real
conflict, and the in-progress pick is aborted so the checkout stays
usable. The commits an apply produced are read back off the checkout
rather than tracked per-invocation, which stays correct when the
sequencer drops some.

**Referenced commits are guaranteed present before anything is
applied.** The default fetch refspec is `+refs/heads/*`, which does not
cover a provider's change refs: a pull request head never also pushed as
a branch — the normal case for a fork — is simply absent, and the apply
then fails with git's "bad object", indistinguishable from a conflict.
Every commit the request names is now fetched and verified up front, for
all steps, so an unusable request fails without having mutated the
checkout. Commits are requested by SHA (relying on the server serving a
want for a reachable-but-unadvertised object, which github.com allows),
falling back to the provider's canonical ref, with deployment-supplied
refspecs as a last resort. Neither fetch is shallow — the range needs
ancestry.

A commit a *reachable* remote cannot supply is terminal; a remote that
will not answer stays retryable. The first is a property of the request,
the second a property of the moment.

**One seam for change providers.** Every URI is reduced to the only
three things the merger needs — the commit to apply, the ref the
provider publishes it under, and a label for synthesized messages.
`github://` and `git://` are supported; an unrecognized scheme is
terminal. Adding a provider is one case in that mapping rather than a
change to any apply path.

**Optional staleness check.** Fetching by SHA guarantees the merger
applies exactly the commit the URI names, not that it is still the
change's head — a force-push leaves the superseded commit fetchable on
most hosts. When enabled, each change's canonical ref is read (one ref
advertisement, no object transfer) and a mismatch is terminal.

**Atomicity, contention, dry run.** Nothing reaches the remote until the
final push. If the push is rejected because the remote tip moved, the
whole reset/apply/push cycle retries up to a bounded number of attempts.
`CheckMergeability` runs the identical apply path but never pushes, then
resets and reports empty outputs, committing intermediate steps locally
so a multi-step check sees the same conflict surface a real merge would.

**Runtime hygiene.** Every invocation uses an explicitly pinned git
runtime and a scrubbed environment — no system or global config, no
interactive prompts. That leaves no ambient identity, so the committer
is injected per-invocation.

`isConcreteStrategy` currently admits only REBASE; SQUASH_REBASE, MERGE
and PROMOTE are rejected as invalid requests until their apply paths
land later in this stack. The merger is not wired into the server yet,
so this adds no production behavior.

## Test Plan

✅ `bazel test //runway/...` — 6/6 targets pass, including the new
`//runway/extension/merger/git` suite (40s)

The suite drives a real git binary against throwaway repositories.
Beyond the single-commit cases (stacked URIs, already-landed changes,
multi-step requests, conflicts, checkout recovery, contention retry,
give-up after max attempts, DEFAULT resolution, dry runs), it covers
what this change is actually about: a multi-commit change expressed as
**one** URI for both disjoint and overlapping edits, a partially-landed
change, an empty commit inside a range, a conflict inside a range
leaving no sequencer state behind, stacked multi-commit changes not
duplicating each other's commits, a head reachable only via its
pull-request ref, an unavailable commit classified as invalid rather
than conflicting, the staleness check on and off, and provider
resolution across schemes.

The regression tests were verified to fail against head-only picking:
reverting just that line fails 5 of them, and they pass with the range
applied.


## Stack
1. #459
1. @ #460
1. #461
1. #462
1. #463
1. #476
1. #477
behinddwalls added a commit that referenced this pull request Jul 31, 2026
@behinddwalls
feat(runway): git merger SQUASH_REBASE and MERGE (#461)
44322c3 
## Summary

### Why?

The git merger landed with REBASE only. `SQUASH_REBASE` and `MERGE` are
part of the wire contract SubmitQueue already publishes against, and
until they apply here a request naming either is rejected as an invalid
request. This adds the two remaining transforming strategies on top of
the shared apply machinery.

### What?

**SQUASH_REBASE** applies each change exactly like REBASE — replaying
every commit it introduces — then collapses what that change produced
into a single commit. The squash unit is the change: a change of ten
commits becomes one, and a step whose change carries several URIs yields
one commit per URI. Those URIs are a stack of pull requests, and
squashing them together would erase the per-PR boundary the stack exists
to express.

Two degenerate cases produce no output rather than an empty commit. A
change already present on the target creates no commits, so there is
nothing to squash. A change that does create commits whose net tree
matches the base would squash to an empty commit, so the intermediates
are dropped. Both keep redelivery idempotent.

**MERGE** creates a `--no-ff` merge commit per change, which keeps the
change's original commits reachable through second-parent history — the
property that separates it from the picking strategies, which rewrite
those hashes. A change already contained in HEAD is skipped rather than
merged again.

**Not every failed merge is a conflict.** `applyMerge` previously
reported any `git merge` failure as `ErrConflict`, which tells the
client its change collides with the target even when nothing collided.
Failures are now classified, and the case that matters in practice is an
unrelated history.

**Importing an unrelated history.** A repository migration arrives as an
ordinary change in the target repo whose branch carries the source
repo's whole history. Being in the target repo is what makes the commits
fetchable; it says nothing about ancestry, and git refuses to merge two
graphs with no common ancestor. `AllowUnrelatedHistories` lifts that
refusal for a queue that exists to perform such imports. It is off by
default because the refusal is a genuine safeguard — with it always on,
merging the wrong object silently produces a nonsense result instead of
failing. Without the option, the refusal is now reported as an invalid
request rather than a conflict.

MERGE is the only strategy that can serve a migration: it is the only
one that preserves the imported commits' original hashes, and the
picking strategies have no range to compute across disjoint graphs, so
they reject such a change explicitly and say so.

## Test Plan

✅ `bazel test //runway/extension/merger/git:go_default_test` — passes
(58s)

New coverage: SQUASH_REBASE collapsing a multi-commit change into one
commit while landing all of its content, a two-URI change yielding one
squashed commit per URI in application order, SQUASH_REBASE over an
already-landed change producing none, MERGE creating one merge commit
for a multi-commit change, MERGE skipping a change already an ancestor
of the tip, and the MERGE dry-run path.

For migration specifically: importing a three-commit unrelated history
and asserting every imported commit is reachable **under its original
hash**, the merge commit has two parents, and the target keeps its own
files; redelivery of the same request being a no-op; the import rejected
as an invalid request (explicitly not a conflict) when the option is
off, leaving the remote and checkout untouched; and both picking
strategies rejecting an unrelated history rather than rewriting it.


## Stack
1. #459
1. #460
1. @ #461
1. #462
1. #463
1. #476
1. #477
behinddwalls added a commit that referenced this pull request Jul 31, 2026
@behinddwalls
feat(runway): git merger PROMOTE (#462)
732f68f 
## Summary

### Why?

`PROMOTE` is the last strategy in the wire contract without an apply
path. It is also the one that does not fit the shared machinery: the
transforming strategies build new commits locally and push
`HEAD:target`, while PROMOTE advances the target to a commit that
already exists, unchanged.

### What?

Adds the `promote` path, dispatched directly from `process` rather than
through `applyTransforming`.

**Fast-forward only.** After resetting to the remote tip, promote
classifies the named commit three ways. Already the tip, or contained in
it — idempotent success, no push. A strict descendant of the tip — a
genuine fast-forward, pushed as `<sha>:refs/heads/<target>`. Anything
else has diverged and is a terminal `ErrConflict`; PROMOTE never creates
a commit to reconcile the two.

Because it moves the ref to an existing commit, a change of any size
arrives whole by construction — its ancestry comes with it, so PROMOTE
needs none of the range machinery the picking strategies do.

**Exclusivity.** `resolveAndValidate` rejects a PROMOTE that is not the
entire request — one step, one change, one URI — as `ErrInvalidRequest`.
Two reasons, both structural: a pre-existing commit cannot descend from
commits an earlier transforming step just produced, and the push targets
an exact SHA rather than the locally-built HEAD, so there is nothing for
a preceding step to contribute.

**Its own availability checks.** promote bypasses `tryApply`, so it
performs the object-availability and staleness checks itself. Without
them a commit the remote cannot supply makes every containment query
fail with a plain error, which the consumer retries forever rather than
reporting a request that can never succeed.

**Contention.** The same bounded retry as the transforming path, but the
loop re-runs the classification rather than the apply: if the push is
rejected the tip may have moved, and the commit that was a fast-forward
a moment ago may now be contained (success) or divergent (conflict).

The push is a single atomic ref update, so PROMOTE needs no separate
atomicity argument. A dry-run check performs the identical
classification and returns without pushing, reporting no output.

With this the merger implements every strategy in the contract;
`isConcreteStrategy` now admits all four.

## Test Plan

✅ `bazel test //runway/extension/merger/git:go_default_test` — passes
(61s)

New cases: fast-forward promote, promote of a commit already contained
in the tip, divergent promote rejected as a conflict, a multi-commit
change promoted whole to the exact named commit, an unavailable commit
reported as an invalid request rather than retried, both dry-run
classifications, and the two composition rules (PROMOTE with a second
step, PROMOTE with a second URI) rejected as invalid requests.


## Stack
1. #459
1. #460
1. #461
1. @ #462
1. #463
1. #476
1. #477
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kevinlnew kevinlnew kevinlnew approved these changes
@sbalabanov sbalabanov Awaiting requested review from sbalabanov sbalabanov is a code owner

Assignees

No one assigned

Labels

ChangesPlanned

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@behinddwalls @kevinlnew