api

Documentation

Index

• Constants
• Variables
• func AuthHTTPRequest(req *http.Request, info *Info) error
• func ControllerAPIURL(addr string, port int) string
• func CookieURLFromHost(host string) *url.URL
• func CreateCertPool(caCert string) (*x509.CertPool, error)
• func NewFakeStreamReader(r io.Reader) base.Stream
• func NewTLSConfig(certPool *x509.CertPool) *tls.Config
• func PerferredHost(info *Info) string
• func SetServerAddressForTesting(c Connection, scheme, addr string)
• func SupportedFacadeVersions() facades.FacadeVersions
• func WebsocketDialWithErrors(dialer WebsocketDialer, urlStr string, requestHeader http.Header) (base.Stream, error)
• type AllWatch
• type AllWatcher
  • func NewAllModelWatcher(caller base.APICaller, id *string) *AllWatcher
  • func NewAllWatcher(caller base.APICaller, id *string) *AllWatcher
  • func (watcher *AllWatcher) Next() ([]params.Delta, error)
  • func (watcher *AllWatcher) Stop() error
• type Connection
  • func EmptyConnectionForTesting() Connection
  • func Open(info *Info, opts DialOpts) (Connection, error)
• type DNSCache
• type DeadlineStream
  • func (s *DeadlineStream) WriteJSON(v interface{}) error
• type DialOption
  • func WithDialOpts(newOpts DialOpts) DialOption
• type DialOpts
  • func DefaultDialOpts() DialOpts
• type IPAddrResolver
• type Info
  • func (info *Info) Ports() []int
  • func (info *Info) Validate() error
• type OpenFunc
• type RedirectError
  • func (e *RedirectError) Error() string
• type UrlCatcher
  • func (u *UrlCatcher) Headers() http.Header
  • func (u *UrlCatcher) Location() string
  • func (u *UrlCatcher) RecordLocation(d WebsocketDialer, urlStr string, header http.Header) (base.Stream, error)
• type WebsocketDialer

Constants

const AnonymousUsername = "jujuanonymous"

AnonymousUsername is the special username to use for anonymous logins.

const PingPeriod = 1 * time.Minute

PingPeriod defines how often the internal connection health check will run.

Variables

var WebsocketDial = WebsocketDialWithErrors

WebsocketDial is called instead of dialer.Dial so we can override it in tests.

Functions

func AuthHTTPRequest

func AuthHTTPRequest(req *http.Request, info *Info) error

AuthHTTPRequest adds Juju auth info (username, password, nonce, macaroons) to the given HTTP request, suitable for sending to a Juju API server.

func ControllerAPIURL

func ControllerAPIURL(addr string, port int) string

ControllerAPIURL returns the URL to use to connect to the controller API.

func CookieURLFromHost

func CookieURLFromHost(host string) *url.URL

CookieURLFromHost creates a url.URL from a given host.

func CreateCertPool

func CreateCertPool(caCert string) (*x509.CertPool, error)

CreateCertPool creates a new x509.CertPool and adds in the caCert passed in. All certs from the cert directory (/etc/juju/cert.d on ubuntu) are also added.

func NewFakeStreamReader

func NewFakeStreamReader(r io.Reader) base.Stream

func NewTLSConfig

func NewTLSConfig(certPool *x509.CertPool) *tls.Config

NewTLSConfig returns a new *tls.Config suitable for connecting to a Juju API server. If certPool is non-nil, we use it as the config's RootCAs, and the server name is set to "juju-apiserver".

func PerferredHost

func PerferredHost(info *Info) string

PerferredHost returns the SNI hostname or controller name for the cookie URL so that it is stable when used with a HA controller cluster.

func SetServerAddressForTesting

func SetServerAddressForTesting(c Connection, scheme, addr string)

SetServerAddressForTesting allows changing the URL to the internal API server that AddLocalCharm uses in order to test NotImplementedError. Hopefully it will soon be gone forever.

func SupportedFacadeVersions

