plumber

package module
v5.6.5 Latest Latest
Warning

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

 Go to latest Published: Jan 13, 2025 License: MIT Imports: 30 Imported by: 2

README

plumber

Description

A library for creating quick and effective CLI applications that have the process management build inside it.

API Documentation

You can find the API documentation here.

Documentation

Index

Constants

View Source 
const (
	LOG_LEVEL_DEFAULT LogLevel = 0
	LOG_LEVEL_PANIC   LogLevel = logrus.PanicLevel
	LOG_LEVEL_FATAL   LogLevel = logrus.FatalLevel
	LOG_LEVEL_ERROR   LogLevel = logrus.ErrorLevel
	LOG_LEVEL_WARN    LogLevel = logrus.WarnLevel
	LOG_LEVEL_INFO    LogLevel = logrus.InfoLevel
	LOG_LEVEL_DEBUG   LogLevel = logrus.DebugLevel
	LOG_LEVEL_TRACE   LogLevel = logrus.TraceLevel
	LOG_FIELD_CONTEXT string   = "context"
	LOG_FIELD_STATUS  string   = "status"
)
View Source 
const CLI_FLAGS_CATEGORY = "CLI"
View Source 
const (
	COMMAND_RETRY_DELAY time.Duration = time.Second
)

Variables

View Source 
var CliDefaultFlags = []cli.Flag{
	&cli.BoolFlag{
		Category: CLI_FLAGS_CATEGORY,
		Name:     "ci",
		Usage:    "Sets whether this is running inside a CI/CD environment.",
		Hidden:   true,
		EnvVars:  []string{"CI"},
	},

	&cli.BoolFlag{
		Category: CLI_FLAGS_CATEGORY,
		Name:     "debug",
		Usage:    "Enable debugging for the application.",
		EnvVars:  []string{"DEBUG"},
		Hidden:   true,
	},

	&cli.StringFlag{
		Category: CLI_FLAGS_CATEGORY,
		Name:     "log-level",
		Usage:    `Define the log level for the application. enum("panic", "fatal", "warn", "info", "debug", "trace")`,
		EnvVars:  []string{"LOG_LEVEL"},
		Value:    logrus.InfoLevel.String(),
	},

	&cli.StringSliceFlag{
		Category: CLI_FLAGS_CATEGORY,
		Name:     "env-file",
		Usage:    "Environment files to inject.",
		EnvVars:  []string{"ENV_FILE"},
	},
}

flags for a Plumber application.

Functions

func CombineFlags added in v5.6.3 

func CombineFlags(flags ...[]cli.Flag) []cli.Flag

Combine flags together.

func EditCliFlag 

func EditCliFlag[Flag any](flags []cli.Flag, fn func(f Flag) bool, apply func(f Flag) Flag) []cli.Flag

func InlineTemplate 

func InlineTemplate[Ctx any](tmpl string, ctx Ctx, funcs ...template.FuncMap) (string, error)

func InlineTemplates added in v5.3.0 

func InlineTemplates[Ctx any](tmpls []string, ctx Ctx, funcs ...template.FuncMap) ([]string, error)

func OverwriteCliFlag 

func OverwriteCliFlag[Flag any](flags []cli.Flag, fn func(f Flag) bool, apply func(f Flag) Flag)

func ParseEnvironmentVariablesToMap 

func ParseEnvironmentVariablesToMap() map[string]string

func TemplateFuncMap 

func TemplateFuncMap() template.FuncMap

Types

type AppChannel 

type AppChannel struct {
	// to communicate the errors while not blocking
	Err chan error
	// to communicate the errors while not blocking
	CustomErr chan ErrorWithLogger
	// Fatal errors
	Fatal chan error
	// to communicate the errors while not blocking
	CustomFatal chan ErrorWithLogger
	// terminate channel
	Interrupt chan os.Signal
	// exit channel
	Exit *broadcaster.Broadcaster[int]
}

type AppEnvironment 

type AppEnvironment struct {
	Debug bool
	CI    bool
}

type Command 

type Command[Pipe TaskListData] struct {
	Plumber *Plumber
	T       *Task[Pipe]
	TL      *TaskList[Pipe]
	Log     *logrus.Entry

	Command *exec.Cmd
	// contains filtered or unexported fields
}

func NewCommand 

func NewCommand[Pipe TaskListData](
	task *Task[Pipe],
	command string,
	args ...string,
) *Command[Pipe]

NewCommand Creates a new command to be run as a job.

func (*Command[Pipe]) AddSelfToTheParentTask 

func (c *Command[Pipe]) AddSelfToTheParentTask(pt *Task[Pipe]) *Command[Pipe]

Adds the current command to the task with a wrapper.

func (*Command[Pipe]) AddSelfToTheTask 

func (c *Command[Pipe]) AddSelfToTheTask() *Command[Pipe]

Adds the current command to the parent task.

func (*Command[Pipe]) AppendArgs 

func (c *Command[Pipe]) AppendArgs(args ...string) *Command[Pipe]

Appends arguments to the command.

func (*Command[Pipe]) AppendDirectEnvironment 

