scheduler

package
v1.32.1 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 54 Imported by: 0

Documentation

Overview

Package scheduler is a generated GoMock package.

Index

Constants

View Source
const (

	// InvokerMaxStartAttempts is the maximum number of StartWorkflowExecution
	// RPCs issued for an individual buffered action, counting the first call.
	// Attempt numbers are 1-based: recordProcessBufferResult readies a start at
	// Attempt 1, and each retryable failure increments it. The bound is
	// therefore inclusive - a start is refused locally (and dropped) only once
	// its Attempt exceeds this value - so a value of 10 permits ten start RPCs,
	// i.e. the initial call plus nine retries.
	InvokerMaxStartAttempts = 10 // TODO - dial this up/remove it
)
View Source
const ScheduleBufferedStartsCountName = "ScheduleBufferedStartsCount"
View Source
const ScheduleIdleCloseTimeName = "ScheduleIdleCloseTime"
View Source
const ScheduleNextActionTimeName = "ScheduleNextActionTime"
View Source
const ScheduleRunningWorkflowCountName = "ScheduleRunningWorkflowCount"

Variables

View Source
var (
	CurrentTweakables = dynamicconfig.NewNamespaceTypedSetting(
		"scheduler.tweakables",
		DefaultTweakables,
		"A set of tweakable parameters for the CHASM scheduler.")

	RetryPolicyInitialInterval = dynamicconfig.NewGlobalDurationSetting(
		"scheduler.retryPolicy.initialInterval",
		time.Second,
		`The initial backoff interval when retrying a failed task.`,
	)

	RetryPolicyMaximumInterval = dynamicconfig.NewGlobalDurationSetting(
		"scheduler.retryPolicy.maxInterval",
		time.Minute,
		`The maximum backoff interval when retrying a failed task.`,
	)

	ServiceCallTimeout = dynamicconfig.NewGlobalDurationSetting(
		"scheduler.serviceCallTimeout",
		2*time.Second,
		`The upper bound on how long a service call can take before being timed out.`,
	)

	// SentinelIdleTime is how long a CHASM sentinel reserves the schedule ID
	// before auto-closing via the idle task mechanism. Matches the dummy
	// workflow's duration.
	SentinelIdleTime = 15 * time.Minute

	DefaultTweakables = Tweakables{
		DefaultCatchupWindow:              365 * 24 * time.Hour,
		MinCatchupWindow:                  10 * time.Second,
		MaxBufferSize:                     1000,
		GeneratorBufferReserveSize:        50,
		CanceledTerminatedCountAsFailures: false,
		MaxActionsPerExecution:            5,
		IdleTime:                          7 * 24 * time.Hour,
		EventLogMaxEntries:                30,
		EventLogMaxMessageLen:             1000,
	}
)
View Source
var (
	ErrConflictTokenMismatch = serviceerror.NewFailedPrecondition("mismatched conflict token")
	ErrClosed                = serviceerror.NewFailedPrecondition("schedule closed")
	ErrTooManyBackfillers    = serviceerror.NewFailedPrecondition("too many concurrent backfillers")
	ErrInvalidQuery          = serviceerror.NewInvalidArgument("missing or invalid query")
	ErrSentinel              = serviceerror.NewNotFound("schedule is a sentinel")
	ErrSentinelBlocked       = serviceerror.NewUnavailable("schedule is a sentinel; please retry after sentinel expires")
	ErrMigrationPending      = serviceerror.NewUnavailable("schedule has a pending migration to workflow; please retry later")
)

Functions

func Register

func Register(
	registry *chasm.Registry,
	library *Library,
) error

Types

type BackfillRequestType

type BackfillRequestType int
const (
	RequestTypeTrigger BackfillRequestType = iota
	RequestTypeBackfill
)

type Backfiller

The Backfiller component is responsible for buffering manually requested actions. Each backfill request has its own Backfiller node.

func (*Backfiller) LifecycleState

func (b *Backfiller) LifecycleState(ctx chasm.Context) chasm.LifecycleState

func (*Backfiller) RequestType

func (b *Backfiller) RequestType() BackfillRequestType

type BackfillerTaskHandler

type BackfillerTaskHandler struct {
	chasm.PureTaskHandlerBase
	// contains filtered or unexported fields
}

func (*BackfillerTaskHandler) Execute

func (*BackfillerTaskHandler) Validate

func (b *BackfillerTaskHandler) Validate(
	ctx chasm.Context,
	backfiller *Backfiller,
	_ chasm.TaskInvocation,
	task *schedulerpb.BackfillerTask,
) (bool, error)

type BackfillerTaskHandlerOptions

type BackfillerTaskHandlerOptions struct {
	fx.In

	Config         *Config
	MetricsHandler metrics.Handler
	BaseLogger     log.Logger
	SpecProcessor  SpecProcessor
}

type Config

type Config struct {
	Tweakables                      dynamicconfig.TypedPropertyFnWithNamespaceFilter[Tweakables]
	ServiceCallTimeout              dynamicconfig.DurationPropertyFn
	RetryPolicy                     func() backoff.RetryPolicy
	EncodeInternalTokenWithEnvelope dynamicconfig.BoolPropertyFnWithNamespaceFilter
}

Config is the CHASM Scheduler dynamic config, shared among all sub-components.

func ConfigProvider

func ConfigProvider(dc *dynamicconfig.Collection) *Config

type EventLog

type EventLog struct {
	chasm.UnimplementedComponent

	*schedulerpb.EventLog
}

EventLog is a CHASM component that keeps a bounded, human-readable history of state changes for its parent component. Entries are not used for any scheduler computation.

func NewEventLog

func NewEventLog(ctx chasm.MutableContext) *EventLog

NewEventLog returns an initialized EventLog component, intended to be parented under any component that wants to record events.

func (*EventLog) LifecycleState

func (e *EventLog) LifecycleState(ctx chasm.Context) chasm.LifecycleState

func (*EventLog) LogEvent

func (e *EventLog) LogEvent(ctx chasm.MutableContext, msg string)

LogEvent appends an event with the given message. Messages longer than the configured maximum length are truncated at a UTF-8 rune boundary; once the log exceeds the configured maximum entries, the earliest entries are dropped.

type Generator

The Generator component is responsible for buffering actions according to the schedule's specification. Manually requested actions (from an immediate request or backfill) are separately handled in the Backfiller component.

func NewGenerator

func NewGenerator(ctx chasm.MutableContext) *Generator

NewGenerator returns an initialized Generator component, which should be parented under a Scheduler root node.

func (*Generator) Generate

func (g *Generator) Generate(ctx chasm.MutableContext)

Generate immediately kicks off a new GeneratorTask. Used after updating the schedule specification.

func (*Generator) LifecycleState

func (g *Generator) LifecycleState(ctx chasm.Context) chasm.LifecycleState

func (*Generator) UpdateFutureActionTimes

func (g *Generator) UpdateFutureActionTimes(
	ctx chasm.MutableContext,
	specBuilder *scheduler.SpecBuilder,
)

UpdateFutureActionTimes computes and stores the next scheduled action times. On spec-compile error the previously stored times are left untouched.

type GeneratorTaskHandler

type GeneratorTaskHandler struct {
	chasm.PureTaskHandlerBase

	SpecProcessor SpecProcessor
	// contains filtered or unexported fields
}

func (*GeneratorTaskHandler) Execute

func (*GeneratorTaskHandler) Validate

func (g *GeneratorTaskHandler) Validate(
	ctx chasm.Context,
	generator *Generator,
	attrs chasm.TaskInvocation,
	_ *schedulerpb.GeneratorTask,
) (bool, error)

type GeneratorTaskHandlerOptions

type GeneratorTaskHandlerOptions struct {
	fx.In

	Config         *Config
	MetricsHandler metrics.Handler
	BaseLogger     log.Logger
	SpecProcessor  SpecProcessor
	SpecBuilder    *scheduler.SpecBuilder
}

type Invoker

The Invoker component is responsible for executing buffered actions.

func NewInvoker

func NewInvoker(ctx chasm.MutableContext) *Invoker

NewInvoker returns an initialized Invoker component, which should be parented under a Scheduler root component.

func (*Invoker) EnqueueBufferedStarts

func (i *Invoker) EnqueueBufferedStarts(ctx chasm.MutableContext, starts []*schedulespb.BufferedStart)

EnqueueBufferedStarts adds new BufferedStarts to the invocation queue, immediately kicking off a processing task.

func (*Invoker) LifecycleState

func (i *Invoker) LifecycleState(ctx chasm.Context) chasm.LifecycleState

type InvokerExecuteTaskHandler

type InvokerExecuteTaskHandler struct {
	chasm.SideEffectTaskHandlerBase[*schedulerpb.InvokerExecuteTask]
	// contains filtered or unexported fields
}

func (*InvokerExecuteTaskHandler) Execute

func (*InvokerExecuteTaskHandler) Validate

type InvokerProcessBufferTaskHandler

type InvokerProcessBufferTaskHandler struct {
	chasm.PureTaskHandlerBase
	// contains filtered or unexported fields
}

func (*InvokerProcessBufferTaskHandler) Execute

func (*InvokerProcessBufferTaskHandler) Validate

type InvokerTaskHandlerOptions

type InvokerTaskHandlerOptions struct {
	fx.In

	Config         *Config
	MetricsHandler metrics.Handler
	BaseLogger     log.Logger
	SpecProcessor  SpecProcessor

	HistoryClient resource.HistoryClient

	// FrontendClient is used for specifically StartWorkflow calls, to ensure that
	// the request makes it through metering's interceptor. Because we don't change for
	// terminate/cancels, we can go directly to history for other service calls.
	FrontendClient workflowservice.WorkflowServiceClient
}

type Library

type Library struct {
	chasm.UnimplementedLibrary

	SchedulerIdleTaskHandler        *SchedulerIdleTaskHandler
	SchedulerCallbacksTaskHandler   *SchedulerCallbacksTaskHandler
	GeneratorTaskHandler            *GeneratorTaskHandler
	InvokerExecuteTaskHandler       *InvokerExecuteTaskHandler
	InvokerProcessBufferTaskHandler *InvokerProcessBufferTaskHandler
	BackfillerTaskHandler           *BackfillerTaskHandler
	MigrateToWorkflowTaskHandler    *SchedulerMigrateToWorkflowTaskHandler
	// contains filtered or unexported fields
}

func NewLibrary

func NewLibrary(
	config *Config,
	handler *handler,
	SchedulerIdleTaskHandler *SchedulerIdleTaskHandler,
	SchedulerCallbacksTaskHandler *SchedulerCallbacksTaskHandler,
	GeneratorTaskHandler *GeneratorTaskHandler,
	InvokerExecuteTaskHandler *InvokerExecuteTaskHandler,
	InvokerProcessBufferTaskHandler *InvokerProcessBufferTaskHandler,
	BackfillerTaskHandler *BackfillerTaskHandler,
	MigrateToWorkflowTaskHandler *SchedulerMigrateToWorkflowTaskHandler,
) *Library

func NewNilLibrary

func NewNilLibrary() *Library

NewNilLibrary creates a Library with all nil handlers. Useful for registration-only contexts like tdbg where no task execution is needed.

func (*Library) Components

func (l *Library) Components() []*chasm.RegistrableComponent

func (*Library) Name

func (l *Library) Name() string

func (*Library) RegisterServices

func (l *Library) RegisterServices(server *grpc.Server)

func (*Library) Tasks

func (l *Library) Tasks() []*chasm.RegistrableTask

type MockSpecProcessor

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

MockSpecProcessor is a mock of SpecProcessor interface.

func NewMockSpecProcessor

func NewMockSpecProcessor(ctrl *gomock.Controller) *MockSpecProcessor

NewMockSpecProcessor creates a new mock instance.

func (*MockSpecProcessor) EXPECT

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockSpecProcessor) NextTime

func (m *MockSpecProcessor) NextTime(arg0 *Scheduler, after time.Time) (scheduler.GetNextTimeResult, error)

NextTime mocks base method.

func (*MockSpecProcessor) ProcessTimeRange

func (m *MockSpecProcessor) ProcessTimeRange(arg0 *Scheduler, start, end time.Time, overlapPolicy enums.ScheduleOverlapPolicy, workflowID, backfillID string, manual bool, limit *int) (*ProcessedTimeRange, error)

ProcessTimeRange mocks base method.

type MockSpecProcessorMockRecorder

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

MockSpecProcessorMockRecorder is the mock recorder for MockSpecProcessor.

func (*MockSpecProcessorMockRecorder) NextTime

func (mr *MockSpecProcessorMockRecorder) NextTime(arg0, after any) *gomock.Call

NextTime indicates an expected call of NextTime.

func (*MockSpecProcessorMockRecorder) ProcessTimeRange

func (mr *MockSpecProcessorMockRecorder) ProcessTimeRange(arg0, start, end, overlapPolicy, workflowID, backfillID, manual, limit any) *gomock.Call

ProcessTimeRange indicates an expected call of ProcessTimeRange.

type ProcessedTimeRange

type ProcessedTimeRange struct {
	NextWakeupTime time.Time
	LastActionTime time.Time
	BufferedStarts []*schedulespb.BufferedStart
	// DroppedCount is the number of actions that would have been buffered but
	// were dropped due to the limit being reached. Only populated when a limit
	// is provided.
	DroppedCount int64
}

type Scheduler

type Scheduler struct {
	chasm.UnimplementedComponent

	// Persisted internal state, consisting of state relevant to all components in
	// the scheduler tree.
	*schedulerpb.SchedulerState

	// Last success/failure payloads, stored on this separate data node
	// to minimize write traffic.
	LastCompletionResult chasm.Field[*schedulerpb.LastCompletionResult]

	Generator   chasm.Field[*Generator]
	Invoker     chasm.Field[*Invoker]
	Backfillers chasm.Map[string, *Backfiller] // Backfill ID => *Backfiller

	// Human-readable event history used for debugging.
	EventLog chasm.Field[*EventLog]

	Visibility chasm.Field[*chasm.Visibility]
	// contains filtered or unexported fields
}

Scheduler is the root component of a CHASM scheduler tree. The rest of the tree will consist of 2 or more sub-components: - Generator: buffers actions according to the schedule specification - Invoker: executes buffered actions - Backfiller: buffers actions according to requested backfills

func CreateScheduler

func CreateScheduler(
	ctx chasm.MutableContext,
	req *schedulerpb.CreateScheduleRequest,
) (*Scheduler, error)

CreateScheduler initializes a new Scheduler for CreateSchedule requests.

func CreateSchedulerFromMigration

func CreateSchedulerFromMigration(
	ctx chasm.MutableContext,
	req *schedulerpb.CreateFromMigrationStateRequest,
) (*Scheduler, error)

CreateSchedulerFromMigration initializes a CHASM scheduler from migrated V1 state. Unlike CreateScheduler, this preserves the conflict token and other state from V1.

The migrated state components (scheduler, generator, invoker, backfillers) are directly initialized from the request, preserving all state including the conflict token for client compatibility.

func CreateSentinelFn

func CreateSentinelFn(
	ctx chasm.MutableContext,
	req *schedulerpb.CreateSentinelRequest,
) (*Scheduler, error)

CreateSentinelFn is the chasm.StartExecution factory for creating sentinel schedulers. Used by the V1 path to reserve the CHASM key space.

func NewScheduler

func NewScheduler(
	ctx chasm.MutableContext,
	namespace, namespaceID, scheduleID string,
	input *schedulepb.Schedule,
	patch *schedulepb.SchedulePatch,
) (*Scheduler, error)

NewScheduler returns an initialized CHASM scheduler root component.

func NewSentinel

func NewSentinel(
	ctx chasm.MutableContext,
	namespace, namespaceID, scheduleID string,
) *Scheduler

NewSentinel returns a sentinel CHASM scheduler that exists only to reserve the schedule ID. Sentinels have no sub-components (other than Info for idle tracking) and return NotFound on all API operations. An idle task auto-closes the sentinel after SentinelIdleTime.

func (*Scheduler) ContextMetadata

func (s *Scheduler) ContextMetadata(_ chasm.Context) map[string]string

func (*Scheduler) Delete

Delete marks the Scheduler as closed without an idle timer.

func (*Scheduler) Describe

Describe returns the current state of the Scheduler for DescribeSchedule requests.

func (*Scheduler) HandleNexusCompletion

func (s *Scheduler) HandleNexusCompletion(
	ctx chasm.MutableContext,
	info *persistencespb.ChasmNexusCompletion,
) error

HandleNexusCompletion allows Scheduler to record workflow completions from worfklows started by the same scheduler tree's Invoker.

func (*Scheduler) IsSentinel

func (s *Scheduler) IsSentinel() bool

IsSentinel returns true if this is a sentinel scheduler.

func (*Scheduler) LifecycleState

func (s *Scheduler) LifecycleState(ctx chasm.Context) chasm.LifecycleState

LifecycleState implements the chasm.Component interface.

func (*Scheduler) ListInfo

func (s *Scheduler) ListInfo(
	ctx chasm.Context,
) *schedulepb.ScheduleListInfo

ListInfo returns the ScheduleListInfo, used as the visibility memo, and to answer List queries.

func (*Scheduler) ListMatchingTimes

ListMatchingTimes returns the upcoming times that the schedule will trigger within the given time range.

func (*Scheduler) Memo

func (s *Scheduler) Memo(
	ctx chasm.Context,
) proto.Message

Memo returns the scheduler's info block for visibility.

func (*Scheduler) MigrateToWorkflow

MigrateToWorkflow pauses the schedule and schedules a side-effect task to start the V1 workflow. This is the CHASM-side operation for V2-to-V1 migration. It is idempotent: if a migration is already pending, it returns success without taking any action.

func (*Scheduler) NewImmediateBackfiller

func (s *Scheduler) NewImmediateBackfiller(
	ctx chasm.MutableContext,
	request *schedulepb.TriggerImmediatelyRequest,
) *Backfiller

NewImmediateBackfiller returns an intialized Backfiller component, which should be parented under a Scheduler root node.

func (*Scheduler) NewRangeBackfiller

func (s *Scheduler) NewRangeBackfiller(
	ctx chasm.MutableContext,
	request *schedulepb.BackfillRequest,
) *Backfiller

NewRangeBackfiller returns an intialized Backfiller component, which should be parented under a Scheduler root node.

func (*Scheduler) Patch

Patch applies a patch to the schedule for PatchSchedule requests.

func (*Scheduler) SearchAttributes

func (s *Scheduler) SearchAttributes(ctx chasm.Context) []chasm.SearchAttributeKeyValue

SearchAttributes returns the Temporal-managed key values for visibility.

func (*Scheduler) Terminate

Terminate implements the chasm.RootComponent interface.

func (*Scheduler) Update

Update replaces the schedule with a new one for UpdateSchedule requests.

func (*Scheduler) WorkflowID

func (s *Scheduler) WorkflowID() string

WorkflowID returns the Workflow ID given as part of the request spec. During start generation, nominal time is suffixed to this ID.

type SchedulerCallbacksTaskHandler

type SchedulerCallbacksTaskHandler struct {
	chasm.SideEffectTaskHandlerBase[*schedulerpb.SchedulerCallbacksTask]
	// contains filtered or unexported fields
}

func (*SchedulerCallbacksTaskHandler) Execute

func (*SchedulerCallbacksTaskHandler) Validate

type SchedulerCallbacksTaskHandlerOptions

type SchedulerCallbacksTaskHandlerOptions struct {
	fx.In

	Config         *Config
	HistoryClient  resource.HistoryClient
	FrontendClient workflowservice.WorkflowServiceClient
}

type SchedulerIdleTaskHandler

type SchedulerIdleTaskHandler struct {
	chasm.PureTaskHandlerBase
	// contains filtered or unexported fields
}

func (*SchedulerIdleTaskHandler) Execute

func (*SchedulerIdleTaskHandler) Validate

func (r *SchedulerIdleTaskHandler) Validate(
	ctx chasm.Context,
	scheduler *Scheduler,
	taskAttrs chasm.TaskInvocation,
	task *schedulerpb.SchedulerIdleTask,
) (bool, error)

type SchedulerIdleTaskHandlerOptions

type SchedulerIdleTaskHandlerOptions struct {
	fx.In

	Config         *Config
	MetricsHandler metrics.Handler
	BaseLogger     log.Logger
}

type SchedulerMigrateToWorkflowTaskHandler

type SchedulerMigrateToWorkflowTaskHandler struct {
	chasm.SideEffectTaskHandlerBase[*schedulerpb.SchedulerMigrateToWorkflowTask]
	// contains filtered or unexported fields
}

func (*SchedulerMigrateToWorkflowTaskHandler) Execute

func (*SchedulerMigrateToWorkflowTaskHandler) Validate

type SchedulerMigrateToWorkflowTaskHandlerOptions

type SchedulerMigrateToWorkflowTaskHandlerOptions struct {
	fx.In

	Config           *Config
	MetricsHandler   metrics.Handler
	BaseLogger       log.Logger
	HistoryClient    resource.HistoryClient
	SaMapperProvider searchattribute.MapperProvider
}

type SpecProcessor

type SpecProcessor interface {
	// ProcessTimeRange generates buffered actions according to the schedule spec for
	// the given time range.
	//
	// The parameter manual is propagated to the returned BufferedStarts. When the limit
	// is set to a non-nil pointer, it will be decremented for each buffered start, and
	// the function will return early should limit reach 0.
	//
	// If backfillID is set, it will be used to generate request IDs.
	ProcessTimeRange(
		scheduler *Scheduler,
		start, end time.Time,
		overlapPolicy enumspb.ScheduleOverlapPolicy,
		workflowID string,
		backfillID string,
		manual bool,
		limit *int,
	) (*ProcessedTimeRange, error)

	// NextTime provides a peek at the next time in the spec following 'after'.
	NextTime(scheduler *Scheduler, after time.Time) (legacyscheduler.GetNextTimeResult, error)
}

SpecProcessor is used by the Generator and Backfiller to generate buffered actions according to the schedule spec.

type SpecProcessorImpl

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

func NewSpecProcessor

func NewSpecProcessor(
	config *Config,
	metricsHandler metrics.Handler,
	logger log.Logger,
	specBuilder *legacyscheduler.SpecBuilder,
) *SpecProcessorImpl

func (*SpecProcessorImpl) NextTime

func (s *SpecProcessorImpl) NextTime(scheduler *Scheduler, after time.Time) (legacyscheduler.GetNextTimeResult, error)

NextTime returns the next time result, or an error if the schedule cannot be compiled.

func (*SpecProcessorImpl) ProcessTimeRange

func (s *SpecProcessorImpl) ProcessTimeRange(
	scheduler *Scheduler,
	start, end time.Time,
	overlapPolicy enumspb.ScheduleOverlapPolicy,
	workflowID string,
	backfillID string,
	manual bool,
	limit *int,
) (*ProcessedTimeRange, error)

type Tweakables

type Tweakables struct {
	DefaultCatchupWindow              time.Duration // Default for catchup window
	MinCatchupWindow                  time.Duration // Minimum for catchup window
	MaxBufferSize                     int           // MaxBufferSize limits the number of buffered actions pending execution in total
	GeneratorBufferReserveSize        int           // Minimum number of spaces in `BufferedStarts` reserved for automated actions.
	CanceledTerminatedCountAsFailures bool          // Whether cancelled+terminated count for pause-on-failure
	MaxActionsPerExecution            int           // Limits the number of actions (startWorkflow, terminate/cancel) taken by ExecuteTask in a single iteration
	IdleTime                          time.Duration // How long to keep schedules after they're done
	EventLogMaxEntries                int           // Maximum EventLog entries retained per component; the earliest entries are dropped beyond this.
	EventLogMaxMessageLen             int           // Maximum byte length of an EventLog message; longer messages are truncated at a UTF-8 boundary.
}

Directories

Path Synopsis
gen
schedulerpb/v1
Code generated by protoc-gen-go-helpers.
Code generated by protoc-gen-go-helpers.

Jump to

Keyboard shortcuts

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