func SupportedFacadeVersions() facades.FacadeVersions

SupportedFacadeVersions returns the list of facades that the api supports.

func WebsocketDialWithErrors

func WebsocketDialWithErrors(dialer WebsocketDialer, urlStr string, requestHeader http.Header) (base.Stream, error)

WebsocketDialWithErrors dials the websocket and extracts any error from the response if there's a handshake error setting up the socket. Any other errors are returned normally.

Types

type AllWatch

type AllWatch interface {
	Next() ([]params.Delta, error)
	Stop() error
}

AllWatch represents methods used on the AllWatcher Primarily to facilitate mock tests.

type AllWatcher

type AllWatcher struct {
	// contains filtered or unexported fields
}

AllWatcher holds information allowing us to get Deltas describing changes to the entire model or all models (depending on the watcher type).

func NewAllModelWatcher

func NewAllModelWatcher(caller base.APICaller, id *string) *AllWatcher

NewAllModelWatcher returns an AllWatcher instance which interacts with a watcher created by the WatchAllModels API call.

There should be no need to call this from outside of the api package. It is only used by Client.WatchAllModels in api/controller.

func NewAllWatcher

func NewAllWatcher(caller base.APICaller, id *string) *AllWatcher

NewAllWatcher returns an AllWatcher instance which interacts with a watcher created by the WatchAll API call.

There should be no need to call this from outside of the api package. It is only used by Client.WatchAll in this package.

func (*AllWatcher) Next

func (watcher *AllWatcher) Next() ([]params.Delta, error)

Next returns a new set of deltas from a watcher previously created by the WatchAll or WatchAllModels API calls. It will block until there are deltas to return.

func (*AllWatcher) Stop

func (watcher *AllWatcher) Stop() error

Stop shutdowns down a watcher previously created by the WatchAll or WatchAllModels API calls

type Connection

type Connection interface {

	// Close closes the connection.
	Close() error

	// Addr returns the address used to connect to the API server.
	Addr() string

	// IPAddr returns the IP address used to connect to the API server.
	IPAddr() string

	// APIHostPorts returns addresses that may be used to connect
	// to the API server, including the address used to connect.
	//
	// The addresses are scoped (public, cloud-internal, etc.), so
	// the client may choose which addresses to attempt. For the
	// Juju CLI, all addresses must be attempted, as the CLI may
	// be invoked both within and outside the model (think
	// private clouds).
	APIHostPorts() []network.MachineHostPorts

	// Broken returns a channel which will be closed if the connection
	// is detected to be broken, either because the underlying
	// connection has closed or because API pings have failed.
	Broken() <-chan struct{}

	// IsBroken returns whether the connection is broken. It checks
	// the Broken channel and if that is open, attempts a connection
	// ping.
	IsBroken() bool

	// IsProxied returns weather the connection is proxied.
	IsProxied() bool

	// Proxy returns the Proxier used to establish the connection if one was
	// used at all. If no Proxier was used then it's expected that returned
	// Proxier will be nil. Use IsProxied() to test for the presence of a proxy.
	Proxy() proxy.Proxier

	// PublicDNSName returns the host name for which an officially
	// signed certificate will be used for TLS connection to the server.
	// If empty, the private Juju CA certificate must be used to verify
	// the connection.
	PublicDNSName() string

	// These are a bit off -- ServerVersion is apparently not known until after
	// Login()? Maybe evidence of need for a separate AuthenticatedConnection..?
	Login(name names.Tag, password, nonce string, ms []macaroon.Slice) error
	ServerVersion() (version.Number, bool)

	// APICaller provides the facility to make API calls directly.
	// This should not be used outside the api/* packages or tests.
	base.APICaller

	// ControllerTag returns the tag of the controller.
	// This could be defined on base.APICaller.
	ControllerTag() names.ControllerTag

	// AuthTag returns the tag of the authorized user of the state API
	// connection.
	AuthTag() names.Tag

	// ControllerAccess returns the access level of authorized user to the controller.
	ControllerAccess() string

	// CookieURL returns the URL that HTTP cookies for the API will be
	// associated with.
	CookieURL() *url.URL
}