func (c *Command[Pipe]) AppendDirectEnvironment(environment ...string) *Command[Pipe]

Appends environment variables to command directly.

func (*Command[Pipe]) AppendEnvironment 

func (c *Command[Pipe]) AppendEnvironment(environment map[string]string) *Command[Pipe]

Appends environment variables to command as map.

func (*Command[Pipe]) EnableStreamRecording 

func (c *Command[Pipe]) EnableStreamRecording() *Command[Pipe]

Sets the option where this command will save its output to be later accessed in the shouldRunAfterFn.

func (*Command[Pipe]) EnableTerminator 

func (c *Command[Pipe]) EnableTerminator() *Command[Pipe]

Enables global plumber terminator on this command to terminate the current command when the application is terminated.

func (*Command[Pipe]) EnsureIsAlive 

func (c *Command[Pipe]) EnsureIsAlive() *Command[Pipe]

Sets the option where it will raise an error if the underlying command stops.

func (*Command[Pipe]) GetCombinedStream 

func (c *Command[Pipe]) GetCombinedStream() []string

Fetches the saved streams that is recorded. Should have the Command.options.recordStream enabled.

func (*Command[Pipe]) GetFormattedCommand 

func (c *Command[Pipe]) GetFormattedCommand() string

Fetches the name of this command, that is formatted for the logger.

func (*Command[Pipe]) GetStderrStream 

func (c *Command[Pipe]) GetStderrStream() []string

Fetches the saved stderr stream that is recorded. Should have the Command.options.recordStream enabled.

func (*Command[Pipe]) GetStdoutStream 

func (c *Command[Pipe]) GetStdoutStream() []string

Fetches the saved stdout stream that is recorded. Should have the Command.options.recordStream enabled.

func (*Command[Pipe]) HasExited 

func (c *Command[Pipe]) HasExited() bool

Returns whether the command has exited properly or not.

func (*Command[Pipe]) HasFailed 

func (c *Command[Pipe]) HasFailed() bool

Returns whether the command has failed or not.

func (*Command[Pipe]) IsDisabled 

func (c *Command[Pipe]) IsDisabled() bool

Checks whether current command is disabled.

func (*Command[Pipe]) Job 

func (c *Command[Pipe]) Job() Job

Convert Command.Run to a floc job.

func (*Command[Pipe]) Run 

func (c *Command[Pipe]) Run() error

Run the command as defined.

func (*Command[Pipe]) Set 

func (c *Command[Pipe]) Set(fn CommandFn[Pipe]) *Command[Pipe]

Sets the function that should manipulate the command depending on the pipe variables.

func (*Command[Pipe]) SetCredential added in v5.1.0 

func (c *Command[Pipe]) SetCredential(fn CommandCredentialFn[Pipe]) *Command[Pipe]

func (*Command[Pipe]) SetDir 

func (c *Command[Pipe]) SetDir(dir string) *Command[Pipe]

Sets the current directory where the command will be executed.

func (*Command[Pipe]) SetIgnoreError 

func (c *Command[Pipe]) SetIgnoreError() *Command[Pipe]

Sets the option to ignore errors raised by this command therefore a failing command will not fail the application.

func (*Command[Pipe]) SetJobWrapper 

func (c *Command[Pipe]) SetJobWrapper(fn CommandJobWrapperFn[Pipe]) *Command[Pipe]

Extend the job of the current task.

func (*Command[Pipe]) SetLogLevel 

func (c *Command[Pipe]) SetLogLevel(
	stdout LogLevel,
	stderr LogLevel,
	lifetime LogLevel,
) *Command[Pipe]

Sets the log level specific to this command.

func (*Command[Pipe]) SetMaskOsEnvironment 

func (c *Command[Pipe]) SetMaskOsEnvironment() *Command[Pipe]

Sets the option where underlying environment variables are not passed to the command.

func (*Command[Pipe]) SetOnTerminator 

func (c *Command[Pipe]) SetOnTerminator(fn CommandFn[Pipe]) *Command[Pipe]

Sets a function that fires on when the application is globally terminated through plumber.

func (*Command[Pipe]) SetPath 

func (c *Command[Pipe]) SetPath(dir string) *Command[Pipe]

Sets the current directory where the command will be executed.

func (*Command[Pipe]) SetRetries 

func (c *Command[Pipe]) SetRetries(retry *CommandRetry) *Command[Pipe]

Sets the option to retry the command if failed.

func (*Command[Pipe]) SetScript added in v5.1.0 

func (c *Command[Pipe]) SetScript(fn CommandScriptFn[Pipe]) *Command[Pipe]

func (*Command[Pipe]) SetStdin added in v5.1.1 

func (c *Command[Pipe]) SetStdin(fn CommandStdinFn[Pipe]) *Command[Pipe]

func (*Command[Pipe]) ShouldDisable 

func (c *Command[Pipe]) ShouldDisable(fn TaskPredicateFn[Pipe]) *Command[Pipe]

Adds a predicate to check whether this command should be disabled depending on the pipe variables.

