feat(extensions): fake implementations with error injection

submitqueue/core/fakemarker/BUILD.bazel

@@ -0,0 +1,19 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "fakemarker",
+    srcs = ["fakemarker.go"],
+    importpath = "github.com/uber/submitqueue/submitqueue/core/fakemarker",
+    visibility = ["//visibility:public"],
+    deps = ["//submitqueue/entity"],
+)
+
+go_test(
+    name = "fakemarker_test",
+    srcs = ["fakemarker_test.go"],
+    embed = [":fakemarker"],
+    deps = [
+        "//submitqueue/entity",
+        "@com_github_stretchr_testify//assert",
+    ],
+)

submitqueue/core/fakemarker/fakemarker.go

@@ -0,0 +1,58 @@
+// 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 fakemarker holds the shared "sq-fake=<token>" change-URI marker
+// convention used by the extension fakes to inject failures from a request
+// payload. Each fake recognizes its own tokens (e.g. "build-fail", "push-error");
+// this package only locates a token within change URIs so the parsing lives in
+// one place instead of being copied into every fake. It is intended for examples
+// and tests only, never production.
+package fakemarker
+
+import (
+	"strings"
+
+	"github.com/uber/submitqueue/submitqueue/entity"
+)
+
+// Prefix introduces a marker token in a change URI: "sq-fake=<token>".
+const Prefix = "sq-fake="
+
+// Token returns the marker token embedded in the first URI that carries one, or
+// "" if none do. The token ends at the first "&" or "#" delimiter, so a marker
+// may sit among other query parameters or a fragment (e.g.
+// "github://o/r/pull/1/a?sq-fake=build-fail&attempt=2").
+func Token(uris []string) string {
+	for _, u := range uris {
+		if i := strings.Index(u, Prefix); i >= 0 {
+			rest := u[i+len(Prefix):]
+			if j := strings.IndexAny(rest, "&#"); j >= 0 {
+				rest = rest[:j]
+			}
+			return rest
+		}
+	}
+	return ""
+}
+
+// TokenInChanges returns the first marker token found across all changes' URIs,
+// or "" if none carry one.
+func TokenInChanges(changes []entity.Change) string {
+	for _, c := range changes {
+		if tok := Token(c.URIs); tok != "" {
+			return tok
+		}
+	}
+	return ""
+}

submitqueue/core/fakemarker/fakemarker_test.go

@@ -0,0 +1,115 @@
+// 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 fakemarker
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/uber/submitqueue/submitqueue/entity"
+)
+
+func TestToken(t *testing.T) {
+	tests := []struct {
+		name string
+		uris []string
+		want string
+	}{
+		{
+			name: "no uris",
+			uris: nil,
+			want: "",
+		},
+		{
+			name: "no marker",
+			uris: []string{"github://o/r/pull/1/a"},
+			want: "",
+		},
+		{
+			name: "marker at end of uri",
+			uris: []string{"github://o/r/pull/1/a?sq-fake=build-fail"},
+			want: "build-fail",
+		},
+		{
+			name: "marker trimmed at & delimiter",
+			uris: []string{"github://o/r/pull/1/a?sq-fake=build-fail&attempt=2"},
+			want: "build-fail",
+		},
+		{
+			name: "marker trimmed at # delimiter",
+			uris: []string{"github://o/r/pull/1/a?sq-fake=build-fail#frag"},
+			want: "build-fail",
+		},
+		{
+			name: "marker before a query param it precedes",
+			uris: []string{"github://o/r/pull/1/a?sq-fake=push-error&foo=bar#frag"},
+			want: "push-error",
+		},
+		{
+			name: "marker on a later uri",
+			uris: []string{"github://o/r/pull/1/a", "github://o/r/pull/2/b?sq-fake=conflict"},
+			want: "conflict",
+		},
+		{
+			name: "first marker wins",
+			uris: []string{"github://o/r/pull/1/a?sq-fake=first", "github://o/r/pull/2/b?sq-fake=second"},
+			want: "first",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, Token(tt.uris))
+		})
+	}
+}
+
+func TestTokenInChanges(t *testing.T) {
+	tests := []struct {
+		name    string
+		changes []entity.Change
+		want    string
+	}{
+		{
+			name:    "no changes",
+			changes: nil,
+			want:    "",
+		},
+		{
+			name:    "no marker",
+			changes: []entity.Change{{URIs: []string{"github://o/r/pull/1/a"}}},
+			want:    "",
+		},
+		{
+			name:    "marker on first change",
+			changes: []entity.Change{{URIs: []string{"github://o/r/pull/1/a?sq-fake=build-fail&attempt=2"}}},
+			want:    "build-fail",
+		},
+		{
+			name: "marker on later change",
+			changes: []entity.Change{
+				{URIs: []string{"github://o/r/pull/1/a"}},
+				{URIs: []string{"github://o/r/pull/2/b?sq-fake=push-error"}},
+			},
+			want: "push-error",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, TokenInChanges(tt.changes))
+		})
+	}
+}

submitqueue/extension/buildrunner/fake/BUILD.bazel

