app

Documentation

Overview

Package app provides an opinionated common infrastructure to application structure.

Index

• Variables
• func AddCleanup(ctx context.Context, f func())
• func AddCleanupSignal(s ...task.Event)
• func AddInterruptHandler(f func()) func()
• func Run(main task.Task)
• func Usage(ctx context.Context, message string, args ...interface{})
• func VerbMain(ctx context.Context) error
• func WaitForCleanup(ctx context.Context) bool
• type Action
• type AppFlags
• type Cleanup
  • func (c Cleanup) Invoke(ctx context.Context) Cleanup
  • func (c Cleanup) Then(next Cleanup) Cleanup
• type ExitCode
• type LogFlags
• type ProfileFlags
• type Verb
  • func AddVerb(v *Verb) *Verb
  • func FilterVerbs(prefix string) (result []*Verb)
  • func (v *Verb) Add(child *Verb)
  • func (v *Verb) Filter(prefix string) (result []*Verb)
  • func (v *Verb) Invoke(ctx context.Context, args []string) error
• type VersionSpec
  • func (v VersionSpec) Format(f fmt.State, c rune)
  • func (v VersionSpec) GreaterThan(o VersionSpec) bool
  • func (v VersionSpec) IsValid() bool
  • func (v VersionSpec) String() string

Variables

var (
	// Name is the full name of the application
	Name string
	// Flags is the main application flags.
	Flags AppFlags
	// ExitFuncForTesting can be set to change the behaviour when there is a command line parsing failure.
	// It defaults to os.Exit
	ExitFuncForTesting = os.Exit
	// ShortHelp should be set to add a help message to the usage text.
	ShortHelp = ""
	// ShortUsage is usage text for the additional non-flag arguments.
	ShortUsage = ""
	// UsageFooter is printed at the bottom of the usage text
	UsageFooter = ""
	// Version holds the version specification for the application.
	// The default version is the one defined in version.cmake.
	// If valid a command line option to report it will be added automatically.
	Version VersionSpec
	// Restart is the error to return to cause the app to restart itself.
	Restart = fault.Const("Restart")
)

var (
	// CleanupTimeout is the time to wait for all cleanup signals to fire when shutting down.
	CleanupTimeout = time.Second * 10
)

var LogHandler log.Indirect

LogHandler is the primary application logger target. It is assigned to the main context on startup and is closed on shutdown.

Functions

func AddCleanup

func AddCleanup(ctx context.Context, f func())

AddCleanup calls f when the context is cancelled. Application will wait (for a maximum of CleanupTimeout) for f to complete before terminiating the application.

func AddCleanupSignal

func AddCleanupSignal(s ...task.Event)

AddCleanupSignal adds a signal the app should wait on when shutting down. The signal will automatically be dropped when it is fired, no need unregister it.

func AddInterruptHandler

func AddInterruptHandler(f func()) func()

AddInterruptHandler adds a function that will be called on the next interrupt. It returns a function that can be called to remove the value from the list

func Run

func Run(main task.Task)

Run performs all the work needed to start up an application. It parsers the main command line arguments, builds a primary context that will be cancelled on exit runs the provided task, cancels the primary context and then waits for either the maximum shutdown delay or all registered signals whichever comes first.

func Usage

func Usage(ctx context.Context, message string, args ...interface{})

Usage prints message with the formatting args to stderr, and then prints the command usage information and terminates the program.

func VerbMain

func VerbMain(ctx context.Context) error

VerbMain is a task that can be handed to Run to invoke the verb handling system.

func WaitForCleanup

func WaitForCleanup(ctx context.Context) bool

WaitForCleanup waits for all the cleanup signals to fire, or the cleanup timeout to expire, whichever comes first.

Types

type Action

type Action interface {
	// Run executes the action.
	Run(ctx context.Context, flags flag.FlagSet) error
}

Action is the interface for verb actions that can be run. Exported fields will be exposed as flags for the verb. Use the `help` tag to expose a flag description.

