client

package
v0.0.23 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 24, 2022 License: MPL-2.0 Imports: 22 Imported by: 2

Documentation

Index

Constants

View Source 
const (
	// EnvOverrideHost is the name of the environment variable that can be used
	// to override the default host to connect to (DefaultEnvdServerHost).
	//
	// This env-var is read by FromEnv and WithHostFromEnv and when set to a
	// non-empty value, takes precedence over the default host (which is platform
	// specific), or any host already set.
	EnvOverrideHost = "ENVD_SERVER_HOST"

	// EnvOverrideCertPath is the name of the environment variable that can be
	// used to specify the directory from which to load the TLS certificates
	// (ca.pem, cert.pem, key.pem) from. These certificates are used to configure
	// the Client for a TCP connection protected by TLS client authentication.
	//
	// TLS certificate verification is enabled by default if the Client is configured
	// to use a TLS connection. Refer to EnvTLSVerify below to learn how to
	// disable verification for testing purposes.
	//
	//
	// For local access to the API, it is recommended to connect with the daemon
	// using the default local socket connection (on Linux), or the named pipe
	// (on Windows).
	//
	// If you need to access the API of a remote daemon, consider using an SSH
	// (ssh://) connection, which is easier to set up, and requires no additional
	// configuration if the host is accessible using ssh.
	EnvOverrideCertPath = "ENVD_SERVER_CERT_PATH"

	// EnvTLSVerify is the name of the environment variable that can be used to
	// enable or disable TLS certificate verification. When set to a non-empty
	// value, TLS certificate verification is enabled, and the client is configured
	// to use a TLS connection, using certificates from the default directories
	// (within `~/.envd`); refer to EnvOverrideCertPath above for additional
	// details.
	//
	//
	// Before setting up your client and daemon to use a TCP connection with TLS
	// client authentication, consider using one of the alternatives mentioned
	// in EnvOverrideCertPath above.
	//
	// Disabling TLS certificate verification (for testing purposes)
	//
	// TLS certificate verification is enabled by default if the Client is configured
	// to use a TLS connection, and it is highly recommended to keep verification
	// enabled to prevent machine-in-the-middle attacks.
	//
	// Set the "ENVD_SERVER_TLS_VERIFY" environment to an empty string ("") to
	// disable TLS certificate verification. Disabling verification is insecure,
	// so should only be done for testing purposes. From the Go documentation
	// (https://pkg.go.dev/crypto/tls#Config):
	//
	// InsecureSkipVerify controls whether a client verifies the server's
	// certificate chain and host name. If InsecureSkipVerify is true, crypto/tls
	// accepts any certificate presented by the server and any host name in that
	// certificate. In this mode, TLS is susceptible to machine-in-the-middle
	// attacks unless custom verification is used. This should be used only for
	// testing or in combination with VerifyConnection or VerifyPeerCertificate.
	EnvTLSVerify = "ENVD_SERVER_TLS_VERIFY"
)
View Source 
const DefaultEnvdServerHost = "http://0.0.0.0:8080"

Variables

View Source 
var (
	ErrNoUser = errors.New("no user provided")
)
View Source 
var ErrRedirect = errors.New("unexpected redirect in response")

ErrRedirect is the error returned by checkRedirect when the request is non-GET.

Functions

func CheckRedirect 

func CheckRedirect(req *http.Request, via []*http.Request) error

CheckRedirect specifies the policy for dealing with redirect responses: If the request is non-GET return ErrRedirect, otherwise use the last response.

Go 1.8 changes behavior for HTTP redirects (specifically 301, 307, and 308) in the client. The envd client (and by extension envd API client) can be made to send a request like POST /containers//start where what would normally be in the name section of the URL is empty. This triggers an HTTP 301 from the daemon.

In go 1.8 this 301 will be converted to a GET request, and ends up getting a 404 from the daemon. This behavior change manifests in the client in that before, the 301 was not followed and the client did not generate an error, but now results in a message like Error response from daemon: page not found.

func ErrorConnectionFailed 

func ErrorConnectionFailed(host string) error

ErrorConnectionFailed returns an error with host in the error message when connection to docker daemon failed.

func FromEnv 

func FromEnv(c *Client) error

FromEnv configures the client with values from environment variables.

FromEnv uses the following environment variables:

ENVD_SERVER_HOST (EnvOverrideHost) to set the URL to the docker server.

ENVD_SERVER_CERT_PATH (EnvOverrideCertPath) to specify the directory from which to load the TLS certificates (ca.pem, cert.pem, key.pem).

ENVD_SERVER_TLS_VERIFY (EnvTLSVerify) to enable or disable TLS verification (off by default).

func IsErrConnectionFailed 

func IsErrConnectionFailed(err error) bool

IsErrConnectionFailed returns true if the error is caused by connection failed.

func IsErrNotFound 

func IsErrNotFound(err error) bool

IsErrNotFound returns true if the error is a NotFound error, which is returned by the API when some object is not found.

func IsErrNotImplemented deprecated 

func IsErrNotImplemented(err error) bool

IsErrNotImplemented returns true if the error is a NotImplemented error. This is returned by the API when a requested feature has not been implemented.

Deprecated: use errdefs.IsNotImplemented

func IsErrUnauthorized deprecated 

func IsErrUnauthorized(err error) bool

IsErrUnauthorized returns true if the error is caused when a remote registry authentication fails

Deprecated: use errdefs.IsUnauthorized

