sdk

func TaskConstraints ¶ added in v0.10.0

func TaskConstraints(v any) []Constraint

TaskConstraints returns the rules over several of v's fields, the same ones TaskSchema.Constraints publishes. v is a task, an element struct, or a pointer to either. Nil when it declares none.

func WithUnknown ¶ added in v0.11.0

func WithUnknown(paths ...string) ConstraintOption

WithUnknown is a ConstraintViolations option naming the recipe key paths whose values are not known yet, in the form Violation.Field uses: `app`, `users`, `users[1]` or `users[1].hash`.

An unknown field counts as set for a rule that needs it present: its required_when, a list item's required keys, an at_least_one_of or all_or_none_of it is in, and the fields a required_with requires. A rule whose outcome turns on its value is skipped rather than reported: its forbidden_when, an exactly_one_of with at most one known field set, which it might complete or break, a conflicts_with it is in, and a required_with it is the Field of. A rule the known fields decide on their own is reported as without the option: two set fields in an exactly_one_of or a conflicts_with, or a set and an unset field in an all_or_none_of, whatever the unknown ones hold.

An unknown `state` leaves every rule scoped to a state undecided, so they are all skipped: each field's required_when and forbidden_when and every constraint that lists States, the task's own and its list items'. Rules that apply in every state are still checked. An unknown `property` skips the check that a property task's property is not one another task manages.

An unknown structured list (`users`) is unknown as a field, and none of its items are checked, since neither how many there are nor what they hold is known; an unknown item (`users[1]`) is skipped the same way while the other items are checked. The same holds for a list tagged unique: an unknown list is not checked for repeats, and an unknown member (`phases[1]`) is not compared with the others, while two known members that repeat each other are still reported. A path naming no field of the task is ignored.

package main

