workflow

type API[Type any, Status StatusType] interface {
	// Name returns the name of the implemented workflow.
	Name() string

	// Trigger will kickstart a workflow Run for the provided foreignID starting from the default entrypoint to
	// the workflow which is the first "from" status added via the builder
	// (e.g. builder.AddStep(FromStatus, func{}, ToStatus). There is no limitation as to where you start the workflow
	// from and can do so via the WithStartAt trigger option. WithInitialValue should be used when you need data to be
	// present in the workflow Run before it starts. This can be used to reduce the need for duplicating reads.
	//
	// foreignID should not be random and should be deterministic for the thing that you are running the workflow for.
	// This especially helps when connecting other workflows as the foreignID is the only way to connect the streams. The
	// same goes for Callback as you will need the foreignID to connect the callback back to the workflow instance that
	// was run.
	Trigger(
		ctx context.Context,
		foreignID string,
		opts ...TriggerOption[Type, Status],
	) (runID string, err error)

	// Schedule takes a cron spec and will call Trigger at the specified intervals. Schedule is a blocking call and all
	// schedule errors will be retried indefinitely. The same options are available for Schedule as they are
	// for Trigger.
	Schedule(foreignID string, spec string, opts ...ScheduleOption[Type, Status]) error

	// Await is a blocking call that returns the typed Run when the workflow of the specified run ID reaches the
	// specified status.
	Await(ctx context.Context, foreignID, runID string, status Status, opts ...AwaitOption) (*Run[Type, Status], error)

	// Callback can be used if Builder.AddCallback has been defined for the provided status. The data in the reader
	// will be passed to the CallbackFunc that you specify and so the serialisation and deserialisation is in the
	// hands of the user.
	Callback(ctx context.Context, foreignID string, status Status, payload io.Reader) error

	// Run must be called in order to start up all the background consumers / consumers required to run the workflow. Run
	// only needs to be called once. Any subsequent calls to run are safe and are noop.
	Run(ctx context.Context)

	// Stop tells the workflow to shut down gracefully.
	Stop()
}

type Ack func() error

type AwaitOption func(o *awaitOpts)

type BuildOption func(w *buildOptions)

type Builder[Type any, Status StatusType] struct {
	// contains filtered or unexported fields
}

type CallbackFunc[Type any, Status StatusType] func(ctx context.Context, r *Run[Type, Status], reader io.Reader) (Status, error)

type ConnectorConstructor interface {
	Make(ctx context.Context, consumerName string) (ConnectorConsumer, error)
}

type ConnectorConsumer interface {
	Recv(ctx context.Context) (*ConnectorEvent, Ack, error)
	Close() error
}

type ConnectorEvent struct {
	// ID is a unique ID for the event.
	ID string
	// ForeignID refers to the ID of the element that the event relates to.
	ForeignID string
	// Type relates to the StatusType that the associated record changed to.
	Type string
	// Headers stores meta-data in a simple and easily queryable way.
	Headers map[string]string
	// CreatedAt is the time that the event was produced and is generated by the event streamer.
	CreatedAt time.Time
}

type ConnectorEventFilter func(e *ConnectorEvent) bool

type ConnectorFunc[Type any, Status StatusType] func(ctx context.Context, api API[Type, Status], e *ConnectorEvent) error

type ConsumerFunc[Type any, Status StatusType] func(ctx context.Context, r *Run[Type, Status]) (Status, error)

type Event struct {
	// ID is a unique ID for the event generated by the event streamer.
	ID int64

	// ForeignID refers to the ID of a record in the record store.
	ForeignID string

	// Type relates to the StatusType that the associated record changed to.
	Type int

	// Headers stores meta-data in a simple and easily queryable way.
	Headers map[Header]string

	// CreatedAt is the time that the event was produced and is generated by the event streamer.
	CreatedAt time.Time
}

type EventFilter func(e *Event) bool

type EventReceiver interface {
	Recv(ctx context.Context) (*Event, Ack, error)
	Close() error
}

type EventSender interface {
	Send(ctx context.Context, foreignID string, statusType int, headers map[Header]string) error
	Close() error
}

type EventStreamer interface {
	NewSender(ctx context.Context, topic string) (EventSender, error)
	NewReceiver(ctx context.Context, topic string, name string, opts ...ReceiverOption) (EventReceiver, error)
}

type Filter struct {
	Enabled      bool
	IsMultiMatch bool
	// contains filtered or unexported fields
}

type Header string

type Logger interface {
	// Debug will be used by workflow for debug logs when in debug mode.
	Debug(ctx context.Context, msg string, meta map[string]string)
	// Error is used when writing errors to the logs.
	Error(ctx context.Context, err error)
}

