host

Documentation

Overview

Package host implements the plugin hosting functionality.

Index

• Variables
• type AdmissionPlugin
  • func NewAdmissionPlugin(ctx context.Context, host *Host, args []string) *AdmissionPlugin
  • func (p *AdmissionPlugin) CheckAdmission(pin common.Pin) plugin.Promise
  • func (p *AdmissionPlugin) ClearCache()
  • func (p *AdmissionPlugin) Close(ctx context.Context)
  • func (p *AdmissionPlugin) Executable() string
• type Controller
• type Host
  • func (h *Host) Close(ctx context.Context)
  • func (h *Host) Config() plugin.Config
  • func (h *Host) Initialize(cfg plugin.Config) error
  • func (h *Host) LaunchPlugin(ctx context.Context, args []string, ctrl *Controller) (*PluginProcess, error)
  • func (h *Host) NewAdmissionPlugin(cmdLine []string) (plugin.AdmissionPlugin, error)
• type PluginProcess
  • func (p *PluginProcess) Done() <-chan struct{}
  • func (p *PluginProcess) Err() error
  • func (p *PluginProcess) Terminate(ctx context.Context) error
• type Promise
  • func (p *Promise) Wait(ctx context.Context) error

Variables

var ErrAborted = errors.Reason("the admission plugin is terminating").Err()

ErrAborted is returned by CheckAdmission promise when the plugin terminates.

var ErrTerminated = errors.Reason("terminated with 0 exit code").Err()

ErrTerminated is returned by PluginProcess.Err() if the plugin process exited with 0 exit code.

Types

type AdmissionPlugin

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

AdmissionPlugin launches and communicates with an admission plugin.

It is instantiated by the CIPD client if it detects there's an admission plugin configured.

Implements plugin.AdmissionPlugin interface.

func NewAdmissionPlugin

func NewAdmissionPlugin(ctx context.Context, host *Host, args []string) *AdmissionPlugin

NewAdmissionPlugin returns a host-side representation of an admission plugin.

The returned *AdmissionPlugin can be used right away to enqueue admission checks. The plugin subprocess will lazily be started on the first CheckAdmission call. All enqueued checks will eventually be processed by the plugin or rejected if the plugin fails to start.

The context is used for logging from the plugin.

func (*AdmissionPlugin) CheckAdmission

func (p *AdmissionPlugin) CheckAdmission(pin common.Pin) plugin.Promise

CheckAdmission enqueues an admission check to be performed by the plugin.

The plugin will be asked if it's OK to deploy a package with the given pin hosted on the CIPD service used by the running CIPD client.

Returns a promise which is resolved when the result is available. If such check is already pending (or has been done before), returns an existing (perhaps already resolved) promise.

func (*AdmissionPlugin) ClearCache

func (p *AdmissionPlugin) ClearCache()

ClearCache drops all resolved promises to free up some memory.

func (*AdmissionPlugin) Close

func (p *AdmissionPlugin) Close(ctx context.Context)

Close terminates the plugin (if it was running) and aborts all pending checks.

Tries to gracefully terminate the plugin, killing it with SIGKILL on the context timeout or after 5 sec.

Note that calling Close is not necessary if the plugin host itself terminates. The plugin subprocess will be terminated by the host in this case.

func (*AdmissionPlugin) Executable

func (p *AdmissionPlugin) Executable() string

Executable is a path to this plugin's executable.

type Controller

type Controller struct {
	Admissions protocol.AdmissionsServer // non-nil for deployment admission plugins
}

Controller lives in the host process and manages communication with a plugin.

Each instance of a plugin has a Controller associated with it. The controller exposes a subset of gRPC services that the particular plugin is allowed to call. That way it's possible to have different kinds of plugins by exposing different services to them.

type Host

type Host struct {
	// PluginsContext is used for asynchronous logging from plugins.
	PluginsContext context.Context
	// contains filtered or unexported fields
}

Host launches plugin subprocesses and accepts connections from them.

Implements plugin.Host interface.

func (*Host) Close

func (h *Host) Close(ctx context.Context)

Close terminates all plugins and releases all resources.

Waits for the plugins to terminate gracefully. On context deadline kills them with SIGKILL.

It is a part of plugin.Host interface.

func (*Host) Config

func (h *Host) Config() plugin.Config

Config returns the config passed to Initialize or a default one.

func (*Host) Initialize

func (h *Host) Initialize(cfg plugin.Config) error

Initialize is called when the CIPD client starts before any other call.

It is a part of plugin.Host interface.

func (*Host) LaunchPlugin

func (h *Host) LaunchPlugin(ctx context.Context, args []string, ctrl *Controller) (*PluginProcess, error)

LaunchPlugin launches a plugin subprocesses.

Does not wait for it to connect. Returns a handle that can be used to control the process.

Uses the given context for logging from the plugin.

func (*Host) NewAdmissionPlugin

func (h *Host) NewAdmissionPlugin(cmdLine []string) (plugin.AdmissionPlugin, error)

NewAdmissionPlugin returns a handle to an admission plugin.

It is a part of plugin.Host interface.

type PluginProcess

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

PluginProcess represents a plugin subprocess.

func (*PluginProcess) Done

func (p *PluginProcess) Done() <-chan struct{}

Done returns a channel that closes when the plugin terminates.

func (*PluginProcess) Err

func (p *PluginProcess) Err() error

Err returns an error if the plugin terminated (gracefully or not).

Valid only if Done() is already closed, nil otherwise.

func (*PluginProcess) Terminate

func (p *PluginProcess) Terminate(ctx context.Context) error

Terminate tries to gracefully terminate the plugin process, killing it with SIGKILL on the context expiration or after 5 sec.

Returns the same value as Err(). Does nothing if the process is already terminated.

type Promise

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

Promise is a pending or finished result of an admission check.

Implements plugin.Promise interface.

func (*Promise) Wait

func (p *Promise) Wait(ctx context.Context) error

Wait blocks until the promise is fulfilled or the context expires.

Returns nil if the admission check passed.