Documentation
¶
Overview ¶
Package hooks defines the contract between the Docker CLI and CLI plugin hook implementations.
Audience ¶
This package is intended to be imported by CLI plugin implementations that implement a "hooks" subcommand, and by the Docker CLI when invoking those hooks.
Contract and wire format ¶
Hook inputs (see Request) are serialized as JSON and passed to the plugin hook subcommand (currently as a command-line argument). Hook outputs are emitted by the plugin as JSON (see Response).
Stability ¶
The types that represent the hook contract (Request, Response and related constants) are considered part of Docker CLI's public Go API. Fields and values may be extended in a backwards-compatible way (for example, adding new fields), but existing fields and their meaning should remain stable. Plugins should ignore unknown fields and unknown hook types to remain forwards-compatible.
Index ¶
- Variables
- func ParseTemplate(hookTemplate string, cmd *cobra.Command) ([]string, error)
- func PrintNextSteps(out io.Writer, messages []string)
- func TemplateReplaceArg(i int) string
- func TemplateReplaceFlagValue(flag string) string
- func TemplateReplaceSubcommandName() string
- type HookMessagedeprecated
- type HookTypedeprecated
- type Request
- type Response
- type ResponseType
Constants ¶
This section is empty.
Variables ¶
var ErrHookTemplateParse = errors.New("failed to parse hook template")
Functions ¶
func PrintNextSteps ¶
PrintNextSteps renders list of NextSteps messages and writes them to out. It is a no-op if messages is empty.
func TemplateReplaceArg ¶
TemplateReplaceArg takes an index i and returns a hook template string that the CLI will replace the template with the ith argument after processing the passed flags.
Example:
Response{
Type: NextSteps,
Template: "run this image with `docker run " + TemplateReplaceArg(0) + "`",
}
when being executed after the command:
docker pull alpine
It results in the message:
Run this image with `docker run alpine`
func TemplateReplaceFlagValue ¶
TemplateReplaceFlagValue returns a hook template string that will be replaced with the flags value when printed by the CLI.
Example:
Response{
Type: NextSteps,
Template: "you ran a container named: " + TemplateReplaceFlagValue("name"),
}
when executed after the command:
docker run --name "my-container" alpine
it results in the message:
you ran a container named: my-container
func TemplateReplaceSubcommandName ¶
func TemplateReplaceSubcommandName() string
TemplateReplaceSubcommandName returns a hook template string that will be replaced by the CLI subcommand being executed
Example:
Response{
Type: NextSteps,
Template: "you ran the subcommand: " + TemplateReplaceSubcommandName(),
}
When being executed after the command:
docker run --name "my-container" alpine
It results in the message:
you ran the subcommand: run
Types ¶
type HookMessage
deprecated
type HookType
deprecated
type HookType = ResponseType
HookType is the type of response from the plugin.
Deprecated: use ResponseType instead.
type Request ¶
type Request struct {
// RootCmd is a string representing the matching hook configuration
// which is currently being invoked. If a hook for "docker context"
// is configured and the user executes "docker context ls", the plugin
// is invoked with "context".
RootCmd string `json:"RootCmd,omitzero"`
// Flags contains flags that were set on the command for which the
// hook was invoked. It uses flag names as key, with leading hyphens
// removed ("--flag" and "-flag" are included as "flag" and "f").
//
// Flag values are not included and are set to an empty string,
// except for boolean flags known to the CLI itself, for which
// the value is either "true", or "false".
//
// Plugins can use this information to adjust their [Response]
// based on whether the command triggering the hook was invoked
// with.
Flags map[string]string `json:"Flags,omitzero"`
// CommandError is a string containing the error output (if any)
// of the command for which the hook was invoked.
CommandError string `json:"CommandError,omitzero"`
}
Request is the type representing the information that plugins declaring support for hooks get passed when being invoked following a CLI command execution.
type Response ¶
type Response struct {
Type ResponseType `json:"Type"`
Template string `json:"Template,omitzero"`
}
Response represents a plugin hook response. Plugins declaring support for CLI hooks need to print a JSON representation of this type when their hook subcommand is invoked.
type ResponseType ¶
type ResponseType int
ResponseType is the type of response from the plugin.
const (
NextSteps ResponseType = 0
)
Source Files