feat(client): a SubmitQueue client library, with list and watch

## Summary

### Why?

Seeing what a queue was doing meant running the demo tool, which creates pull requests as a side effect. The live table it draws is the good part, and it was trapped inside a tool whose job is generating traffic. Meanwhile the gateway has exposed a paged `List` RPC that no client has ever called, and the CLI's `status` reads one request at a time by id — so there was no way to ask what a whole queue was doing without adding to it.

Underneath that sat a duplication problem heading somewhere worse. Three binaries dialled the gateway for themselves, `parseStrategy` existed twice verbatim, and the demo was growing a second copy of everything the CLI would eventually need. Extracting only the table would have treated the symptom.

### What?

`submitqueue/client` is now the client for the domain: dialling, the calls made against a gateway, and the terminal view of a queue. Both binaries become thin over it — the CLI is flag parsing, and the demo is GitHub scaffolding plus calls into the library. The demo's `main.go` drops from 1069 lines to 369 with no change in what it does, and its GitHub REST helpers move to their own file, since they are not SubmitQueue client code.

**`list` and `watch`.** `list` draws a queue's recent requests once, following continuation tokens so a caller gets the answer rather than a cursor. `watch` seeds its rows from the same listing, or from named ids, and then follows them with the tracker that already existed. Its set is fixed when it starts: a watch that grew as its queue did would never finish, and finishing is what makes it usable from a script — it exits non-zero if anything settles anywhere other than `landed`, the contract the demo used to own alone.

**Addressing.** `-addr` is unchanged and passed to the dialler untouched, so `dns:///host:port` and `unix:///path.sock` work alongside a plain `host:port`. Transport security is a separate `-tls` flag rather than part of the address, because gRPC keeps target resolution and credentials apart — there is no scheme meaning "use TLS", and inventing one would only mislead. The demo's odd `-gateway` flag is renamed to `-addr` to match the three real clients.

**The changes column.** It was the one part of the table tied to having created the pull requests. A row now carries cells of text and an optional URL, supplied by the caller: the demo passes pull request numbers linked to their pages, and a client watching a queue it did not create passes the change URIs the gateway reports. The hyperlink and width handling is shared, including that padding counts on-screen width — a hyperlink is mostly escape bytes occupying no columns.

**Credentials.** The client can present a bearer token. `TokenEnv` names the variable holding it rather than carrying the token, so a secret never reaches a command line, and an unset variable sends nothing rather than failing. Nothing in this repository checks it — the gateway admits every caller — so it is there for a gateway reached through something that does: a proxy, a sidecar, an ingress terminating auth ahead of the service. gRPC refuses per-RPC credentials on an insecure connection unless they declare they do not need transport security, which is why the credential declares it and `-tls` stays a separate choice.

## Test Plan

✅ `bazel test //...` — all 112 targets pass, including the Docker-backed integration and end-to-end suites.

✅ The extraction is behaviour-preserving by construction: all 23 view tests moved to `submitqueue/client` and pass unchanged there. None was lost — the demo had 28, and 23 plus the 5 file-layout tests that stayed accounts for all of them.

✅ `TestCredentialsReachTheServerOverPlaintext` runs a real gRPC server on a loopback port and asserts the token arrives as `Bearer …`. This is the case that silently breaks otherwise: gRPC refuses per-RPC credentials on an insecure connection unless they declare they do not need transport security, so a token that works over TLS can simply never be sent without it.

✅ `List` paging: pages are followed to the end, a limit cuts across pages without over-fetching, an empty page ends the walk so a server that never stops handing out tokens cannot spin, and `-since` becomes a receipt-time bound while its absence leaves the window open.

Not driven by hand: `list` and `watch` have not been pointed at a running gateway, so the end-to-end shape of the rendered table against real data is unverified. Their paging, settle and verdict logic is covered hermetically above.

Author: behinddwalls

Makefile

@@ -57,6 +57,8 @@ DEMO_REPO ?= behinddwalls/sq-demo
 COUNT ?= 3
 FILES ?= 3
 STACKED ?= false
+SINCE ?= 1h
+LIMIT ?= 50
 LAND ?= true
 WATCH ?= true
 QUEUE ?= demo-queue
@@ -159,7 +161,7 @@ demo-pr: ## Create N PRs in the demo repo, enqueue each as it is created, and wa
 		-count $(COUNT) \
 		-files $(FILES) \
 		-stacked=$(STACKED) \