Connection represents a connection to a Juju API server.

func EmptyConnectionForTesting

func EmptyConnectionForTesting() Connection

EmptyConnectionForTesting exists only to allow api/client/client.BarebonesClient() to be implemented. Hopefully it will soon be gone forever.

func Open

func Open(info *Info, opts DialOpts) (Connection, error)

Open establishes a connection to the API server using the Info given, returning a State instance which can be used to make API requests.

If the model is hosted on a different server, Open will return an error with a *RedirectError cause holding the details of another server to connect to.

See Connect for details of the connection mechanics.

type DNSCache

type DNSCache interface {
	// Lookup returns the IP addresses associated
	// with the given host.
	Lookup(host string) []string
	// Add sets the IP addresses associated with
	// the given host name.
	Add(host string, ips []string)
}

DNSCache implements a cache of DNS lookup results.

type DeadlineStream

type DeadlineStream struct {
	*websocket.Conn

	Timeout time.Duration
}

DeadlineStream wraps a websocket connection and applies a write deadline to each WriteJSON call.

func (*DeadlineStream) WriteJSON

func (s *DeadlineStream) WriteJSON(v interface{}) error

WriteJSON is part of base.Stream.

type DialOption

type DialOption func(*DialOpts)

DialOption is the type of functions that mutate DialOpts

func WithDialOpts

func WithDialOpts(newOpts DialOpts) DialOption

WithDialOpts sets the DialOpts to the one specified

type DialOpts

type DialOpts struct {
	// DialAddressInterval is the amount of time to wait
	// before starting to dial another address.
	DialAddressInterval time.Duration

	// DialTimeout is the amount of time to wait for the dial
	// portion only of the api.Open to succeed. If this is zero,
	// there is no dial timeout.
	DialTimeout time.Duration

	// Timeout is the amount of time to wait for the entire
	// api.Open to succeed (including dial and login). If this is
	// zero, there is no timeout.
	Timeout time.Duration

	// RetryDelay is the amount of time to wait between
	// unsuccessful connection attempts. If this is
	// zero, only one attempt will be made.
	RetryDelay time.Duration

	// BakeryClient is the httpbakery Client, which
	// is used to do the macaroon-based authorization.
	// This and the *http.Client inside it are copied
	// by Open, and any RoundTripper field
	// the HTTP client is ignored.
	BakeryClient *httpbakery.Client

	// InsecureSkipVerify skips TLS certificate verification
	// when connecting to the controller. This should only
	// be used in tests, or when verification cannot be
	// performed and the communication need not be secure.
	InsecureSkipVerify bool

	// DialWebsocket is used to make connections to API servers.
	// It will be called with a websocket URL to connect to,
	// and the TLS configuration to use to secure the connection.
	// If ipAddr is non-empty, the actual net.Dial should use
	// that IP address, regardless of the URL host.
	//
	// If DialWebsocket is nil, a default implementation using
	// gorilla websockets will be used.
	DialWebsocket func(ctx context.Context, urlStr string, tlsConfig *tls.Config, ipAddr string) (jsoncodec.JSONConn, error)

	// IPAddrResolver is used to resolve host names to IP addresses.
	// If it is nil, net.DefaultResolver will be used.
	IPAddrResolver IPAddrResolver

	// DNSCache is consulted to find and store cached DNS lookups.
	// If it is nil, no cache will be used or updated.
	DNSCache DNSCache

	// Clock is used as a time source for retries.
	// If it is nil, clock.WallClock will be used.
	Clock clock.Clock

	// VerifyCA is an optional callback that is invoked by the dialer when
	// the remote server presents a CA certificate that cannot be
	// automatically verified. If the callback returns a non-nil error then
	// the connection attempt will be aborted.
	VerifyCA func(host, endpoint string, caCert *x509.Certificate) error
}