type AppFlags

type AppFlags struct {
	Version     bool `help:"_Display the application version"`
	Log         LogFlags
	Profile     ProfileFlags
	Analytics   string `help:"_If non-empty enable analytics using the specified user-id"`
	CrashReport bool   `help:"_Automatically send crash reports to Google"`
	DecodeStack string `help:"_Decode a stackdump generated by this executable"`
	FullHelp    bool   `help:"_Display the full help"`
	Args        string `help:"_A single string that will be parsed into extra individual arguments"`
}

type Cleanup

type Cleanup func(ctx context.Context)

Cleanup is a function that is invoked at a later time to perform the cleanup.

func (Cleanup) Invoke

func (c Cleanup) Invoke(ctx context.Context) Cleanup

Invoke invokes the possibly nil cleanup safely. Returns a nil Cleanup, so this can be chained when invoking the cleanup as part of the error handling.

func (Cleanup) Then

func (c Cleanup) Then(next Cleanup) Cleanup

Then combines two clean up functions into a single cleanup function.

type ExitCode

type ExitCode int

ExitCode is the type for named return values from the application main entry point.

const (
	// SuccessExit is the exit code for succesful exit.
	SuccessExit ExitCode = iota
	// FatalExit is the exit code if something logs at a fatal severity (critical or higher by default)
	FatalExit
	// UsageExit is the exit code if the usage function was invoked
	UsageExit
)

type LogFlags

type LogFlags struct {
	Level  log.Severity `help:"_The severity to enable logs at"`
	Style  log.Style    `help:"_The style to use when printing the log"`
	Stacks bool         `help:"_If true, stack traces are logged for all errors"`
	File   string       `help:"_The file to store the logs in"`
	Status bool         `help:"_Log status updates as they happen"`
}

type ProfileFlags

type ProfileFlags struct {
	CPU   string `help:"_write cpu profile to file"`
	Mem   string `help:"_write mem profile to file"`
	Trace string `help:"_write a trace to file"`
}

type Verb

type Verb struct {
	Name       string // The name of the command
	ShortHelp  string // Help for the purpose of the command
	ShortUsage string // Help for how to use the command
	Action     Action // The verb's action. Must be set.
	// contains filtered or unexported fields
}

Verb holds information about a runnable api command.

func AddVerb

func AddVerb(v *Verb) *Verb

AddVerb adds a new verb to the supported set, it will panic if a duplicate name is encountered. v is returned so the function can be used in a fluent-style.

func FilterVerbs

func FilterVerbs(prefix string) (result []*Verb)

FilterVerbs returns the filtered list of verbs who's names match the specified prefix.

func (*Verb) Add

func (v *Verb) Add(child *Verb)

Add adds a new verb to the supported set, it will panic if a duplicate name is encountered.

func (*Verb) Filter

func (v *Verb) Filter(prefix string) (result []*Verb)

Filter returns the filtered list of verbs who's names match the specified prefix.

func (*Verb) Invoke

func (v *Verb) Invoke(ctx context.Context, args []string) error

Invoke runs a verb, handing it the command line arguments it should process.

type VersionSpec

type VersionSpec struct {
	// Major version, the version structure is in valid if <0
	Major int
	// Minor version, not used if <0
	Minor int
	// Point version, not used if <0
	Point int
	// The build identifier, not used if an empty string
	Build string
}

VersionSpec is the structure for the version of an application.

func (VersionSpec) Format

func (v VersionSpec) Format(f fmt.State, c rune)

Format implements fmt.Formatter to print the version.

func (VersionSpec) GreaterThan

func (v VersionSpec) GreaterThan(o VersionSpec) bool

GreaterThan returns true if v is greater than o.

func (VersionSpec) IsValid

func (v VersionSpec) IsValid() bool

IsValid reports true if the VersionSpec is valid, ie it has a Major version.

func (VersionSpec) String

func (v VersionSpec) String() string