-		-gateway $(GATEWAY_ADDR) \
+		-addr $(GATEWAY_ADDR) \
 		-queue $(QUEUE) \
 		-strategy $(STRATEGY) \
 		-land=$(LAND) -watch=$(WATCH)
@@ -227,6 +229,14 @@ land-status: ## Read a landed request's status (SQID=... [QUEUE=demo-queue])
 	@$(BAZEL) run //service/submitqueue/gateway/client:gateway -- \
 		-addr $(GATEWAY_ADDR) status -queue $(QUEUE) -sqid $(SQID)
 
+land-list: ## Show a queue's recent requests as a table (QUEUE=demo-queue SINCE=1h LIMIT=50)
+	@$(BAZEL) run //service/submitqueue/gateway/client:gateway -- \
+		-addr $(GATEWAY_ADDR) list -queue $(QUEUE) -since $(SINCE) -limit $(LIMIT)
+
+land-watch: ## Follow a queue's requests until they settle (QUEUE=demo-queue SINCE=15m LIMIT=50)
+	@$(BAZEL) run //service/submitqueue/gateway/client:gateway -- \
+		-addr $(GATEWAY_ADDR) watch -queue $(QUEUE) -since $(SINCE) -limit $(LIMIT)
+
 license-fix: ## Add missing license headers to source files
 	@$(BAZEL) run //tool/linter/licenseheader -- --fix
 

doc/howto/PROVIDER-E2E.md

@@ -129,6 +129,40 @@ The command exits non-zero if any request settles anywhere other than `landed`,
 
 ## Watching it work
 
+The queue itself is readable without creating any traffic:
+
+```bash
+make land-list                       # a table of recent requests
+make land-list SINCE=24h LIMIT=200   # a wider window
+make land-watch                      # follow them until they settle
+```
+
+Both draw the same table `make demo-pr` does — the demo tool and the CLI share it — but against whatever the queue already holds, so watching a queue no longer means adding to it. `land-watch` fixes its set when it starts and exits non-zero if any request in that set finishes anywhere other than `landed`, which makes it usable from a script. A request accepted after the watch begins is not picked up: a watch that grew as the queue did would never finish.
+
+Under the hood these are `client list` and `client watch`, which take a queue and reach any gateway:
+
+```bash
+bazel run //service/submitqueue/gateway/client:gateway -- \
+  -addr sq.example.com:443 -tls list -queue my-queue -since 1h
+```
+
+`-addr` is passed to the dialler untouched, so `dns:///host:port` and `unix:///path.sock` work as well as a plain `host:port`. Transport security is a separate flag rather than part of the address, because gRPC keeps target resolution and credentials apart — there is no `grpcs://` to write.
+
+Bear in mind that a request reads `batched` for the whole of its active life (see above), so a listing of a busy queue is mostly `batched` rows until the pipeline reports its finer stages.
+
+### Authentication
+
+The gateway admits every caller. It is a sandbox stack, and nothing in it checks a credential.
+
+The client can still present one, for a gateway reached through something that does — a proxy, a mesh sidecar, an ingress that terminates auth ahead of the service. It reads `SQ_TOKEN` by default and sends it as `Authorization: Bearer …`; `-token-env` names a different variable, and an unset one sends nothing rather than failing, which is how it stays usable against a stack that wants no credential.
+
+```bash
+SQ_TOKEN=$(cat ~/.sq-token) bazel run //service/submitqueue/gateway/client:gateway -- \
+  -addr sq.example.com:443 -tls list -queue my-queue
+```
+
+### Service logs
+
 ```bash
 docker compose -p submitqueue-provider logs -f runway-service
 ```

service/submitqueue/demo/pr/BUILD.bazel

@@ -2,17 +2,16 @@ load("@rules_go//go:def.bzl", "go_binary", "go_library", "go_test")
 
 go_library(
     name = "go_default_library",
-    srcs = ["main.go"],
+    srcs = [
+        "github.go",
+        "main.go",
+    ],
     importpath = "github.com/uber/submitqueue/service/submitqueue/demo/pr",
     visibility = ["//visibility:private"],
     deps = [
-        "//api/base/change/protopb:go_default_library",
         "//api/base/mergestrategy/protopb:go_default_library",
-        "//api/submitqueue/gateway/protopb:go_default_library",
         "//platform/base/change/github:go_default_library",
-        "//submitqueue/entity:go_default_library",
-        "@org_golang_google_grpc//:go_default_library",
-        "@org_golang_google_grpc//credentials/insecure:go_default_library",
+        "//submitqueue/client:go_default_library",
     ],
 )
 
