apicaller

Documentation

Index

• Variables
• func APIOpen(info *api.Info, opts api.DialOpts) (api.Connection, error)
• func Manifold(config ManifoldConfig) dependency.Manifold
• func OnlyConnect(a agent.Agent, apiOpen api.OpenFunc) (api.Connection, error)
• func ScaryConnect(a agent.Agent, apiOpen api.OpenFunc) (_ api.Connection, err error)
• type ConnectFunc
• type ManifoldConfig

Variables

var (

	// ErrConnectImpossible indicates that we can contact an apiserver
	// but have no hope of authenticating a connection with it.
	ErrConnectImpossible = errors.New("connection permanently impossible")

	// ErrChangedPassword indicates that the agent config used to connect
	// has been updated with a new password, and you should try again.
	ErrChangedPassword = errors.New("insecure password replaced; retry")
)

Functions

func APIOpen

func APIOpen(info *api.Info, opts api.DialOpts) (api.Connection, error)

APIOpen is an api.OpenFunc that wraps api.Open, and handles the edge case where a model has jumping several versions and doesn't yet have the model UUID cached in the agent config; in which case we fall back to login version 1.

You probably want to use this in ManifoldConfig; *we* probably want to put this particular hack inside api.Open, but I seem to recall there being some complication last time I thought that was a good idea.

func Manifold

func Manifold(config ManifoldConfig) dependency.Manifold

Manifold returns a manifold whose worker wraps an API connection made as configured.

func OnlyConnect

func OnlyConnect(a agent.Agent, apiOpen api.OpenFunc) (api.Connection, error)

OnlyConnect logs into the API using the supplied agent's credentials.

func ScaryConnect

func ScaryConnect(a agent.Agent, apiOpen api.OpenFunc) (_ api.Connection, err error)

ScaryConnect logs into the API using the supplied agent's credentials, like OnlyConnect; and then:

• returns ErrConnectImpossible if the agent entity is dead or unauthorized for all known passwords;
• if the agent's config does not specify a model, tries to record the model we just connected to;
• replaces insecure credentials with freshly (locally) generated ones (and returns ErrPasswordChanged, expecting to be reinvoked);
• unconditionally resets the remote-state password to its current value (for what seems like a bad reason).

This is clearly a mess but at least now it's a documented and localized mess; it should be used only when making the primary API connection for a machine or unit agent running in its own process.

Types

type ConnectFunc

type ConnectFunc func(agent.Agent, api.OpenFunc) (api.Connection, error)

ConnectFunc is responsible for making and validating an API connection on behalf of an agent.

type ManifoldConfig

type ManifoldConfig struct {

	// AgentName is the name of the Agent resource that supplies
	// connection information.
	AgentName string

	// APIConfigWatcherName identifies a resource that will be
	// invalidated when api configuration changes. It's not really
	// fundamental, because it's not used directly, except to create
	// Inputs; it would be perfectly reasonable to wrap a Manifold
	// to report an extra Input instead.
	APIConfigWatcherName string

	// APIOpen is passed into NewConnection, and should be used to
	// create an API connection. You should probably just set it to
	// the local APIOpen func.
	APIOpen api.OpenFunc

	// NewConnection is responsible for getting a connection from an
	// agent, and may be responsible for other things that need to be
	// done before anyone else gets to see the connection.
	//
	// You should probably set it to ScaryConnect when running a
	// machine agent, and to OnlyConnect when running a model agent
	// (which doesn't have its own process). Unit agents should use
	// ScaryConnect at the moment; and probably switch to OnlyConnect
	// when they move into machine agent processes.
	NewConnection ConnectFunc

	// Filter is used to specialize responses to connection errors
	// made on behalf of different kinds of agent.
	Filter dependency.FilterFunc
}

ManifoldConfig defines a Manifold's dependencies.