diff --git a/Makefile b/Makefile index 328d00ec..ddc7aeab 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/speculation/enumerator/... ./submitqueue/extension/speculation/dependencylimit/... ./submitqueue/extension/speculation/scorer/... ./submitqueue/extension/speculation/selector/... ./submitqueue/extension/speculation/selectionlimit/... ./platform/consumer/... ./submitqueue/core/changeset/... ./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/enumerator/... ./submitqueue/extension/speculation/dependencylimit/... ./submitqueue/extension/speculation/scorer/... ./submitqueue/extension/speculation/selector/... ./submitqueue/extension/speculation/selectionlimit/... ./submitqueue/extension/speculation/prioritizer/... ./submitqueue/extension/speculation/prioritizationlimit/... ./platform/consumer/... ./submitqueue/core/changeset/... ./stovepipe/extension/storage/... ./stovepipe/extension/sourcecontrol/... @echo "Mocks generated successfully!" proto: ## Generate protobuf files from .proto definitions diff --git a/submitqueue/extension/speculation/prioritizationlimit/BUILD.bazel b/submitqueue/extension/speculation/prioritizationlimit/BUILD.bazel new file mode 100644 index 00000000..b777ccaf --- /dev/null +++ b/submitqueue/extension/speculation/prioritizationlimit/BUILD.bazel @@ -0,0 +1,8 @@ +load("@rules_go//go:def.bzl", "go_library") + +go_library( + name = "go_default_library", + srcs = ["prioritizationlimit.go"], + importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizationlimit", + visibility = ["//visibility:public"], +) diff --git a/submitqueue/extension/speculation/prioritizationlimit/README.md b/submitqueue/extension/speculation/prioritizationlimit/README.md new file mode 100644 index 00000000..8859a6c6 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizationlimit/README.md @@ -0,0 +1,17 @@ +# Prioritization Limit + +Vendor-agnostic "how much" policy that bounds how many builds a queue may run at once — the queue's concurrent-build budget. + +See the [Speculation RFC](../../../../doc/rfc/submitqueue/speculation.md) for the end-to-end design and how limits fit into the two-layer speculation model. + +## Prioritization Limit + +The prioritization limit is the [prioritizer](../prioritizer)'s companion. The prioritizer decides **which** of the queue's pending builds run — its ranking across all in-flight batches; the prioritization limit decides **how many** fit at once. It is the queue-wide resource knob, the ultimate cap on speculation's demand on CI. + +The value is **signal-driven**, not a fixed constant. Its primary input is the build system's available capacity, but a policy may also weigh cost budgets, time of day, or an experiment toggle. + +It is **injected into the prioritizer** at construction and called by it, never passed as a method parameter — following the repo's extension-contract pattern, keeping the prioritizer interface limit-free and stable, and letting the limit be swapped independently of prioritizer logic. + +## Factory + +A per-queue factory returns the limit policy for a queue, following the repo's extension contract. It is handed only the queue identity; the signals a policy weighs — a capacity feed, cost budgets, config — are injected at construction by the integrator in the wiring layer, which is also where the limit is handed to the prioritizer. Computing the limit itself takes no further inputs. diff --git a/submitqueue/extension/speculation/prioritizationlimit/fake/BUILD.bazel b/submitqueue/extension/speculation/prioritizationlimit/fake/BUILD.bazel new file mode 100644 index 00000000..1610a824 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizationlimit/fake/BUILD.bazel @@ -0,0 +1,19 @@ +load("@rules_go//go:def.bzl", "go_library", "go_test") + +go_library( + name = "go_default_library", + srcs = ["fake.go"], + importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizationlimit/fake", + visibility = ["//visibility:public"], + deps = ["//submitqueue/extension/speculation/prioritizationlimit:go_default_library"], +) + +go_test( + name = "go_default_test", + srcs = ["fake_test.go"], + embed = [":go_default_library"], + deps = [ + "@com_github_stretchr_testify//assert:go_default_library", + "@com_github_stretchr_testify//require:go_default_library", + ], +) diff --git a/submitqueue/extension/speculation/prioritizationlimit/fake/fake.go b/submitqueue/extension/speculation/prioritizationlimit/fake/fake.go new file mode 100644 index 00000000..e8328f69 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizationlimit/fake/fake.go @@ -0,0 +1,53 @@ +// 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 programmable prioritizationlimit.PrioritizationLimit +// for tests and examples. New sets the value returned by Limit; FailWith injects +// an error on every call. It is intended for examples and tests only, never +// production. +package fake + +import ( + "context" + + "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizationlimit" +) + +// PrioritizationLimit is a programmable prioritizationlimit.PrioritizationLimit. +type PrioritizationLimit struct { + limit int + err error +} + +// New returns a fake PrioritizationLimit whose Limit returns the given value. +func New(value int) *PrioritizationLimit { + return &PrioritizationLimit{limit: value} +} + +// FailWith makes every Limit call return err. +func (l *PrioritizationLimit) FailWith(err error) *PrioritizationLimit { + l.err = err + return l +} + +// Limit returns the configured value, or the injected error if FailWith was set. +func (l *PrioritizationLimit) Limit(_ context.Context) (int, error) { + if l.err != nil { + return 0, l.err + } + return l.limit, nil +} + +// ensure the fake satisfies the interface. +var _ prioritizationlimit.PrioritizationLimit = (*PrioritizationLimit)(nil) diff --git a/submitqueue/extension/speculation/prioritizationlimit/fake/fake_test.go b/submitqueue/extension/speculation/prioritizationlimit/fake/fake_test.go new file mode 100644 index 00000000..f49fdcb0 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizationlimit/fake/fake_test.go @@ -0,0 +1,36 @@ +// 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 + +import ( + "context" + "errors" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestLimit_ReturnsConfiguredValue(t *testing.T) { + got, err := New(8).Limit(context.Background()) + require.NoError(t, err) + assert.Equal(t, 8, got) +} + +func TestLimit_FailWith(t *testing.T) { + sentinel := errors.New("boom") + _, err := New(8).FailWith(sentinel).Limit(context.Background()) + require.ErrorIs(t, err, sentinel) +} diff --git a/submitqueue/extension/speculation/prioritizationlimit/mock/BUILD.bazel b/submitqueue/extension/speculation/prioritizationlimit/mock/BUILD.bazel new file mode 100644 index 00000000..cefd8ff5 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizationlimit/mock/BUILD.bazel @@ -0,0 +1,12 @@ +load("@rules_go//go:def.bzl", "go_library") + +go_library( + name = "go_default_library", + srcs = ["prioritizationlimit_mock.go"], + importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizationlimit/mock", + visibility = ["//visibility:public"], + deps = [ + "//submitqueue/extension/speculation/prioritizationlimit:go_default_library", + "@org_uber_go_mock//gomock:go_default_library", + ], +) diff --git a/submitqueue/extension/speculation/prioritizationlimit/mock/prioritizationlimit_mock.go b/submitqueue/extension/speculation/prioritizationlimit/mock/prioritizationlimit_mock.go new file mode 100644 index 00000000..277b8cf1 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizationlimit/mock/prioritizationlimit_mock.go @@ -0,0 +1,96 @@ +// Code generated by MockGen. DO NOT EDIT. +// Source: prioritizationlimit.go +// +// Generated by this command: +// +// mockgen -source=prioritizationlimit.go -destination=mock/prioritizationlimit_mock.go -package=mock +// + +// Package mock is a generated GoMock package. +package mock + +import ( + context "context" + reflect "reflect" + + prioritizationlimit "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizationlimit" + gomock "go.uber.org/mock/gomock" +) + +// MockPrioritizationLimit is a mock of PrioritizationLimit interface. +type MockPrioritizationLimit struct { + ctrl *gomock.Controller + recorder *MockPrioritizationLimitMockRecorder + isgomock struct{} +} + +// MockPrioritizationLimitMockRecorder is the mock recorder for MockPrioritizationLimit. +type MockPrioritizationLimitMockRecorder struct { + mock *MockPrioritizationLimit +} + +// NewMockPrioritizationLimit creates a new mock instance. +func NewMockPrioritizationLimit(ctrl *gomock.Controller) *MockPrioritizationLimit { + mock := &MockPrioritizationLimit{ctrl: ctrl} + mock.recorder = &MockPrioritizationLimitMockRecorder{mock} + return mock +} + +// EXPECT returns an object that allows the caller to indicate expected use. +func (m *MockPrioritizationLimit) EXPECT() *MockPrioritizationLimitMockRecorder { + return m.recorder +} + +// Limit mocks base method. +func (m *MockPrioritizationLimit) Limit(ctx context.Context) (int, error) { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "Limit", ctx) + ret0, _ := ret[0].(int) + ret1, _ := ret[1].(error) + return ret0, ret1 +} + +// Limit indicates an expected call of Limit. +func (mr *MockPrioritizationLimitMockRecorder) Limit(ctx any) *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Limit", reflect.TypeOf((*MockPrioritizationLimit)(nil).Limit), ctx) +} + +// 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 prioritizationlimit.Config) (prioritizationlimit.PrioritizationLimit, error) { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "For", cfg) + ret0, _ := ret[0].(prioritizationlimit.PrioritizationLimit) + 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/prioritizationlimit/prioritizationlimit.go b/submitqueue/extension/speculation/prioritizationlimit/prioritizationlimit.go new file mode 100644 index 00000000..6022d51e --- /dev/null +++ b/submitqueue/extension/speculation/prioritizationlimit/prioritizationlimit.go @@ -0,0 +1,57 @@ +// 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 prioritizationlimit + +//go:generate mockgen -source=prioritizationlimit.go -destination=mock/prioritizationlimit_mock.go -package=mock + +import "context" + +// PrioritizationLimit is the "how much" policy that bounds how many builds a +// queue may run at once — the queue's concurrent-build budget. +// +// It is the prioritizer's companion: the prioritizer decides *which* of the +// queue's pending builds run (its ranking across all in-flight batches); the +// prioritization limit decides *how many* fit at once. It is the queue-wide +// resource knob, the ultimate cap on speculation's demand on CI. +// +// The value is dynamic: it may change between calls, so the prioritizer reads it +// each round rather than caching it. +// +// It is injected into the prioritizer at construction and called by it, never +// passed as a method parameter, keeping the prioritizer interface limit-free and +// stable. +type PrioritizationLimit interface { + // Limit returns the current maximum number of concurrent builds for the + // queue. The prioritizer admits at most this many candidates. It takes no + // parameters; anything an implementation needs is injected at construction. + Limit(ctx context.Context) (int, error) +} + +// Config carries the per-queue identity handed to a Factory. The system knows +// only the queue name; everything a policy needs to compute the limit (a +// capacity feed, cost budgets, config) is injected at construction by the +// integrator. +type Config struct { + // QueueName identifies the queue this PrioritizationLimit serves. + QueueName string +} + +// Factory builds the PrioritizationLimit for a queue. Implementations are +// provided by integrators (and tests) and inject whatever signals they need at +// construction. +type Factory interface { + // For returns the PrioritizationLimit for the given queue. + For(cfg Config) (PrioritizationLimit, error) +} diff --git a/submitqueue/extension/speculation/prioritizer/BUILD.bazel b/submitqueue/extension/speculation/prioritizer/BUILD.bazel new file mode 100644 index 00000000..f7ceb281 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizer/BUILD.bazel @@ -0,0 +1,9 @@ +load("@rules_go//go:def.bzl", "go_library") + +go_library( + name = "go_default_library", + srcs = ["prioritizer.go"], + importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizer", + visibility = ["//visibility:public"], + deps = ["//submitqueue/entity:go_default_library"], +) diff --git a/submitqueue/extension/speculation/prioritizer/README.md b/submitqueue/extension/speculation/prioritizer/README.md new file mode 100644 index 00000000..d9eef980 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizer/README.md @@ -0,0 +1,19 @@ +# Speculation Prioritizer + +Vendor-agnostic interface for the queue-wide policy that rations a shared build budget across every in-flight batch in a queue. + +See the [Speculation RFC](../../../../doc/rfc/submitqueue/speculation.md) for the end-to-end design and how prioritization fits into the orchestrator pipeline. + +## Prioritizer + +Selection is per batch and blind to other batches, so it cannot ration a shared budget: if every batch promoted generously, their combined demand could swamp CI. The prioritizer closes that gap. It sees every path across all of the queue's in-flight batches that is running or wants to run, ranks them by each path's score (plus any fairness or tie-break policy), and admits only the subset that fits the queue's concurrent-build budget. Selection expresses *desire* per batch; prioritization reconciles that desire against *supply* — it is the queue-wide enforcer. + +The controller hands the prioritizer the queue's candidate paths directly — every path that is `Selected` (wants a slot) or `Prioritized`/`Building` (holds a slot), each carrying its score. It returns **sparse decisions**: `Promote` to admit a pending path, `Cancel` to preempt a running one. Paths it omits are left as-is. It never writes: the controller maps each decision to a guarded status transition (`Promote` → `Prioritized`, `Cancel` → `Cancelling`) and enacts it, staying the single writer. + +**Whether to preempt is the prioritizer's own policy**, swappable per queue. A sticky-slots implementation never emits `Cancel` for a running path — it only fills free slots, and a higher-priority path waits until a slot frees. A preemptive implementation ranks running and pending paths together and may `Cancel` a running path to admit a higher-scored one. Both read the same input through the same interface; only the ranking/eviction logic differs. (Preemption discards in-flight CI work, so "fill free slots only" is a common default.) + +Prioritization is queue-wide — a different vantage point than the per-batch seams (enumerator, scorer, selector) — but it acts in the same currency: it ranks on the same path `Score` the scorer produces and emits the same `SpeculationPathDecision` the selector does. Where the queue-wide reconcile runs in the pipeline is an integration detail; the contract here is unaffected by it. + +## Factory + +A per-queue factory returns the prioritizer for a queue, following the repo's extension contract. It is handed only the queue identity; the prioritization limit, fairness policy, and capacity signals are injected at construction by the integrator in the wiring layer, which resolves per-queue settings through `queueconfig`. Prioritization itself stays config-free. diff --git a/submitqueue/extension/speculation/prioritizer/fake/BUILD.bazel b/submitqueue/extension/speculation/prioritizer/fake/BUILD.bazel new file mode 100644 index 00000000..34481788 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizer/fake/BUILD.bazel @@ -0,0 +1,23 @@ +load("@rules_go//go:def.bzl", "go_library", "go_test") + +go_library( + name = "go_default_library", + srcs = ["fake.go"], + importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizer/fake", + visibility = ["//visibility:public"], + deps = [ + "//submitqueue/entity:go_default_library", + "//submitqueue/extension/speculation/prioritizer:go_default_library", + ], +) + +go_test( + name = "go_default_test", + srcs = ["fake_test.go"], + embed = [":go_default_library"], + deps = [ + "//submitqueue/entity:go_default_library", + "@com_github_stretchr_testify//assert:go_default_library", + "@com_github_stretchr_testify//require:go_default_library", + ], +) diff --git a/submitqueue/extension/speculation/prioritizer/fake/fake.go b/submitqueue/extension/speculation/prioritizer/fake/fake.go new file mode 100644 index 00000000..0c4082e2 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizer/fake/fake.go @@ -0,0 +1,61 @@ +// 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 programmable prioritizer.Prioritizer for tests and +// examples. It returns the decisions seeded via SetDecisions (none by default, +// i.e. leave every candidate as-is). FailWith injects an error on every call. It +// is intended for examples and tests only, never production. +package fake + +import ( + "context" + + "github.com/uber/submitqueue/submitqueue/entity" + "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizer" +) + +// Prioritizer is a programmable prioritizer.Prioritizer. +type Prioritizer struct { + decisions []entity.SpeculationPathDecision + err error +} + +// New returns a fake Prioritizer that decides nothing (leaves every candidate +// as-is). Seed decisions with SetDecisions. +func New() *Prioritizer { + return &Prioritizer{} +} + +// SetDecisions seeds the decisions returned by Prioritize, in the order given. +func (p *Prioritizer) SetDecisions(decisions ...entity.SpeculationPathDecision) *Prioritizer { + p.decisions = decisions + return p +} + +// FailWith makes every Prioritize call return err. +func (p *Prioritizer) FailWith(err error) *Prioritizer { + p.err = err + return p +} + +// Prioritize returns the seeded decisions. The candidates argument is ignored. +func (p *Prioritizer) Prioritize(_ context.Context, _ []entity.SpeculationPathInfo) ([]entity.SpeculationPathDecision, error) { + if p.err != nil { + return nil, p.err + } + return p.decisions, nil +} + +// ensure the fake satisfies the interface. +var _ prioritizer.Prioritizer = (*Prioritizer)(nil) diff --git a/submitqueue/extension/speculation/prioritizer/fake/fake_test.go b/submitqueue/extension/speculation/prioritizer/fake/fake_test.go new file mode 100644 index 00000000..59609b07 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizer/fake/fake_test.go @@ -0,0 +1,50 @@ +// 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 + +import ( + "context" + "errors" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/uber/submitqueue/submitqueue/entity" +) + +func TestPrioritize_DefaultDecidesNothing(t *testing.T) { + got, err := New().Prioritize(context.Background(), nil) + require.NoError(t, err) + assert.Empty(t, got) +} + +func TestPrioritize_ReturnsSeededDecisions(t *testing.T) { + want := []entity.SpeculationPathDecision{ + {Path: entity.SpeculationPath{Head: "q/batch/2"}, Action: entity.SpeculationPathActionPromote}, + {Path: entity.SpeculationPath{Base: []string{"q/batch/1"}, Head: "q/batch/3"}, Action: entity.SpeculationPathActionCancel}, + } + candidates := []entity.SpeculationPathInfo{ + {Path: entity.SpeculationPath{Head: "q/batch/2"}, Status: entity.SpeculationPathStatusSelected, Score: 0.9}, + } + got, err := New().SetDecisions(want...).Prioritize(context.Background(), candidates) + require.NoError(t, err) + assert.Equal(t, want, got) +} + +func TestPrioritize_FailWith(t *testing.T) { + sentinel := errors.New("boom") + _, err := New().FailWith(sentinel).Prioritize(context.Background(), nil) + require.ErrorIs(t, err, sentinel) +} diff --git a/submitqueue/extension/speculation/prioritizer/mock/BUILD.bazel b/submitqueue/extension/speculation/prioritizer/mock/BUILD.bazel new file mode 100644 index 00000000..10287a77 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizer/mock/BUILD.bazel @@ -0,0 +1,13 @@ +load("@rules_go//go:def.bzl", "go_library") + +go_library( + name = "go_default_library", + srcs = ["prioritizer_mock.go"], + importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizer/mock", + visibility = ["//visibility:public"], + deps = [ + "//submitqueue/entity:go_default_library", + "//submitqueue/extension/speculation/prioritizer:go_default_library", + "@org_uber_go_mock//gomock:go_default_library", + ], +) diff --git a/submitqueue/extension/speculation/prioritizer/mock/prioritizer_mock.go b/submitqueue/extension/speculation/prioritizer/mock/prioritizer_mock.go new file mode 100644 index 00000000..50f1a877 --- /dev/null +++ b/submitqueue/extension/speculation/prioritizer/mock/prioritizer_mock.go @@ -0,0 +1,97 @@ +// Code generated by MockGen. DO NOT EDIT. +// Source: prioritizer.go +// +// Generated by this command: +// +// mockgen -source=prioritizer.go -destination=mock/prioritizer_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" + prioritizer "github.com/uber/submitqueue/submitqueue/extension/speculation/prioritizer" + gomock "go.uber.org/mock/gomock" +) + +// MockPrioritizer is a mock of Prioritizer interface. +type MockPrioritizer struct { + ctrl *gomock.Controller + recorder *MockPrioritizerMockRecorder + isgomock struct{} +} + +// MockPrioritizerMockRecorder is the mock recorder for MockPrioritizer. +type MockPrioritizerMockRecorder struct { + mock *MockPrioritizer +} + +// NewMockPrioritizer creates a new mock instance. +func NewMockPrioritizer(ctrl *gomock.Controller) *MockPrioritizer { + mock := &MockPrioritizer{ctrl: ctrl} + mock.recorder = &MockPrioritizerMockRecorder{mock} + return mock +} + +// EXPECT returns an object that allows the caller to indicate expected use. +func (m *MockPrioritizer) EXPECT() *MockPrioritizerMockRecorder { + return m.recorder +} + +// Prioritize mocks base method. +func (m *MockPrioritizer) Prioritize(ctx context.Context, candidates []entity.SpeculationPathInfo) ([]entity.SpeculationPathDecision, error) { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "Prioritize", ctx, candidates) + ret0, _ := ret[0].([]entity.SpeculationPathDecision) + ret1, _ := ret[1].(error) + return ret0, ret1 +} + +// Prioritize indicates an expected call of Prioritize. +func (mr *MockPrioritizerMockRecorder) Prioritize(ctx, candidates any) *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Prioritize", reflect.TypeOf((*MockPrioritizer)(nil).Prioritize), ctx, candidates) +} + +// 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 prioritizer.Config) (prioritizer.Prioritizer, error) { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "For", cfg) + ret0, _ := ret[0].(prioritizer.Prioritizer) + 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/prioritizer/prioritizer.go b/submitqueue/extension/speculation/prioritizer/prioritizer.go new file mode 100644 index 00000000..5e45a19c --- /dev/null +++ b/submitqueue/extension/speculation/prioritizer/prioritizer.go @@ -0,0 +1,69 @@ +// 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 prioritizer + +//go:generate mockgen -source=prioritizer.go -destination=mock/prioritizer_mock.go -package=mock + +import ( + "context" + + "github.com/uber/submitqueue/submitqueue/entity" +) + +// Prioritizer is the queue-wide policy that rations a shared build budget across +// every in-flight batch in a queue. +// +// Selection is per batch and blind to other batches, so it cannot ration a +// shared budget: if every batch promoted generously, their combined demand could +// swamp CI. Prioritization closes that gap. It sees every path across all of the +// queue's in-flight batches that is running or wants to run, ranks them (by each +// path's score, plus any fairness or tie-break policy), and admits only the +// subset that fits the queue's concurrent-build budget. Selection expresses +// desire per batch; prioritization reconciles that desire against supply. It is +// constructed with its prioritization limit and applies it itself. +// +// The controller hands it the queue's candidate paths directly — every path that +// is Selected (wants a slot) or Prioritized/Building (holds a slot), each +// carrying its score. The prioritizer returns sparse decisions: Promote to admit +// a pending path, Cancel to preempt a running one; paths it omits are left as-is. +// Whether it preempts at all is its own policy — a sticky-slots implementation +// never emits Cancel for a running path and only fills free slots, while a +// preemptive one ranks running and pending together and may Cancel a running +// path to admit a higher-scored one. It never writes: the controller maps each +// decision to a guarded status transition (Promote → Prioritized, Cancel → +// Cancelling) and enacts it, staying the single writer. +type Prioritizer interface { + // Prioritize ranks the queue's candidate paths and returns the decisions to + // apply: Promote for paths admitted to run now, Cancel for running paths it + // chooses to preempt. Omitted paths are left as-is. Ranking is by score plus + // any fairness policy, bounded by the prioritization limit. + Prioritize(ctx context.Context, candidates []entity.SpeculationPathInfo) ([]entity.SpeculationPathDecision, error) +} + +// Config carries the per-queue identity handed to a Factory. The system knows +// only the queue name; everything an implementation needs (its prioritization +// limit, fairness policy, capacity signals) is injected at construction by the +// integrator. +type Config struct { + // QueueName identifies the queue this Prioritizer serves. + QueueName string +} + +// Factory builds the Prioritizer for a queue. Implementations are provided by +// integrators (and tests) and inject whatever they need at construction. +type Factory interface { + // For returns the Prioritizer for the given queue. + For(cfg Config) (Prioritizer, error) +}