@@ -27,9 +26,7 @@ go_test(
     srcs = ["main_test.go"],
     embed = [":go_default_library"],
     deps = [
-        "//api/submitqueue/gateway/protopb:go_default_library",
         "@com_github_stretchr_testify//assert:go_default_library",
         "@com_github_stretchr_testify//require:go_default_library",
-        "@org_golang_google_grpc//:go_default_library",
     ],
 )

service/submitqueue/demo/pr/github.go

@@ -0,0 +1,125 @@
+// Copyright (c) 2025 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+)
+
+// githubClient is the slice of GitHub's REST API this tool needs: read a
+// branch, create a branch, commit a file, open a pull request.
+type githubClient struct {
+	root  string
+	token string
+	owner string
+	repo  string
+}
+
+func (g *githubClient) branchSHA(ctx context.Context, branch string) (string, error) {
+	var out struct {
+		Object struct {
+			SHA string `json:"sha"`
+		} `json:"object"`
+	}
+	if err := g.do(ctx, http.MethodGet, "/git/ref/heads/"+branch, nil, &out); err != nil {
+		return "", err
+	}
+	return out.Object.SHA, nil
+}
+
+func (g *githubClient) createBranch(ctx context.Context, branch, fromSHA string) error {
+	return g.do(ctx, http.MethodPost, "/git/refs",
+		map[string]string{"ref": "refs/heads/" + branch, "sha": fromSHA}, nil)
+}
+
+// commitFile writes a file on a branch and returns the resulting commit SHA —
+// the commit a change URI pins the pull request to.
+func (g *githubClient) commitFile(ctx context.Context, branch, path, content, message string) (string, error) {
+	body := map[string]string{
+		"message": message,
+		"content": base64.StdEncoding.EncodeToString([]byte(content)),
+		"branch":  branch,
+	}
+	var out struct {
+		Commit struct {
+			SHA string `json:"sha"`
+		} `json:"commit"`
+	}
+	if err := g.do(ctx, http.MethodPut, "/contents/"+path, body, &out); err != nil {
+		return "", err
+	}
+	return out.Commit.SHA, nil
+}
+
+func (g *githubClient) openPR(ctx context.Context, title, head, base string) (int, string, error) {
+	body := map[string]string{"title": title, "head": head, "base": base, "body": "Opened by service/submitqueue/demo/pr."}
+	var out struct {
+		Number  int    `json:"number"`
+		HTMLURL string `json:"html_url"`
+	}
+	if err := g.do(ctx, http.MethodPost, "/pulls", body, &out); err != nil {
+		return 0, "", err
+	}
+	return out.Number, out.HTMLURL, nil
+}
+
+// do issues one authenticated request against the repository, decoding into out
+// when it is non-nil.
+func (g *githubClient) do(ctx context.Context, method, path string, body any, out any) error {
+	endpoint := fmt.Sprintf("%s/repos/%s/%s%s", g.root, g.owner, g.repo, path)
+
+	var payload []byte
+	if body != nil {
+		var err error
+		if payload, err = json.Marshal(body); err != nil {
+			return fmt.Errorf("encode request for %s: %w", endpoint, err)
+		}
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, endpoint, bytes.NewReader(payload))
+	if err != nil {
+		return fmt.Errorf("build request for %s: %w", endpoint, err)
+	}
+	req.Header.Set("Accept", "application/vnd.github+json")
+	req.Header.Set("Authorization", "Bearer "+g.token)
+	if payload != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("%s %s: %w", method, endpoint, err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		var detail bytes.Buffer
+		_, _ = detail.ReadFrom(resp.Body)
+		return fmt.Errorf("%s %s returned %s: %s", method, endpoint, resp.Status, strings.TrimSpace(detail.String()))
+	}
+	if out == nil {
+		return nil
+	}
+	if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
+		return fmt.Errorf("decode response from %s: %w", endpoint, err)
+	}
+	return nil
+}