fw

Documentation

Overview

Package fw is composed of a framework for designing tinyCI runner agents.

Inside this directory as subdirectories are several packages that cover config files, signals, and other features that are documented and also optional in most cases.

To implement a runner, it must contain a struct that must satisfy the Runner interface. Then, an Entrypoint must be created with metadata about the runner, and the runner struct itself. Then, Run(Entrypoint) needs to be called. The rest of the system will automate the process of:

• Coordinating and starting your run
• Managing signals and cancellations
• Logging certain functionality

What is done outside of these framework needs is largely irrelevant to the framework itself.

Index

• func Launch(e *Entrypoint) error
• type Entrypoint
  • func (e *Entrypoint) SetTerminate(log *log.SubLogger)
• type Run
• type Runner

Functions

func Launch

func Launch(e *Entrypoint) error

Launch runs the given Entrypoint, which should contain a Runner to launch as well as other information about the runner. On error you can assume the only safe option is to exit.

At the time of this call, arguments will be parsed. Avoid parsing arguments before this call.

Types

type Entrypoint

type Entrypoint struct {
	// Usage is the way to use the runner application.
	Usage string
	// Description is an extended description of what the runner does and how it works.
	Description string
	// Version is the version of the runner program.
	Version string
	// Author is the author of the runner program.
	Author string
	// Flags are any extra flags you want to handle. We use urfave/cli for managing flags.
	Flags []cli.Flag
	// TeardownTimeout is the amount of time to wait for the runner to tear down
	// everything so it can exit.
	TeardownTimeout time.Duration
	// Launch is the Runner intended to be executed.
	Launch Runner
	// contains filtered or unexported fields
}

Entrypoint is composed of boot-time entities used to start up the application, such as the argument parser and Runner object to enter.

func (*Entrypoint) SetTerminate

func (e *Entrypoint) SetTerminate(log *log.SubLogger)

SetTerminate tells the runner to terminate at the end of the next iteration

type Run

type Run interface {
	fmt.Stringer

	// Name is the name of the run
	Name() string

	// RunContext returns the *fwcontext.RunContext used to create this run.
	RunContext() *fwcontext.RunContext

	// BeforeRun is executed to set up the run but not actually execute it.
	BeforeRun() error

	// Run is the actual running of the job. Errors from contexts are handled as
	// cancellations. The status (pass/fail) is returned as the primary value.
	Run() (bool, error)

	// AfterRun is executed after the run has completed.
	AfterRun() error
}

Run is the lifecycle of a single run.

type Runner

type Runner interface {

	// Init is the entrypoint of the runner application and will be run shortly
	// after command line arguments are processed.
	Init(*fwcontext.Context) error

	// MakeRun allows the user to customize the run before returning it. See the
	// `Run` interface.
	MakeRun(string, *fwcontext.RunContext) (Run, error)

	// AfterRun executes after the run has been completed.
	AfterRun(string, *fwcontext.RunContext)

	// Ready just indicates when the runner is ready for another queue item
	Ready() bool

	//
	// Data calls
	//
	// QueueName is the name of the queue to pull runs off of.
	QueueName() string
	// Hostname is the name of the host; a tag to uniquely identify it.
	Hostname() string

	//
	// Client acquisition
	//
	// QueueClient is a client to the queuesvc.
	QueueClient() *queue.Client
	// LogsvcClient is a client to the logsvc.
	LogsvcClient(*fwcontext.RunContext) *log.SubLogger
}

Runner is the interface that a runner must implement to leverage this framework.