schema

type Action string

type Attribute struct {
	// Name is the unique name of the field within the resource schema.
	Name string `json:"name"`

	// Type is the value type (e.g. "string", "int", "bool", "duration",
	// "[]string").
	Type string `json:"type"`

	// Description is a human-readable explanation of the field.
	Description string `json:"description,omitempty"`

	// Required indicates the field must be set by the caller.
	Required bool `json:"required,omitempty"`

	// Default is the value used when the caller does not set the field.
	// It must be assignable to Type.
	Default any `json:"default,omitempty"`

	// Sensitive marks the field as containing secrets that should not
	// appear in logs or plan output.
	Sensitive bool `json:"sensitive,omitempty"`

	// ReadOnly marks the field as computed by the provider. It is not
	// settable by the caller and is populated during [Apply].
	ReadOnly bool `json:"readonly,omitempty"`

	// Reference indicates this attribute is a dependency on another
	// resource instance, resolved by name at decode time.
	Reference bool `json:"reference,omitempty"`
}

type Change struct {
	// Field is the attribute name.
	Field string

	// Old is the current value (nil on create).
	Old any

	// New is the desired value (nil on destroy).
	New any
}

type CreateResourceInstanceRequest struct {
	Name string `json:"name" arg:"" help:"Instance name as resource.label (e.g. \"httpserver.main\")"`
}

type CreateResourceInstanceResponse struct {
	Instance InstanceMeta `json:"instance"`
}

type DestroyResourceInstanceRequest struct {
	Name    string `json:"name"`              // instance name
	Cascade bool   `json:"cascade,omitempty"` // also destroy dependents in topological order
}

type DestroyResourceInstanceResponse struct {
	Instances []InstanceMeta `json:"instances"`
}

type GetResourceInstanceResponse struct {
	Instance InstanceMeta `json:"instance"`
}

type InstanceMeta struct {
	Name       string   `json:"name"`
	Resource   string   `json:"resource"`
	ReadOnly   bool     `json:"readonly,omitempty"`
	State      State    `json:"state,omitempty"`
	References []string `json:"references,omitempty"`
}

type ListResourcesRequest struct {
	Type *string `json:"type,omitempty" arg:"" optional:"" help:"Resource type name (e.g. \"httpserver\")"` // filter by type name
}

type ListResourcesResponse struct {
	Provider    string         `json:"provider"`
	Description string         `json:"description,omitempty"`
	Version     string         `json:"version,omitempty"`
	Resources   []ResourceMeta `json:"resources"`
}

type Plan struct {
	// Action is the high-level operation (create, update, destroy, noop).
	Action Action

	// Changes lists the individual field-level diffs. It is empty when
	// Action is Noop or Destroy.
	Changes []Change
}

type Provider interface {
	// Name returns the unique name for the provider.
	Name() string

	// Description returns a human-readable summary of the provider.
	Description() string

	// Resources returns the set of resources this provider can manage.
	Resources() []Resource
}

type Resolver func(name string) ResourceInstance

type Resource interface {
	// Name returns a unique name for this resource type, used in
	// configuration and plan output.
	Name() string

	// Schema returns the attribute definitions for this resource type,
	// used for validation and documentation.
	Schema() []Attribute

	// New creates a named resource instance.
	// The returned instance is not yet applied; call
	// [ResourceInstance.Apply] to materialise it.
	New(name string) (ResourceInstance, error)
}

type ResourceInstance interface {
	// Name returns the logical name of this resource instance
	// (e.g. "main", "api-v1").
	Name() string

	// Resource returns the resource type that created this instance.
	Resource() Resource

	// Validate decodes the incoming [State] using the given [Resolver],
	// checks that the resulting configuration is complete and consistent,
	// and returns the typed configuration value (as any) for use by
	// [Plan] and [Apply].
	Validate(context.Context, State, Resolver) (any, error)

	// Plan computes the difference between the validated configuration
	// (returned by [Validate]) and the instance's current state,
	// returning a set of planned changes without modifying anything.
	Plan(context.Context, any) (Plan, error)

	// Apply materialises the resource using the validated configuration
	// (returned by [Validate]), creating or updating it to match the
	// desired state.
	Apply(context.Context, any) error

	// Destroy tears down the resource and releases its backing
	// infrastructure. It returns an error if the resource cannot be
	// cleanly removed.
	Destroy(context.Context) error

	// Read returns the current live state of the instance. This is
	// used to refresh the manager's cached state and to detect drift
	// from the desired configuration. Implementations may re-read
	// computed fields (e.g. endpoint URLs) from the running infra.
	Read(context.Context) (State, error)

	// References returns the labels of other resources this resource
	// depends on. The runtime must ensure those resources are applied
	// first and destroyed last.
	References() []string
}

type ResourceMeta struct {
	Name       string         `json:"name"`
	Attributes []Attribute    `json:"attributes"`
	Instances  []InstanceMeta `json:"instances"`
}

type State map[string]any

type UpdateResourceInstanceRequest struct {
	Attributes State `json:"attributes,omitempty"` // desired attribute values
	Apply      bool  `json:"apply"`                // false = plan only, true = apply changes
}

type UpdateResourceInstanceResponse struct {
	Instance InstanceMeta `json:"instance"`
	Plan     Plan         `json:"plan"`
}