Documentation
¶
Overview ¶
Package cli is a command line client for the admin JSON API (github.com/ubgo/workflow/admin): list and inspect runs, retry, cancel and delete them one at a time or by filter, pause and resume, list and trigger schedules, watch a queue drain and read run-end history.
It talks HTTP only. It imports nothing beyond the standard library (not even the workflow core), so installing it pulls no driver, SDK or database code, and it works against an app in any language that serves the same API. A test (TestGuard_StdlibOnly) fails if that changes.
Connecting ¶
The API is closed by default and authenticated by the app, so the CLI sends whatever the app's Identify accepts:
--url URL where the app mounted admin.NewHandler; env WORKFLOW_ADMIN_URL --token T sent as "Authorization: Bearer T"; env WORKFLOW_ADMIN_TOKEN --header 'K: V' any header, repeatable (a session cookie, a tenant header); env WORKFLOW_ADMIN_HEADER holds one
The token is never printed, not even in an error.
Commands ¶
caps operations the server's driver supports runs|failures|discarded list runs; --workflow --queue --status --label k=v --tenant --from --to --limit --cursor --count inspect RUN one run, its attempt errors and, with --output, captured output retry RUN | retry --all retry one failed run, or every failed run a filter matches cancel RUN | cancel --all cancel one run, or every run a filter matches delete RUN | delete --all forget one finished run, or every finished run a filter matches reschedule RUN --at T move a delayed run that has not started cancel-step RUN STEP withdraw one step of a run pause|resume --workflow W | --queue Q | --everything pauses the active pauses queues depth and oldest wait per queue schedules | schedule ID list schedules, or show one trigger SCHEDULE run a schedule now drain wait until no run is queued or running (--queue, --wait, --interval) metrics run ends per step by status (--window, --step, --workflow) health live, ready and each check; exit 1 when not ready nodes the nodes that are online
Every destructive command takes --dry-run, which reads what it would touch and changes nothing; --all on retry, cancel and delete asks the server to preview with the same filter. Every command takes --json, which prints the API's own JSON answer instead of a table. The exit code is 0 on success, 1 when the API refused or failed (or drain timed out), and 2 on a usage error.
Embedding ¶
Run is the whole CLI as a function, so an app can ship it as a subcommand of its own binary (with its own default URL and auth), and cmd/workflow is the stand-alone binary.
Index ¶
Constants ¶
const ( // EnvURL is the admin API's mount point, the default of --url. EnvURL = "WORKFLOW_ADMIN_URL" // EnvToken is a bearer token, the default of --token. EnvToken = "WORKFLOW_ADMIN_TOKEN" // EnvHeader is one extra header, "Name: value", added before any // --header flag. EnvHeader = "WORKFLOW_ADMIN_HEADER" )
The environment variables Run reads through Options.Getenv.
const ( ExitOK = 0 // the command did what it was asked ExitError = 1 // the API refused or failed, or drain timed out ExitUsage = 2 // the command line is wrong )
The exit codes Run returns.
const DefaultTimeout = 30 * time.Second
DefaultTimeout bounds one HTTP request when Options.HTTPClient is nil.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type APIError ¶
APIError is an error answer from the admin API: its HTTP status and the code and message from its {"error":{...}} body.
type Options ¶
type Options struct {
// Stdout gets results; Stderr gets errors and usage. Nil discards.
Stdout, Stderr io.Writer
// Getenv reads EnvURL, EnvToken and EnvHeader; nil reads nothing (an
// embedding app passes os.Getenv, or its own lookup).
Getenv func(string) string
// HTTPClient sends the requests; nil is a client with DefaultTimeout.
HTTPClient *http.Client
// Now and Sleep drive drain's polling; nil means the wall clock.
// Sleep returns early with ctx's error when ctx ends.
Now func() time.Time
Sleep func(ctx context.Context, d time.Duration) error
// Name is the program name in usage text; empty means "workflow".
Name string
}
Options are what Run takes from the process around it, so an app can embed the CLI and a test can drive it without a real terminal, network or clock.