README
¶
Runway message queue contract
The published, language-neutral contract for the merge queues Runway owns. A client — in any language — publishes a merge request and consumes the result without access to Runway's Go types or storage. See the message queue contract RFC for the design.
Payloads are defined as proto3 messages in proto/merge.proto and generated into protopb/; the proto is the authority and a non-Go client compiles against it directly. On the wire, payloads are serialized as protobuf JSON (protojson), so the queue keeps storing self-describing JSON. The message types are generated, so the Go helpers in this package are just generic protojson glue — Marshal(m) and Unmarshal[T](b, m) — for Go callers; field names stay snake_case (UseProtoNames) and enums serialize as their UPPER_SNAKE value name.
The shared field types Change and MergeStrategy come from api/base/change and api/base/mergestrategy, imported by the contract.
Merge strategy
Each MergeStep carries a Strategy (from api/base/mergestrategy) naming how that step is integrated into the merge target. REBASE, SQUASH_REBASE, and MERGE transform the change onto the branch tip and produce new revisions. PROMOTE is different: it integrates the exact revision as-is, advancing the merge target to an already-existing commit with no content transform and no new revision. Each backend realizes PROMOTE natively — git fast-forward, Mercurial bookmark advance, Subversion/Perforce copy — so for PROMOTE a step's StepOutput.id is the same revision the request named rather than a freshly created one. It is the strategy a post-merge verifier (e.g. Stovepipe) uses to advance a verified branch like verified/main to an already-landed, already-verified commit. DEFAULT lets the server pick per queue configuration.
Topic keys
The binding between a topic key and its payload lives in each message's topic_keys option (defined in api/base/messagequeue); TopicKeys reads it back by reflection. A topic key is a stable logical name, not a concrete wire topic — each implementer maps the key to whatever topic name its broker/queue requires. Our Go wiring maps it via consumer.TopicRegistry.
| Message | Direction | Topic keys |
|---|---|---|
MergeRequest |
client → Runway | merge-conflict-check, merge |
MergeResult |
Runway → client | merge-conflict-check-signal, merge-signal |
One message serves a queue pair because a merge-conflict check is a dry run of a merge: Runway applies the same ordered steps onto the same merge target, and the topic key the request arrives on decides whether it commits the result and reports the produced revisions. A request on merge-conflict-check is a dry run; a request on merge commits.
Result shape
MergeResult.outcome is an Outcome enum (OUTCOME_UNSPECIFIED/SUCCEEDED/FAILED): SUCCEEDED means mergeable (check) or merged (commit), FAILED a conflict or a failed apply; reason carries the explanation when FAILED. Per-step detail is in steps (request order): each StepResult.outputs is the list of StepOutputs the step produced on the merge target, in application order (the order they were created). A committing merge populates outputs; a dry-run check, an already-present change, or a failed step leaves them empty. StepOutput.id is the VCS-neutral revision identifier (git SHA, Mercurial hash, Subversion revision, Perforce changelist, …), with room to grow (author, timestamp, …).
Evolution
Contract changes are additive-only: add new fields; never remove, rename, repurpose, or retype an existing field, and never reuse a field number. protojson ignores unknown fields on read and omits zero-valued fields on write, so a new optional field is backward-compatible in both directions.
Documentation
¶
Overview ¶
Package messagequeue holds Runway's external message-queue contract: the wire payloads for the merge queues Runway owns, defined by the proto files in proto/ and generated into protopb/. The proto is the language-neutral authority; the generated Go types in protopb are the binding for Go callers.
The message types are generated into protopb; this package adds only generic protojson glue (Marshal/Unmarshal) and the topic-key reflection lookup (TopicKeys), so there is no per-message serialization code. Payloads are serialized as protobuf JSON, not binary, so the MySQL-backed queue keeps storing self-describing JSON. The topic key that carries each payload is declared on the message itself via the topic_keys proto option (see api/base/messagequeue).
One contract serves two queue pairs because a merge-conflict check is a dry run of a merge: Runway applies the same ordered steps onto the same target branch, and the only difference is whether it commits the result and reports the revisions it produced. The topic key a request arrives on encodes that choice — the merge-conflict-check pair for a dry run, the merge pair for a committing merge — so MergeRequest and MergeResult are identical on both.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
Marshal serializes any contract message to protojson bytes for the queue payload, keeping the proto field names (snake_case) on the wire.
Types ¶
type MergeRequest ¶
type MergeRequest = protopb.MergeRequest
MergeRequest is the payload a client publishes to one of Runway's merge queues: the merge-conflict-check topic for a dry-run check, the merge topic for a committing merge.
type MergeResult ¶
type MergeResult = protopb.MergeResult
MergeResult is the payload Runway publishes to the corresponding signal queue once a request completes.
type MergeStep ¶
MergeStep is one step of an ordered merge: a single set of change(s) applied with a strategy.
type StepOutput ¶
type StepOutput = protopb.StepOutput
StepOutput is a single revision a merge step produced on the merge target.
type StepResult ¶
type StepResult = protopb.StepResult
StepResult reports what happened to a single MergeStep.
type TopicKey ¶
TopicKey is the typed identifier used to look up a queue backend, topic name, and subscription config in a consumer.TopicRegistry. The constants below are the wire topic names a client uses to publish to / consume from Runway's merge queues; they are the same strings each message lists in its topics option.
const ( // TopicKeyMergeConflictCheck carries dry-run merge-conflict check requests. // A client publishes a MergeRequest here; Runway attempts the merge without // committing and reports only whether it was mergeable. TopicKeyMergeConflictCheck TopicKey = "merge-conflict-check" // TopicKeyMergeConflictCheckSignal carries merge-conflict check results. // Runway publishes a MergeResult here (with no produced revisions); the // requesting client consumes it. TopicKeyMergeConflictCheckSignal TopicKey = "merge-conflict-check-signal" // TopicKeyMerge carries committing merge requests. A client publishes a // MergeRequest here; Runway applies the steps, commits the result, and // reports the revisions it produced. TopicKeyMerge TopicKey = "runway-merge" // TopicKeyMergeSignal carries committing merge results. Runway publishes a // MergeResult here (with the produced revisions populated); the requesting // client consumes it. TopicKeyMergeSignal TopicKey = "merge-signal" )
Source Files
Directories