func ParseHostURL 

func ParseHostURL(host string) (*url.URL, error)

ParseHostURL parses a url string, validates the string is a host url, and returns the parsed URL

Types

type Client 

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

Client is the API client that performs all operations against a docker server.

func NewClientWithOpts 

func NewClientWithOpts(ops ...Opt) (*Client, error)

NewClientWithOpts initializes a new API client with a default HTTPClient, and default API host and version. It also initializes the custom HTTP headers to add to each request.

It takes an optional list of Opt functional arguments, which are applied in the order they're provided, which allows modifying the defaults when creating the client. For example, the following initializes a client that configures itself with values from environment variables (client.FromEnv), and has automatic API version negotiation enabled (client.WithAPIVersionNegotiation()). 

cli, err := client.NewClientWithOpts(
	client.FromEnv,
	client.WithAPIVersionNegotiation(),
)

func (*Client) Close 

func (cli *Client) Close() error

Close the transport used by the client

func (*Client) DaemonHost 

func (cli *Client) DaemonHost() string

DaemonHost returns the host address used by the client

func (*Client) EnvironmentCreate 

func (cli *Client) EnvironmentCreate(ctx context.Context,
	req types.EnvironmentCreateRequest) (types.EnvironmentCreateResponse, error)

EnvironmentCreate creates the environment.

func (*Client) EnvironmentGet added in v0.0.5 

func (cli *Client) EnvironmentGet(ctx context.Context, name string) (types.EnvironmentGetResponse, error)

EnvironmentGet gets the environment.

func (*Client) EnvironmentList added in v0.0.3 

func (cli *Client) EnvironmentList(ctx context.Context) (types.EnvironmentListResponse, error)

EnvironmentList lists the environment.

func (*Client) EnvironmentRemove added in v0.0.4 

func (cli *Client) EnvironmentRemove(ctx context.Context,
	name string) error

EnvironmentList lists the environment.

func (*Client) HTTPClient 

func (cli *Client) HTTPClient() *http.Client

HTTPClient returns a copy of the HTTP client bound to the server

func (*Client) ImageGetByName added in v0.0.18 

func (cli *Client) ImageGetByName(
	ctx context.Context, name string) (types.ImageGetResponse, error)

ImageGetByName gets the image info.

func (*Client) ImageList added in v0.0.7 

func (cli *Client) ImageList(ctx context.Context) (types.ImageListResponse, error)

ImageList lists the images.

func (*Client) KeyCreate added in v0.0.19 

func (cli *Client) KeyCreate(ctx context.Context,
	req types.KeyCreateRequest) (types.KeyCreateResponse, error)

KeyCreate creates the ssh public key.

func (*Client) Login added in v0.0.13 

func (cli *Client) Login(ctx context.Context, auth types.AuthNRequest) (types.AuthNResponse, error)

Login logins the envd server. It returns unauthorizedError when the authentication fails.

func (*Client) Register added in v0.0.13 

func (cli *Client) Register(ctx context.Context, auth types.AuthNRequest) (types.AuthNResponse, error)

Register authenticates the envd server. It returns unauthorizedError when the authentication fails.

type Opt 

type Opt func(*Client) error

Opt is a configuration option to initialize a client

func WithDialContext 

func WithDialContext(dialContext func(ctx context.Context, network, addr string) (net.Conn, error)) Opt

WithDialContext applies the dialer to the client transport. This can be used to set the Timeout and KeepAlive settings of the client.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Opt

WithHTTPClient overrides the client http client with the specified one

func WithHTTPHeaders 

func WithHTTPHeaders(headers map[string]string) Opt

WithHTTPHeaders overrides the client default http headers

func WithHost 

func WithHost(host string) Opt

WithHost overrides the client host with the specified one.

func WithHostFromEnv 

func WithHostFromEnv() Opt

WithHostFromEnv overrides the client host with the host specified in the DOCKER_HOST (EnvOverrideHost) environment variable. If DOCKER_HOST is not set, or set to an empty value, the host is not modified.

func WithJWTToken added in v0.0.13 

func WithJWTToken(user, token string) Opt

WithJWTToken applies a jwt token and the user to the client transport. Cannot be used with `WithUserNoAuth`

func WithScheme 

func WithScheme(scheme string) Opt

WithScheme overrides the client scheme with the specified one

func WithTLSClientConfig 

func WithTLSClientConfig(cacertPath, certPath, keyPath string) Opt

WithTLSClientConfig applies a tls config to the client transport.

func WithTLSClientConfigFromEnv 

func WithTLSClientConfigFromEnv() Opt

WithTLSClientConfigFromEnv configures the client's TLS settings with the settings in the DOCKER_CERT_PATH and DOCKER_TLS_VERIFY environment variables. If DOCKER_CERT_PATH is not set or empty, TLS configuration is not modified.

WithTLSClientConfigFromEnv uses the following environment variables:

DOCKER_CERT_PATH (EnvOverrideCertPath) to specify the directory from which to load the TLS certificates (ca.pem, cert.pem, key.pem).

DOCKER_TLS_VERIFY (EnvTLSVerify) to enable or disable TLS verification (off by default).

func WithTimeout 

func WithTimeout(timeout time.Duration) Opt

WithTimeout configures the time limit for requests made by the HTTP client

func WithVersion 

func WithVersion(version string) Opt

WithVersion overrides the client version with the specified one. If an empty version is specified, the value will be ignored to allow version negotiation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.