func (*Command[Pipe]) ShouldRunAfter 

func (c *Command[Pipe]) ShouldRunAfter(fn CommandFn[Pipe]) *Command[Pipe]

Sets a function that should run after the main command has exited successfully.

func (*Command[Pipe]) ShouldRunBefore 

func (c *Command[Pipe]) ShouldRunBefore(fn CommandFn[Pipe]) *Command[Pipe]

Sets a function that should run after the main command has exited successfully.

func (*Command[Pipe]) ToCtx added in v5.6.0 

func (c *Command[Pipe]) ToCtx() *CommandCtx

Converts the command to a command context.

type CommandCredentialFn added in v5.2.4 

type CommandCredentialFn[Pipe TaskListData] func(c *Command[Pipe], credential *syscall.Credential) *syscall.Credential

type CommandCtx added in v5.5.0 

type CommandCtx struct {
	TL *TaskListCtx
	T  *TaskCtx

	Plumber *Plumber
	Log     *logrus.Entry

	Command *exec.Cmd
}

type CommandFn 

type CommandFn[Pipe TaskListData] func(*Command[Pipe]) error

type CommandJobWrapperFn added in v5.1.3 

type CommandJobWrapperFn[Pipe TaskListData] func(job Job, c *Command[Pipe]) Job

type CommandOptions 

type CommandOptions[Pipe TaskListData] struct {
	// contains filtered or unexported fields
}

type CommandRetry added in v5.1.8 

type CommandRetry struct {
	Tries  uint32
	Always bool
	Delay  time.Duration
}

type CommandScript added in v5.1.0 

type CommandScript struct {
	Inline string
	File   string
	Ctx    interface{}
	Funcs  []template.FuncMap
}

type CommandScriptFn added in v5.2.2 

type CommandScriptFn[Pipe TaskListData] func(c *Command[Pipe]) *CommandScript

type CommandStatus 

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

type CommandStdinFn added in v5.2.2 

type CommandStdinFn[Pipe TaskListData] func(c *Command[Pipe]) io.Reader

type DeprecationNotice 

type DeprecationNotice struct {
	Message     string
	Environment []string
	Flag        []string
	Level       LogLevel
}

type DocumentationOptions 

type DocumentationOptions struct {
	MarkdownOutputFile          string
	EmbeddedMarkdownOutputFile  string
	MarkdownBehead              int
	ExcludeFlags                bool
	ExcludeEnvironmentVariables bool
	ExcludeHelpCommand          bool
}

type ErrorWithLogger 

type ErrorWithLogger struct {
	Log *logrus.Entry
	Err error
}

type GuardHandlerFn 

type GuardHandlerFn[Pipe TaskListData] func(*TaskList[Pipe])

type Job 

type Job = floc.Job

type JobFn added in v5.0.2 

type JobFn func(job Job) Job

type JobPredicate 

type JobPredicate = floc.Predicate

type LogLevel 

type LogLevel = logrus.Level

type Plumber 

type Plumber struct {
	Cli         *cli.App
	Log         *logrus.Logger
	Environment AppEnvironment
	Channel     AppChannel
	Terminator
	Validator *validator.Validate
	// contains filtered or unexported fields
}

func NewPlumber 

func NewPlumber(fn PlumberNewFn) *Plumber

Creates a new Plumber instance and initiates it.

func (*Plumber) AppendFlags 

func (p *Plumber) AppendFlags(flags ...[]cli.Flag) []cli.Flag

Appends flags together. @deprecated.

func (*Plumber) AppendSecrets 

func (p *Plumber) AppendSecrets(secrets ...string) *Plumber

Adds sensitive information so that the logger will not log out the given secrets.

func (*Plumber) DeregisterTerminator added in v5.1.6 

func (p *Plumber) DeregisterTerminator() *Plumber

func (*Plumber) DisableGreeter added in v5.1.0 

func (p *Plumber) DisableGreeter() *Plumber

Disables the greeter function to print out the CLI name and version.

func (*Plumber) EnableTerminator 

func (p *Plumber) EnableTerminator() *Plumber

Enables terminator globally for the current application.

If terminator functions are going to be used inside task lists, tasks and commands, terminator should be globally enabled. The terminate information will be propagated through the channels to the subcomponents.

func (*Plumber) New 

func (p *Plumber) New(
	fn PlumberNewFn,
) *Plumber

Creates a new plumber.

func (*Plumber) RegisterTerminated 

func (p *Plumber) RegisterTerminated() *Plumber

Register a component as successfully terminated.

func (*Plumber) RegisterTerminator 

func (p *Plumber) RegisterTerminator() *Plumber

Registers a new component that should be handled by the terminator.

func (*Plumber) Run 

func (p *Plumber) Run()

Starts the application.

func (*Plumber) SendCustomError 

func (p *Plumber) SendCustomError(log *logrus.Entry, err error) *Plumber

Sends an error with its custom instance of logger through the channel.

func (*Plumber) SendCustomFatal 

func (p *Plumber) SendCustomFatal(log *logrus.Entry, err error) *Plumber

