base

Documentation

Overview

Package base is shared functionality used by all Swarming CLI subcommands.

Its things like registering command line flags, setting up the context, writing output.

Index

• Constants
• type AuthFlags
• type CommandRun
  • func NewCommandRun(authFlags AuthFlags, impl Subcommand, feats Features) *CommandRun
  • func (cr *CommandRun) Run(app subcommands.Application, args []string, env subcommands.Env) int
  • func (cr *CommandRun) TestingMocks(ctx context.Context, svc swarming.Client, env subcommands.Env, err *error, ...)
• type Extra
• type Features
• type OutputJSON
• type Subcommand

Constants

const Unlimited = -1

Unlimited can be passed as Features.MaxArgs to indicate no limit.

Types

type AuthFlags

type AuthFlags interface {
	// Register registers auth flags to the given flag set.
	Register(f *flag.FlagSet)
	// Parse parses auth flags.
	Parse() error
	// NewHTTPClient creates an authenticating http.Client.
	NewHTTPClient(ctx context.Context) (*http.Client, error)
	// NewRBEClient creates an authenticating RBE Client.
	NewRBEClient(ctx context.Context, addr string, instance string) (*rbeclient.Client, error)
}

AuthFlags is registered in a flag set and creates http.Client and CAS Client.

It encapsulates a way of getting credentials and constructing RPC transports. It is constructed by whoever assembles the final cli.Application.

type CommandRun

type CommandRun struct {
	subcommands.CommandRunBase
	// contains filtered or unexported fields
}

CommandRun implements the command part of subcommand processing.

It is responsible for registering and parsing flags, setting up the root context and calling the subcommand implementation.

func NewCommandRun

func NewCommandRun(authFlags AuthFlags, impl Subcommand, feats Features) *CommandRun

NewCommandRun creates a CommandRun that runs the given subcommand.

func (*CommandRun) Run

func (cr *CommandRun) Run(app subcommands.Application, args []string, env subcommands.Env) int

Run is part of subcommands.CommandRun interface.

func (*CommandRun) TestingMocks

func (cr *CommandRun) TestingMocks(ctx context.Context, svc swarming.Client, env subcommands.Env, err *error, stdout, stderr io.Writer)

TestingMocks is used in tests to mock dependencies.

type Extra

type Extra struct {
	// AuthFlags is parsed auth flags.
	//
	// Can be used to construct any extra authenticated clients (like CAS client).
	AuthFlags AuthFlags

	// ServerURL is parsed and validated URL of the swarming host.
	//
	// It has its path stripped.
	ServerURL *url.URL

	// OutputJSON is path to the file where the results will be stored, if any.
	//
	// It is empty if JSON results aren't being written anywhere. It can be
	// literal `-` if results are written to stdout.
	//
	// No need to manually write anything to it. Instead write to `sink` passed
	// to Execute. This value is exposed to allow to reference it in logs.
	OutputJSON string

	// Standard output stream, perhaps redirected somewhere.
	Stdout io.Writer

	// Standard error stream, perhaps redirected somewhere.
	Stderr io.Writer
}

Extra is passed to an executing subcommand and it contains any additional context the subcommand may need.

type Features

type Features struct {
	// MinArgs is the minimum number of expected positional arguments.
	MinArgs int
	// MaxArgs is the maximum number of expected positional arguments.
	MaxArgs int
	// MeasureDuration indicates to measure and log how long the command took.
	MeasureDuration bool
	// UsesCAS indicates if `-cas-addr` flag should be exposed.
	UsesCAS bool
	// OutputJSON indicates if the command supports emitting JSON output.
	OutputJSON OutputJSON
}

Features customize "standard" behaviors exposed by a subcommand.

If a multiple subcommands use a particular behavior, it is represented by a feature here.

type OutputJSON

type OutputJSON struct {
	// Enabled indicates if JSON output flag (`-json-output`) is enabled.
	Enabled bool
	// DeprecatedAliasFlag is how to name a flag that aliases `-json-output'.
	DeprecatedAliasFlag string
	// Usage is a flag usage string, if the command needs a custom one.
	Usage string
	// DefaultToStdout if true indicate to write to stdout if the flag is unset.
	DefaultToStdout bool
}

OutputJSON describes behavior of the command line flag with JSON file path.

type Subcommand

type Subcommand interface {
	// RegisterFlags registers subcommand flags, if any.
	RegisterFlags(fs *flag.FlagSet)
	// ParseInputs extracts information from flags, CLI args and environ.
	ParseInputs(ctx context.Context, args []string, env subcommands.Env, extra Extra) error
	// Execute executes the subcommand.
	Execute(ctx context.Context, svc swarming.Client, sink *output.Sink, extra Extra) error
}

Subcommand is implemented by individual Swarming subcommands.