type MermaidDirection string

type MermaidFormat struct {
	WorkflowName   string
	Direction      MermaidDirection
	Nodes          []int
	StartingPoints []int
	TerminalPoints []int
	Transitions    []MermaidTransition
}

type MermaidTransition struct {
	From int
	To   []int
}

type Meta struct {
	// RunStateReason provides a human-readable explanation for the current run state.
	// This field helps to understand the cause behind the current state of the run, such as "Paused", "Canceled", or "Deleted".
	// For instance, calling functions like Pause, Cancel, or DeleteData will update this field with a descriptive reason
	// that explains why the run is in its current state, making it easier to understand the context behind the state transition.
	RunStateReason string

	// StatusDescription provides a human-readable version of the Status field (int).
	// It allows for better understanding and readability of the status at the time of the computation, especially when reviewing
	// historical data. While the `Status` field stores the status as an integer, `StatusDescription` maps that status to a
	// corresponding string description, making it easier to interpret the status without needing to refer to status codes.
	StatusDescription string

	// Version defines the version of the record. The Workflow increments this value before storing it in the
	// RecordStore and uses it for data validation when consuming an event. The event will contain a matching version,
	// ensuring that the event and the record from the RecordStore align, and that the data is not stale. This versioning
	// mechanism also helps address replication lag issues, particularly in systems using databases that experience
	// replication delays between replicas. By matching the version, Workflow ensures that the version collected from
	// the reader is indeed the version expected. If the version in the RecordStore is greater than the event can be
	// ignored as it has already been processed.
	Version uint

	// TraceOrigin contains a trace of the origin or source where the workflow Run was triggered from.
	// It provides a line trace or path that helps track where the execution was initiated,
	// offering context for debugging or auditing purposes by capturing the origin of the workflow trigger.
	TraceOrigin string
}

type Option func(so *options)

type OrderType int

type OutboxEvent struct {
	// ID is a unique ID for this specific OutboxEvent.
	ID string

	// WorkflowName refers to the name of the workflow that the OutboxEventData belongs to.
	WorkflowName string

	// Data represents a slice of bytes the OutboxEventDataMaker constructs via serialising event data
	// in an expected way for it to also be deserialized by the outbox consumer.
	Data []byte

	// CreatedAt is the time that this specific OutboxEvent was produced.
	CreatedAt time.Time
}

type OutboxEventData struct {
	ID string

	// WorkflowName refers to the name of the workflow that the OutboxEventData belongs to.
	WorkflowName string

	// Data represents a slice of bytes the OutboxEventDataMaker constructs via serialising event data
	// in an expected way for it to also be deserialized by the outbox consumer.
	Data []byte
}

type OutboxOption func(w *outboxConfig)

type ReceiverOption func(*ReceiverOptions)

type ReceiverOptions struct {
	PollFrequency    time.Duration
	StreamFromLatest bool
}

type Record struct {
	// WorkflowName is the name of the workflow associated with this record. It helps to identify which workflow
	// this record belongs to.
	WorkflowName string

	// ForeignID is an external identifier for this record, often used to associate it with an external system or
	// resource. This can be useful for linking data across systems.
	ForeignID string

	// RunID uniquely identifies the specific execution or instance of the workflow Run and is a UUID v4.
	// It allows tracking of different runs of the same workflow and foreign id.
	RunID string

	// RunState represents the current state of the workflow Run (e.g., running, paused, completed).
	// This field is important for understanding the lifecycle status of the run.
	RunState RunState

	// Status is an integer representing the numerical status code of the record.
	// Terminal, or end, statuses are written as past tense as they are fact and cannot change but present continuous
	// tense is used to describe the current process taking place (e.g. submitting, creating, storing)
	Status int

	// Object contains the actual data associated with the workflow Run, serialized as bytes.
	// This could be any kind of structured data related to the workflow execution. To unmarshal this data Unmarshal
	// must be used to do so and the type matches the generic type called "Type" provided to the workflow builder
	// ( e.g. NewBuilder[Type any, ...])
	Object []byte

	// CreatedAt is the timestamp when the record was created, providing context on when the workflow Run was initiated.
	CreatedAt time.Time

	// UpdatedAt is the timestamp when the record was last updated. This helps track the most recent changes made to
	// the record.
	UpdatedAt time.Time

	// Meta stores any additional metadata related to the record, such as human-readable reasons for the RunState
	// or other contextual information that can assist with debugging or auditing.
	Meta Meta
}

type RecordFilter func(filters *recordFilters)