Sends an fatal error with its custom instance of logger through the channel.

func (*Plumber) SendError 

func (p *Plumber) SendError(err error) *Plumber

Sends an error through the channel.

func (*Plumber) SendExit 

func (p *Plumber) SendExit(code int) *Plumber

Sends exit code to terminate the application.

func (*Plumber) SendFatal 

func (p *Plumber) SendFatal(err error) *Plumber

Sends an fatal error through the channel.

func (*Plumber) SendTerminate 

func (p *Plumber) SendTerminate(sig os.Signal, code int)

Sends a terminate request to the application via interruption signal.

func (*Plumber) Set 

func (p *Plumber) Set(fn PlumberFn) *Plumber

Sets additional configuration fields.

func (*Plumber) SetDelimiter 

func (p *Plumber) SetDelimiter(delimiter string) *Plumber

Sets delimiter for the application.

func (*Plumber) SetDeprecationNotices 

func (p *Plumber) SetDeprecationNotices(notices ...[]DeprecationNotice) *Plumber

Sets the deprecation notices for the application.

func (*Plumber) SetDocumentationOptions 

func (p *Plumber) SetDocumentationOptions(options DocumentationOptions) *Plumber

Sets documentation options of the application.

func (*Plumber) SetFormatter 

func (p *Plumber) SetFormatter(formatter *logger.Formatter) *Plumber

sets formatter for the plumber.

func (*Plumber) SetGreeter added in v5.1.0 

func (p *Plumber) SetGreeter(fn PlumberFn) *Plumber

Sets the greeter function to print out the CLI name and version.

func (*Plumber) SetOnTerminate 

func (p *Plumber) SetOnTerminate(fn PlumberOnTerminateFn) *Plumber

Sets the action that would be executed on terminate.

func (*Plumber) SetTerminatorTimeout 

func (p *Plumber) SetTerminatorTimeout(timeout time.Duration) *Plumber

Sets timeout for terminator of the application.

func (*Plumber) Terminate 

func (p *Plumber) Terminate(code int)

Sends a terminate request through the application.

This will gracefully try to stop the application components that are registered and listening for the terminator.

type PlumberFn 

type PlumberFn func(p *Plumber) error

type PlumberNewFn 

type PlumberNewFn func(p *Plumber) *cli.App

type PlumberOnTerminateFn 

type PlumberOnTerminateFn func() error

type PlumberOptions 

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

type Result 

type Result = floc.Result
const (
	TASK_ANY       Result = floc.None
	TASK_COMPLETED Result = floc.Completed
	TASK_CANCELLED Result = floc.Canceled
	TASK_FAILED    Result = floc.Failed
)

type ResultMask 

type ResultMask = floc.ResultMask

type StatusStopCases 

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

type SubtaskExtendFn added in v5.1.0 

type SubtaskExtendFn[Pipe TaskListData] func(pt *Task[Pipe], st *Task[Pipe])

type Task 

type Task[Pipe TaskListData] struct {
	Plumber *Plumber
	TL      *TaskList[Pipe]
	Log     *logrus.Entry
	Channel *AppChannel
	Pipe    *Pipe
	Control floc.Control
	Name    string

	Lock *sync.RWMutex
	// contains filtered or unexported fields
}

func NewTask 

func NewTask[Pipe TaskListData](tl *TaskList[Pipe], name ...string) *Task[Pipe]

NewTask Creates a new task to be run as a job.

func (*Task[Pipe]) AddCommands 

func (t *Task[Pipe]) AddCommands(commands ...*Command[Pipe]) *Task[Pipe]

Attaches existing commands to this task.

func (*Task[Pipe]) AddSelfToTheParent 

func (t *Task[Pipe]) AddSelfToTheParent(
	fn SubtaskExtendFn[Pipe],
) *Task[Pipe]

Attaches this task to the parent task with a wrapper.

func (*Task[Pipe]) AddSelfToTheParentAsParallel 

func (t *Task[Pipe]) AddSelfToTheParentAsParallel() *Task[Pipe]

Attaches this task to the parent task in parallel.

func (*Task[Pipe]) AddSelfToTheParentAsSequence 

func (t *Task[Pipe]) AddSelfToTheParentAsSequence() *Task[Pipe]

Attaches this task to the parent task in sequence.

func (*Task[Pipe]) CreateCommand 

func (t *Task[Pipe]) CreateCommand(command string, args ...string) *Command[Pipe]

Creates a NewCommand attached to the current task.

func (*Task[Pipe]) CreateSubtask 

func (t *Task[Pipe]) CreateSubtask(name ...string) *Task[Pipe]

Creates a subtask that is attached to the current task.

func (*Task[Pipe]) EnableTerminator 

func (t *Task[Pipe]) EnableTerminator() *Task[Pipe]

Enables global plumber terminator on this task.

func (*Task[Pipe]) ExtendSubtask 

func (t *Task[Pipe]) ExtendSubtask(fn JobFn) *Task[Pipe]

Extends the subtask of the current task with a wrapper.

func (*Task[Pipe]) GetCommandJobAsJobParallel 

