uber / uber/submitqueue

submitqueue: port internal queue contracts to proto (submitqueue/core/messagequeue)

Open
#356 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
225
Forks
11
Avg merge
3d 8h
Merged PRs (30d)
61

Description

Problem

The repo's queue-contract convention (doc/rfc/messagequeue-contract.md) is proto3 payloads serialized as protojson, with a contract package owning both the messages and their topic_keys bindings — api/runway/messagequeue/ is the reference example and stovepipe/core/messagequeue/ follows it. The submitqueue domain has not been ported: there is no submitqueue/core/messagequeue/ package, and 11 of its 12 topics still carry hand-rolled JSON via ToBytes/FromBytes methods on entity types.

Current state per topic:

Topic key Payload Serialization
start RequestID entity JSON
cancel CancelRequest entity JSON
validate RequestID entity JSON
batch RequestID entity JSON
score BatchID entity JSON
speculate BatchID entity JSON
prioritize QueueID entity JSON
build BatchID entity JSON
buildsignal BuildID entity JSON
conclude BatchID entity JSON
log RequestLog entity JSON
merge MergeRequest ✅ protojson (api/runway/messagequeue — correctly borrowed; runway owns that queue's contract)

Consequences of the split: no additive-evolution guarantees (protojson's unknown-field discard, UPPER_SNAKE enums, int64-as-string are only enforced on merge), no topic_keys binding or contract test for internal topics, and queue-payload serialization concerns living on domain entities (which are supposed to be pure data).

Work

  1. Create submitqueue/core/messagequeue/ mirroring the reference layout: proto/ sources, committed protopb/, and the generic protojson glue (Marshal / Unmarshal[T] / TopicKeys) — same as stovepipe/core/messagequeue/.
  2. Define proto messages for each payload shape (request-ID carrier, batch-ID carrier, build-ID carrier, queue-ID carrier, cancel request, request log) and bind each topic key to its message via the topic_keys option from api/base/messagequeue.
  3. Add the contract test: protojson round-trip per message + every topic key bound to exactly one message.
  4. Migrate producers and consumers topic by topic (gateway Land/Cancel publishes, all orchestrator stage controllers, core/request.PublishLog, and the DLQ controllers/republish tooling — anything touching msg.Payload).
  5. Once no queue payload uses them, remove ToBytes/FromBytes from the submitqueue entity types (RequestID, BatchID, BuildID, QueueID, CancelRequest, RequestLog, and the full-entity variants) so entities go back to being pure data.
  6. Bazel visibility stays domain-scoped per the internal-contract rule.

Caveats

  • Wire-format flip: protojson output (snake_case fields, int64-as-string) differs from the current encoding/json entity output, so in-flight messages from before a cutover won't parse after it. Port topic-by-topic with drained queues (fine at the current pre-prod stage), or give consumers a transitional dual-format read if needed.
  • The log topic crosses gateway ↔ orchestrator but both are submitqueue-domain services, so the internal contract location (submitqueue/core/messagequeue/) is correct — it must not go under api/.
  • The message-ID convention is a separate concern tracked in #352 (intent-scoped message IDs); porting payloads to proto neither depends on nor resolves it, but call sites will be touched by both — coordinate to avoid churn.

Related

  • #352 — intent-scoped message IDs (same call sites)
  • #357 — stovepipe counterpart (retire leftover JSON serializers, contracts for upcoming stages)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with doc/rfc/messagequeue-contract.md and compare api/runway/messagequeue/ with stovepipe/core/messagequeue/. Map the twelve topics across gateway Land/Cancel, orchestrator stage controllers, core/request.PublishLog, and the DLQ controllers and republish tooling. Done means submitqueue/core/messagequeue/ has the proto contracts, generated protopb, glue, bindings, and contract tests, all payload users are migrated, and the listed entity serializers are removed.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
distributed-systems
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.