Documentation
¶
Overview ¶
Package actionrpc is the protocol between the workflow runner and its actions. Each action runs in a process of its own, started from the probe binary, and is called over go-plugin's gRPC transport.
Index ¶
- Variables
- func LogOutcome(log hclog.Logger, subject string, ret map[string]any, err error)
- func LogParams(log hclog.Logger, msg string, with map[string]any)
- func Run(name string, with map[string]any, log hclog.Logger) (map[string]any, error)
- func RunExecutable(path string, sum []byte, with map[string]any, log hclog.Logger) (map[string]any, error)
- func RunExecutableStep(path string, sum []byte, call Call, log hclog.Logger) (map[string]any, map[string]any, error)
- func RunStep(name string, call Call, log hclog.Logger) (map[string]any, map[string]any, error)
- func Sendable(v map[string]any) (map[string]any, error)
- func Serve(newAction func(log hclog.Logger) Action)
- type Action
- type Call
- type Client
- type Plugin
- type Server
- type Step
- type StepAction
Constants ¶
This section is empty.
Variables ¶
var ( // BuiltinCmd is the subcommand of the probe binary that serves an action. BuiltinCmd = "builtin-actions" // Handshake is the go-plugin handshake both sides of an action agree on. Handshake = plugin.HandshakeConfig{ProtocolVersion: 1, MagicCookieKey: "probe", MagicCookieValue: "actions"} // PluginMap is the set of plugins the runner can dispense. PluginMap = map[string]plugin.Plugin{"actions": &Plugin{}} )
Functions ¶
func LogOutcome ¶
LogOutcome records how an action finished. subject names what was attempted, for example "http request", and is used to build the message.
func LogParams ¶
LogParams records the parameters an action received, truncating long values so that a large request body does not flood the log. Actions are separate processes, so their log records reach the workflow runner as JSON on stderr and are re-filtered there by the runner's own level.
func Run ¶
Run starts the action named name from the running probe binary, calls it once with the given parameters, and stops it. The action's own log records reach log, which decides what of them is shown.
func RunExecutable ¶ added in v1.17.0
func RunExecutable(path string, sum []byte, with map[string]any, log hclog.Logger) (map[string]any, error)
RunExecutable starts the action served by the executable at path, calls it once with the given parameters, and stops it, as Run does for a built-in one. When sum is not empty, the executable is started only if its SHA-256 digest is sum.
func RunExecutableStep ¶ added in v1.19.0
func RunExecutableStep(path string, sum []byte, call Call, log hclog.Logger) (map[string]any, map[string]any, error)
RunExecutableStep is RunExecutable for a step, as RunStep is Run for one.
func RunStep ¶ added in v1.19.0
RunStep is Run for a step: the action is told about the step and given the state it left in the job, and the state it leaves is returned, which is nil when it keeps none.
func Sendable ¶ added in v1.19.0
Sendable returns a copy of v as an action in a process of its own sends it and the runner receives it: maps keyed by strings, lists, and plain values, with whole numbers as int64. The maps and lists are new, so the copy shares none of them with v. It fails for a value that cannot be sent, as sending it would.
Types ¶
type Action ¶
Action is what an action implements: it runs once with the step's `with` parameters and returns its result.
type Call ¶ added in v1.19.0
type Call struct {
// With holds the step's with parameters, as Action.Run is given them.
With map[string]any
// State is the state the action left in the job, or nil when it left
// none. The runner keeps the state the action returns without reading
// it, and gives it to the action again in the next step of the job that
// uses it. The state starts empty in each run of a job, and a nil state
// returned keeps it as it was.
State map[string]any
// Step is the step the action runs for.
Step Step
}
Call is what a StepAction is given to run once for a step.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls an Action in another process.
type Plugin ¶
Plugin serves an Action over gRPC, and is what the runner dispenses to call one.
func (*Plugin) GRPCClient ¶
func (p *Plugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (any, error)
func (*Plugin) GRPCServer ¶
type Server ¶
type Server struct {
Impl Action
// contains filtered or unexported fields
}
Server answers the runner's calls with an Action.
func (*Server) Run ¶
func (m *Server) Run(ctx context.Context, req *pb.RunRequest) (*pb.RunResponse, error)
Run runs the action with the request's parameters.
type Step ¶ added in v1.19.0
type Step struct {
// RunID names the run of probe, the same for every step of every job in
// it, and for a job run by the embedded action.
RunID string
JobID string
JobName string
// Index is the position of the step in the job, from 0.
Index int
// ID is the id the step is given, or empty.
ID string
Name string
// Repeat is which run of a repeated job this is, from 0.
Repeat int
// Attempt is which attempt of a retried step this is, from 1.
Attempt int
}
Step tells an action about the step it runs for.
type StepAction ¶ added in v1.19.0
type StepAction interface {
Action
RunStep(call Call) (result, newState map[string]any, err error)
}
StepAction is an Action that is told about the step it runs for, and may keep state in a job from one step that uses it to the next, such as the cookies a server set. What it does with either is up to the action.
Source Files