func (t *Task[Pipe]) GetCommandJobAsJobParallel() Job

Returns the attached commands to this task as a job to run as parallel depending on their definition order.

func (*Task[Pipe]) GetCommandJobAsJobSequence 

func (t *Task[Pipe]) GetCommandJobAsJobSequence() Job

Returns the attached commands to this task as a job to run as sequence depending on their definition order.

func (*Task[Pipe]) GetCommandJobs 

func (t *Task[Pipe]) GetCommandJobs() []Job

Returns the attached commands to this task as a slice of jobs.

func (*Task[Pipe]) GetCommands 

func (t *Task[Pipe]) GetCommands() []*Command[Pipe]

Returns the attached commands to this task.

func (*Task[Pipe]) GetSubtasks 

func (t *Task[Pipe]) GetSubtasks() Job

Returns the subtasks of this task.

func (*Task[Pipe]) HasParent 

func (t *Task[Pipe]) HasParent() bool

Checks whether this task has a parent task.

func (*Task[Pipe]) IsDisabled 

func (t *Task[Pipe]) IsDisabled() bool

Checks whether the current task is disabled or not.

func (*Task[Pipe]) IsSkipped 

func (t *Task[Pipe]) IsSkipped() bool

Checks whether the current task is skipped or not.

func (*Task[Pipe]) Job 

func (t *Task[Pipe]) Job() Job

Runs the current task as a job.

func (*Task[Pipe]) Run 

func (t *Task[Pipe]) Run() error

Runs the current task.

func (*Task[Pipe]) RunCommandJob added in v5.1.0 

func (t *Task[Pipe]) RunCommandJob(fn TaskJobParserFn[Pipe]) error

Runs the commands that are attached to this task as parallel with the given wrapper.

func (*Task[Pipe]) RunCommandJobAsJobParallel 

func (t *Task[Pipe]) RunCommandJobAsJobParallel() error

Runs the commands that are attached to this task as parallel.

func (*Task[Pipe]) RunCommandJobAsJobSequence 

func (t *Task[Pipe]) RunCommandJobAsJobSequence() error

Runs the commands that are attached to this task as sequence.

func (*Task[Pipe]) RunSubtasks 

func (t *Task[Pipe]) RunSubtasks() error

Runs the subtasks of the current task.

func (*Task[Pipe]) SendError 

func (t *Task[Pipe]) SendError(err error) *Task[Pipe]

Send the error message to plumber while running inside a routine.

func (*Task[Pipe]) SendExit 

func (t *Task[Pipe]) SendExit(code int) *Task[Pipe]

Trigger the exit protocol of plumber.

func (*Task[Pipe]) SendFatal 

func (t *Task[Pipe]) SendFatal(err error) *Task[Pipe]

Send the fatal error message to plumber while running inside a routine.

func (*Task[Pipe]) Set 

func (t *Task[Pipe]) Set(fn TaskFn[Pipe]) *Task[Pipe]

Sets the function that should run as task.

func (*Task[Pipe]) SetJobWrapper 

func (t *Task[Pipe]) SetJobWrapper(fn TaskJobWrapperFn[Pipe]) *Task[Pipe]

Extend the job of the current task.

func (*Task[Pipe]) SetOnTerminator 

func (t *Task[Pipe]) SetOnTerminator(fn TaskFn[Pipe]) *Task[Pipe]

Sets the function that should fire whenever the application is globally terminated.

func (*Task[Pipe]) SetSubtask 

func (t *Task[Pipe]) SetSubtask(job Job) *Task[Pipe]

Sets the subtask of this task directly.

func (*Task[Pipe]) ShouldDisable 

func (t *Task[Pipe]) ShouldDisable(fn TaskPredicateFn[Pipe]) *Task[Pipe]

Sets the predicate that should conditionally disable the task depending on the pipe variables.

func (*Task[Pipe]) ShouldRunAfter 

func (t *Task[Pipe]) ShouldRunAfter(fn TaskFn[Pipe]) *Task[Pipe]

Sets the function that should run after the task.

func (*Task[Pipe]) ShouldRunBefore 

func (t *Task[Pipe]) ShouldRunBefore(fn TaskFn[Pipe]) *Task[Pipe]

Sets the function that should run before the task.

func (*Task[Pipe]) ShouldSkip 

func (t *Task[Pipe]) ShouldSkip(fn TaskPredicateFn[Pipe]) *Task[Pipe]

Sets the predicate that should conditionally skip the task depending on the pipe variables.

func (*Task[Pipe]) ToCtx added in v5.6.0 

func (t *Task[Pipe]) ToCtx() *TaskCtx

func (*Task[Pipe]) ToParent 

func (t *Task[Pipe]) ToParent(
	parent *Task[Pipe],
	fn SubtaskExtendFn[Pipe],
) *Task[Pipe]

Attaches this task to a arbitatary given parent task.

type TaskCtx added in v5.5.0 

type TaskCtx struct {
	Plumber *Plumber
	TL      *TaskListCtx
	Log     *logrus.Entry

	Name string

	Lock *sync.RWMutex
}

