sdk

func As ¶

func As[T Task](e ExportedTask) (T, bool)

As returns an exported task's body as T, the value type registered under e.Type (ConfigTask, not *ConfigTask). It reports false for any other type.

func CheckMinimumVersions ¶ added in v0.9.1

func CheckMinimumVersions(ctx context.Context, typeKey string, task Task) error

CheckMinimumVersions returns a *VersionError when the server ctx targets, or an installed plugin task needs, is older than the floor task declares. Call it before a task's Plan or Execute. It returns nil when ctx carries no gate, when task declares no floor, and when a plugin task needs is not installed, which the task's own probe reports. typeKey names the task in the error, such as "dokku_app".

func ContextWithRunner ¶ added in v0.9.1

func ContextWithRunner(ctx context.Context, fn ExecRunner) context.Context

ContextWithRunner returns a copy of ctx whose commands go to fn instead of to a real process or server. The runner travels on the context rather than in a package variable, so two tests can install different fakes at the same time and both can call t.Parallel().

Production code must not use it. The seam exists so a test can drive a task without a server; a caller that wants to change where commands actually run sets a Target.

fn receives every command a call makes, not only dokku's, with its arguments as they would have run: unmasked, and without the sudo or SSH wrapping a Target adds. A Target on ctx has no effect while fn is installed.

A command that ran and exited non-zero is a response carrying that ExitCode. A probe reads it as its answer whether fn returns a nil error alongside it or, as the real runner does, an *ExecError with Ran set. An apply fails only on an error, so return the *ExecError to fail one. Any other error is a command that could not run, which a probe reports as an error rather than as absence.

The response's Command is what an apply records in TaskOutputState.Commands, so set it when a test reads that.

package main

import (
	"context"
	"fmt"
	"strings"

	"github.com/dokku/docket/sdk"
)

func main() {
	var calls []string
	ctx := sdk.ContextWithRunner(context.Background(), func(_ context.Context, in sdk.ExecCommandInput) (sdk.ExecCommandResponse, error) {
		calls = append(calls, strings.Join(in.Args, " "))
		if len(in.Args) > 1 && in.Args[1] == "apps:exists" {
			// The app is absent: the command ran and exited non-zero.
			return sdk.ExecCommandResponse{ExitCode: 1}, nil
		}
		return sdk.ExecCommandResponse{}, nil
	})

	task, _ := sdk.NewTask("dokku_app")
	app := task.(*sdk.AppTask)
	app.App = "api"

	plan := app.Plan(ctx)
	fmt.Println(plan.Reason, plan.Commands)

	state := sdk.ExecutePlan(ctx, plan)
	fmt.Println(state.Changed, calls)
}

Output:
app missing [dokku --quiet apps:create api]
true [--quiet apps:exists api --quiet apps:create api]

func ContextWithTarget ¶

func ContextWithTarget(ctx context.Context, target Target) context.Context

ContextWithTarget returns a copy of ctx that sends dokku commands to target. A context derived from a session context still belongs to that session.

func ContextWithVersionGate ¶ added in v0.9.1

func ContextWithVersionGate(ctx context.Context) context.Context

ContextWithVersionGate returns a copy of ctx on which CheckMinimumVersions compares a task's floor with the server. The versions it reads are cached per target for as long as the context lives, so install it once per run. A context that already carries a gate is returned as-is.

func IdentityAddress ¶

func IdentityAddress(typeKey string, t Task) string

IdentityAddress renders the resource t addresses, such as `dokku_config[app=api]`. It is the form ParseIdentityAddress and ParseResourceSelectors read back.

func ParseIdentityAddress ¶

func ParseIdentityAddress(address string) (string, map[string]string, error)

ParseIdentityAddress parses `dokku_config[app=api]` into its type key and key map. A bare type key parses to an empty map.

func TaskDeprecation ¶

func TaskDeprecation(t Task) string

TaskDeprecation returns t's deprecation notice, or "" when t is current.

func TaskSensitiveValues ¶ added in v0.9.1

func TaskSensitiveValues(t Task) []string

TaskSensitiveValues returns the values the CLI masks for t before a run: its `sensitive:"true"` fields, including those of nested items, the value of a property marked sensitive, and whatever t's own SensitiveValues method returns. Pass them to NewMasker. Empty values are dropped and duplicates removed; the order is unspecified.

A value only known once the server is read, such as a secret property's current value, is added to the context's masker during Plan.

package main

import (
	"fmt"

	"github.com/dokku/docket/sdk"
)

func main() {
	task, err := sdk.DecodeTask("dokku_http_auth_user", []byte(`
app: api
users:
  - username: admin
    password: s3cr3t
`))
	if err != nil {
		panic(err)
	}

	masker := sdk.NewMasker(sdk.TaskSensitiveValues(task)...)
	fmt.Println(masker.String("http-auth:add-user api admin s3cr3t"))
}

Output:
http-auth:add-user api admin ***

func TaskSynopsis ¶

func TaskSynopsis(t Task) string

TaskSynopsis returns t's description, or "" when it has none.

func TaskTypes ¶

func TaskTypes() []string

TaskTypes returns every registered task type, sorted. The slice is the caller's own.

package main

import (
	"fmt"

	"github.com/dokku/docket/sdk"
)

func main() {
	for _, typeKey := range sdk.TaskTypes() {
		task, _ := sdk.Lookup(typeKey)
		if typeKey == "dokku_app" {
			fmt.Println(typeKey, "-", sdk.TaskSynopsis(task))
		}
	}
}

Output:
dokku_app - Creates or destroys an app

func ValidateSSHOptions ¶ added in v0.9.1

func ValidateSSHOptions(opts []string) error

ValidateSSHOptions reports whether opts can be a Target's SSHOptions, without contacting anything: each must be non-empty, free of control characters, and must not set an option docket manages itself.