type RecordStore interface {
	// Store should create or update a record depending on whether the underlying store is mutable or append only. Store
	// must implement transactions and a separate outbox store to store the outbox record (that should be
	// generated using MakeOutboxEventData) which can be retrieved when calling ListOutboxEvents and can be
	// deleted when DeleteOutboxEvent is called.
	Store(ctx context.Context, record *Record) error
	Lookup(ctx context.Context, runID string) (*Record, error)
	Latest(ctx context.Context, workflowName, foreignID string) (*Record, error)

	// List provides a slice of Record where the total items will be equal or less than the limit depending
	// on the offset provided and how many records remain after that ID.
	List(ctx context.Context, workflowName string, offsetID int64, limit int, order OrderType, filters ...RecordFilter) ([]Record, error)

	// ListOutboxEvents lists all events that are yet to be published to the event streamer. A requirement for
	// implementation of the RecordStore is to support a Transactional Outbox that has Event's written to it when
	// Store is called.
	ListOutboxEvents(ctx context.Context, workflowName string, limit int64) ([]OutboxEvent, error)
	// DeleteOutboxEvent will expect an Event's ID field and will remove the event from the outbox store when the
	// event has successfully been published to the event streamer.
	DeleteOutboxEvent(ctx context.Context, id string) error
}

type RoleScheduler interface {
	// Await must return a child context of the provided (parent) context. Await should block until the role is
	// assigned to the caller. Only one caller should be able to be assigned the role at any given time. The returned
	// context.CancelFunc is called after each process execution. Some process executions can be more long living and
	// others not but if any process errors the context.CancelFunc will be called after the specified error backoff
	// has finished.
	Await(ctx context.Context, role string) (context.Context, context.CancelFunc, error)
}

type Run[Type any, Status StatusType] struct {
	TypedRecord[Type, Status]
	// contains filtered or unexported fields
}

type RunState int

type RunStateChangeHookFunc[Type any, Status StatusType] func(ctx context.Context, record *TypedRecord[Type, Status]) error

type RunStateController interface {
	// Pause will take the workflow run specified and move it into a temporary state where it will no longer be processed.
	// A paused workflow run can be resumed by calling Resume. ErrUnableToPause is returned when a workflow is not in a
	// state to be paused.
	Pause(ctx context.Context, reason string) error
	// Cancel can be called after Pause has been called. A paused run of the workflow can be indefinitely cancelled.
	// Once cancelled, DeleteData can be called and will move the run into an indefinite state of DataDeleted.
	// ErrUnableToCancel is returned when the workflow record is not in a state to be cancelled.
	Cancel(ctx context.Context, reason string) error
	// Resume can be called on a workflow run that has been paused. ErrUnableToResume is returned when the workflow
	// run is not in a state to be resumed.
	Resume(ctx context.Context) error
	// DeleteData can be called after a workflow run has been completed or cancelled. DeleteData should be used to
	// comply with the right to be forgotten such as complying with GDPR. ErrUnableToDelete is returned when the
	// workflow run is not in a state to be deleted.
	DeleteData(ctx context.Context, reason string) error
}

type ScheduleOption[Type any, Status StatusType] func(o *scheduleOpts[Type, Status])

type SkipType int

type State int

type StatusType interface {
	~int | ~int32 | ~int64

	String() string
}

type TestingRecordStore interface {
	RecordStore

	Snapshots(workflowName, foreignID, runID string) []*Record
}

type TestingRunOption func(*testingRunOpts)

type TimeoutFunc[Type any, Status StatusType] func(ctx context.Context, r *Run[Type, Status], now time.Time) (Status, error)

type TimeoutRecord struct {
	ID           int64
	WorkflowName string
	ForeignID    string
	RunID        string
	Status       int
	Completed    bool
	ExpireAt     time.Time
	CreatedAt    time.Time
}

type TimeoutStore interface {
	Create(ctx context.Context, workflowName, foreignID, runID string, status int, expireAt time.Time) error
	Complete(ctx context.Context, id int64) error
	Cancel(ctx context.Context, id int64) error
	List(ctx context.Context, workflowName string) ([]TimeoutRecord, error)
	ListValid(ctx context.Context, workflowName string, status int, now time.Time) ([]TimeoutRecord, error)
}

type TimerFunc[Type any, Status StatusType] func(ctx context.Context, r *Run[Type, Status], now time.Time) (time.Time, error)

type TriggerOption[Type any, Status StatusType] func(o *triggerOpts[Type, Status])

type TypedRecord[Type any, Status StatusType] struct {
	Record
	Status Status
	Object *Type
}

type Workflow[Type any, Status StatusType] struct {
	// contains filtered or unexported fields
}