apicaller

Documentation

Index

• Variables
• func Manifold(config ManifoldConfig) dependency.Manifold
• func NewExternalControllerConnection(ctx context.Context, apiInfo *api.Info) (api.Connection, error)
• func OnlyConnect(ctx context.Context, a agent.Agent, apiOpen api.OpenFunc, logger logger.Logger) (api.Connection, error)
• func ScaryConnect(ctx context.Context, a agent.Agent, apiOpen api.OpenFunc, logger logger.Logger) (_ api.Connection, err error)
• type ConnectFunc
• type ManifoldConfig
• type NewExternalControllerConnectionFunc

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 Manifold

func Manifold(config ManifoldConfig) dependency.Manifold

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

func NewExternalControllerConnection

func NewExternalControllerConnection(ctx context.Context, apiInfo *api.Info) (api.Connection, error)

NewExternalControllerConnection returns an api connection to a controller with the specified api info.

func OnlyConnect

func OnlyConnect(ctx context.Context, a agent.Agent, apiOpen api.OpenFunc, logger logger.Logger) (api.Connection, error)

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

func ScaryConnect

func ScaryConnect(ctx context.Context, a agent.Agent, apiOpen api.OpenFunc, logger logger.Logger) (_ 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;
• 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(context.Context, agent.Agent, api.OpenFunc, logger.Logger) (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

	// Logger is used to write logging statements for the worker.
	Logger logger.Logger
}

ManifoldConfig defines a Manifold's dependencies.

type NewExternalControllerConnectionFunc

type NewExternalControllerConnectionFunc func(context.Context, *api.Info) (api.Connection, error)

NewExternalControllerConnectionFunc returns a function returning an api connection to a controller with the specified api info.