sdk

func TaskConstraints ¶ added in v0.10.0

func TaskConstraints(t Task) []Constraint

TaskConstraints returns the rules over several of t's fields, the same ones TaskSchema.Constraints publishes. Nil when t declares none.

func ExportRecipe ¶

func ExportRecipe(ctx context.Context, opts ExportOptions) (*ExportResult, error)

ExportRecipe reads the server ctx targets and returns the recipe that describes it. An export that finds nothing is not an error: check Report.MissingApps and Report.MissingResources.

An exporter whose task declares a floor newer than the server is skipped with a warning and listed in Report.VersionErrors. Set ExportOptions.IgnoreVersion to read it anyway.

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	session := sdk.NewSession(nil)
	defer func() { _ = session.Close() }()
	ctx := session.Context(context.Background(), sdk.Target{Host: "dokku@dokku.example.com"})

	res, err := sdk.ExportRecipe(ctx, sdk.ExportOptions{Inline: true})
	if err != nil {
		panic(err)
	}

	// Register what the export read before printing anything it produced.
	masker := sdk.NewMasker(res.SensitiveValues()...)
	for _, w := range res.Report.Warnings {
		fmt.Fprintln(os.Stderr, masker.String(w))
	}

	for _, play := range res.Plays() {
		for _, task := range play.Tasks {
			cfg, ok := sdk.As[sdk.ConfigTask](task)
			if !ok {
				continue
			}
			fmt.Println(play.Name, cfg.App, len(cfg.Config))
		}
	}
}

Output:

func TaskExportSupport ¶

func TaskExportSupport(t Task) (ExportSupport, bool)

TaskExportSupport reports whether ExportRecipe can reconstruct t from a server. The bool is false when t declares nothing.

func NewMasker ¶

func NewMasker(values ...string) *Masker

NewMasker returns a masker for values.

func TaskProbeSupport ¶

func TaskProbeSupport(t Task) (ProbeSupport, bool)

TaskProbeSupport reports how much of its own state t's Plan can read back. The bool is false when t declares nothing.

func ParseResourceSelectors ¶

func ParseResourceSelectors(addresses []string) ([]ResourceSelector, error)

ParseResourceSelectors parses addresses for ExportOptions.Resources. Each must name a registered, exportable task type and only keys it declares.

func NewSession ¶

func NewSession(masker *Masker, opts ...SessionOption) *Session

NewSession returns a session whose contexts carry masker and whatever opts, such as WithVersionGate, install. A nil masker leaves any masker already on the parent context in place.

Every context the session hands out also carries one lock table, so Execute calls made under the session - from any goroutine - take turns on the same app or datastore service rather than colliding on dokku's deploy lock. See LockTask.

package main