DialOpts holds configuration parameters that control the Dialing behavior when connecting to a controller.

func DefaultDialOpts

func DefaultDialOpts() DialOpts

DefaultDialOpts returns a DialOpts representing the default parameters for contacting a controller.

type IPAddrResolver

type IPAddrResolver interface {
	LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)
}

IPAddrResolver implements a resolved from host name to the set of IP addresses associated with it. It is notably implemented by net.Resolver.

type Info

type Info struct {

	// Addrs holds the addresses of the controllers.
	Addrs []string

	// ControllerUUID is the UUID of the controller.
	ControllerUUID string

	// SNIHostName optionally holds the host name to use for
	// server name indication (SNI) when connecting
	// to the addresses in Addrs above. If CACert is non-empty,
	// this field is ignored.
	SNIHostName string

	// CACert holds the CA certificate that will be used
	// to validate the controller's certificate, in PEM format.
	// If this is empty, the standard system root certificates
	// will be used.
	CACert string

	// ModelTag holds the model tag for the model we are
	// trying to connect to. If this is empty, a controller-only
	// login will be made.
	ModelTag names.ModelTag

	// SkipLogin, if true, skips the Login call on connection. It is an
	// error to set Tag, Password, or Macaroons if SkipLogin is true.
	SkipLogin bool `yaml:"-"`

	// Tag holds the name of the entity that is connecting.
	// If this is nil, and the password is empty, macaroon authentication
	// will be used to log in unless SkipLogin is true.
	Tag names.Tag

	// Password holds the password for the administrator or connecting entity.
	Password string

	// Macaroons holds a slice of macaroon.Slice that may be used to
	// authenticate with the API server.
	Macaroons []macaroon.Slice `yaml:",omitempty"`

	// Nonce holds the nonce used when provisioning the machine. Used
	// only by the machine agent.
	Nonce string `yaml:",omitempty"`

	// Proxier describes a proxier to use to for establing an API connection
	// A nil proxier means that it will not be used.
	Proxier proxy.Proxier
}

Info encapsulates information about a server holding juju state and can be used to make a connection to it.

func (*Info) Ports

func (info *Info) Ports() []int

Ports returns the unique ports for the api addresses.

func (*Info) Validate

func (info *Info) Validate() error

Validate validates the API info.

type OpenFunc

type OpenFunc func(*Info, DialOpts) (Connection, error)

OpenFunc is the usual form of a function that opens an API connection.

type RedirectError

type RedirectError struct {
	// Servers holds the sets of addresses of the redirected
	// servers.
	Servers []network.MachineHostPorts

	// CACert holds the certificate of the remote server.
	CACert string

	// FollowRedirect is set to true for cases like JAAS where the client
	// needs to automatically follow the redirect to the new controller.
	FollowRedirect bool

	// ControllerTag uniquely identifies the controller being redirected to.
	ControllerTag names.ControllerTag

	// An optional alias for the controller the model got redirected to.
	// It can be used by the client to present the user with a more
	// meaningful juju login -c XYZ command
	ControllerAlias string
}

RedirectError is returned from Open when the controller needs to inform the client that the model is hosted on a different set of API addresses.

func (*RedirectError) Error

func (e *RedirectError) Error() string

type UrlCatcher

type UrlCatcher struct {
	// contains filtered or unexported fields
}

func (*UrlCatcher) Headers

func (u *UrlCatcher) Headers() http.Header

func (*UrlCatcher) Location

func (u *UrlCatcher) Location() string

func (*UrlCatcher) RecordLocation

func (u *UrlCatcher) RecordLocation(d WebsocketDialer, urlStr string, header http.Header) (base.Stream, error)

type WebsocketDialer

type WebsocketDialer interface {
	Dial(string, http.Header) (*websocket.Conn, *http.Response, error)
}

WebsocketDialer is something that can make a websocket connection. Enables testing the error unpacking in websocketDialWithErrors.