From 648e491ab6046a2831efb4e47926543d5ae6c49b Mon Sep 17 00:00:00 2001 From: Preetam Dwivedi Date: Fri, 24 Jul 2026 10:52:40 -0700 Subject: [PATCH] feat(speculation): speculator extension contract Add submitqueue/extension/speculation/speculator, the one controller-facing speculation extension. Speculate returns the build and cancel actions to take from a queue snapshot and can never express a verdict; Config/Factory carry per-queue wiring. Includes the generated mocks. Register the speculation packages with the mocks make target so `make mocks` regenerates them. --- Makefile | 2 +- .../speculation/speculator/BUILD.bazel | 9 ++ .../speculation/speculator/README.md | 13 +++ .../speculation/speculator/mock/BUILD.bazel | 13 +++ .../speculator/mock/speculator_mock.go | 97 +++++++++++++++++++ .../speculation/speculator/speculator.go | 54 +++++++++++ 6 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 submitqueue/extension/speculation/speculator/BUILD.bazel create mode 100644 submitqueue/extension/speculation/speculator/README.md create mode 100644 submitqueue/extension/speculation/speculator/mock/BUILD.bazel create mode 100644 submitqueue/extension/speculation/speculator/mock/speculator_mock.go create mode 100644 submitqueue/extension/speculation/speculator/speculator.go diff --git a/Makefile b/Makefile index a0178520..2437968d 100644 --- a/Makefile +++ b/Makefile @@ -364,7 +364,7 @@ local-stovepipe-stop: ## Stop the Stovepipe service mocks: ## Generate mock files using mockgen @echo "Generating mocks..." - @$(BAZEL) run @rules_go//go -- generate ./submitqueue/extension/storage/... ./submitqueue/extension/buildrunner/... ./submitqueue/extension/changeprovider/... ./platform/extension/counter/... ./platform/extension/messagequeue/... ./submitqueue/extension/queueconfig/... ./submitqueue/extension/mergechecker/... ./submitqueue/extension/pusher/... ./submitqueue/extension/scorer/... ./submitqueue/extension/conflict/... ./submitqueue/extension/validator/... ./platform/consumer/... ./stovepipe/extension/storage/... ./stovepipe/extension/sourcecontrol/... + @$(BAZEL) run @rules_go//go -- generate ./submitqueue/extension/storage/... ./submitqueue/extension/buildrunner/... ./submitqueue/extension/changeprovider/... ./platform/extension/counter/... ./platform/extension/messagequeue/... ./submitqueue/extension/queueconfig/... ./submitqueue/extension/mergechecker/... ./submitqueue/extension/pusher/... ./submitqueue/extension/scorer/... ./submitqueue/extension/conflict/... ./submitqueue/extension/speculation/... ./submitqueue/extension/validator/... ./platform/consumer/... ./stovepipe/extension/storage/... ./stovepipe/extension/sourcecontrol/... @echo "Mocks generated successfully!" proto: ## Generate protobuf files from .proto definitions diff --git a/submitqueue/extension/speculation/speculator/BUILD.bazel b/submitqueue/extension/speculation/speculator/BUILD.bazel new file mode 100644 index 00000000..78be7e31 --- /dev/null +++ b/submitqueue/extension/speculation/speculator/BUILD.bazel @@ -0,0 +1,9 @@ +load("@rules_go//go:def.bzl", "go_library") + +go_library( + name = "go_default_library", + srcs = ["speculator.go"], + importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/speculator", + visibility = ["//visibility:public"], + deps = ["//submitqueue/entity:go_default_library"], +) diff --git a/submitqueue/extension/speculation/speculator/README.md b/submitqueue/extension/speculation/speculator/README.md new file mode 100644 index 00000000..835af489 --- /dev/null +++ b/submitqueue/extension/speculation/speculator/README.md @@ -0,0 +1,13 @@ +# speculator + +The `speculator` package defines the one speculation extension the speculate controller calls. A `Speculator` decides **which speculation paths to build and which running ones to cancel**, within the queue's build budget — and nothing else. It can never express a verdict: whether a batch merges or fails is fixed by the facts and computed by the controller, so swapping in a different `Speculator` changes which paths run, never a batch's outcome. + +`Speculate` is handed the queue's in-flight batches plus any finalized batches still referenced as dependencies (each with its dependency list and state) and every path set for them — live and recently finished, so a `Speculator` will not re-propose a path that already passed or failed. It returns a list of build and cancel actions; a path it wants left as-is has no entry in the result. The controller validates the output (dropping builds it shouldn't propose and rejecting cancels of passed paths), so an implementation may read extra injected data without affecting correctness. + +`Cancel` is a `Speculator`'s only cancel power — preempting an in-flight path to free budget for a better candidate. Correctness cancels (refuting a path whose bet a resolved dependency broke, and batch cancellation) belong to the controller and are not routed through the extension. + +Like the other extensions, a `Speculator` is selected **per queue** by the wiring layer through the `Config` (queue name) and `Factory` interface. Budget, depth bound, clock, and any extra data are injected at construction by the integrator, not carried on the contract. + +## Adding a backend + +Create a package under `speculator//` whose `New(...)` returns a `speculator.Speculator`, injecting whatever it needs at construction. Resolve any content it requires internally; do not add a `Config` or `Factory` implementation here — per-queue routing and the factory adapter live in the wiring layer. diff --git a/submitqueue/extension/speculation/speculator/mock/BUILD.bazel b/submitqueue/extension/speculation/speculator/mock/BUILD.bazel new file mode 100644 index 00000000..57b41cd4 --- /dev/null +++ b/submitqueue/extension/speculation/speculator/mock/BUILD.bazel @@ -0,0 +1,13 @@ +load("@rules_go//go:def.bzl", "go_library") + +go_library( + name = "go_default_library", + srcs = ["speculator_mock.go"], + importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/speculator/mock", + visibility = ["//visibility:public"], + deps = [ + "//submitqueue/entity:go_default_library", + "//submitqueue/extension/speculation/speculator:go_default_library", + "@org_uber_go_mock//gomock:go_default_library", + ], +) diff --git a/submitqueue/extension/speculation/speculator/mock/speculator_mock.go b/submitqueue/extension/speculation/speculator/mock/speculator_mock.go new file mode 100644 index 00000000..4348ec38 --- /dev/null +++ b/submitqueue/extension/speculation/speculator/mock/speculator_mock.go @@ -0,0 +1,97 @@ +// Code generated by MockGen. DO NOT EDIT. +// Source: speculator.go +// +// Generated by this command: +// +// mockgen -source=speculator.go -destination=mock/speculator_mock.go -package=mock +// + +// Package mock is a generated GoMock package. +package mock + +import ( + context "context" + reflect "reflect" + + entity "github.com/uber/submitqueue/submitqueue/entity" + speculator "github.com/uber/submitqueue/submitqueue/extension/speculation/speculator" + gomock "go.uber.org/mock/gomock" +) + +// MockSpeculator is a mock of Speculator interface. +type MockSpeculator struct { + ctrl *gomock.Controller + recorder *MockSpeculatorMockRecorder + isgomock struct{} +} + +// MockSpeculatorMockRecorder is the mock recorder for MockSpeculator. +type MockSpeculatorMockRecorder struct { + mock *MockSpeculator +} + +// NewMockSpeculator creates a new mock instance. +func NewMockSpeculator(ctrl *gomock.Controller) *MockSpeculator { + mock := &MockSpeculator{ctrl: ctrl} + mock.recorder = &MockSpeculatorMockRecorder{mock} + return mock +} + +// EXPECT returns an object that allows the caller to indicate expected use. +func (m *MockSpeculator) EXPECT() *MockSpeculatorMockRecorder { + return m.recorder +} + +// Speculate mocks base method. +func (m *MockSpeculator) Speculate(ctx context.Context, batches []entity.Batch, pathSets []entity.SpeculationPathSet) ([]entity.Speculation, error) { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "Speculate", ctx, batches, pathSets) + ret0, _ := ret[0].([]entity.Speculation) + ret1, _ := ret[1].(error) + return ret0, ret1 +} + +// Speculate indicates an expected call of Speculate. +func (mr *MockSpeculatorMockRecorder) Speculate(ctx, batches, pathSets any) *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Speculate", reflect.TypeOf((*MockSpeculator)(nil).Speculate), ctx, batches, pathSets) +} + +// MockFactory is a mock of Factory interface. +type MockFactory struct { + ctrl *gomock.Controller + recorder *MockFactoryMockRecorder + isgomock struct{} +} + +// MockFactoryMockRecorder is the mock recorder for MockFactory. +type MockFactoryMockRecorder struct { + mock *MockFactory +} + +// NewMockFactory creates a new mock instance. +func NewMockFactory(ctrl *gomock.Controller) *MockFactory { + mock := &MockFactory{ctrl: ctrl} + mock.recorder = &MockFactoryMockRecorder{mock} + return mock +} + +// EXPECT returns an object that allows the caller to indicate expected use. +func (m *MockFactory) EXPECT() *MockFactoryMockRecorder { + return m.recorder +} + +// For mocks base method. +func (m *MockFactory) For(cfg speculator.Config) (speculator.Speculator, error) { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "For", cfg) + ret0, _ := ret[0].(speculator.Speculator) + ret1, _ := ret[1].(error) + return ret0, ret1 +} + +// For indicates an expected call of For. +func (mr *MockFactoryMockRecorder) For(cfg any) *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "For", reflect.TypeOf((*MockFactory)(nil).For), cfg) +} diff --git a/submitqueue/extension/speculation/speculator/speculator.go b/submitqueue/extension/speculation/speculator/speculator.go new file mode 100644 index 00000000..1cc5f199 --- /dev/null +++ b/submitqueue/extension/speculation/speculator/speculator.go @@ -0,0 +1,54 @@ +// 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 speculator + +//go:generate mockgen -source=speculator.go -destination=mock/speculator_mock.go -package=mock + +import ( + "context" + + "github.com/uber/submitqueue/submitqueue/entity" +) + +// Speculator decides which speculation paths to build and which running ones to +// cancel, within the queue's build budget. It is the only speculation extension the +// speculate controller calls. It can never express a verdict: whether a batch +// merges or fails is fixed by the facts and computed by the controller, so a +// swapped-in Speculator changes which paths run, never a batch's outcome. +type Speculator interface { + // Speculate is handed the queue's in-flight batches plus any finalized + // batches still referenced as dependencies (each with its dependency list and + // state) and every path set for them — live and recently finished, so it will + // not re-propose a path that already passed or failed. It returns the build + // and cancel actions it proposes; a path it wants left as-is has no entry in + // the result. + Speculate(ctx context.Context, batches []entity.Batch, pathSets []entity.SpeculationPathSet) ([]entity.Speculation, error) +} + +// Config carries the per-queue identity handed to a Factory. The system knows +// only the queue name; everything an implementation needs is injected at +// construction by the integrator. +type Config struct { + // QueueName identifies the queue this Speculator serves. + QueueName string +} + +// Factory builds the Speculator for a queue. Implementations are provided by +// integrators (and tests) and inject whatever they need — budget, depth bound, +// clock, and any extra data — at construction. +type Factory interface { + // For returns the Speculator for the given queue. + For(cfg Config) (Speculator, error) +}