engine

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 6, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package engine implements VegaLoad's core execution engine: the virtual user (VU) scheduler and the load-shape executors that decide how many VUs run, and when, over the life of a scenario.

This package knows nothing about HTTP, gRPC, WebSocket, JavaScript, or Harness RT. It schedules calls to an IterationFunc supplied by the caller — the protocol and scripting layers (built later in Phase 0) are what give that function its real behaviour. See AGENTS.md at the repository root for the module boundary this package is expected to hold.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConstantArrivalRate

type ConstantArrivalRate struct {
	// Rate is the target number of iterations per second.
	Rate float64
	// Dur is the total duration this executor runs for.
	Dur time.Duration
	// PreAllocatedVUs is accepted for forward compatibility with
	// k6-style arrival-rate configuration. The current implementation
	// spawns goroutines on demand up to MaxVUs rather than pre-warming
	// a fixed pool, since goroutines are cheap; this field is not yet
	// used.
	PreAllocatedVUs int
	// MaxVUs caps concurrently running iterations. Arrivals beyond
	// this cap are dropped. Defaults to 1 if left at 0.
	MaxVUs int
}

ConstantArrivalRate starts iterations at a fixed rate, independent of how long each iteration takes — an open workload model. FixedVUs, Ramp, and Step all hold a VU count steady and let each VU run iterations back-to-back (a closed model); under that model, a slow target automatically throttles the iteration rate, because VUs spend longer per iteration. ConstantArrivalRate does not throttle: it keeps starting new iterations on schedule even if earlier ones are still running, which is the point of it — it answers "can this target sustain X requests per second", not "what throughput do N users produce".

If an iteration takes longer than the arrival interval, more than one VU runs concurrently to keep up. MaxVUs caps how many will ever run at once; an arrival that would exceed MaxVUs is dropped and recorded as a failed iteration with VUID -1, rather than queued, so a struggling target doesn't cause unbounded VU growth.

func (ConstantArrivalRate) Duration

func (c ConstantArrivalRate) Duration() time.Duration

Duration implements Executor.

func (ConstantArrivalRate) Name

func (c ConstantArrivalRate) Name() string

Name implements Executor.

func (ConstantArrivalRate) Run

Run implements Executor.

type Executor

type Executor interface {
	// Name identifies the load shape, e.g. "fixed-vus", "ramp".
	Name() string
	// Duration is the total wall-clock time this executor will run for.
	Duration() time.Duration
	// Run executes the shape, calling iter for every iteration across
	// however many VUs the shape decides to run, and sending every
	// result to rec.
	Run(ctx context.Context, iter IterationFunc, rec Recorder) error
}

Executor runs a scenario's iterations according to one load shape (fixed-VU, ramp, step, or constant-arrival-rate) and reports every iteration to rec. Run blocks until the shape's duration elapses or ctx is cancelled, whichever comes first.

The four executors in this package are the only four load shapes FR-CLI-04 requires for Phase 0. Adding a fifth later means adding a type that implements this interface — it should never require changing the ones that already exist.

type FixedVUs

type FixedVUs struct {
	VUs int
	Dur time.Duration
}

FixedVUs runs a constant number of virtual users for a fixed duration. Each VU loops iterations back-to-back for the whole duration. This is the simplest load shape: no ramping, no arrival rate, just "N users, hammering, for T time."

func (FixedVUs) Duration

func (f FixedVUs) Duration() time.Duration

Duration implements Executor.

func (FixedVUs) Name

func (f FixedVUs) Name() string

Name implements Executor.

func (FixedVUs) Run

func (f FixedVUs) Run(ctx context.Context, iter IterationFunc, rec Recorder) error

Run implements Executor.

type IterationFunc

type IterationFunc func(ctx context.Context) error

IterationFunc runs one iteration of a scenario. It returns a non-nil error if the iteration failed — a connection error, a timeout, a threshold the scenario itself chose to enforce, and so on. A VU calls this repeatedly for as long as its executor keeps it alive.

Implementations should respect ctx cancellation promptly: an executor cancels ctx when the load shape's duration elapses or the run is stopped, and a slow-to-return IterationFunc delays shutdown.

type IterationResult

type IterationResult struct {
	VUID     int
	Start    time.Time
	Duration time.Duration
	Err      error
}

IterationResult is what the engine records after every iteration. VUID identifies which VU ran the iteration; it has no meaning beyond that, except for ConstantArrivalRate, where -1 marks an arrival that was dropped rather than run (see that executor's doc comment).

type Ramp

type Ramp struct {
	Stages []Stage
}

Ramp runs a variable number of virtual users, linearly interpolating the target VU count between each Stage's start and end over that stage's duration — the "ramping-vus" shape k6 and Gatling both call a ramp. The VU count starts at 0 before the first stage.

func (Ramp) Duration

func (r Ramp) Duration() time.Duration

Duration implements Executor.

func (Ramp) Name

func (r Ramp) Name() string

Name implements Executor.

func (Ramp) Run

func (r Ramp) Run(ctx context.Context, iter IterationFunc, rec Recorder) error

Run implements Executor.

type Recorder

type Recorder interface {
	Record(IterationResult)
}

Recorder receives one IterationResult per completed iteration, from any number of VUs concurrently. Implementations must be safe for concurrent use.

This package ships only Summary, a minimal Recorder for tests and simple use. The real HTML/JSON report (Phase 1, internal/report) will implement this same interface with full percentile tracking — engine does not need to know that package exists.

type Stage

type Stage struct {
	Target   int
	Duration time.Duration
}

Stage is one segment of a Ramp or Step load shape: hold, or move toward, Target VUs over Duration.

type Step

type Step struct {
	Stages []Stage
}

Step runs a variable number of virtual users, holding each Stage's target VU count constant for that stage's duration, then jumping straight to the next stage's target — no interpolation in between, unlike Ramp.

func (Step) Duration

func (s Step) Duration() time.Duration

Duration implements Executor.

func (Step) Name

func (s Step) Name() string

Name implements Executor.

func (Step) Run

func (s Step) Run(ctx context.Context, iter IterationFunc, rec Recorder) error

Run implements Executor.

type Summary

type Summary struct {
	// contains filtered or unexported fields
}

Summary is a minimal Recorder that keeps running counts: total iterations, failed iterations, and mean duration. It exists so the engine and its tests have something to record into in Phase 0, before internal/report exists. It is not a substitute for that package's real percentile tracking.

func NewSummary

func NewSummary() *Summary

NewSummary returns an empty Summary, ready to use.

func (*Summary) Failed

func (s *Summary) Failed() int64

Failed returns the number of recorded iterations that had a non-nil error, including arrivals ConstantArrivalRate dropped.

func (*Summary) MeanDuration

func (s *Summary) MeanDuration() time.Duration

MeanDuration returns the mean iteration duration across every recorded iteration, including failed ones. It returns 0 if nothing has been recorded yet.

func (*Summary) Record

func (s *Summary) Record(r IterationResult)

Record implements Recorder.

func (*Summary) Total

func (s *Summary) Total() int64

Total returns the number of iterations recorded so far.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL