chasm

package
v1.32.0 Latest Latest
Warning

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

Go to latest
Published: Apr 22, 2026 License: MIT Imports: 45 Imported by: 0

Documentation

Overview

Package chasm is a generated GoMock package.

Package chasm is a generated GoMock package.

Package chasm is a generated GoMock package.

Package chasm is a generated GoMock package.

Package chasm is a generated GoMock package.

Index

Constants

View Source
const (
	CallbackLibraryName   = "callback"
	CallbackComponentName = "callback"
)
View Source
const (
	SchedulerLibraryName   = "scheduler"
	SchedulerComponentName = "scheduler"
)
View Source
const (
	UserMemoKey  = "__user__"
	ChasmMemoKey = "__chasm__"
)
View Source
const (
	WorkflowLibraryName   = "workflow"
	WorkflowComponentName = "workflow"
)
View Source
const NexusCompletionHandlerURL = "temporal://internal"

NexusCompletionHandlerURL is the user-visible URL for Nexus->CHASM callbacks.

Variables

View Source
var (
	SearchAttributeFieldBool01 = newSearchAttributeFieldBool(1)
	SearchAttributeFieldBool02 = newSearchAttributeFieldBool(2)

	SearchAttributeFieldDateTime01 = newSearchAttributeFieldDateTime(1)
	SearchAttributeFieldDateTime02 = newSearchAttributeFieldDateTime(2)

	SearchAttributeFieldInt01 = newSearchAttributeFieldInt(1)
	SearchAttributeFieldInt02 = newSearchAttributeFieldInt(2)

	SearchAttributeFieldDouble01 = newSearchAttributeFieldDouble(1)
	SearchAttributeFieldDouble02 = newSearchAttributeFieldDouble(2)

	SearchAttributeFieldKeyword01 = newSearchAttributeFieldKeyword(1)
	SearchAttributeFieldKeyword02 = newSearchAttributeFieldKeyword(2)
	SearchAttributeFieldKeyword03 = newSearchAttributeFieldKeyword(3)
	SearchAttributeFieldKeyword04 = newSearchAttributeFieldKeyword(4)

	// SearchAttributeFieldLowCardinalityKeyword is a search attribute field for a low cardinality keyword value.
	// Used for categorical data that support GROUP BY aggregations, eg. CHASM Execution Statuses.
	SearchAttributeFieldLowCardinalityKeyword01 = newSearchAttributeFieldLowCardinalityKeyword(1)

	SearchAttributeFieldKeywordList01 = newSearchAttributeFieldKeywordList(1)
	SearchAttributeFieldKeywordList02 = newSearchAttributeFieldKeywordList(2)

	SearchAttributeTaskQueue                            = newSearchAttributeKeywordByField(sadefs.TaskQueue)
	SearchAttributeTemporalChangeVersion                = newSearchAttributeKeywordListByField(sadefs.TemporalChangeVersion)
	SearchAttributeBinaryChecksums                      = newSearchAttributeKeywordListByField(sadefs.BinaryChecksums)
	SearchAttributeBuildIds                             = newSearchAttributeKeywordListByField(sadefs.BuildIds)
	SearchAttributeBatcherNamespace                     = newSearchAttributeKeywordByField(sadefs.BatcherNamespace)
	SearchAttributeBatcherUser                          = newSearchAttributeKeywordByField(sadefs.BatcherUser)
	SearchAttributeTemporalScheduledStartTime           = newSearchAttributeDateTimeByField(sadefs.TemporalScheduledStartTime)
	SearchAttributeTemporalScheduledByID                = newSearchAttributeKeywordByField(sadefs.TemporalScheduledById)
	SearchAttributeTemporalSchedulePaused               = newSearchAttributeBoolByField(sadefs.TemporalSchedulePaused)
	SearchAttributeTemporalNamespaceDivision            = newSearchAttributeKeywordByField(sadefs.TemporalNamespaceDivision)
	SearchAttributeTemporalPauseInfo                    = newSearchAttributeKeywordListByField(sadefs.TemporalPauseInfo)
	SearchAttributeTemporalReportedProblems             = newSearchAttributeKeywordListByField(sadefs.TemporalReportedProblems)
	SearchAttributeTemporalWorkerDeploymentVersion      = newSearchAttributeKeywordByField(sadefs.TemporalWorkerDeploymentVersion)
	SearchAttributeTemporalWorkflowVersioningBehavior   = newSearchAttributeKeywordByField(sadefs.TemporalWorkflowVersioningBehavior)
	SearchAttributeTemporalWorkerDeployment             = newSearchAttributeKeywordByField(sadefs.TemporalWorkerDeployment)
	SearchAttributeTemporalUsedWorkerDeploymentVersions = newSearchAttributeKeywordListByField(sadefs.TemporalUsedWorkerDeploymentVersions)
)

CHASM Search Attribute User Guide:

This contains CHASM search attribute field constants. These predefined fields correspond to the exact column name in Visibility storage. For each root component, search attributes can be mapped from a user defined alias to these fields. Each component must register its search attributes with the CHASM Registry.

To define a CHASM search attribute, create this as a package/global scoped variable. Below is an example: var testComponentCompletedSearchAttribute = NewSearchAttributeBool("Completed", SearchAttributeFieldBool01) var testComponentFailedSearchAttribute = NewSearchAttributeBool("Failed", SearchAttributeFieldBool02) var testComponentStartTimeSearchAttribute = NewSearchAttributeTime("StartTime", SearchAttributeFieldDateTime01) var testComponentCategorySearchAttribute = NewSearchAttributeLowCardinalityKeyword("Category", SearchAttributeFieldLowCardinalityKeyword01)

Each CHASM search attribute field is associated with a specific indexed value type. The Value() method of a search attribute specifies the supported value type to set at compile time. eg. DateTime values must be set with a time.Time typed value.

Low Cardinality Keyword Fields: used for categorical data that support GROUP BY aggregations. Values must be limited to a small number of dimensions.

Each root component can only use a predefined search attribute field once. Developers should not reassign aliases to different fields. Reassiging aliases to different fields will result in incorrect visibility query results.

To register these search attributes with the CHASM Registry, use the WithSearchAttributes() option when creating the component in the library. eg. NewRegistrableComponent[T]("testcomponent", WithSearchAttributes(testComponentCompletedSearchAttribute, testComponentStartTimeSearchAttribute))

View Source
var ErrInvalidComponentRef = serviceerror.NewInvalidArgument("invalid component ref")

ErrInvalidComponentRef is returned when component ref bytes deserialize to an invalid component ref.

View Source
var ErrInvalidTransition = serviceerror.NewFailedPrecondition("invalid transition")

ErrInvalidTransition is returned from Transition.Apply on an invalid state transition.

View Source
var ErrMalformedComponentRef = serviceerror.NewInvalidArgument("malformed component ref")

ErrMalformedComponentRef is returned when component ref bytes cannot be deserialized.

View Source
var Module = fx.Module(
	"chasm",
	fx.Provide(NewRegistry),
	fx.Invoke(func(registry *Registry) error {
		return registry.Register(&CoreLibrary{})
	}),
)
View Source
var TaskScheduledTimeImmediate = time.Time{}
View Source
var UnimplementedComponentT = reflect.TypeFor[UnimplementedComponent]()

Functions

func AugmentContextForComponent

func AugmentContextForComponent[C Context](
	ctx C,
	component any,
	registry *Registry,
) C

AugmentContextForComponent returns a new Context with all context values associated with the given component in the registry added. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func ContextWithValue

func ContextWithValue[C Context](c C, key any, value any) C

ContextWithValue returns a new Context with the given key-value pair added. Added key-value pairs will be accessible via the Value() method on the returned Context, and the behavior of the key-value pair is the same as context.Context.WithValue().

func DeleteExecution

func DeleteExecution[C RootComponent](
	ctx context.Context,
	key ExecutionKey,
	request DeleteExecutionRequest,
) error

DeleteExecution deletes the execution identified by the supplied execution key. If the execution is still running, it is terminated first. A DeleteExecutionTask is then queued to remove all execution data from persistence.

func ExecutionStateChanged

func ExecutionStateChanged(c Component, ctx Context, refBytes []byte) (bool, error)

ExecutionStateChanged returns true if execution state has advanced beyond the state encoded in refBytes. It may return ErrInvalidComponentRef or ErrMalformedComponentRef. Callers should consider converting these to serviceerror.NewInvalidArgument.

func FullyQualifiedName

func FullyQualifiedName(libName, name string) string

FullyQualifiedName creates a fully qualified name (FQN) by combining a library name and a component or task name. The FQN is used to uniquely identify components and tasks within the CHASM framework. The format of the returned FQN is: "libName.name"

func GenerateNexusCallback

func GenerateNexusCallback(ctx Context, component NexusCompletionHandlerComponent) (*commonpb.Callback, error)

GenerateNexusCallback generates a Callback message indicating a CHASM component to receive Nexus operation completion callbacks. Particularly useful for components that want to track a workflow start with StartWorkflowExecution.

func GenerateTypeID

func GenerateTypeID(fqn string) uint32

GenerateTypeID generates a unique 32-bit identifier from a fully qualified name (FQN). The generated ID is used to uniquely identify components and tasks within the CHASM framework. The same FQN will always produce the same ID.

func NewEngineContext

func NewEngineContext(
	ctx context.Context,
	engine Engine,
) context.Context

this will be done by the nexus handler? alternatively the engine can be a global variable, but not a good practice in fx.

func NewVisibilityManagerContext

func NewVisibilityManagerContext(
	ctx context.Context,
	engine VisibilityManager,
) context.Context

func PollComponent

func PollComponent[C any, R []byte | ComponentRef, I any, O any](
	ctx context.Context,
	r R,
	monotonicPredicate func(C, Context, I) (O, bool, error),
	input I,
	opts ...TransitionOption,
) (O, []byte, error)

PollComponent waits until the predicate is true when evaluated against the component identified by the supplied component reference. If this times out due to a server-imposed long-poll timeout then it returns (nil, nil, nil), as an indication that the caller should continue long-polling. Otherwise it returns (output, ref, err), where output is the output of the predicate function, and ref is a component reference identifying the state at which the predicate was satisfied. The predicate must be monotonic: if it returns true at execution state transition s then it must return true at all transitions t > s. If the predicate is true at the outset then PollComponent returns immediately. opts are currently ignored.

func ReadComponent

func ReadComponent[C any, R []byte | ComponentRef, I any, O any](
	ctx context.Context,
	r R,
	readFn func(C, Context, I) (O, error),
	input I,
	opts ...TransitionOption,
) (O, error)

ReadComponent returns the result of evaluating readFn against the component identified by the component reference. opts are currently ignored.

func SearchAttributeValue

func SearchAttributeValue[T any](m SearchAttributesMap, sa typedSearchAttribute[T]) (val T, ok bool)

SearchAttributeValue returns the value for a given SearchAttribute with compile-time type safety. The return type T is inferred from the SearchAttribute's type parameter. For example, SearchAttributeBool will return a bool value. If the value is not found or the type does not match, the zero value for the type T is returned and the second return value is false.

func UpdateComponent

func UpdateComponent[C any, R []byte | ComponentRef, I any, O any](
	ctx context.Context,
	r R,
	updateFn func(C, MutableContext, I) (O, error),
	input I,
	opts ...TransitionOption,
) (O, []byte, error)

TODO:

  • consider merge with ReadComponent
  • consider remove ComponentRef from the return value and allow components to get the ref in the transition function. There are some caveats there, check the comment of the NewRef method in MutableContext.

UpdateComponent applies updateFn to the component identified by the supplied component reference. It returns the result, along with the new component reference. opts are currently ignored.

Types

type Archetype

type Archetype = string

Archetype is the fully qualified name of the root component of a CHASM execution.

type ArchetypeID

type ArchetypeID = uint32

ArchetypeID is CHASM framework's internal ID for an Archetype.

const (
	// UnspecifiedArchetypeID is a reserved special ArchetypeID value indicating that the
	// ArchetypeID is not specified.
	// This typically happens when:
	// 1. The chasm tree is not yet initialized with a root component,
	// 2. If it's a field in a persisted record, it means the record is persisted before archetypeID
	// was introduced (basically Workflow).
	UnspecifiedArchetypeID ArchetypeID = 0
)

type BusinessIDConflictPolicy

type BusinessIDConflictPolicy int
const (
	BusinessIDConflictPolicyFail BusinessIDConflictPolicy = iota
	BusinessIDConflictPolicyTerminateExisting
	BusinessIDConflictPolicyUseExisting
)

type BusinessIDReusePolicy

type BusinessIDReusePolicy int
const (
	BusinessIDReusePolicyAllowDuplicate BusinessIDReusePolicy = iota
	BusinessIDReusePolicyAllowDuplicateFailedOnly
	BusinessIDReusePolicyRejectDuplicate
)

type ChasmEngineInterceptor

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

ChasmEngineInterceptor Interceptor that intercepts RPC requests, detects CHASM-specific calls and does additional boilerplate processing before handing off. Visibility is injected separately with ChasmVisibilityInterceptor.

func ChasmEngineInterceptorProvider

func ChasmEngineInterceptorProvider(
	engine Engine,
	logger log.Logger,
	metricsHandler metrics.Handler,
) *ChasmEngineInterceptor

func (*ChasmEngineInterceptor) Intercept

func (i *ChasmEngineInterceptor) Intercept(
	ctx context.Context,
	req any,
	info *grpc.UnaryServerInfo,
	handler grpc.UnaryHandler,
) (resp any, retError error)

type ChasmVisibilityInterceptor

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

ChasmVisibilityInterceptor intercepts RPC requests and adds the CHASM VisibilityManager to their context.

func ChasmVisibilityInterceptorProvider

func ChasmVisibilityInterceptorProvider(visibilityMgr VisibilityManager) *ChasmVisibilityInterceptor

func (*ChasmVisibilityInterceptor) Intercept

func (i *ChasmVisibilityInterceptor) Intercept(
	ctx context.Context,
	req any,
	info *grpc.UnaryServerInfo,
	handler grpc.UnaryHandler,
) (resp any, retError error)

type Component

type Component interface {
	LifecycleState(Context) LifecycleState
	// contains filtered or unexported methods
}

type ComponentFieldOption

type ComponentFieldOption func(*componentFieldOptions)

func ComponentFieldDetached

func ComponentFieldDetached() ComponentFieldOption

type ComponentRef

type ComponentRef struct {
	ExecutionKey
	// contains filtered or unexported fields
}

func DeserializeComponentRef

func DeserializeComponentRef(data []byte) (ComponentRef, error)

DeserializeComponentRef deserializes a byte slice into a ComponentRef. Provides caller the access to information including ExecutionKey, Archetype, and ShardingKey.

func NewComponentRef

func NewComponentRef[C Component](
	executionKey ExecutionKey,
) ComponentRef

NewComponentRef creates a new ComponentRef with a registered root component go type.

In V1, if you don't have a ref, then you can only interact with the (top level) execution.

func ProtoRefToComponentRef

func ProtoRefToComponentRef(pRef *persistencespb.ChasmComponentRef) ComponentRef

ProtoRefToComponentRef converts a persistence ChasmComponentRef reference to a ComponentRef. This is useful for situations where the protobuf ComponentRef has already been deserialized as part of an enclosing message.

func (*ComponentRef) ArchetypeID

func (r *ComponentRef) ArchetypeID(
	registry *Registry,
) (ArchetypeID, error)

func (*ComponentRef) Serialize

func (r *ComponentRef) Serialize(
	registry *Registry,
) ([]byte, error)

type Context

type Context interface {

	// NOTE: component created in the current transaction won't have a ref
	// this is a Ref to the component state at the start of the transition
	Ref(Component) ([]byte, error)
	// Now returns the current time in the context of the given component.
	// In a context of a transaction, this time must be used to allow for framework support of pause and time skipping.
	Now(Component) time.Time
	// ExecutionKey returns the execution key for the execution the context is operating on.
	ExecutionKey() ExecutionKey
	// StateTransitionCount returns the number of create/update transactions in the history of this execution.
	StateTransitionCount() int64
	// ExecutionCloseTime returns the time when the execution was closed. An execution is closed when its root component reaches a terminal
	// state in its lifecycle. If the component is still running (not yet closed), it returns a zero time.Time value.
	ExecutionCloseTime() time.Time
	// Logger returns a logger tagged with execution key and other chasm framework internal information.
	Logger() log.Logger
	// MetricsHandler returns a metrics handler with bare minimum tags (no namespace tag).
	MetricsHandler() metrics.Handler
	// Value returns the value associated with this context for key. The behavior is the same as context.Context.Value().
	// Use WithContextValues RegistrableComponentOption to set key values pair for a component upon registration.
	// Registered key-value pairs will automatically be added to the Context whenever framework accesses the component.
	// Alternatively, use ContextWithValue() to manually set values on Context.
	Value(key any) any
	// contains filtered or unexported methods
}

func NewContext

func NewContext(
	ctx context.Context,
	node *Node,
) Context

NewContext creates a new Context from an existing Context and root Node.

NOTE: Library authors should not invoke this constructor directly, and instead use ReadComponent.

type CoreLibrary

type CoreLibrary struct {
	UnimplementedLibrary
}

CoreLibrary contains built-in components maintained as part of the CHASM framework.

func (*CoreLibrary) Components

func (b *CoreLibrary) Components() []*RegistrableComponent

func (*CoreLibrary) Name

func (b *CoreLibrary) Name() string

func (*CoreLibrary) Tasks

func (b *CoreLibrary) Tasks() []*RegistrableTask

type CountExecutionsRequest

type CountExecutionsRequest struct {
	NamespaceID   string
	NamespaceName string
	Query         string
}

type CountExecutionsResponse

type CountExecutionsResponse struct {
	Count  int64
	Groups []Group
}

func CountExecutions

func CountExecutions[C Component](
	ctx context.Context,
	request *CountExecutionsRequest,
) (*CountExecutionsResponse, error)

CountExecutions counts the executions of a CHASM archetype given an initial query. The generic parameter C is the CHASM component type used for executions and search attribute filtering. The query string can specify any combination of CHASM, custom, and predefined/system search attributes. Note: For CHASM executions, TemporalNamespaceDivision is the predefined search attribute that is used to identify the archetype of the execution. If the query string does not specify TemporalNamespaceDivision, the archetype C of the request will be used to count the executions. If the initial query already specifies TemporalNamespaceDivision, the archetype C of the request will only be used to get the registered SearchAttributes.

type DeleteExecutionRequest

type DeleteExecutionRequest struct {
	TerminateComponentRequest
}

DeleteExecutionRequest is the request for DeleteExecution. TerminateComponentRequest will only be used if the execution is still running. The actual deletion of the execution is async, and will return after creating the DeleteExecutionTask.

type Engine

type Engine interface {
	StartExecution(
		context.Context,
		ComponentRef,
		func(MutableContext, ArchetypeID, *Registry) (RootComponent, error),
		...TransitionOption,
	) (StartExecutionResult, error)
	UpdateWithStartExecution(
		context.Context,
		ComponentRef,
		func(MutableContext, ArchetypeID, *Registry) (RootComponent, error),
		func(MutableContext, Component, *Registry) error,
		...TransitionOption,
	) (EngineUpdateWithStartExecutionResult, error)

	UpdateComponent(
		context.Context,
		ComponentRef,
		func(MutableContext, Component, *Registry) error,
		...TransitionOption,
	) ([]byte, error)
	ReadComponent(
		context.Context,
		ComponentRef,
		func(Context, Component, *Registry) error,
		...TransitionOption,
	) error

	PollComponent(
		context.Context,
		ComponentRef,
		func(Context, Component, *Registry) (bool, error),
		...TransitionOption,
	) ([]byte, error)

	DeleteExecution(
		context.Context,
		ComponentRef,
		DeleteExecutionRequest,
	) error

	// NotifyExecution notifies any PollComponent callers waiting on the execution.
	NotifyExecution(ExecutionKey)
}

type EngineUpdateWithStartExecutionResult

type EngineUpdateWithStartExecutionResult = UpdateWithStartExecutionResult[struct{}]

EngineUpdateWithStartExecutionResult is a type alias for the result type returned by the UpdateWithStart Engine implementation.

type ExecutionAlreadyStartedError

type ExecutionAlreadyStartedError struct {
	Message          string
	CurrentRequestID string
	CurrentRunID     string
}

func NewExecutionAlreadyStartedErr

func NewExecutionAlreadyStartedErr(
	message, currentRequestID, currentRunID string,
) *ExecutionAlreadyStartedError

func (*ExecutionAlreadyStartedError) Error

type ExecutionInfo

type ExecutionInfo[M proto.Message] struct {
	BusinessID             string
	RunID                  string
	StartTime              time.Time
	CloseTime              time.Time
	HistoryLength          int64
	HistorySizeBytes       int64
	StateTransitionCount   int64
	ChasmSearchAttributes  SearchAttributesMap
	CustomSearchAttributes map[string]*commonpb.Payload
	Memo                   *commonpb.Memo
	ChasmMemo              M
}

type ExecutionKey

type ExecutionKey struct {
	NamespaceID string
	BusinessID  string
	RunID       string
}

ExecutionKey uniquely identifies a CHASM execution in the system.

type Field

type Field[T any] struct {
	// This struct needs to be created via reflection, but reflection can't set private fields.
	Internal fieldInternal
}

func ComponentPointerTo

func ComponentPointerTo[C Component](
	ctx MutableContext,
	c C,
) Field[C]

ComponentPointerTo returns a CHASM field populated with a pointer to the given component. Pointers are resolved at the time the transaction is closed, and the transaction will fail if any pointers cannot be resolved.

func DataPointerTo

func DataPointerTo[D proto.Message](
	ctx MutableContext,
	d D,
) Field[D]

DataPointerTo returns a CHASM field populated with a pointer to the given message. Pointers are resolved at the time the transaction is closed, and the transaction will fail if any pointers cannot be resolved.

func NewComponentField

func NewComponentField[C Component](
	ctx MutableContext,
	c C,
	options ...ComponentFieldOption,
) Field[C]

func NewDataField

func NewDataField[D proto.Message](
	ctx MutableContext,
	d D,
) Field[D]

re. Data v.s. Component. Components have behavior and has a lifecycle. while Data doesn't and must be attached to a component.

You can define a component just for storing the data, that may contain other information like ref count etc. most importantly, the framework needs to know when it's safe to delete the data. i.e. the lifecycle of that data component reaches completed.

func NewEmptyField

func NewEmptyField[T any]() Field[T]

func (Field[T]) Get

func (f Field[T]) Get(chasmContext Context) T

Get returns the value of the field, deserializing it if necessary. Panics rather than returning an error, as errors are supposed to be handled by the framework as opposed to the application, even if the error is an application bug.

func (Field[T]) TryGet

func (f Field[T]) TryGet(chasmContext Context) (T, bool)

TryGet returns the value of the field and a boolean indicating if the value was found, deserializing if necessary. Panics rather than returning an error, as errors are supposed to be handled by the framework as opposed to the application, even if the error is an application bug.

type Group

type Group struct {
	Values []*commonpb.Payload
	Count  int64
}

type Library

type Library interface {
	Name() string
	Components() []*RegistrableComponent
	Tasks() []*RegistrableTask
	RegisterServices(server *grpc.Server)
	// NexusServices returns a list of nexus.Service instances to register with the __temporal_system Nexus endpoint.
	NexusServices() []*nexus.Service
	// NexusServiceProcessors returns a list of NexusServiceProcessor instances to register with the __temporal_system
	// Nexus endpoint.
	NexusServiceProcessors() []*NexusServiceProcessor
	// contains filtered or unexported methods
}

type LifecycleState

type LifecycleState int

Shall it be named ComponentLifecycleState?

const (
	// Lifecycle states that are considered OPEN
	//
	// LifecycleStateCreated LifecycleState = 1 << iota
	LifecycleStateRunning LifecycleState = 2 << iota

	// Lifecycle states that are considered CLOSED
	//
	LifecycleStateCompleted
	LifecycleStateFailed
)

func (LifecycleState) IsClosed

func (s LifecycleState) IsClosed() bool

func (LifecycleState) String

func (s LifecycleState) String() string

type ListExecutionsRequest

type ListExecutionsRequest struct {
	NamespaceID   string
	NamespaceName string
	Query         string
	PageSize      int
	NextPageToken []byte
}

type ListExecutionsResponse

type ListExecutionsResponse[M proto.Message] struct {
	Executions    []*ExecutionInfo[M]
	NextPageToken []byte
}

func ListExecutions

func ListExecutions[C Component, M proto.Message](
	ctx context.Context,
	request *ListExecutionsRequest,
) (*ListExecutionsResponse[M], error)

ListExecutions lists the executions of a CHASM archetype given an initial query. The query string can specify any combination of CHASM, custom, and predefined/system search attributes. The generic parameter C is the CHASM component type used for executions and search attribute filtering. The generic parameter M is the type of the memo payload to be unmarshaled from the execution. PageSize is required, must be greater than 0. NextPageToken is optional, set on subsequent requests to continue listing the next page of executions. Note: For CHASM executions, TemporalNamespaceDivision is the predefined search attribute that is used to identify the archetype of the execution. If the query string does not specify TemporalNamespaceDivision, the archetype C of the request will be used to filter the executions. If the initial query already specifies TemporalNamespaceDivision, the archetype C of the request will only be used to get the registered SearchAttributes.

type MSPointer

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

MSPointer is a special CHASM type which components can use to access their Node's underlying backend (i.e. mutable state). It is used to expose methods needed from the mutable state without polluting the chasm.Context interface. When deserializing components with fields of this type, the CHASM engine will set the value to its NodeBackend. This should only be used by the Workflow component.

func NewMSPointer

func NewMSPointer(backend NodeBackend) MSPointer

NewMSPointer creates a new MSPointer instance.

func (MSPointer) GetNexusCompletion

func (m MSPointer) GetNexusCompletion(ctx Context, requestID string) (nexusrpc.CompleteOperationOptions, error)

GetNexusCompletion retrieves the Nexus operation completion data for the given request ID from the underlying mutable state.

type Map

type Map[K string | int | int8 | int32 | int64 | uint | uint8 | uint32 | uint64 | bool, T any] map[K]Field[T]

type MockComponent

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

MockComponent is a mock of Component interface.

func NewMockComponent

func NewMockComponent(ctrl *gomock.Controller) *MockComponent

NewMockComponent creates a new mock instance.

func (*MockComponent) EXPECT

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

func (*MockComponent) LifecycleState

func (m *MockComponent) LifecycleState(arg0 Context) LifecycleState

LifecycleState mocks base method.

type MockComponentMockRecorder

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

MockComponentMockRecorder is the mock recorder for MockComponent.

func (*MockComponentMockRecorder) LifecycleState

func (mr *MockComponentMockRecorder) LifecycleState(arg0 any) *gomock.Call

LifecycleState indicates an expected call of LifecycleState.

type MockContext

type MockContext struct {
	HandleExecutionKey         func() ExecutionKey
	HandleNow                  func(component Component) time.Time
	HandleRef                  func(component Component) ([]byte, error)
	HandleExecutionCloseTime   func() time.Time
	HandleStateTransitionCount func() int64
	HandleMetricsHandler       func() metrics.Handler
	// contains filtered or unexported fields
}

MockContext is a mock implementation of Context.

func (*MockContext) ExecutionCloseTime

func (c *MockContext) ExecutionCloseTime() time.Time

func (*MockContext) ExecutionKey

func (c *MockContext) ExecutionKey() ExecutionKey

func (*MockContext) Logger

func (c *MockContext) Logger() log.Logger

func (*MockContext) MetricsHandler

func (c *MockContext) MetricsHandler() metrics.Handler

func (*MockContext) Now

func (c *MockContext) Now(cmp Component) time.Time

func (*MockContext) Ref

func (c *MockContext) Ref(cmp Component) ([]byte, error)

func (*MockContext) StateTransitionCount

func (c *MockContext) StateTransitionCount() int64

func (*MockContext) Value

func (c *MockContext) Value(key any) any

type MockEngine

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

MockEngine is a mock of Engine interface.

func NewMockEngine

func NewMockEngine(ctrl *gomock.Controller) *MockEngine

NewMockEngine creates a new mock instance.

func (*MockEngine) DeleteExecution

func (m *MockEngine) DeleteExecution(arg0 context.Context, arg1 ComponentRef, arg2 DeleteExecutionRequest) error

DeleteExecution mocks base method.

func (*MockEngine) EXPECT

func (m *MockEngine) EXPECT() *MockEngineMockRecorder

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

func (*MockEngine) NotifyExecution

func (m *MockEngine) NotifyExecution(arg0 ExecutionKey)

NotifyExecution mocks base method.

func (*MockEngine) PollComponent

func (m *MockEngine) PollComponent(arg0 context.Context, arg1 ComponentRef, arg2 func(Context, Component, *Registry) (bool, error), arg3 ...TransitionOption) ([]byte, error)

PollComponent mocks base method.

func (*MockEngine) ReadComponent

func (m *MockEngine) ReadComponent(arg0 context.Context, arg1 ComponentRef, arg2 func(Context, Component, *Registry) error, arg3 ...TransitionOption) error

ReadComponent mocks base method.

func (*MockEngine) StartExecution

StartExecution mocks base method.

func (*MockEngine) UpdateComponent

func (m *MockEngine) UpdateComponent(arg0 context.Context, arg1 ComponentRef, arg2 func(MutableContext, Component, *Registry) error, arg3 ...TransitionOption) ([]byte, error)

UpdateComponent mocks base method.

func (*MockEngine) UpdateWithStartExecution

UpdateWithStartExecution mocks base method.

type MockEngineMockRecorder

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

MockEngineMockRecorder is the mock recorder for MockEngine.

func (*MockEngineMockRecorder) DeleteExecution

func (mr *MockEngineMockRecorder) DeleteExecution(arg0, arg1, arg2 any) *gomock.Call

DeleteExecution indicates an expected call of DeleteExecution.

func (*MockEngineMockRecorder) NotifyExecution

func (mr *MockEngineMockRecorder) NotifyExecution(arg0 any) *gomock.Call

NotifyExecution indicates an expected call of NotifyExecution.

func (*MockEngineMockRecorder) PollComponent

func (mr *MockEngineMockRecorder) PollComponent(arg0, arg1, arg2 any, arg3 ...any) *gomock.Call

PollComponent indicates an expected call of PollComponent.

func (*MockEngineMockRecorder) ReadComponent

func (mr *MockEngineMockRecorder) ReadComponent(arg0, arg1, arg2 any, arg3 ...any) *gomock.Call

ReadComponent indicates an expected call of ReadComponent.

func (*MockEngineMockRecorder) StartExecution

func (mr *MockEngineMockRecorder) StartExecution(arg0, arg1, arg2 any, arg3 ...any) *gomock.Call

StartExecution indicates an expected call of StartExecution.

func (*MockEngineMockRecorder) UpdateComponent

func (mr *MockEngineMockRecorder) UpdateComponent(arg0, arg1, arg2 any, arg3 ...any) *gomock.Call

UpdateComponent indicates an expected call of UpdateComponent.

func (*MockEngineMockRecorder) UpdateWithStartExecution

func (mr *MockEngineMockRecorder) UpdateWithStartExecution(arg0, arg1, arg2, arg3 any, arg4 ...any) *gomock.Call

UpdateWithStartExecution indicates an expected call of UpdateWithStartExecution.

type MockLibrary

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

MockLibrary is a mock of Library interface.

func NewMockLibrary

func NewMockLibrary(ctrl *gomock.Controller) *MockLibrary

NewMockLibrary creates a new mock instance.

func (*MockLibrary) Components

func (m *MockLibrary) Components() []*RegistrableComponent

Components mocks base method.

func (*MockLibrary) EXPECT

func (m *MockLibrary) EXPECT() *MockLibraryMockRecorder

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

func (*MockLibrary) Name

func (m *MockLibrary) Name() string

Name mocks base method.

func (*MockLibrary) NexusServiceProcessors

func (m *MockLibrary) NexusServiceProcessors() []*NexusServiceProcessor

NexusServiceProcessors mocks base method.

func (*MockLibrary) NexusServices

func (m *MockLibrary) NexusServices() []*nexus.Service

NexusServices mocks base method.

func (*MockLibrary) RegisterServices

func (m *MockLibrary) RegisterServices(server *grpc.Server)

RegisterServices mocks base method.

func (*MockLibrary) Tasks

func (m *MockLibrary) Tasks() []*RegistrableTask

Tasks mocks base method.

type MockLibraryMockRecorder

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

MockLibraryMockRecorder is the mock recorder for MockLibrary.

func (*MockLibraryMockRecorder) Components

func (mr *MockLibraryMockRecorder) Components() *gomock.Call

Components indicates an expected call of Components.

func (*MockLibraryMockRecorder) Name

func (mr *MockLibraryMockRecorder) Name() *gomock.Call

Name indicates an expected call of Name.

func (*MockLibraryMockRecorder) NexusServiceProcessors

func (mr *MockLibraryMockRecorder) NexusServiceProcessors() *gomock.Call

NexusServiceProcessors indicates an expected call of NexusServiceProcessors.

func (*MockLibraryMockRecorder) NexusServices

func (mr *MockLibraryMockRecorder) NexusServices() *gomock.Call

NexusServices indicates an expected call of NexusServices.

func (*MockLibraryMockRecorder) RegisterServices

func (mr *MockLibraryMockRecorder) RegisterServices(server any) *gomock.Call

RegisterServices indicates an expected call of RegisterServices.

func (*MockLibraryMockRecorder) Tasks

func (mr *MockLibraryMockRecorder) Tasks() *gomock.Call

Tasks indicates an expected call of Tasks.

type MockMutableContext

type MockMutableContext struct {
	MockContext

	Tasks []MockTask
	// contains filtered or unexported fields
}

MockMutableContext is a mock implementation of MutableContext that records added tasks for inspection in tests.

func (*MockMutableContext) AddTask

func (c *MockMutableContext) AddTask(component Component, attributes TaskAttributes, payload any)

type MockNodeBackend

type MockNodeBackend struct {
	// Optional function overrides. If nil, methods return zero-values.
	HandleGetExecutionState          func() *persistencespb.WorkflowExecutionState
	HandleGetExecutionInfo           func() *persistencespb.WorkflowExecutionInfo
	HandleGetCurrentVersion          func() int64
	HandleNextTransitionCount        func() int64
	HandleCurrentVersionedTransition func() *persistencespb.VersionedTransition
	HandleGetWorkflowKey             func() definition.WorkflowKey
	HandleUpdateWorkflowStateStatus  func(state enumsspb.WorkflowExecutionState, status enumspb.WorkflowExecutionStatus) (bool, error)
	HandleIsWorkflow                 func() bool
	HandleGetNexusCompletion         func(ctx context.Context, requestID string) (nexusrpc.CompleteOperationOptions, error)

	TasksByCategory     map[tasks.Category][]tasks.Task
	DeletePureTaskCalls []time.Time
	UpdateCalls         []struct {
		State  enumsspb.WorkflowExecutionState
		Status enumspb.WorkflowExecutionStatus
	}
	// contains filtered or unexported fields
}

MockNodeBackend is a lightweight manual mock for the NodeBackend interface. Methods may be stubbed by assigning the corresponding Handle fields. Update call history is recorded in the struct fields (thread-safe).

func (*MockNodeBackend) AddTasks

func (m *MockNodeBackend) AddTasks(ts ...tasks.Task)

func (*MockNodeBackend) CurrentVersionedTransition

func (m *MockNodeBackend) CurrentVersionedTransition() *persistencespb.VersionedTransition

func (*MockNodeBackend) DeleteCHASMPureTasks

func (m *MockNodeBackend) DeleteCHASMPureTasks(maxScheduledTime time.Time)

func (*MockNodeBackend) GetCurrentVersion

func (m *MockNodeBackend) GetCurrentVersion() int64

func (*MockNodeBackend) GetExecutionInfo

func (m *MockNodeBackend) GetExecutionInfo() *persistencespb.WorkflowExecutionInfo

func (*MockNodeBackend) GetExecutionState

func (m *MockNodeBackend) GetExecutionState() *persistencespb.WorkflowExecutionState

func (*MockNodeBackend) GetNexusCompletion

func (m *MockNodeBackend) GetNexusCompletion(
	ctx context.Context,
	requestID string,
) (nexusrpc.CompleteOperationOptions, error)

func (*MockNodeBackend) GetWorkflowKey

func (m *MockNodeBackend) GetWorkflowKey() definition.WorkflowKey

func (*MockNodeBackend) IsWorkflow

func (m *MockNodeBackend) IsWorkflow() bool

func (*MockNodeBackend) LastDeletePureTaskCall

func (m *MockNodeBackend) LastDeletePureTaskCall() time.Time

func (*MockNodeBackend) LastUpdateWorkflowState

func (m *MockNodeBackend) LastUpdateWorkflowState() enumsspb.WorkflowExecutionState

func (*MockNodeBackend) LastUpdateWorkflowStatus

func (m *MockNodeBackend) LastUpdateWorkflowStatus() enumspb.WorkflowExecutionStatus

func (*MockNodeBackend) NextTransitionCount

func (m *MockNodeBackend) NextTransitionCount() int64

func (*MockNodeBackend) NumTasksAdded

func (m *MockNodeBackend) NumTasksAdded() int

func (*MockNodeBackend) UpdateWorkflowStateStatus

func (m *MockNodeBackend) UpdateWorkflowStateStatus(
	state enumsspb.WorkflowExecutionState,
	status enumspb.WorkflowExecutionStatus,
) (bool, error)

type MockNodePureTask

type MockNodePureTask struct {
	HandleExecutePureTask  func(baseCtx context.Context, taskAttributes TaskAttributes, taskInstance any) (bool, error)
	HandleValidatePureTask func(baseCtx context.Context, taskAttributes TaskAttributes, taskInstance any) (bool, error)

	ExecuteCalls []struct {
		BaseCtx    context.Context
		Attributes TaskAttributes
		Task       any
	}
	ValidateCalls []struct {
		BaseCtx    context.Context
		Attributes TaskAttributes
		Task       any
	}
	// contains filtered or unexported fields
}

MockNodePureTask is a lightweight manual mock for the NodePureTask interface. Methods may be stubbed by assigning the corresponding Handle fields. Call history is recorded in the struct fields (thread-safe).

func (*MockNodePureTask) ExecutePureTask

func (m *MockNodePureTask) ExecutePureTask(
	baseCtx context.Context,
	taskAttributes TaskAttributes,
	taskInstance any,
) (bool, error)

func (*MockNodePureTask) ValidatePureTask

func (m *MockNodePureTask) ValidatePureTask(
	baseCtx context.Context,
	taskAttributes TaskAttributes,
	taskInstance any,
) (bool, error)

type MockPureTaskExecutor

type MockPureTaskExecutor[C any, T any] struct {
	// contains filtered or unexported fields
}

MockPureTaskExecutor is a mock of PureTaskExecutor interface.

func NewMockPureTaskExecutor

func NewMockPureTaskExecutor[C any, T any](ctrl *gomock.Controller) *MockPureTaskExecutor[C, T]

NewMockPureTaskExecutor creates a new mock instance.

func (*MockPureTaskExecutor[C, T]) EXPECT

func (m *MockPureTaskExecutor[C, T]) EXPECT() *MockPureTaskExecutorMockRecorder[C, T]

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

func (*MockPureTaskExecutor[C, T]) Execute

func (m *MockPureTaskExecutor[C, T]) Execute(arg0 MutableContext, arg1 C, arg2 TaskAttributes, arg3 T) error

Execute mocks base method.

type MockPureTaskExecutorMockRecorder

type MockPureTaskExecutorMockRecorder[C any, T any] struct {
	// contains filtered or unexported fields
}

MockPureTaskExecutorMockRecorder is the mock recorder for MockPureTaskExecutor.

func (*MockPureTaskExecutorMockRecorder[C, T]) Execute

func (mr *MockPureTaskExecutorMockRecorder[C, T]) Execute(arg0, arg1, arg2, arg3 any) *gomock.Call

Execute indicates an expected call of Execute.

type MockRootComponent

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

MockRootComponent is a mock of RootComponent interface.

func NewMockRootComponent

func NewMockRootComponent(ctrl *gomock.Controller) *MockRootComponent

NewMockRootComponent creates a new mock instance.

func (*MockRootComponent) EXPECT

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

func (*MockRootComponent) LifecycleState

func (m *MockRootComponent) LifecycleState(arg0 Context) LifecycleState

LifecycleState mocks base method.

func (*MockRootComponent) Terminate

Terminate mocks base method.

type MockRootComponentMockRecorder

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

MockRootComponentMockRecorder is the mock recorder for MockRootComponent.

func (*MockRootComponentMockRecorder) LifecycleState

func (mr *MockRootComponentMockRecorder) LifecycleState(arg0 any) *gomock.Call

LifecycleState indicates an expected call of LifecycleState.

func (*MockRootComponentMockRecorder) Terminate

func (mr *MockRootComponentMockRecorder) Terminate(arg0, arg1 any) *gomock.Call

Terminate indicates an expected call of Terminate.

type MockSideEffectTaskExecutor

type MockSideEffectTaskExecutor[C any, T any] struct {
	// contains filtered or unexported fields
}

MockSideEffectTaskExecutor is a mock of SideEffectTaskExecutor interface.

func NewMockSideEffectTaskExecutor

func NewMockSideEffectTaskExecutor[C any, T any](ctrl *gomock.Controller) *MockSideEffectTaskExecutor[C, T]

NewMockSideEffectTaskExecutor creates a new mock instance.

func (*MockSideEffectTaskExecutor[C, T]) EXPECT

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

func (*MockSideEffectTaskExecutor[C, T]) Execute

func (m *MockSideEffectTaskExecutor[C, T]) Execute(arg0 context.Context, arg1 ComponentRef, arg2 TaskAttributes, arg3 T) error

Execute mocks base method.

type MockSideEffectTaskExecutorMockRecorder

type MockSideEffectTaskExecutorMockRecorder[C any, T any] struct {
	// contains filtered or unexported fields
}

MockSideEffectTaskExecutorMockRecorder is the mock recorder for MockSideEffectTaskExecutor.

func (*MockSideEffectTaskExecutorMockRecorder[C, T]) Execute

func (mr *MockSideEffectTaskExecutorMockRecorder[C, T]) Execute(arg0, arg1, arg2, arg3 any) *gomock.Call

Execute indicates an expected call of Execute.

type MockTask

type MockTask struct {
	Component  Component
	Attributes TaskAttributes
	Payload    any
}

type MockTaskValidator

type MockTaskValidator[C any, T any] struct {
	// contains filtered or unexported fields
}

MockTaskValidator is a mock of TaskValidator interface.

func NewMockTaskValidator

func NewMockTaskValidator[C any, T any](ctrl *gomock.Controller) *MockTaskValidator[C, T]

NewMockTaskValidator creates a new mock instance.

func (*MockTaskValidator[C, T]) EXPECT

func (m *MockTaskValidator[C, T]) EXPECT() *MockTaskValidatorMockRecorder[C, T]

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

func (*MockTaskValidator[C, T]) Validate

func (m *MockTaskValidator[C, T]) Validate(arg0 Context, arg1 C, arg2 TaskAttributes, arg3 T) (bool, error)

Validate mocks base method.

type MockTaskValidatorMockRecorder

type MockTaskValidatorMockRecorder[C any, T any] struct {
	// contains filtered or unexported fields
}

MockTaskValidatorMockRecorder is the mock recorder for MockTaskValidator.

func (*MockTaskValidatorMockRecorder[C, T]) Validate

func (mr *MockTaskValidatorMockRecorder[C, T]) Validate(arg0, arg1, arg2, arg3 any) *gomock.Call

Validate indicates an expected call of Validate.

type MockTerminableComponent

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

MockTerminableComponent is a mock of TerminableComponent interface.

func NewMockTerminableComponent

func NewMockTerminableComponent(ctrl *gomock.Controller) *MockTerminableComponent

NewMockTerminableComponent creates a new mock instance.

func (*MockTerminableComponent) EXPECT

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

func (*MockTerminableComponent) LifecycleState

func (m *MockTerminableComponent) LifecycleState(arg0 Context) LifecycleState

LifecycleState mocks base method.

func (*MockTerminableComponent) Terminate

Terminate mocks base method.

type MockTerminableComponentMockRecorder

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

MockTerminableComponentMockRecorder is the mock recorder for MockTerminableComponent.

func (*MockTerminableComponentMockRecorder) LifecycleState

func (mr *MockTerminableComponentMockRecorder) LifecycleState(arg0 any) *gomock.Call

LifecycleState indicates an expected call of LifecycleState.

func (*MockTerminableComponentMockRecorder) Terminate

func (mr *MockTerminableComponentMockRecorder) Terminate(arg0, arg1 any) *gomock.Call

Terminate indicates an expected call of Terminate.

type MockVisibilityManager

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

MockVisibilityManager is a mock of VisibilityManager interface.

func NewMockVisibilityManager

func NewMockVisibilityManager(ctrl *gomock.Controller) *MockVisibilityManager

NewMockVisibilityManager creates a new mock instance.

func (*MockVisibilityManager) CountExecutions

CountExecutions mocks base method.

func (*MockVisibilityManager) EXPECT

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

func (*MockVisibilityManager) ListExecutions

ListExecutions mocks base method.

type MockVisibilityManagerMockRecorder

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

MockVisibilityManagerMockRecorder is the mock recorder for MockVisibilityManager.

func (*MockVisibilityManagerMockRecorder) CountExecutions

func (mr *MockVisibilityManagerMockRecorder) CountExecutions(arg0, arg1, arg2 any) *gomock.Call

CountExecutions indicates an expected call of CountExecutions.

func (*MockVisibilityManagerMockRecorder) ListExecutions

func (mr *MockVisibilityManagerMockRecorder) ListExecutions(arg0, arg1, arg2 any) *gomock.Call

ListExecutions indicates an expected call of ListExecutions.

type Mocknamer

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

Mocknamer is a mock of namer interface.

func NewMocknamer

func NewMocknamer(ctrl *gomock.Controller) *Mocknamer

NewMocknamer creates a new mock instance.

func (*Mocknamer) EXPECT

func (m *Mocknamer) EXPECT() *MocknamerMockRecorder

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

func (*Mocknamer) Name

func (m *Mocknamer) Name() string

Name mocks base method.

type MocknamerMockRecorder

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

MocknamerMockRecorder is the mock recorder for Mocknamer.

func (*MocknamerMockRecorder) Name

func (mr *MocknamerMockRecorder) Name() *gomock.Call

Name indicates an expected call of Name.

type MutableContext

type MutableContext interface {
	Context

	// AddTask adds a task to be emitted as part of the current transaction.
	// The task is associated with the given component and will be invoked via the registered executor for the given task
	// referencing the component.
	AddTask(Component, TaskAttributes, any)
}

func NewMutableContext

func NewMutableContext(
	ctx context.Context,
	node *Node,
) MutableContext

NewMutableContext creates a new MutableContext from an existing Context and root Node.

NOTE: Library authors should not invoke this constructor directly, and instead use the UpdateComponent, UpdateWithStartExecution, or StartExecution APIs.

type NexusCompletionHandler

type NexusCompletionHandler interface {
	HandleNexusCompletion(ctx MutableContext, completion *persistencespb.ChasmNexusCompletion) error
}

NexusCompletionHandler is implemented by CHASM components that want to handle Nexus operation completion callbacks.

type NexusCompletionHandlerComponent

type NexusCompletionHandlerComponent interface {
	Component
	NexusCompletionHandler
}

NexusCompletionHandlerComponent is a CHASM Component that also implements NexusCompletionHandler.

type NexusEndpointProcessor

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

NexusEndpointProcessor handles input processing for Nexus operations across multiple services within a Nexus endpoint. It routes requests to the appropriate service processor based on the service name.

func NewNexusEndpointProcessor

func NewNexusEndpointProcessor() *NexusEndpointProcessor

NewNexusEndpointProcessor creates a new NexusEndpointProcessor.

func (*NexusEndpointProcessor) MustRegisterServiceProcessor

func (p *NexusEndpointProcessor) MustRegisterServiceProcessor(processor *NexusServiceProcessor)

MustRegisterServiceProcessor registers the service processor and panics if registration fails.

func (*NexusEndpointProcessor) ProcessInput

ProcessInput routes the input processing request to the appropriate service processor and returns routing information for the operation.

Returns a nexus.HandlerError if the service is not found or if input processing fails.

func (*NexusEndpointProcessor) RegisterServiceProcessor

func (p *NexusEndpointProcessor) RegisterServiceProcessor(processor *NexusServiceProcessor) error

RegisterServiceProcessor adds a service-level processor to the endpoint keyed by its name. Returns an error if a processor with the same name is already registered.

type NexusOperationProcessor

type NexusOperationProcessor[I any] interface {
	// ProcessInput validates the input, and returns routing information for processing this operation. The
	// method may mutate the input to set default values.
	ProcessInput(ctx NexusOperationProcessorContext, input I) (*NexusOperationProcessorResult, error)
}

NexusOperationProcessor is an interface that can be implemented per operation to validate and determine routing for the operation.

type NexusOperationProcessorContext

type NexusOperationProcessorContext struct {
	// Namespace is the target namespace used for routing and validation of Nexus operations.
	Namespace *namespace.Namespace
	// RequestID is a unique identifier for the incoming operation request, used for correlation and idempotency
	// across retries.
	RequestID string
	Links     []nexus.Link
	// A boolean indicating whether the operation processor framework should re-serialize the input and store it in the
	// [NexusOperationProcessorResult.ReserializedInputPayload] field. Processor implementations may mutate the input regardless.
	ReserializeInputPayload bool
}

NexusOperationProcessorContext contains context for processing a Nexus operation's input, including the target namespace and a request identifier used for tracing and idempotency.

type NexusOperationProcessorResult

type NexusOperationProcessorResult struct {
	// RoutingKey determines which history shard should process the operation.
	RoutingKey NexusOperationRoutingKey
	// A field set by the framework to containing the re-serialized input payload if requested in the given context.
	ReserializedInputPayload *commonpb.Payload
}

NexusOperationProcessorResult contains the result of processing a Nexus operation input, including the routing key that determines which shard should handle the operation.

type NexusOperationRoutingKey

type NexusOperationRoutingKey interface {
	// ShardID returns the target shard ID for this routing key given the total number of shards.
	ShardID(numShards int32) int32
}

NexusOperationRoutingKey determines which history shard should process a Nexus operation. Different implementations provide different routing strategies (e.g., by execution, random).

type NexusOperationRoutingKeyExecution

type NexusOperationRoutingKeyExecution struct {
	// NamespaceID is the ID of the namespace containing the execution whose shard should be targeted.
	NamespaceID string
	// BusinessID is the business identifier (e.g., workflow ID) of the execution.
	BusinessID string
}

NexusOperationRoutingKeyExecution routes operations to a specific shard based on an execution key. This ensures that operations related to the same execution are processed on the same shard.

func (NexusOperationRoutingKeyExecution) ShardID

func (r NexusOperationRoutingKeyExecution) ShardID(numShards int32) int32

ShardID returns the shard that owns the execution identified by the namespace and business IDs.

type NexusOperationRoutingKeyRandom

type NexusOperationRoutingKeyRandom struct {
}

NexusOperationRoutingKeyRandom routes operations to a random shard. The ShardID method returns a randomly selected valid shard ID.

func (NexusOperationRoutingKeyRandom) ShardID

func (NexusOperationRoutingKeyRandom) ShardID(numShards int32) int32

ShardID returns a randomly selected shard ID in the range [1, numShards].

type NexusServiceProcessor

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

NexusServiceProcessor handles input processing for operations within a specific Nexus service. It uses reflection to dynamically invoke the ProcessInput method on operations that implement it.

func NewNexusServiceProcessor

func NewNexusServiceProcessor(name string) *NexusServiceProcessor

NewNexusServiceProcessor constructs a processor for a single Nexus service that can register and invoke operation processors by name.

func (*NexusServiceProcessor) MustRegisterOperation

func (p *NexusServiceProcessor) MustRegisterOperation(name string, op RegisterableNexusOperationProcessor)

MustRegisterOperation registers a named operation and panics if registration fails.

func (*NexusServiceProcessor) ProcessInput

ProcessInput routes the input processing request to the appropriate operation processor and returns routing information for the operation.

Returns a nexus.HandlerError if the operation is not found or if input processing fails.

func (*NexusServiceProcessor) RegisterOperation

RegisterOperation registers a named operation with this service processor. Returns an error if an operation with the same name is already registered.

type NoValue

type NoValue = *struct{}

NoValue is a sentinel type representing no value. Useful for accessing components using the engine methods (e.g., [GetComponent]) with a function that does not need to return any information.

type Node

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

Node is the in-memory representation of a persisted CHASM node.

Node and all its methods are NOT meant to be used by CHASM component authors. They are exported for use by the CHASM engine and underlying MutableState implementation only.

func NewEmptyTree

func NewEmptyTree(
	registry *Registry,
	timeSource clock.TimeSource,
	backend NodeBackend,
	pathEncoder NodePathEncoder,
	logger log.Logger,
	metricsHandler metrics.Handler,
) *Node

NewEmptyTree creates a new empty in-memory CHASM tree.

func NewTreeFromDB

func NewTreeFromDB(
	serializedNodes map[string]*persistencespb.ChasmNode,
	registry *Registry,
	timeSource clock.TimeSource,
	backend NodeBackend,
	pathEncoder NodePathEncoder,
	logger log.Logger,
	metricsHandler metrics.Handler,
) (*Node, error)

NewTreeFromDB creates a new in-memory CHASM tree from a collection of flattened persistence CHASM nodes. This method should only be used when loading an existing CHASM tree from database. If serializedNodes is empty, the tree will be considered as a legacy Workflow execution without any CHASM nodes.

func (*Node) AddTask

func (n *Node) AddTask(
	component Component,
	taskAttributes TaskAttributes,
	task any,
)

AddTask implements the CHASM MutableContext interface

func (*Node) ApplyMutation

func (n *Node) ApplyMutation(
	mutation NodesMutation,
) error

ApplyMutation is used by replication stack to apply node mutations from the source cluster.

NOTE: It will be an error if UpdatedNodes and DeletedNodes have overlapping keys, as the CHASM tree does not have enough information to tell if the deletion happens before or after the update.

func (*Node) ApplySnapshot

func (n *Node) ApplySnapshot(
	incomingSnapshot NodesSnapshot,
) error

ApplySnapshot is used by replication stack to apply node snapshot from the source cluster.

If we simply substituting the entire CHASM tree, we will be forced to close the transaction as snapshot and potentially write extra data to persistence. This method will instead figure out the mutations needed to bring the current tree to the be the same as the snapshot, thus allowing us to close the transaction as mutation.

func (*Node) ApplySystemMutation

func (n *Node) ApplySystemMutation(
	mutation NodesMutation,
) error

ApplySystemMutation should only used by internal persistence layer logic to force apply cluster specific chasm tree changes. DO NOT USE if you don't know why this method is introduced.

func (*Node) Archetype

func (n *Node) Archetype() (Archetype, error)

Archetype returns the root component's fully qualified name. Deprecated: use ArchetypeID() instead, this method will be removed.

func (*Node) ArchetypeID

func (n *Node) ArchetypeID() ArchetypeID

ArchetypeID returns the framework's internal ID for the root component's fully qualified name.

func (*Node) CloseTransaction

func (n *Node) CloseTransaction() (NodesMutation, error)

CloseTransaction is used by MutableState to close the transaction and track changes made in the current transaction.

func (*Node) Component

func (n *Node) Component(
	chasmContext Context,
	ref ComponentRef,
) (Component, error)

Component retrieves a component from the tree rooted at node n using the provided component reference It also performs access rule, and task validation checks (for task processing requests) before returning the component.

func (*Node) ComponentByPath

func (n *Node) ComponentByPath(
	chasmContext Context,
	path []string,
) (Component, error)

func (*Node) EachPureTask

func (n *Node) EachPureTask(
	referenceTime time.Time,
	callback func(executor NodePureTask, taskAttributes TaskAttributes, taskInstance any) (bool, error),
) error

EachPureTask runs the callback for all expired/runnable pure tasks within the CHASM tree (including invalid tasks). The CHASM tree is left untouched, even if invalid tasks are detected (these are cleaned up as part of transaction close).

func (*Node) ExecutePureTask

func (n *Node) ExecutePureTask(
	baseCtx context.Context,
	taskAttributes TaskAttributes,
	taskInstance any,
) (_ bool, retErr error)

ExecutePureTask validates and then executes the given taskInstance against the node's component. Executing an invalid task is a no-op (no error returned).

func (*Node) ExecuteSideEffectTask

func (n *Node) ExecuteSideEffectTask(
	ctx context.Context,
	registry *Registry,
	executionKey ExecutionKey,
	chasmTask *tasks.ChasmTask,
	validate func(NodeBackend, Context, Component) error,
) (retErr error)

ExecuteSideEffectTask executes the given ChasmTask on its associated node without holding the execution lock.

WARNING: This method *must not* access the node's properties without first locking the execution.

ctx should have a CHASM engine already set.

func (*Node) IsDirty

func (n *Node) IsDirty() bool

IsDirty returns true if any node in the tree has been modified, and need to be persisted in DB. The result will be reset to false after a call to CloseTransaction().

func (*Node) IsStale

func (n *Node) IsStale(
	ref ComponentRef,
) error

func (*Node) IsStateDirty

func (n *Node) IsStateDirty() bool

IsStateDirty returns true if any node in the tree has USER DATA modified, which need to be persisted to DB AND replicated to other clusters. The result will be reset to false after a call to CloseTransaction().

func (*Node) Now

func (n *Node) Now(
	_ Component,
) time.Time

Now implements the CHASM Context interface

func (*Node) Ref

func (n *Node) Ref(
	component Component,
) ([]byte, error)

Ref implements the CHASM Context interface

func (*Node) RefreshTasks

func (n *Node) RefreshTasks() error

func (*Node) SetDeleteAfterClose

func (n *Node) SetDeleteAfterClose(deleteAfterClose bool)

SetDeleteAfterClose suppresses the close visibility task when an execution is being terminated as part of a delete operation. Must be called before a [Terminate] call, like in DeleteExecution.

func (*Node) SetRootComponent

func (n *Node) SetRootComponent(
	rootComponent Component,
) error

func (*Node) Snapshot

func (n *Node) Snapshot(
	exclusiveMinVT *persistencespb.VersionedTransition,
) NodesSnapshot

Snapshot returns all nodes in the tree that have been modified after the given min versioned transition. A nil exclusiveMinVT will be treated as the same as the zero versioned transition and returns all nodes in the tree. This method should only be invoked on root CHASM node when IsDirty() is false.

func (*Node) Terminate

func (n *Node) Terminate(
	request TerminateComponentRequest,
) error

func (*Node) ValidatePureTask

func (n *Node) ValidatePureTask(
	ctx context.Context,
	taskAttributes TaskAttributes,
	taskInstance any,
) (bool, error)

ValidatePureTask runs a pure task's associated validator, returning true if the task is valid. Intended for use by standby executors as part of EachPureTask's callback. This method assumes the node's value has already been prepared (hydrated).

func (*Node) ValidateSideEffectTask

func (n *Node) ValidateSideEffectTask(
	ctx context.Context,
	chasmTask *tasks.ChasmTask,
) (isValid bool, retErr error)

ValidateSideEffectTask runs a side effect task's associated validator, returning the deserialized task instance if the task is valid. Intended for use by standby executors.

If validation succeeds but the task is invalid, nil is returned to signify the task can be skipped/deleted.

If validation fails, that error is returned.

type NodeBackend

type NodeBackend interface {
	// TODO: Add methods needed from MutateState here.
	GetExecutionState() *persistencespb.WorkflowExecutionState
	GetExecutionInfo() *persistencespb.WorkflowExecutionInfo
	GetCurrentVersion() int64
	NextTransitionCount() int64
	CurrentVersionedTransition() *persistencespb.VersionedTransition
	GetWorkflowKey() definition.WorkflowKey
	AddTasks(...tasks.Task)
	DeleteCHASMPureTasks(maxScheduledTime time.Time)
	UpdateWorkflowStateStatus(
		state enumsspb.WorkflowExecutionState,
		status enumspb.WorkflowExecutionStatus,
	) (bool, error)
	IsWorkflow() bool
	GetNexusCompletion(
		ctx context.Context,
		requestID string,
	) (nexusrpc.CompleteOperationOptions, error)
}

NodeBackend is a set of methods needed from MutableState

This is for breaking cycle dependency between this package and service/history/workflow package where MutableState is defined.

type NodePathEncoder

type NodePathEncoder interface {
	Encode(node *Node, path []string) (string, error)
	// TODO: Return a iterator on node name instead of []string,
	// so that we can get a node by encoded path without additional
	// allocation for the decoded path.
	Decode(encodedPath string) ([]string, error)
}

NodePathEncoder is an interface for encoding and decoding node paths. Logic outside the chasm package should only work with encoded paths.

var DefaultPathEncoder NodePathEncoder = &defaultPathEncoder{}

type NodePureTask

type NodePureTask interface {
	ExecutePureTask(baseCtx context.Context, taskAttributes TaskAttributes, taskInstance any) (bool, error)
	ValidatePureTask(baseCtx context.Context, taskAttributes TaskAttributes, taskInstance any) (bool, error)
}

NodePureTask is intended to be implemented and used within the CHASM framework only.

type NodesMutation

type NodesMutation struct {
	UpdatedNodes map[string]*persistencespb.ChasmNode // encoded node path -> chasm node
	DeletedNodes map[string]struct{}
}

NodesMutation is a set of mutations for all nodes rooted at a given node n, including the node n itself.

type NodesSnapshot

type NodesSnapshot struct {
	Nodes map[string]*persistencespb.ChasmNode // encoded node path -> chasm node
}

NodesSnapshot is a snapshot for all nodes rooted at a given node n, including the node n itself.

type OperationIntent

type OperationIntent int
const (
	OperationIntentProgress OperationIntent = 1 << iota
	OperationIntentObserve

	OperationIntentUnspecified = OperationIntent(0)
)

type ParentPtr

type ParentPtr[T any] struct {
	// Exporting this field as this generic struct needs to be created via reflection,
	// and reflection can't set private fields.
	Internal parentPtrInternal
}

ParentPtr is a in-memory pointer to the parent component of a CHASM component.

CHASM map is not a component, so if a component is inside a map, its ParentPtr will point to the nearest ancestor component that is not a map.

ParentPtr is only initialized and available for use **after** the transition that creates the component using ParentPtr is completed.

func (ParentPtr[T]) Get

func (p ParentPtr[T]) Get(chasmContext Context) T

Get returns the parent component, deserializing it if necessary. Panics rather than returning an error, as errors are supposed to be handled by the framework as opposed to the application.

func (ParentPtr[T]) TryGet

func (p ParentPtr[T]) TryGet(chasmContext Context) (T, bool)

TryGet returns the parent component and a boolean indicating if the value was found, deserializing if necessary. Panics rather than returning an error, as errors are supposed to be handled by the framework as opposed to the application.

type PureTaskExecutor

type PureTaskExecutor[C any, T any] interface {
	Execute(MutableContext, C, TaskAttributes, T) error
}

type RegisterableNexusOperationProcessor

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

RegisterableNexusOperationProcessor adapts a typed Nexus operation processor for dynamic registration and invocation within a service processor.

func NewRegisterableNexusOperationProcessor

func NewRegisterableNexusOperationProcessor[I any](op NexusOperationProcessor[I]) RegisterableNexusOperationProcessor

NewRegisterableNexusOperationProcessor wraps a typed NexusOperationProcessor and returns a registerable adapter.

type RegistrableComponent

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

func NewRegistrableComponent

func NewRegistrableComponent[C Component](
	componentType string,
	opts ...RegistrableComponentOption,
) *RegistrableComponent

func (*RegistrableComponent) GoType

func (rc *RegistrableComponent) GoType() reflect.Type

GoType returns the reflect.Type of the component's Go struct.

func (*RegistrableComponent) IsDetached

func (rc *RegistrableComponent) IsDetached() bool

IsDetached returns true if the component type is registered as detached.

func (*RegistrableComponent) SearchAttributesMapper

func (rc *RegistrableComponent) SearchAttributesMapper() *VisibilitySearchAttributesMapper

SearchAttributesMapper returns the search attributes mapper for this component.

type RegistrableComponentOption

type RegistrableComponentOption func(*RegistrableComponent)

func WithBusinessIDAlias

func WithBusinessIDAlias(
	alias string,
) RegistrableComponentOption

WithBusinessIDAlias allows specifying the business ID alias of the component. This option must be specified if the archetype uses the Visibility component.

func WithContextValues

func WithContextValues(
	keyVals map[any]any,
) RegistrableComponentOption

WithContextValues allows specifying key-value pairs that will be available in the Context via the Value() method whenever the chasm framework starts, updates, reads, polls, executes or validates tasks on a component.

This is useful for propagating values needed for those processing logic but are not avaiable via the component's struct definition, such as configurations.

func WithDetached

func WithDetached() RegistrableComponentOption

WithDetached marks the registrable component as detached. Detached components ignore parent lifecycle validation, allowing them to continue operating when their parent is closed/terminated. If a registrable component is not detached by default, a component definition can specify its child as detached via ComponentFieldDetached() option.

func WithEphemeral

func WithEphemeral() RegistrableComponentOption

func WithSearchAttributes

func WithSearchAttributes(
	searchAttributes ...SearchAttribute,
) RegistrableComponentOption

func WithSingleCluster

func WithSingleCluster() RegistrableComponentOption

Is there any use case where we don't want to replicate certain instances of a archetype?

type RegistrableTask

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

func NewRegistrablePureTask

func NewRegistrablePureTask[C any, T any](
	taskType string,
	validator TaskValidator[C, T],
	executor PureTaskExecutor[C, T],
	opts ...RegistrableTaskOption,
) *RegistrableTask

func NewRegistrableSideEffectTask

func NewRegistrableSideEffectTask[C any, T any](
	taskType string,
	validator TaskValidator[C, T],
	executor SideEffectTaskExecutor[C, T],
	opts ...RegistrableTaskOption,
) *RegistrableTask

NOTE: C is not Component but any.

func (*RegistrableTask) GoType

func (rt *RegistrableTask) GoType() reflect.Type

GoType returns the reflect.Type of the task's Go struct.

type RegistrableTaskOption

type RegistrableTaskOption func(*RegistrableTask)

type Registry

type Registry struct {
	NexusEndpointProcessor *NexusEndpointProcessor
	// contains filtered or unexported fields
}

func NewRegistry

func NewRegistry(logger log.Logger) *Registry

func (*Registry) ArchetypeDisplayName

func (r *Registry) ArchetypeDisplayName(id ArchetypeID) (string, bool)

ArchetypeDisplayName returns the human-readable name for a given archetype ID. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func (*Registry) ArchetypeIDOf

func (r *Registry) ArchetypeIDOf(componentGoType reflect.Type) (ArchetypeID, bool)

ArchetypeIDOf returns the ArchetypeID for the given component Go type. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func (*Registry) ComponentByID

func (r *Registry) ComponentByID(id uint32) (*RegistrableComponent, bool)

ComponentByID returns the registrable component for a given archetype ID. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func (*Registry) ComponentFqnByID

func (r *Registry) ComponentFqnByID(id uint32) (string, bool)

ComponentFqnByID converts component type ID to fully qualified component type name. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func (*Registry) ComponentIDByFqn

func (r *Registry) ComponentIDByFqn(fqn string) (uint32, bool)

ComponentIDByFqn converts fully qualified component type name to component type ID. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func (*Registry) ComponentIDFor

func (r *Registry) ComponentIDFor(componentInstance any) (uint32, bool)

ComponentIDFor converts registered component instance to component type ID. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func (*Registry) NexusServices

func (r *Registry) NexusServices() map[string]*nexus.Service

NexusServices returns all registered Nexus services.

func (*Registry) Register

func (r *Registry) Register(lib Library) error

func (*Registry) RegisterServices

func (r *Registry) RegisterServices(server *grpc.Server)

RegisterServices registers all gRPC services from all registered libraries.

func (*Registry) TaskByID

func (r *Registry) TaskByID(id uint32) (*RegistrableTask, bool)

TaskByID returns the registrable task for a given task type ID. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func (*Registry) TaskFqnByID

func (r *Registry) TaskFqnByID(id uint32) (string, bool)

TaskFqnByID converts task type ID to fully qualified task type name. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

func (*Registry) TaskIDFor

func (r *Registry) TaskIDFor(taskInstance any) (uint32, bool)

TaskIDFor converts registered task instance to task type ID. This method should only be used by CHASM framework internal code, NOT CHASM library developers.

type RootComponent

type RootComponent interface {
	TerminableComponent
}

RootComponent is the interface that must be implemented by the top level component of a chasm execution. When the RootComponent's LifecycleState transitions to a closed state, the entire execution is considered closed, and will be cleaned up by the chasm framework after namespace's retention period. The BusinessID is also available for reuse.

TODO: (not yet true) Visibility record will no longer be updated after RootComponent is closed.

type SearchAttribute

type SearchAttribute interface {
	// contains filtered or unexported methods
}

SearchAttribute is a shared interface for all search attribute types. Each type must embed searchAttributeDefinition.

type SearchAttributeBool

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

SearchAttributeBool is a search attribute for a boolean value.

func NewSearchAttributeBool

func NewSearchAttributeBool(alias string, boolField SearchAttributeFieldBool) SearchAttributeBool

NewSearchAttributeBool creates a new boolean search attribute given a predefined chasm field

func (SearchAttributeBool) Value

func (s SearchAttributeBool) Value(value bool) SearchAttributeKeyValue

Value sets the boolean value of the search attribute.

type SearchAttributeDateTime

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

SearchAttributeDateTime is a search attribute for a datetime value.

func NewSearchAttributeDateTime

func NewSearchAttributeDateTime(alias string, datetimeField SearchAttributeFieldDateTime) SearchAttributeDateTime

NewSearchAttributeDateTime creates a new date time search attribute given a predefined chasm field

func (SearchAttributeDateTime) Value

func (s SearchAttributeDateTime) Value(value time.Time) SearchAttributeKeyValue

Value sets the date time value of the search attribute.

type SearchAttributeDouble

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

SearchAttributeDouble is a search attribute for a double value.

func NewSearchAttributeDouble

func NewSearchAttributeDouble(alias string, doubleField SearchAttributeFieldDouble) SearchAttributeDouble

NewSearchAttributeDouble creates a new double search attribute given a predefined chasm field

func (SearchAttributeDouble) Value

func (s SearchAttributeDouble) Value(value float64) SearchAttributeKeyValue

Value sets the double value of the search attribute.

type SearchAttributeFieldBool

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

SearchAttributeFieldBool is a search attribute field for a boolean value.

type SearchAttributeFieldDateTime

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

SearchAttributeFieldDateTime is a search attribute field for a datetime value.

type SearchAttributeFieldDouble

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

SearchAttributeFieldDouble is a search attribute field for a double value.

type SearchAttributeFieldInt

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

SearchAttributeFieldInt is a search attribute field for an integer value.

type SearchAttributeFieldKeyword

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

SearchAttributeFieldKeyword is a search attribute field for a keyword value.

type SearchAttributeFieldKeywordList

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

SearchAttributeFieldKeywordList is a search attribute field for a keyword list value.

type SearchAttributeInt

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

SearchAttributeInt is a search attribute for an integer value.

func NewSearchAttributeInt

func NewSearchAttributeInt(alias string, intField SearchAttributeFieldInt) SearchAttributeInt

NewSearchAttributeInt creates a new integer search attribute given a predefined chasm field

func (SearchAttributeInt) Value

func (s SearchAttributeInt) Value(value int64) SearchAttributeKeyValue

Value sets the integer value of the search attribute.

type SearchAttributeKeyValue

type SearchAttributeKeyValue struct {
	// Alias refers to the user defined name of the search attribute
	Alias string
	// Field refers to a fully formed schema field, which is a Predefined CHASM search attribute
	Field string
	// Value refers to the current value of the search attribute. Must support encoding to a Payload.
	Value VisibilityValue
}

SearchAttributeKeyValue is a key value pair of a search attribute. Represents the current value of a search attribute in a CHASM Component during a transaction.

type SearchAttributeKeyword

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

SearchAttributeKeyword is a search attribute for a keyword value.

func NewSearchAttributeKeyword

func NewSearchAttributeKeyword(alias string, keywordField SearchAttributeFieldKeyword) SearchAttributeKeyword

NewSearchAttributeKeyword creates a new keyword search attribute given a predefined chasm field

func (SearchAttributeKeyword) Value

func (s SearchAttributeKeyword) Value(value string) SearchAttributeKeyValue

Value sets the string value of the search attribute.

type SearchAttributeKeywordList

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

SearchAttributeKeywordList is a search attribute for a keyword list value.

func NewSearchAttributeKeywordList

func NewSearchAttributeKeywordList(alias string, keywordListField SearchAttributeFieldKeywordList) SearchAttributeKeywordList

NewSearchAttributeKeywordList creates a new keyword list search attribute given a predefined chasm field

func (SearchAttributeKeywordList) Value

func (s SearchAttributeKeywordList) Value(value []string) SearchAttributeKeyValue

Value sets the string list value of the search attribute.

type SearchAttributesMap

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

SearchAttributesMap wraps search attribute values with type-safe access.

func NewSearchAttributesMap

func NewSearchAttributesMap(values map[string]VisibilityValue) SearchAttributesMap

NewSearchAttributesMap creates a new SearchAttributeMap from raw values.

type SideEffectTaskExecutor

type SideEffectTaskExecutor[C any, T any] interface {
	Execute(context.Context, ComponentRef, TaskAttributes, T) error
}

type StartExecutionResult

type StartExecutionResult struct {
	ExecutionKey ExecutionKey
	ExecutionRef []byte
	Created      bool
}

StartExecutionResult contains the outcome of creating a new execution via StartExecution.

This struct provides information about whether a new execution was actually created, along with identifiers needed to reference the execution in subsequent operations.

Fields:

func StartExecution

func StartExecution[C RootComponent, I any](
	ctx context.Context,
	key ExecutionKey,
	startFn func(MutableContext, I) (C, error),
	input I,
	opts ...TransitionOption,
) (StartExecutionResult, error)

StartExecution creates a new execution with a component initialized by the provided factory function.

This is the primary entry point for starting a new execution in the CHASM engine. It handles the lifecycle of creating and persisting a new component within an execution context.

Type Parameters:

  • C: The component type to create, must implement RootComponent
  • I: The input type passed to the factory function
  • O: The output type returned by the factory function

Parameters:

  • ctx: Context containing the CHASM engine (must be created via NewEngineContext)
  • key: Unique identifier for the execution, used for deduplication and lookup
  • startFn: Factory function that creates the component and produces output. Receives a MutableContext for accessing engine capabilities and the input value.
  • input: Application-specific data passed to startFn
  • opts: Optional TransitionOption functions to configure creation behavior:
  • WithBusinessIDPolicy: Controls duplicate handling and conflict resolution
  • WithRequestID: Sets a request ID for idempotency
  • WithSpeculative: Defers persistence until the next non-speculative transition

Returns:

  • O: The output value produced by startFn
  • [NewExecutionResult]: Contains the execution key, serialized ref, and whether a new execution was created
  • error: Non-nil if creation failed or policy constraints were violated

type StateMachine

type StateMachine[S comparable] interface {
	StateMachineState() S
	SetStateMachineState(S)
}

A StateMachine is anything that can get and set a comparable state S and re-generate tasks based on current state. It is meant to be used with Transition objects to safely transition their state on a given event.

type TaskAttributes

type TaskAttributes struct {
	ScheduledTime time.Time
	Destination   string
}

func (*TaskAttributes) IsImmediate

func (a *TaskAttributes) IsImmediate() bool

func (*TaskAttributes) IsValid

func (a *TaskAttributes) IsValid() bool

type TaskValidator

type TaskValidator[C any, T any] interface {
	// Validate determines whether a task should proceed with execution based on the current context, component
	// state, task attributes, and task data.
	//
	// This function serves as a gate to prevent unnecessary task execution in several scenarios:
	// 1. Standby cluster deduplication: When state is replicated to standby clusters, tasks are also replicated.
	//    Validate allows standby clusters to check if a task was already completed on the active cluster and
	//    skip execution if so (e.g., checking if an activity already transitioned from scheduled to started state).
	// 2. Task obsolescence: Tasks can become irrelevant when state changes invalidate them (e.g., when a scheduler
	//    is updated to run at a different time, making the previously scheduled task invalid for the new state).
	//    For pure tasks that can run in a single transaction, Validate is called before execution to avoid
	//    unnecessary work.
	//
	// The framework automatically calls Validate at key points, such as after closing transactions, to check all
	// generated tasks before they execute.
	//
	// Returns:
	// - (true, nil) if the task is valid and should be executed
	// - (false, nil) if the task should be silently dropped (it's no longer relevant)
	// - (anything, error) if validation fails with an error
	Validate(Context, C, TaskAttributes, T) (bool, error)
}

type TerminableComponent

type TerminableComponent interface {
	Component

	// Terminate method is invoked by the chasm framework on an execution's root component when the execution
	// needs to be forcefully terminated.
	// Some examples include:
	// - Execution state becomes too large.
	// - Two running executions with the same businessID when namespace performs a force failover.
	Terminate(MutableContext, TerminateComponentRequest) (TerminateComponentResponse, error)
}

type TerminateComponentRequest

type TerminateComponentRequest struct {
	Identity  string
	Reason    string
	Details   *commonpb.Payloads
	RequestID string
}

type TerminateComponentResponse

type TerminateComponentResponse struct{}

type Transition

type Transition[S comparable, SM StateMachine[S], E any] struct {
	// Source states that are valid for this transition.
	Sources []S
	// Destination state to transition to.
	Destination S
	// contains filtered or unexported fields
}

Transition represents a state machine transition for a machine of type SM with state S and event E.

func NewTransition

func NewTransition[S comparable, SM StateMachine[S], E any](src []S, dst S, apply func(SM, MutableContext, E) error) Transition[S, SM, E]

NewTransition creates a new Transition from the given source states to a destination state for a given event. The apply function is called after verifying the transition is possible and setting the destination state.

func (Transition[S, SM, E]) Apply

func (t Transition[S, SM, E]) Apply(sm SM, ctx MutableContext, event E) error

Apply applies a transition event to the given state machine changing the state machine's state to the transition's Destination on success.

func (Transition[S, SM, E]) Possible

func (t Transition[S, SM, E]) Possible(sm SM) bool

Possible returns a boolean indicating whether the transition is possible for the current state.

type TransitionOption

type TransitionOption func(*TransitionOptions)

func WithBusinessIDPolicy

func WithBusinessIDPolicy(
	reusePolicy BusinessIDReusePolicy,
	conflictPolicy BusinessIDConflictPolicy,
) TransitionOption

WithBusinessIDPolicy sets the businessID reuse and conflict policy used in the transition when creating a new execution. This option only applies to StartExecution() and UpdateWithStartExecution().

func WithRequestID

func WithRequestID(
	requestID string,
) TransitionOption

WithRequestID sets the requestID used when creating a new execution. This option only applies to StartExecution() and UpdateWithStartExecution().

func WithSpeculative

func WithSpeculative() TransitionOption

(only) this transition will not be persisted The next non-speculative transition will persist this transition as well. Compared to the ExecutionEphemeral() operation on RegistrableComponent, the scope of this operation is limited to a certain transition, while the ExecutionEphemeral() applies to all transitions. TODO: we need to figure out a way to run the tasks generated in a speculative transition

type TransitionOptions

type TransitionOptions struct {
	ReusePolicy    BusinessIDReusePolicy
	ConflictPolicy BusinessIDConflictPolicy
	RequestID      string
	Speculative    bool
}

type UnimplementedComponent

type UnimplementedComponent struct{}

Embed UnimplementedComponent to get forward compatibility

type UnimplementedLibrary

type UnimplementedLibrary struct{}

func (UnimplementedLibrary) Components

func (UnimplementedLibrary) NexusServiceProcessors

func (UnimplementedLibrary) NexusServiceProcessors() []*NexusServiceProcessor

func (UnimplementedLibrary) NexusServices

func (UnimplementedLibrary) NexusServices() []*nexus.Service

func (UnimplementedLibrary) RegisterServices

func (UnimplementedLibrary) RegisterServices(_ *grpc.Server)

RegisterServices Registers the gRPC calls to the handlers of the library.

func (UnimplementedLibrary) Tasks

type UpdateWithStartExecutionResult

type UpdateWithStartExecutionResult[O any] struct {
	ExecutionKey ExecutionKey
	ExecutionRef []byte
	Created      bool
	UpdateOutput O
}

UpdateWithStartExecutionResult is the result of a UpdateWithStartExecution operation.

Fields:

  • ExecutionKey: The unique identifier for the execution. This key can be used to look up or reference the execution in future operations.
  • ExecutionRef: A serialized reference to the newly created root component. This can be passed to UpdateComponent, ReadComponent, or PollComponent to interact with the component. Use DeserializeComponentRef to convert this back to a ComponentRef if needed.
  • Created: Indicates whether a new execution was actually created. When false, the execution already existed (based on the BusinessIDReusePolicy and BusinessIDConflictPolicy configured via WithBusinessIDPolicy), and the existing execution was returned instead.
  • UpdateOutput: The output value returned by the update function.

func UpdateWithStartExecution

func UpdateWithStartExecution[C RootComponent, I any, O any](
	ctx context.Context,
	key ExecutionKey,
	startFn func(MutableContext, I) (C, error),
	updateFn func(C, MutableContext, I) (O, error),
	input I,
	opts ...TransitionOption,
) (UpdateWithStartExecutionResult[O], error)

type Visibility

type Visibility struct {
	UnimplementedComponent

	Data *persistencespb.ChasmVisibilityData

	// Do NOT access those fields directly.
	// Use the provided getters and setters instead.
	SA   Field[*commonpb.SearchAttributes]
	Memo Field[*commonpb.Memo]
}

func NewVisibility

func NewVisibility(
	mutableContext MutableContext,
) *Visibility

func NewVisibilityWithData

func NewVisibilityWithData(
	mutableContext MutableContext,
	customSearchAttributes map[string]*commonpb.Payload,
	customMemo map[string]*commonpb.Payload,
) *Visibility

func (*Visibility) CustomMemo

func (v *Visibility) CustomMemo(
	chasmContext Context,
) map[string]*commonpb.Payload

CustomMemo returns the stored custom memo fields. Nil is returned if there are none.

Returned map is NOT a deep copy of the underlying data, so do NOT modify it directly, use Merge/ReplaceCustomMemo methods instead.

func (*Visibility) CustomSearchAttributes

func (v *Visibility) CustomSearchAttributes(
	chasmContext Context,
) map[string]*commonpb.Payload

CustomSearchAttributes returns the stored custom search attribute fields. Nil is returned if there are none.

Returned map is NOT a deep copy of the underlying data, so do NOT modify it directly, use Merge/ReplaceCustomSearchAttributes methods instead.

func (*Visibility) LifecycleState

func (v *Visibility) LifecycleState(_ Context) LifecycleState

func (*Visibility) MergeCustomMemo

func (v *Visibility) MergeCustomMemo(
	mutableContext MutableContext,
	customMemo map[string]*commonpb.Payload,
)

MergeCustomMemo merges the provided custom memo fields into the existing ones.

  • If a key in `customMemo` already exists, the value in `customMemo` replaces the existing value.
  • If a key in `customMemo` has nil or empty slice payload value, the key is deleted from the existing memo if it exists. If all memo fields are removed, the underlying memo node is deleted.
  • If `customMemo` is empty, this is a no-op.

func (*Visibility) MergeCustomSearchAttributes

func (v *Visibility) MergeCustomSearchAttributes(
	mutableContext MutableContext,
	customSearchAttributes map[string]*commonpb.Payload,
)

MergeCustomSearchAttributes merges the provided custom search attribute fields into the existing ones.

  • If a key in `customSearchAttributes` already exists, the value in `customSearchAttributes` replaces the existing value.
  • If a key in `customSearchAttributes` has nil or empty slice payload value, the key is deleted from the existing search attributes if it exists. If all search attributes are removed, the underlying search attributes node is deleted.
  • If `customSearchAttributes` is empty, this is a no-op.

func (*Visibility) ReplaceCustomMemo

func (v *Visibility) ReplaceCustomMemo(
	mutableContext MutableContext,
	customMemo map[string]*commonpb.Payload,
)

ReplaceCustomMemo replaces the existing custom memo fields with the provided ones. If `customMemo` is empty, the underlying memo node is deleted.

func (*Visibility) ReplaceCustomSearchAttributes

func (v *Visibility) ReplaceCustomSearchAttributes(
	mutableContext MutableContext,
	customSearchAttributes map[string]*commonpb.Payload,
)

ReplaceCustomSearchAttributes replaces the existing custom search attribute fields with the provided ones. If `customSearchAttributes` is empty, the underlying search attributes node is deleted.

type VisibilityMemoProvider

type VisibilityMemoProvider interface {
	Memo(Context) proto.Message
}

VisibilityMemoProvider if implemented by the root Component, allows the CHASM framework to automatically determine, at the end of a transaction, if a visibility task needs to be generated to update the visibility record with the returned memo.

type VisibilitySearchAttributesMapper

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

VisibilitySearchAttributesMapper is a mapper for CHASM search attributes.

func NewTestVisibilitySearchAttributesMapper

func NewTestVisibilitySearchAttributesMapper(
	fieldToAlias map[string]string,
	saTypeMap map[string]enumspb.IndexedValueType,
) *VisibilitySearchAttributesMapper

NewTestVisibilitySearchAttributesMapper creates a new VisibilitySearchAttributesMapper. For testing only.

func (*VisibilitySearchAttributesMapper) Alias

Alias returns the alias for a given field.

func (*VisibilitySearchAttributesMapper) Field

Field returns the field for a given alias.

func (*VisibilitySearchAttributesMapper) SATypeMap

SATypeMap returns the type map for the CHASM search attributes.

func (*VisibilitySearchAttributesMapper) ValueType

ValueType returns the type of a CHASM search attribute field. Returns an error if the field is not found in the type map.

type VisibilitySearchAttributesProvider

type VisibilitySearchAttributesProvider interface {
	SearchAttributes(Context) []SearchAttributeKeyValue
}

VisibilitySearchAttributesProvider if implemented by the root Component, allows the CHASM framework to automatically determine, at the end of a transaction, if a visibility task needs to be generated to update the visibility record with the returned search attributes.

type VisibilityValue

type VisibilityValue interface {
	MustEncode() *commonpb.Payload
	Equal(VisibilityValue) bool
	Value() any
}

type VisibilityValueBool

type VisibilityValueBool bool

func (VisibilityValueBool) Equal

func (v VisibilityValueBool) Equal(other VisibilityValue) bool

func (VisibilityValueBool) MustEncode

func (v VisibilityValueBool) MustEncode() *commonpb.Payload

func (VisibilityValueBool) Value

func (v VisibilityValueBool) Value() any

type VisibilityValueByteSlice

type VisibilityValueByteSlice []byte

func (VisibilityValueByteSlice) Equal

func (VisibilityValueByteSlice) MustEncode

func (v VisibilityValueByteSlice) MustEncode() *commonpb.Payload

func (VisibilityValueByteSlice) Value

func (v VisibilityValueByteSlice) Value() any

type VisibilityValueFloat64

type VisibilityValueFloat64 float64

func (VisibilityValueFloat64) Equal

func (VisibilityValueFloat64) MustEncode

func (v VisibilityValueFloat64) MustEncode() *commonpb.Payload

func (VisibilityValueFloat64) Value

func (v VisibilityValueFloat64) Value() any

type VisibilityValueInt

type VisibilityValueInt int

func (VisibilityValueInt) Equal

func (v VisibilityValueInt) Equal(other VisibilityValue) bool

func (VisibilityValueInt) MustEncode

func (v VisibilityValueInt) MustEncode() *commonpb.Payload

func (VisibilityValueInt) Value

func (v VisibilityValueInt) Value() any

type VisibilityValueInt32

type VisibilityValueInt32 int32

func (VisibilityValueInt32) Equal

func (v VisibilityValueInt32) Equal(other VisibilityValue) bool

func (VisibilityValueInt32) MustEncode

func (v VisibilityValueInt32) MustEncode() *commonpb.Payload

func (VisibilityValueInt32) Value

func (v VisibilityValueInt32) Value() any

type VisibilityValueInt64

type VisibilityValueInt64 int64

func (VisibilityValueInt64) Equal

func (v VisibilityValueInt64) Equal(other VisibilityValue) bool

func (VisibilityValueInt64) MustEncode

func (v VisibilityValueInt64) MustEncode() *commonpb.Payload

func (VisibilityValueInt64) Value

func (v VisibilityValueInt64) Value() any

type VisibilityValueString

type VisibilityValueString string

func (VisibilityValueString) Equal

func (VisibilityValueString) MustEncode

func (v VisibilityValueString) MustEncode() *commonpb.Payload

func (VisibilityValueString) Value

func (v VisibilityValueString) Value() any

type VisibilityValueStringSlice

type VisibilityValueStringSlice []string

func (VisibilityValueStringSlice) Equal

func (VisibilityValueStringSlice) MustEncode

func (VisibilityValueStringSlice) Value

func (v VisibilityValueStringSlice) Value() any

type VisibilityValueTime

type VisibilityValueTime time.Time

func (VisibilityValueTime) Equal

func (v VisibilityValueTime) Equal(other VisibilityValue) bool

func (VisibilityValueTime) MustEncode

func (v VisibilityValueTime) MustEncode() *commonpb.Payload

func (VisibilityValueTime) Value

func (v VisibilityValueTime) Value() any

Directories

Path Synopsis
lib
activity/gen/activitypb/v1
Code generated by protoc-gen-go-helpers.
Code generated by protoc-gen-go-helpers.
callback/gen/callbackpb/v1
Code generated by protoc-gen-go-helpers.
Code generated by protoc-gen-go-helpers.
nexusoperation/gen/nexusoperationpb/v1
Code generated by protoc-gen-go-helpers.
Code generated by protoc-gen-go-helpers.
scheduler
Package scheduler is a generated GoMock package.
Package scheduler is a generated GoMock package.
scheduler/gen/schedulerpb/v1
Code generated by protoc-gen-go-helpers.
Code generated by protoc-gen-go-helpers.
tests/gen/testspb/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