type TaskFn 

type TaskFn[Pipe TaskListData] func(t *Task[Pipe]) error

type TaskJobParserFn added in v5.1.3 

type TaskJobParserFn[Pipe TaskListData] func(t *Task[Pipe]) Job

type TaskJobWrapperFn added in v5.1.3 

type TaskJobWrapperFn[Pipe TaskListData] func(job Job, t *Task[Pipe]) Job

type TaskList 

type TaskList[Pipe TaskListData] struct {
	Plumber    *Plumber
	CliContext *cli.Context
	Pipe       Pipe
	Channel    *AppChannel
	Control    floc.Control

	Name string

	Lock *sync.RWMutex
	Log  *logrus.Entry
	// contains filtered or unexported fields
}

func NewTaskList 

func NewTaskList[Pipe TaskListData](p *Plumber) *TaskList[Pipe]

Creates a new task list and initiates it.

func (*TaskList[Pipe]) CreateBasicJob 

func (tl *TaskList[Pipe]) CreateBasicJob(fn func() error) Job

func (*TaskList[Pipe]) CreateJob 

func (tl *TaskList[Pipe]) CreateJob(fn func(tl *TaskList[Pipe]) error) Job

func (*TaskList[Pipe]) CreateTask 

func (tl *TaskList[Pipe]) CreateTask(name ...string) *Task[Pipe]

Creates a new task.

func (*TaskList[Pipe]) GuardAlways 

func (tl *TaskList[Pipe]) GuardAlways(job Job) Job

Always run this job!

func (*TaskList[Pipe]) GuardIgnorePanic 

func (tl *TaskList[Pipe]) GuardIgnorePanic(job Job) Job

func (*TaskList[Pipe]) GuardOnPanic 

func (tl *TaskList[Pipe]) GuardOnPanic(job Job, fn GuardHandlerFn[Pipe]) Job

OnPanic protects the job from falling into panic. In addition it takes PanicTrigger func which is called in case of panic. Guarding the job from falling into panic is effective only if the job runs in the current goroutine.

func (*TaskList[Pipe]) GuardOnTimeout 

func (tl *TaskList[Pipe]) GuardOnTimeout(
	job Job,
	fn GuardHandlerFn[Pipe],
	timeout time.Duration,
) Job

OnTimeout protects the job from taking too much time on execution. In addition it takes TimeoutTrigger func (t *TaskList[Pipe]) which called if time is out. The job is run in it's own goroutine while the current goroutine waits until the job finished or time went out or the flow is finished.

func (*TaskList[Pipe]) GuardPanic 

func (tl *TaskList[Pipe]) GuardPanic(job Job) Job

Panic protects the job from falling into panic. On panic the flow will be canceled with the ErrPanic result. Guarding the job from falling into panic is effective only if the job runs in the current goroutine.

func (*TaskList[Pipe]) GuardResume 

func (tl *TaskList[Pipe]) GuardResume(job Job, mask Result) Job

Resume resumes execution of the flow possibly finished by the job. If the mask is empty execution will be resumed regardless the reason it was finished. Otherwise execution will be resumed if the reason it finished with is masked.

func (*TaskList[Pipe]) GuardTimeout 

func (tl *TaskList[Pipe]) GuardTimeout(job Job, timeout time.Duration) Job

GuardTimeout protects the job from taking too much time on execution. The job is run in it's own goroutine while the current goroutine waits until the job finished or time went out or the flow is finished.

func (*TaskList[Pipe]) IsDisabled 

func (tl *TaskList[Pipe]) IsDisabled() bool

Checks whether the current task is disabled or not.

func (*TaskList[Pipe]) IsSkipped 

func (tl *TaskList[Pipe]) IsSkipped() bool

Checks whether the current task is skipped or not.

func (*TaskList[Pipe]) Job 

func (t *TaskList[Pipe]) Job() Job

Returns this task list as a job.

func (*TaskList[Pipe]) JobBackground 

func (tl *TaskList[Pipe]) JobBackground(job Job) Job

JobBackground starts the job in it's own goroutine. The function does not track the lifecycle of the job started and does no synchronization with it therefore the job running in background may remain active even if the flow is finished. The function assumes the job is aware of the flow state and/or synchronization and termination of it is implemented outside. 

floc.Run(run.Background(
	func(ctx floc.Context, ctrl floc.Control) error {
		for !ctrl.IsFinished() {
			fmt.Println(time.Now())
		}

		return nil
	}
})

Summary:

  • Run jobs in goroutines : YES
  • Wait all jobs finish : NO
  • Run order : SINGLE

Diagram: 

--+----------->
  |
  +-->[JOB]

func (*TaskList[Pipe]) JobDelay 

func (tl *TaskList[Pipe]) JobDelay(job Job, delay time.Duration) Job

JobDelay does delay before starting the job.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

--(DELAY)-->[JOB]-->

func (*TaskList[Pipe]) JobElse 

func (tl *TaskList[Pipe]) JobElse(job Job) Job

JobElse just returns the job unmodified. Else is used for expressiveness and can be omitted.

