client

package
v0.0.0-...-564ba19 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2018 License: Apache-2.0 Imports: 32 Imported by: 0

README

Go client for the Malice Engine API

The malice command uses this package to communicate with the daemon. It can also be used by your own Go applications to do anything the command-line interface does – running scans, installing plugins, managing swarms, etc.

For example, to list installed plugins (the equivalent of malice plugin ls):

package main

import (
	"context"
	"fmt"

	"github.com/maliceio/engine/api/types"
	"github.com/maliceio/engine/client"
)

func main() {
	cli, err := client.NewEnvClient()
	if err != nil {
		panic(err)
	}

	plugins, err := cli.PluginList(context.Background(), types.PluginListListOptions{})
	if err != nil {
		panic(err)
	}

	for _, plugin := range plugins {
		fmt.Printf("%s %s\n", plugin.Name, plugin.Image)
	}
}

Full documentation is available on GoDoc.

Documentation

Overview

Package client is a Go client for the Malice Engine API.

The "malice" command uses this package to communicate with the daemon. It can also be used by your own Go applications to do anything the command-line interface does - running containers, pulling images, managing swarms, etc.

For more information about the Engine API, see the documentation: https://docs.malice.io/engine/reference/api/

Usage

You use the library by creating a client object and calling methods on it. The client can be created either from environment variables with NewEnvClient, or configured manually with NewClient.

For example, to list running containers (the equivalent of "malice plugin ls"): 

package main

import (
	"context"
	"fmt"

	"github.com/maliceio/engine/api/types"
	"github.com/maliceio/engine/client"
)

func main() {
	cli, err := client.NewEnvClient()
	if err != nil {
		panic(err)
	}

	plugins, err := cli.PluginList(context.Background(), types.PluginListListOptions{})
	if err != nil {
		panic(err)
	}

	for _, plugin := range plugins {
		fmt.Printf("%s %s\n", plugin.Name, plugin.Image)
	}
}

Index

Constants

View Source 
const DefaultDockerHost = "unix:///var/run/malice.sock"

DefaultDockerHost defines os specific default if DOCKER_HOST is unset

Variables

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 Docker client (and by extension maliceio API client) can be made to 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.

Supported environment variables: DOCKER_HOST to set the url to the maliceio server. DOCKER_API_VERSION to set the version of the API to reach, leave empty for latest. DOCKER_CERT_PATH to load the TLS certificates from. DOCKER_TLS_VERIFY 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 

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.

func IsErrPluginPermissionDenied 

func IsErrPluginPermissionDenied(err error) bool

IsErrPluginPermissionDenied returns true if the error is caused when a user denies a plugin's permissions

func IsErrUnauthorized 

func IsErrUnauthorized(err error) bool

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

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

func WithDialer 

func WithDialer(dialer *net.Dialer) func(*Client) error

WithDialer applies the dialer.DialContext 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) func(*Client) error

WithHTTPClient overrides the client http client with the specified one

func WithHTTPHeaders 

func WithHTTPHeaders(headers map[string]string) func(*Client) error

WithHTTPHeaders overrides the client default http headers

func WithHost 

func WithHost(host string) func(*Client) error

WithHost overrides the client host with the specified one.

func WithTLSClientConfig 

func WithTLSClientConfig(cacertPath, certPath, keyPath string) func(*Client) error

WithTLSClientConfig applies a tls config to the client transport.

func WithVersion 

func WithVersion(version string) func(*Client) error

WithVersion overrides the client version with the specified one

Types

type APIClient 

type APIClient interface {
	CommonAPIClient
}

APIClient is an interface that clients that talk with a docker server must implement.

type Client 

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

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

func NewClient 

func NewClient(host string, version string, client *http.Client, httpHeaders map[string]string) (*Client, error)

NewClient initializes a new API client for the given host and API version. It uses the given http client as transport. It also initializes the custom http headers to add to each request.

It won't send any version information if the version number is empty. It is highly recommended that you set a version or your client may break if the server is upgraded. Deprecated: use NewClientWithOpts

func NewClientWithOpts 

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

NewClientWithOpts initializes a new API client with default values. It takes functors to modify values when creating it, like `NewClientWithOpts(WithVersion(…))` It also initializes the custom http headers to add to each request.

It won't send any version information if the version number is empty. It is highly recommended that you set a version or your client may break if the server is upgraded.

func NewEnvClient deprecated 

func NewEnvClient() (*Client, error)

NewEnvClient initializes a new API client based on environment variables. See FromEnv for a list of support environment variables.

Deprecated: use NewClientWithOpts(FromEnv)

func (*Client) ClientVersion 

func (cli *Client) ClientVersion() string

ClientVersion returns the API version used by this client.

func (*Client) Close 

func (cli *Client) Close() error

Close the transport used by the client

func (*Client) CustomHTTPHeaders 

func (cli *Client) CustomHTTPHeaders() map[string]string

CustomHTTPHeaders returns the custom http headers stored by the client.

func (*Client) DaemonHost 

