internal/pkg/simulation/interfaces.go

// Copyright 2026 Google LLC
//
// 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 simulation

import "time"

// Event is the minimum interface required for any item participating in a simulation.
type Event interface {
	// Offset returns the duration from the start of the simulation when this event occurs.
	Offset() time.Duration
}

// Clock provides the source of truth for the current time within a simulation.
type Clock interface {
	// Now returns the current simulated wall-clock time.
	Now() time.Time
	// Offset returns the current duration from the start of the simulation.
	Offset() time.Duration
}

// StaticClock is a simple Clock implementation for testing.
type StaticClock struct {
	T time.Time
	O time.Duration
}

func (s StaticClock) Now() time.Time        { return s.T }
func (s StaticClock) Offset() time.Duration { return s.O }

// WallClock is a Clock implementation that uses the real system time.
type WallClock struct {
	Start time.Time
}

// NewWallClock returns a new WallClock starting at the current time.
func NewWallClock() WallClock {
	return WallClock{Start: time.Now()}
}

func (w WallClock) Now() time.Time        { return time.Now() }
func (w WallClock) Offset() time.Duration { return time.Since(w.Start) }

// Timeline represents an ordered source of simulation events.
type Timeline interface {
	// Peek returns the next n events in the timeline without advancing the simulation.
	// Events must be returned in increasing order of their Offset().
	Peek(n int) []Event
}