Summary:

  • Run jobs in goroutines : N/A
  • Wait all jobs finish : N/A
  • Run order : N/A

Diagram: 

----[JOB]--->

func (*TaskList[Pipe]) JobIf 

func (tl *TaskList[Pipe]) JobIf(predicate JobPredicate, jobs ...Job) Job

JobIf runs the first job if the condition is met and runs the second job, if it's passed, if the condition is not met. The function panics if no or more than two jobs are given.

For expressiveness Then() and Else() can be used. 

flow := run.If(testSomething,
  run.Then(doSomething),
  run.Else(doSomethingElse),
)

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

                    +----->[JOB_1]---+
                    | YES            |
--(CONDITION MET?)--+                +-->
                    | NO             |
                    +----->[JOB_2]---+

func (*TaskList[Pipe]) JobIfNot 

func (tl *TaskList[Pipe]) JobIfNot(predicate JobPredicate, jobs ...Job) Job

JobIfNot runs the first job if the condition is not met and runs the second job, if it's passed, if the condition is met. The function panics if no or more than two jobs are given.

For expressiveness Then() and Else() can be used. 

flow := run.IfNot(testSomething,
  run.Then(doSomething),
  run.Else(doSomethingElse),
)

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

                    +----->[JOB_1]---+
                    | NO             |
--(CONDITION MET?)--+                +-->
                    | YES            |
                    +----->[JOB_2]---+

func (*TaskList[Pipe]) JobLoop 

func (tl *TaskList[Pipe]) JobLoop(job Job) Job

JobLoop repeats running the job forever.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

  +----------+
  |          |
  V          |
----->[JOB]--+

func (*TaskList[Pipe]) JobLoopWithWaitAfter 

func (tl *TaskList[Pipe]) JobLoopWithWaitAfter(job Job, delay time.Duration) Job

func (*TaskList[Pipe]) JobParallel 

func (tl *TaskList[Pipe]) JobParallel(jobs ...Job) Job

JobParallel runs jobs in their own goroutines and waits until all of them finish.

Summary:

  • Run jobs in goroutines : YES
  • Wait all jobs finish : YES
  • Run order : PARALLEL

Diagram: 

  +-->[JOB_1]--+
  |            |
--+-->  ..   --+-->
  |            |
  +-->[JOB_N]--+

func (*TaskList[Pipe]) JobRepeat 

func (tl *TaskList[Pipe]) JobRepeat(job Job, times int) Job

JobRepeat repeats running the job for N times.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

                        NO
  +-----------[JOB]<---------+
  |                          |
  V                          | YES
----(ITERATED COUNT TIMES?)--+---->

func (*TaskList[Pipe]) JobSequence 

func (tl *TaskList[Pipe]) JobSequence(jobs ...Job) Job

JobSequence runs jobs sequentially, one by one.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SEQUENCE

Diagram: 

-->[JOB_1]-...->[JOB_N]-->

func (*TaskList[Pipe]) JobThen 

func (tl *TaskList[Pipe]) JobThen(job Job) Job

Then just returns the job unmodified. Then is used for expressiveness and can be omitted.

Summary:

  • Run jobs in goroutines : N/A
  • Wait all jobs finish : N/A
  • Run order : N/A

Diagram: 

----[JOB]--->

func (*TaskList[Pipe]) JobWait 

func (tl *TaskList[Pipe]) JobWait(predicate JobPredicate, sleep time.Duration) Job

JobWait waits until the condition is met. The function falls into sleep with the duration given between condition checks. The function does not run any job actually and just repeatedly checks predicate's return value. When the predicate returns true the function finishes.

Summary:

  • Run jobs in goroutines : N/A
  • Wait all jobs finish : N/A
  • Run order : N/A

Diagram: 

                  NO
  +------(SLEEP)------+
  |                   |
  V                   | YES
----(CONDITION MET?)--+----->

func (*TaskList[Pipe]) JobWaitForTerminator 

func (tl *TaskList[Pipe]) JobWaitForTerminator() Job

func (*TaskList[Pipe]) JobWhile 

func (tl *TaskList[Pipe]) JobWhile(predicate JobPredicate, job Job) Job

JobWhile repeats running the job while the condition is met.

Summary:

  • Run jobs in goroutines : NO
  • Wait all jobs finish : YES
  • Run order : SINGLE

Diagram: 

                  YES
  +-------[JOB]<------+
  |                   |
  V                   | NO
----(CONDITION MET?)--+---->

func (*TaskList[Pipe]) New 

func (tl *TaskList[Pipe]) New(p *Plumber) *TaskList[Pipe]

Creates a new task list.

func (*TaskList[Pipe]) NewResultMask 

func (tl *TaskList[Pipe]) NewResultMask(mask Result) ResultMask

NewResultMask constructs new instance from the mask given.

func (*TaskList[Pipe]) Predicate 

func (tl *TaskList[Pipe]) Predicate(fn TaskListPredicateFn[Pipe]) JobPredicate

Creates a new floc predicate out of the given conditions.