func (cli *Client) DaemonHost() string

DaemonHost returns the host address used by the client

func (*Client) DialSession 

func (cli *Client) DialSession(ctx context.Context, proto string, meta map[string][]string) (net.Conn, error)

DialSession returns a connection that can be used communication with daemon

func (*Client) DiskUsage 

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

DiskUsage requests the current data usage from the daemon

func (*Client) HTTPClient 

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

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

func (*Client) NegotiateAPIVersion 

func (cli *Client) NegotiateAPIVersion(ctx context.Context)

NegotiateAPIVersion queries the API and updates the version to match the API version. Any errors are silently ignored.

func (*Client) NegotiateAPIVersionPing 

func (cli *Client) NegotiateAPIVersionPing(p types.Ping)

NegotiateAPIVersionPing updates the client version to match the Ping.APIVersion if the ping version is less than the default version.

func (*Client) NewVersionError 

func (cli *Client) NewVersionError(APIrequired, feature string) error

NewVersionError returns an error if the APIVersion required if less than the current supported version

func (*Client) Ping 

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

Ping pings the server and returns the value of the "Docker-Experimental", "OS-Type" & "API-Version" headers

func (*Client) PluginDisable 

func (cli *Client) PluginDisable(ctx context.Context, name string, options plugin.DisableOptions) error

PluginDisable disables a plugin

func (*Client) PluginEnable 

func (cli *Client) PluginEnable(ctx context.Context, name string, options plugin.EnableOptions) error

PluginEnable enables a plugin

func (*Client) PluginInstall 

func (cli *Client) PluginInstall(ctx context.Context, name string, options plugin.InstallOptions) (rc io.ReadCloser, err error)

PluginInstall installs a plugin

func (*Client) PluginList 

func (cli *Client) PluginList(ctx context.Context, filter filters.Args) (plugin.ListResponse, error)

PluginList returns the installed plugins

func (*Client) PluginRemove 

func (cli *Client) PluginRemove(ctx context.Context, name string, options plugin.RemoveOptions) error

PluginRemove removes a plugin

func (*Client) PluginSet 

func (cli *Client) PluginSet(ctx context.Context, name string, args []string) error

PluginSet modifies settings for an existing plugin

func (*Client) PluginUpgrade 

func (cli *Client) PluginUpgrade(ctx context.Context, name string, options plugin.InstallOptions) (rc io.ReadCloser, err error)

PluginUpgrade upgrades a plugin

func (*Client) ServerVersion 

func (cli *Client) ServerVersion(ctx context.Context) (types.Version, error)

ServerVersion returns information of the docker client and server host.

func (*Client) SetCustomHTTPHeaders 

func (cli *Client) SetCustomHTTPHeaders(headers map[string]string)

SetCustomHTTPHeaders that will be set on every HTTP request made by the client. Deprecated: use WithHTTPHeaders when creating the client.

type CommonAPIClient 

type CommonAPIClient interface {
	// ConfigAPIClient
	// ContainerAPIClient
	// DistributionAPIClient
	// ImageAPIClient
	// NodeAPIClient
	// NetworkAPIClient
	PluginAPIClient
	// ServiceAPIClient
	// SwarmAPIClient
	// SecretAPIClient
	SystemAPIClient
	// VolumeAPIClient
	ClientVersion() string
	DaemonHost() string
	HTTPClient() *http.Client
	ServerVersion(ctx context.Context) (types.Version, error)
	NegotiateAPIVersion(ctx context.Context)
	NegotiateAPIVersionPing(types.Ping)
	DialSession(ctx context.Context, proto string, meta map[string][]string) (net.Conn, error)
	Close() error
}

CommonAPIClient is the common methods between stable and experimental versions of APIClient.

type PluginAPIClient 

type PluginAPIClient interface {
	PluginList(ctx context.Context, filter filters.Args) (plugin.ListResponse, error)
	PluginRemove(ctx context.Context, name string, options plugin.RemoveOptions) error
	PluginEnable(ctx context.Context, name string, options plugin.EnableOptions) error
	PluginDisable(ctx context.Context, name string, options plugin.DisableOptions) error
	PluginInstall(ctx context.Context, name string, options plugin.InstallOptions) (io.ReadCloser, error)
	PluginUpgrade(ctx context.Context, name string, options plugin.InstallOptions) (io.ReadCloser, error)
}

PluginAPIClient defines API client methods for the plugins

type SystemAPIClient 

type SystemAPIClient interface {
	// 	Events(ctx context.Context, options types.EventsOptions) (<-chan events.Message, <-chan error)
	// 	Info(ctx context.Context) (types.Info, error)
	// 	RegistryLogin(ctx context.Context, auth types.AuthConfig) (registry.AuthenticateOKBody, error)
	// 	DiskUsage(ctx context.Context) (types.DiskUsage, error)
	Ping(ctx context.Context) (types.Ping, error)
}

SystemAPIClient defines API client methods for the system

Source Files

View all Source files

Directories

Path Synopsis

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.