@@ -0,0 +1,25 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "fake",
+    srcs = ["fake.go"],
+    importpath = "github.com/uber/submitqueue/submitqueue/extension/buildrunner/fake",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//submitqueue/core/fakemarker",
+        "//submitqueue/entity",
+        "//submitqueue/extension/buildrunner",
+    ],
+)
+
+go_test(
+    name = "fake_test",
+    srcs = ["fake_test.go"],
+    embed = [":fake"],
+    deps = [
+        "//submitqueue/entity",
+        "//submitqueue/extension/buildrunner",
+        "@com_github_stretchr_testify//assert",
+        "@com_github_stretchr_testify//require",
+    ],
+)

submitqueue/extension/buildrunner/fake/fake.go

@@ -0,0 +1,122 @@
+// 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 fake provides a buildrunner.BuildRunner whose outcome is driven by the
+// triggered changes. With no marker every build immediately succeeds, behaving
+// as a best-case stub for wiring and baselines. Failures are injected by
+// embedding a marker token in a head change URI of the form "sq-fake=<token>":
+//
+//	sq-fake=trigger-error -> Trigger returns a non-nil error
+//	sq-fake=build-fail    -> Status reports BuildStatusFailed
+//	sq-fake=build-error   -> Status returns a non-nil error
+//
+// The runner is stateless: Trigger encodes the desired terminal outcome into the
+// returned BuildID, and Status decides the result purely from the BuildID it is
+// given — no per-build bookkeeping. This means any runner instance can answer
+// Status for an ID minted by any other (Trigger and Status can even live in
+// different controllers/processes), and a single running stack can exercise the
+// negative paths purely by varying request payloads. It is intended for examples
+// and tests only, never production.
+package fake
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"strings"
+
+	"github.com/uber/submitqueue/submitqueue/core/fakemarker"
+	"github.com/uber/submitqueue/submitqueue/entity"
+	"github.com/uber/submitqueue/submitqueue/extension/buildrunner"
+)
+
+// Recognized marker tokens. See the package doc for the convention.
+const (
+	tokenTriggerError = "trigger-error"
+	tokenFail         = "build-fail"
+	tokenError        = "build-error"
+)
+
+// outcomeOK is the BuildID outcome segment for a build that should succeed.
+const outcomeOK = "ok"
+
+// runner is a buildrunner.BuildRunner that reports every build as succeeded
+// unless a marker token in a head change URI requests otherwise. It holds no
+// per-build state: the outcome is encoded in the BuildID at Trigger and read
+// back out at Status. Uniqueness comes from a random suffix per ID, so it needs
+// no shared counter and never collides across instances or processes.
+type runner struct{}
+
+// New returns a buildrunner.BuildRunner that defaults to succeeding and honors
+// marker tokens embedded in head change URIs.
+func New() buildrunner.BuildRunner {
+	return &runner{}
+}
+
+// Trigger fails when a head change URI carries the trigger-error marker;
+// otherwise it returns a unique BuildID that encodes the terminal outcome the
+// build should report at Status time (decided from the head marker). The base
+// changes and metadata are ignored.
+func (r *runner) Trigger(_ context.Context, _ []entity.Change, head []entity.Change, _ entity.BuildMetadata) (entity.BuildID, error) {
+	outcome := outcomeOK
+	switch fakemarker.TokenInChanges(head) {
+	case tokenTriggerError:
+		return entity.BuildID{}, fmt.Errorf("fake: marked trigger error")
+	case tokenFail:
+		outcome = tokenFail
+	case tokenError:
+		outcome = tokenError
+	}
+
+	// Encode the outcome in the ID (e.g. "fake-build-fail-a1b2c3d4") so Status is
+	// stateless. The random suffix keeps IDs globally unique across instances and
+	// processes — the BuildID uniqueness contract — without any shared state.
+	suffix, err := randomSuffix()
+	if err != nil {
+		return entity.BuildID{}, fmt.Errorf("fake: generating build id: %w", err)
+	}
+	id := fmt.Sprintf("fake-%s-%s", outcome, suffix)
+	return entity.BuildID{ID: id}, nil
+}
+
+// randomSuffix returns a short random hex string used to keep fake BuildIDs
+// globally unique. Hex digits never spell the outcome marker tokens, so the
+// suffix cannot interfere with Status decoding the outcome via substring match.
+func randomSuffix() (string, error) {
+	var b [4]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b[:]), nil
+}
+
+// Status decides the result purely from the BuildID's encoded outcome. IDs that
+// carry no recognized outcome (including those not minted by this fake) default
+// to succeeded, keeping the runner best-case.
+func (r *runner) Status(_ context.Context, buildID entity.BuildID) (entity.BuildStatus, entity.BuildMetadata, error) {
+	switch {
+	case strings.Contains(buildID.ID, tokenError):
+		return entity.BuildStatusUnknown, nil, fmt.Errorf("fake: marked build error")
+	case strings.Contains(buildID.ID, tokenFail):
+		return entity.BuildStatusFailed, nil, nil
+	default:
+		return entity.BuildStatusSucceeded, nil, nil
+	}
+}
+
+// Cancel is a no-op and always succeeds.
+func (r *runner) Cancel(_ context.Context, _ entity.BuildID) error {
+	return nil
+}