func (*TaskList[Pipe]) PredicateAnd 

func (tl *TaskList[Pipe]) PredicateAnd(predicates ...JobPredicate) JobPredicate

PredicateAnd returns a predicate which chains multiple predicates into a condition with AND logic. The result predicate finishes calculation of the condition as fast as the result is known. The function panics if the number of predicates is less than 2.

The result predicate tests the condition as follows. 

[PRED_1] AND ... AND [PRED_N]

func (*TaskList[Pipe]) PredicateNot 

func (tl *TaskList[Pipe]) PredicateNot(predicate JobPredicate) JobPredicate

PredicateNot returns the negated value of the predicate.

The result predicate tests the condition as follows. 

NOT [PRED]

func (*TaskList[Pipe]) PredicateOr 

func (tl *TaskList[Pipe]) PredicateOr(predicates ...JobPredicate) JobPredicate

PredicateOr returns a predicate which chains multiple predicates into a condition with OR logic. The result predicate finishes calculation of the condition as fast as the result is known.

The result predicate tests the condition as follows. 

[PRED_1] OR ... OR [PRED_N]

func (*TaskList[Pipe]) PredicateXor 

func (tl *TaskList[Pipe]) PredicateXor(predicates ...JobPredicate) JobPredicate

Xor returns a predicate which chains multiple predicates into a condition with XOR logic. The result predicate finishes calculation of the condition as fast as the result is known.

The result predicate tests the condition as follows. 

(([PRED_1] XOR [PRED_2]) ... XOR [PRED_N])

func (*TaskList[Pipe]) Run 

func (t *TaskList[Pipe]) Run() error

Runs the current task list.

func (*TaskList[Pipe]) RunJobs 

func (t *TaskList[Pipe]) RunJobs(job Job) error

Runs a the provided job.

func (*TaskList[Pipe]) Set 

func (tl *TaskList[Pipe]) Set(fn TaskListJobFn[Pipe]) *TaskList[Pipe]

Sets the tasks of the task list.

func (*TaskList[Pipe]) SetCliContext 

func (tl *TaskList[Pipe]) SetCliContext(ctx *cli.Context) *TaskList[Pipe]

Sets the CLI context for urfave/cli that is coming from the action function.

func (*TaskList[Pipe]) SetRuntimeDepth 

func (tl *TaskList[Pipe]) SetRuntimeDepth(depth int) *TaskList[Pipe]

Sets the runtime depth for the logger.

func (*TaskList[Pipe]) ShouldDisable 

func (tl *TaskList[Pipe]) ShouldDisable(fn TaskListPredicateFn[Pipe]) *TaskList[Pipe]

Sets the predicate that should conditionally disable the task list depending on the pipe variables.

func (*TaskList[Pipe]) ShouldRunAfter 

func (tl *TaskList[Pipe]) ShouldRunAfter(fn TaskListFn[Pipe]) *TaskList[Pipe]

Sets the function that should run after the task list.

func (*TaskList[Pipe]) ShouldRunBefore 

func (tl *TaskList[Pipe]) ShouldRunBefore(fn TaskListFn[Pipe]) *TaskList[Pipe]

Sets the function that should run before the task list.

func (*TaskList[Pipe]) ShouldSkip 

func (tl *TaskList[Pipe]) ShouldSkip(fn TaskListPredicateFn[Pipe]) *TaskList[Pipe]

Sets the predicate that should conditionally skip the task list depending on the pipe variables.

func (*TaskList[Pipe]) ToCtx added in v5.6.0 

func (t *TaskList[Pipe]) ToCtx() *TaskListCtx

Returns the context of the current task list.

func (*TaskList[Pipe]) Validate 

func (t *TaskList[Pipe]) Validate(data TaskListData) error

Validates the current pipe of the task list.

type TaskListCtx added in v5.6.0 

type TaskListCtx struct {
	Plumber    *Plumber
	CliContext *cli.Context

	Name string
	Lock *sync.RWMutex
	Log  *logrus.Entry
}

type TaskListData 

type TaskListData interface {
	any
}

type TaskListFn 

type TaskListFn[Pipe TaskListData] func(tl *TaskList[Pipe]) error

type TaskListJobFn 

type TaskListJobFn[Pipe TaskListData] func(tl *TaskList[Pipe]) Job

type TaskListOptions 

type TaskListOptions[Pipe TaskListData] struct {
	// contains filtered or unexported fields
}

type TaskListPredicateFn 

type TaskListPredicateFn[Pipe TaskListData] func(tl *TaskList[Pipe]) bool

type TaskOptions 

type TaskOptions[Pipe TaskListData] struct {
	// contains filtered or unexported fields
}

type TaskPredicateFn 

type TaskPredicateFn[Pipe TaskListData] func(t *Task[Pipe]) bool

type TaskStatus 

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

type Terminator 

type Terminator struct {
	Enabled         bool
	ShouldTerminate *broadcaster.Broadcaster[os.Signal]
	Terminated      *broadcaster.Broadcaster[bool]
	Lock            *sync.RWMutex
	// contains filtered or unexported fields
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.