import (
	"context"

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

func main() {
	session := sdk.NewSession(sdk.NewMasker("s3cr3t"))
	defer func() { _ = session.Close() }()

	ctx := session.Context(context.Background(), sdk.Target{
		Host: "deploy@dokku.example.com",
		Sudo: true,
	})
	_ = ctx
}

Output:

func WithVersionGate ¶ added in v0.10.0

func WithVersionGate() SessionOption

WithVersionGate is a NewSession option that installs the version gate on every context the session hands out. They share one cache per target for as long as the session lives, so `dokku version` and `plugin:list` are read once per server per session rather than once per call, while each context keeps the cancellation of the parent it was built from. Only a successful read is cached; a failed one is retried by the next call. Each session gets its own cache, and the session's gate replaces one already on the parent context.

package main

import (
	"context"

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

func main() {
	session := sdk.NewSession(nil, sdk.WithVersionGate())
	defer func() { _ = session.Close() }()

	serve := func(reqCtx context.Context) {
		ctx := session.Context(reqCtx, sdk.Target{Host: "deploy@dokku.example.com"})
		_ = ctx
	}
	serve(context.Background())
	serve(context.Background())
}

Output:

func DecodeTask ¶

func DecodeTask(typeKey string, body []byte) (Task, error)

DecodeTask builds a task of the registered type typeKey from a YAML task body, with defaults applied.

func Lookup ¶

func Lookup(typeKey string) (Task, bool)

Lookup reports whether typeKey is a registered task type and, when it is, returns a new zero-value instance of it for reading metadata. It has no defaults applied; use NewTask for a task to run.

func NewTask ¶

func NewTask(typeKey string) (Task, error)

NewTask returns a new task of the registered type typeKey, such as "dokku_app", with its `default:` values applied. Use it rather than a struct literal, which leaves State as "" instead of the default the field documents.

The task is a pointer to the registered type, so fields are set through a type assertion:

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

package main

import (
	"fmt"

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

func main() {
	task, err := sdk.NewTask("dokku_app")
	if err != nil {
		panic(err)
	}
	app := task.(*sdk.AppTask)
	app.App = "api"

	fmt.Println(sdk.IdentityAddress("dokku_app", app), app.State)
}

Output:
dokku_app[app=api] present

func ReadAddress ¶ added in v0.10.0

func ReadAddress(ctx context.Context, address string) (Task, bool, error)

ReadAddress returns the resource an identity address names, such as `dokku_buildpacks[app=api]`, as it exists on the server, and whether it exists, from the address alone; nothing is applied. It reads every member the resource has, the way a task in state set or clear would own them: a dokku_config leaves out the keys docket keeps (linked-service DSNs, NO_VHOST, the git rev env var), and a dokku_ps_scale leaves out process types scaled to zero. The returned task and errors are ReadTask's: the value type registered for the task, the *VersionError when ctx carries a gate the server is behind, and an error wrapping ErrStateUnreadable for a task whose probe cannot read its state.

The address must name one resource. A bare type, a key the task does not declare, or a missing required key is an error, raised before the server is contacted. IdentityAddress renders the address of a task you hold.

package main

import (
	"context"
	"fmt"
	"strings"

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

func main() {
	ctx := sdk.ContextWithRunner(context.Background(), func(_ context.Context, in sdk.ExecCommandInput) (sdk.ExecCommandResponse, error) {
		switch strings.Join(in.Args, " ") {
		case "version":
			return sdk.ExecCommandResponse{Stdout: "dokku version 0.38.31"}, nil
		case "--quiet buildpacks:list api":
			return sdk.ExecCommandResponse{Stdout: "=====> api buildpack urls\nhttps://github.com/heroku/heroku-buildpack-nodejs.git"}, nil
		}
		return sdk.ExecCommandResponse{}, nil
	})
	ctx = sdk.ContextWithVersionGate(ctx)

	current, exists, err := sdk.ReadAddress(ctx, "dokku_buildpacks[app=api]")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(exists, current.(sdk.BuildpacksTask).Buildpacks)
}

Output:
true [https://github.com/heroku/heroku-buildpack-nodejs.git]

func ReadTask ¶ added in v0.9.2

func ReadTask(ctx context.Context, task Task) (Task, bool, error)

ReadTask returns task as it exists on the server, and whether the resource exists, from a single Plan; nothing is applied. The returned task is the value type registered for task (AppTask, not *AppTask), carrying the identity keys from task and every field the server reports. Fields whose catalog entry is WriteOnly or ApplyOnly are left empty or at their default.

task must be a valid task: its State picks which members of a collection are read, so a dokku_config in state present reads the keys it names, and one in state set reads every key it would own. A property task known only by its identity keys is read with State absent, which needs no Value.

When ctx carries a version gate and the server is older than task's floor, the error is the *VersionError, never a resource reported as absent. A task whose probe cannot read its state returns an error wrapping ErrStateUnreadable.

package main

import (
	"context"
	"errors"
	"fmt"
	"strings"

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

func main() {
	ctx := sdk.ContextWithRunner(context.Background(), func(_ context.Context, in sdk.ExecCommandInput) (sdk.ExecCommandResponse, error) {
		switch strings.Join(in.Args, " ") {
		case "version":
			return sdk.ExecCommandResponse{Stdout: "dokku version 0.38.31"}, nil
		case "--quiet config:export --format json api":
			return sdk.ExecCommandResponse{Stdout: `{"LOG_LEVEL":"debug","OTHER":"x"}`}, nil
		}
		return sdk.ExecCommandResponse{}, nil
	})
	ctx = sdk.ContextWithVersionGate(ctx)

	task, _ := sdk.NewTask("dokku_config")
	cfg := task.(*sdk.ConfigTask)
	cfg.App = "api"
	cfg.Config = map[string]string{"LOG_LEVEL": "info"}

	current, exists, err := sdk.ReadTask(ctx, cfg)
	var verr *sdk.VersionError
	if errors.As(err, &verr) {
		fmt.Println("server too old for", verr.TaskType)
		return
	}
	if err != nil {
		fmt.Println(err)
		return
	}
	observed := current.(sdk.ConfigTask)
	fmt.Println(exists, observed.Config)
}

Output:
true map[LOG_LEVEL:debug]

func Catalog ¶

func Catalog() (TaskCatalog, error)

Catalog describes every registered task type. It is what `docket schema` emits.

func CatalogFor ¶

func CatalogFor(typeKeys []string) (TaskCatalog, error)

CatalogFor describes only the given task types. An unregistered type is an error.

package main

import (
	"fmt"

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

func main() {
	catalog, err := sdk.CatalogFor([]string{"dokku_app"})
	if err != nil {
		panic(err)
	}
	for _, schema := range catalog.Tasks {
		fmt.Println(schema.Type, "-", schema.Synopsis)
	}
}

Output:
dokku_app - Creates or destroys an app

func TaskObjects ¶ added in v0.10.0

func TaskObjects(t Task) []TaskObject

TaskObjects returns the app and the datastore service t changes, app first: the recipe keys naming each and the values t holds for them, whether t creates it, and when t restarts or redeploys it. The catalog publishes the same data as TaskSchema.Objects. Nil when t changes neither.

func ExecutePlan ¶

func ExecutePlan(ctx context.Context, p PlanResult) TaskOutputState

ExecutePlan applies p, the result of a task's Plan, without probing the server again. A plan that is already in sync applies nothing.

func TaskMinimumVersions ¶ added in v0.9.1

func TaskMinimumVersions(t Task) (VersionSupport, bool)

TaskMinimumVersions reports the oldest Dokku, and the plugins, t declares it runs on. The bool is false when t declares nothing.

func ConstraintViolations ¶ added in v0.10.0

func ConstraintViolations(t Task) []Violation

ConstraintViolations returns every declared field constraint t breaks - the required_when and forbidden_when of each field, the task's Constraints, and those of each element of its structured lists - or nil when it satisfies them all. A task's Validate and Plan reject the first of these; this reports them all at once, as `docket validate` does.