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 PrintMessages(out io.Writer, messages []Response, evaluate func(Response) []string)
- func PrintNextSteps(out io.Writer, messages []string)deprecated
- 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 PrintMessages ¶
PrintMessages groups messages by type and writes them to out. Generic messages appear first, without a header or indentation, followed by next steps under a shared "What's next:" header. Order within each type is preserved. Messages with no lines or an unknown type produce no output.
func PrintNextSteps
deprecated
PrintNextSteps renders list of NextSteps messages and writes them to out. It is a no-op if messages is empty.
Deprecated: use PrintMessages instead.
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 renders suggestions under a shared "What's next:" header. NextSteps ResponseType = 0 // GenericMessage renders before NextSteps, without a header or indentation. // CLI versions that do not recognize this type ignore the response. GenericMessage ResponseType = 1 )
Source Files