Documentation

Overview

    Package host implements the plugin hosting functionality.

    Index

    Constants

    This section is empty.

    Variables

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

      ErrAborted is returned by CheckAdmission promise when the plugin terminates.

      View Source
      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.

        Functions

        This section is empty.

        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.

                  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.
                    	//
                    	// If not set, all logs from plugins will be ignored.
                    	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.