import (
	"fmt"

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

func main() {
	task, err := sdk.NewTask("dokku_http_auth_user")
	if err != nil {
		panic(err)
	}
	users := task.(*sdk.HttpAuthUserTask)
	users.Users = []sdk.HttpAuthUser{
		{Username: "a", Password: "p", Hash: "h"},
		{Username: "b"},
	}

	for _, v := range sdk.ConstraintViolations(users, sdk.WithUnknown("app", "users[1].hash")) {
		fmt.Printf("%s: %s\n", v.Field, v.Message)
	}
}

Output:
users[0].password: 'users[0].password' and 'users[0].hash' are mutually exclusive

func Diagnostics ¶ added in v0.11.0

func Diagnostics(ctx context.Context, result any) []Diagnostic

Diagnostics returns the errors and warnings in result, masked with the masker on ctx, so a caller can show them without masking or classifying each one itself. result is a PlanResult, a TaskOutputState (or a pointer to either), or an error, such as the one ReadTask or ReadAddress returns.

The error, when there is one, comes first, then one warning per entry in Warnings, in order, each keeping its Reason. A result with neither, a nil error and a nil pointer return nil. Any other type returns a single error diagnostic naming it.

An error is classified by what it wraps, first match wins: a failure of the ssh transport, a *VersionError, an *ObjectMissingError, ErrStateUnreadable, a command that failed (an *ExecError, or a result carrying a non-zero ExitCode), and anything else.

package main

import (
	"context"
	"fmt"

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

func main() {
	session := sdk.NewSession(sdk.NewMasker())
	defer func() { _ = session.Close() }()
	// The server holds no app web.
	ctx := dokkutest.New(nil).Context(session.Context(context.Background(), sdk.Target{}))

	task := sdk.ConfigTask{App: "web", Config: map[string]string{"LOG_LEVEL": "info"}, State: sdk.StatePresent}
	_, _, err := sdk.ReadTask(ctx, task)
	for _, d := range sdk.Diagnostics(ctx, err) {
		fmt.Println(d.Severity, d.Reason, d.Summary)
	}
}

Output:
error object_missing app web does not exist

package main

import (
	"context"
	"errors"
	"fmt"

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

func main() {
	session := sdk.NewSession(sdk.NewMasker())
	defer func() { _ = session.Close() }()
	server := dokkutest.New(nil).SeedApp("web")
	server.HandlePrefix("--quiet config:set", func(context.Context, sdk.ExecCommandInput) (sdk.ExecCommandResponse, error) {
		res := sdk.ExecCommandResponse{Stdout: "-----> Setting config vars", Stderr: "refusing to set TOKEN=hunter2", ExitCode: 1}
		return res, &sdk.ExecError{Response: res, Err: errors.New(res.Stderr), Ran: true}
	})
	ctx := server.Context(session.Context(context.Background(), sdk.Target{}))

	task := sdk.ConfigTask{App: "web", Config: map[string]string{"TOKEN": "hunter2"}, State: sdk.StatePresent}
	state := sdk.ExecutePlan(ctx, task.Plan(ctx))
	for _, d := range sdk.Diagnostics(ctx, state) {
		fmt.Println(d.Summary)
		fmt.Println(d.Detail)
	}
}

Output:
the command failed with exit code 1
refusing to set TOKEN=***

stdout:
-----> Setting config vars

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 TaskLifecycle ¶ added in v0.11.0

func TaskLifecycle(t Task) LifecycleSchema

TaskLifecycle returns the state that applies t's resource and the state that tears it down, the same pair the catalog publishes as `lifecycle`. Apply is `set` when t offers it and the `state` field's default otherwise; Teardown is `clear` when offered, else `absent`, and empty when t is imperative. A task the rule does not fit declares its own pair instead: dokku_storage_ensure offers `absent` but refuses it, so it has no Teardown.

func NewMasker ¶

func NewMasker(values ...string) *Masker

NewMasker returns a masker for values. A Masker built with no values is still usable; more can be added.

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, the values of `export --resource`. Each must name a registered task type that ExportRecipe can reach, and only keys that task declares.

Validation happens here, before the export contacts the server, so a typo in an address fails immediately rather than after an SSH round trip.

func NewSession ¶

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

NewSession returns a session whose contexts carry masker and whatever opts, such as the version gate, 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 WithControlPersist ¶ added in v0.11.0

func WithControlPersist(d time.Duration) SessionOption

WithControlPersist sets how long each SSH connection the session opens stays open after its last command returns, in place of the default 60 seconds. It is rounded up to whole seconds, which is what ssh's ControlPersist counts.

Zero, or a negative d, closes a connection as soon as no command under the session is using it: the call that finishes the last command closes the connection before it returns. That suits an embedder with nowhere to call Close, such as a process that is killed rather than shut down, at the cost of a new connection for each command that runs after the previous one finished. Commands that overlap still share one.

package main

import (
	"context"

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

func main() {
	session := sdk.NewSession(nil, sdk.WithControlPersist(0))

	ctx := session.Context(context.Background(), sdk.Target{Host: "deploy@dokku.example.com"})
	_ = 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 zero-value instance of it for reading the task's metadata - its synopsis, identity keys, export support and so on.

Every call allocates, so a caller may do anything with the result without affecting the registry or any other caller. The instance has no `default:` tags applied; use NewTask for a task to set fields on and 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. A whole collection read that way always exists: one with no members comes back in state clear with exists true, since a missing app or service is reported as an error instead. 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, an *ObjectMissingError when the app or service the resource depends on is missing, 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"

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

func main() {
	server := dokkutest.New(nil).SeedBuildpacks("api", "https://github.com/heroku/heroku-buildpack-nodejs.git")
	ctx := sdk.ContextWithVersionGate(server.Context(context.Background()))

	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, t Task) (Task, bool, error)

ReadTask returns t 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 t (AppTask, not *AppTask), carrying the identity keys from t and every field the server reports. Fields whose catalog entry is WriteOnly or ApplyOnly are left empty or at their default.

t 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.

The State also picks what exists means. A collection task in set or clear owns the whole collection, which exists whenever the read succeeds, with or without members. In present or absent it owns only the members it names, and exists reports whether any of them is there.

When ctx carries a version gate and the server is older than t's floor, the error is the *VersionError, never a resource reported as absent. When the read does not find the resource, or finds a whole collection with no members, and the app or service t depends on is missing, the error is an *ObjectMissingError naming it, which matches ErrObjectMissing; a task that creates its app or service, such as dokku_app, reports itself absent instead. A task whose probe cannot read its state returns an error wrapping ErrStateUnreadable.

package main

import (
	"context"
	"errors"
	"fmt"

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

func main() {
	server := dokkutest.New(nil).SeedConfig("api", map[string]string{"LOG_LEVEL": "debug", "OTHER": "x"})
	ctx := sdk.ContextWithVersionGate(server.Context(context.Background()))

	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 TaskFromValues ¶ added in v0.11.0

func TaskFromValues(typeKey string, values map[string]any) (Task, error)

TaskFromValues builds a task of the registered type typeKey from values keyed by recipe key, with defaults applied, the way DecodeTask builds one from a YAML body. Like DecodeTask it checks shape and type only; the task's own rules - required fields, choices, constraints - are for ConstraintViolations and the task's Validate method.

Each value must match its field's catalog type, and is accepted where the conversion is lossless:

• string: any Go string, including a named string type such as State. A json.Number is a number, not a string, and is refused.
• bool: a bool.
• int: any Go integer type, a float32 or float64 holding a whole number, or a json.Number holding an integer, within the field's range.
• float: any Go integer or float type, or a json.Number.
• list: any slice or array, []any or typed such as []string, whose elements each match the item type.
• dict and object: any map with string keys, map[string]any or typed such as map[string]string; a dict's values each match the item type, and an object's keys are its element's recipe keys.
• any: nil, a bool, a string, a number, or a list or string-keyed map of those, stored with integers as int64 and floats as float64.

A nil value leaves the field unset, so it takes its default; a nil list element or dict value is refused unless the item type is any. An unknown key or a value of the wrong type is an error naming the recipe key path, such as `users[1].hash` or `scale["web"]`, and the first one in sorted key order is reported.

package main

import (
	"fmt"

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

func main() {
	task, err := sdk.TaskFromValues("dokku_ps_scale", map[string]any{
		"app":   "api",
		"scale": map[string]any{"web": 2, "worker": float64(1)},
	})
	if err != nil {
		panic(err)
	}
	values := sdk.TaskValues(task)
	fmt.Printf("%v %T %v %v\n", values["state"], values["scale"].(map[string]any)["web"], values["scale"], values["skip_deploy"])

	_, err = sdk.TaskFromValues("dokku_ps_scale", map[string]any{"scale": map[string]any{"web": "two"}})
	fmt.Println(err)
}

Output:
present int64 map[web:2 worker:1] false
dokku_ps_scale: scale["web"]: expected int, got string

func TaskInState ¶ added in v0.11.0

func TaskInState(t Task, state State) (Task, error)

TaskInState returns a copy of t moved into state: its `state` key set to state, and every field whose `forbidden_when` names state reset to its default, or to its zero value when it has none. Element fields of a list of structs are reset the same way. t itself is left unchanged, and the copy shares no list or map with it.

It is how a consumer tears down a resource it applied: the task it applied carries values the teardown state refuses, such as dokku_ps_scale's `scale` under `clear` or a property task's `value` under `absent`, and moving it with TaskInState(t, TaskLifecycle(t).Teardown) drops them. A field the state requires is not invented, so moving a task into a state it lacks the input for still fails its validation.

The error is a state t does not offer.

package main

import (
	"fmt"

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

func main() {
	task, err := sdk.NewTask("dokku_ps_scale")
	if err != nil {
		panic(err)
	}
	applied := task.(*sdk.PsScaleTask)
	applied.App = "api"
	applied.Scale = map[string]int{"web": 2}

	lifecycle := sdk.TaskLifecycle(applied)
	applied.State = lifecycle.Apply

	moved, err := sdk.TaskInState(applied, lifecycle.Teardown)
	if err != nil {
		panic(err)
	}
	destroy := moved.(*sdk.PsScaleTask)
	fmt.Println(lifecycle.Apply, lifecycle.Teardown)
	fmt.Println(destroy.State, len(destroy.Scale), len(applied.Scale))
	fmt.Println(len(sdk.ConstraintViolations(destroy)))
}

Output:
set clear
clear 0 1
0

func TaskRequires ¶ added in v0.11.0

func TaskRequires(t Task) []Task

TaskRequires returns the tasks t needs applied before it, in the order to apply them, the same derivation the catalog publishes as each example's `requires`: a dokku_plugin installing each non-core plugin t's plugin requirements name, then the task creating each object t names but does not create itself - dokku_app for an app, dokku_service_create for a service - each preceded by the tasks it needs in turn. A task needing nothing returns nil.

The list covers what docket can derive from the task's declarations alone. An example that needs more, such as a deployed app or a storage entry it names, declares it, and the catalog publishes both.

package main

import (
	"fmt"

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

func main() {
	task, err := sdk.NewTask("dokku_service_link")
	if err != nil {
		panic(err)
	}
	link := task.(*sdk.ServiceLinkTask)
	link.App = "api"
	link.Service = "redis"
	link.Name = "cache"

	for _, required := range sdk.TaskRequires(link) {
		fmt.Println(sdk.IdentityAddress(sdk.TaskTypeOf(required), required))
	}
}

Output:
dokku_plugin[name=redis]
dokku_app[app=api]
dokku_service_create[service=redis,name=cache]

func Catalog ¶

func Catalog() (TaskCatalog, error)

Catalog describes every registered task type, sorted by type key. It is what `docket schema` emits.

func CatalogFor ¶

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

CatalogFor describes only the given task types, sorted by type key. A nil or empty selection means every registered task, so the whole catalog and a narrowed one are the same code path rather than two that can drift.

Sorting is by type key whatever order the keys arrived in, which is what lets a narrowed catalog be diffed against a full one and makes two runs of the same selection byte-identical. Duplicates collapse: the document is a set keyed by type, so naming a type twice is not an error.

An unregistered type is an error rather than a silently smaller document - a caller asking for a type that does not exist wants to know. Keys are checked in the order given, so the message names the first one the caller wrote, and all of them are checked before any schema is built.

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

package main

import (
	"fmt"

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

func main() {
	catalog, err := sdk.CatalogFor([]string{"dokku_app_clone"})
	if err != nil {
		panic(err)
	}
	example := catalog.Tasks[0].Examples[0]
	fmt.Println(example.Name)
	for _, required := range example.Requires {
		fmt.Print(required.YAML)
	}
}

Output:
Clone an app
dokku_app:
    app: node-js-app
dokku_git_from_image:
    app: node-js-app
    image: dokku/smoke-test-app:dockerfile

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. A plan that is already in sync applies nothing. It first adds the planned task's sensitive values to the masker on ctx, even when p was planned under another context. It takes no lock; see LockTask.

The returned state's Observed and Exists are the task as the server holds it once the plan is carried out, by the rules PlanResult.Observed follows for a plan in sync: every field the planned task declares as declared, every field it leaves unset as the server reports it, and write_only and apply_only fields left unread. A plan in sync carries its own Observed and Exists. After a successful apply they are built from the plan's read when the planned task declares every field a read fills, so the server is not probed again; otherwise the planned task is planned once more after the apply, since the apply may have moved a field the task leaves to the server, such as the image a dokku_service_create without one is created on. Observed is nil when the plan errored, when the apply failed, when the plan read nothing (a task whose probe cannot read its state, such as dokku_storage_ensure), when that second plan fails, for an imperative task, which runs an operation rather than declaring a resource to observe, and on a context from ContextWithoutObserved.

package main

import (
	"context"
	"fmt"

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

func main() {
	ctx := dokkutest.New(nil).SeedDatastore("postgres", "postgres:17.2").Context(context.Background())

	task := sdk.ServiceCreateTask{Service: "postgres", Name: "db", State: sdk.StatePresent}
	state := sdk.ExecutePlan(ctx, task.Plan(ctx))
	if state.Error != nil {
		fmt.Println(state.Error)
		return
	}
	observed := state.Observed.(sdk.ServiceCreateTask)
	fmt.Println(state.Changed, state.Exists, observed.Image, observed.ImageVersion)
}

Output:
true true postgres 17.2

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(task any, opts ...ConstraintOption) []Violation

ConstraintViolations returns every declared field constraint task breaks - the required_when, forbidden_when and unique of each field in declaration order, the task's Constraints, then those of each element of its structured lists in turn - 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.

A property task naming a property another task manages is the one exception: that is reported alone, because the user wrote a name this task will never manage, and naming the task that does is more use than telling them the app field is missing too.

Pass WithUnknown to check a task before every value is known, such as a Terraform plan whose attributes come from another resource's output: a rule is then reported only when the known fields decide it, and one that turns on an unknown value is skipped. Without options every field holds its final value.