autoflow

type Action interface {
	starlark.Callable
	// Poll invokes the action repeatedly until check (a CEL expression over the
	// action's returned value, bound as `ret`) is satisfied, re-attempting every
	// interval until timeout elapses. The returned Future yields the action's
	// value on success, or timeoutValue once timeout elapses without check
	// passing.
	Poll(
		ctx context.Context,
		check string,
		args starlark.Tuple,
		kwargs []starlark.Tuple,
		interval, timeout time.Duration,
		timeoutValue starlark.Value,
	) (Future, error)
}

type ActionDeriver interface {
	// DeriveAction returns an action that invokes action from within transform, so
	// what reaches action is what transform passes on and what the derived action
	// yields is transform's own output. script is the file the transform was
	// declared in, which is what the runtime needs to recover the transform's
	// source text.
	DeriveAction(action Action, transform *starlark.Function, script Script) (Action, error)
}

type Awaitable interface {
	// Await blocks until a value is available and returns it. A Future yields its
	// single result; a Channel yields its next value and may be awaited again.
	Await() (starlark.Value, error)
}

type Backend interface {
	SetLocals(*starlark.Thread)
	Print(msg string)
	// Select blocks until one of the cases is ready and returns that case's name.
	// If timeout is non-zero and elapses first, it returns timeoutValue.
	Select(ctx context.Context, cases []SelectCase, timeout time.Duration, timeoutValue starlark.Value) (starlark.Value, error)
	// NewChannel constructs a new channel that yields successive values over time.
	NewChannel() Channel
	Sleep(ctx context.Context, duration time.Duration) error
	Timer(duration time.Duration) Future
	WorkflowKey() string
	// Gather waits for all given sources. If returnList is false it returns the
	// single source's value, otherwise a starlark.List of values. If timeout is
	// non-zero and elapses before all sources are ready, it returns timeoutValue
	// instead of a result.
	Gather(ctx context.Context, sources []Awaitable, timeout time.Duration, timeoutValue starlark.Value, returnList bool) (starlark.Value, error)
	// StartWorkflow schedules a fire-and-forget child workflow that runs the given
	// code with the given positional and keyword arguments. It returns the child's
	// workflow key.
	//
	// Exactly one of definition and entryFunction is set: a non-nil definition is
	// a self-contained script whose entry point is main, while an entryFunction
	// makes the child run the calling workflow's own definition with that
	// top-level function as its entry point.
	StartWorkflow(ctx context.Context, definition []byte, entryFunction string, args starlark.Tuple, kwargs []starlark.Tuple) (string, error)
	// ExecuteWorkflow schedules an awaitable child workflow that runs the given
	// code with the given positional and keyword arguments. The returned Future
	// resolves to the child's result; the returned string is the child's workflow
	// key. definition and entryFunction work as in StartWorkflow.
	ExecuteWorkflow(ctx context.Context, definition []byte, entryFunction string, args starlark.Tuple, kwargs []starlark.Tuple) (Future, string, error)
}

type Channel interface {
	Awaitable
	// Name is the channel's identity.
	Name() string
}

type ChannelType struct {
	C Channel
}

type ExecFuncOptions struct {
	Backend Backend
	Tracer  trace.Tracer
	// Globals are the top-level symbols of the flow definition fn belongs to.
	// The child workflow builtins validate function references against them:
	// a child resolves its entry point by name in these globals.
	Globals starlark.StringDict
	// Args and Kwargs are the positional and keyword arguments bound to the
	// fn's parameters, i.e. fn(w, *Args, **Kwargs). Each Kwargs
	// tuple is a (name, value) pair.
	// w is always prepended as the first argument.
	Args   []starlark.Value
	Kwargs []starlark.Tuple
	// MaxSteps is the computation-step budget of the thread fn runs on; zero means
	// the default.
	MaxSteps uint64
	// OnThreadEnd, when set, is called once the thread finished.
	OnThreadEnd ThreadEndFunc
}

type ExecMainOptions struct {
	Definition []byte
	Loader     Loader
	Backend    Backend
	Tracer     trace.Tracer
	// ActionDeriver derives actions for derived_action.
	ActionDeriver ActionDeriver
	// EntryFunction is the name of the top-level function to call. Empty means
	// `main`.
	EntryFunction string
	// Args and Kwargs are the positional and keyword arguments bound to the
	// main's parameters, i.e. main(w, *Args, **Kwargs). Each Kwargs
	// tuple is a (name, value) pair.
	Args   []starlark.Value
	Kwargs []starlark.Tuple
	// MaxSteps is the computation-step budget of the two threads the run builds,
	// the top level's and the entry function's; zero means the default.
	MaxSteps uint64
	// OnThreadEnd, when set, is called once each of those threads finished.
	OnThreadEnd ThreadEndFunc
}

type ExecScriptOptions struct {
	ScriptName string
	Definition []byte
	Loader     Loader
	Backend    Backend
	Tracer     trace.Tracer
	// ActionDeriver derives actions for derived_action.
	ActionDeriver ActionDeriver
	// MaxSteps is the computation-step budget of the thread this script runs on;
	// zero means the default.
	MaxSteps uint64
	// Thread is which of the run's threads this script runs on: the flow file's
	// top level (the zero value) or a loaded module file.
	Thread ThreadKind
	// OnThreadEnd, when set, is called once the thread finished.
	OnThreadEnd ThreadEndFunc
}

type Future interface {
	Awaitable
}

type FutureType struct {
	F Future
}

type Loader interface {
	Load(ctx context.Context, thread *starlark.Thread, moduleURI string) (starlark.StringDict, error)
}

type Script struct {
	Name   string
	Source []byte
}

type SelectCase struct {
	Name string
	// Source is the value the case waits on.
	Source Awaitable
}

type StepLimitError struct {
	Thread   string
	Steps    uint64
	Function string
	Pos      syntax.Position
	Err      error
}

type ThreadEndFunc func(ctx context.Context, thread ThreadKind, steps uint64)

type ThreadKind string