Documentation
¶
Overview ¶
Package deploy assembles a deployment from a resource+agent document: the Document DTO (resources forming a dependency DAG, agents binding them), and the Builder with two phases: Build constructs resources in topological order, Wire attaches observers and hooks and binds agents. Builder.Deploy runs both.
The package imports only core packages: the resource protocol (resource) and error classification (errdefs). It knows no concrete resource kind.
Index ¶
- func BindAgent(ctx context.Context, reg *resource.Registry, result *Result, ...) (*agent.Agent, error)
- func LoadLayers(ctx context.Context, layers []Layer) (Document, Provenance, error)
- type Builder
- type BuilderOption
- type Document
- type External
- type ExternalResource
- type Layer
- type LayerRef
- type Provenance
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BindAgent ¶ added in v0.1.11
func BindAgent( ctx context.Context, reg *resource.Registry, result *Result, loader *resource.Loader, resolver *resource.ReferenceResolver, secrets *resource.SecretResolver, name string, def agent.Definition, ) (*agent.Agent, error)
BindAgent assembles one agent.Agent from its Definition: the engine from the registry (kind = EngineRef.Kind / Impl), then each hook under "hook.<slot>", wiring resource.Wireable hooks before recording them on the agent. It never mutates result (result.agents stays untouched), so callers decide where the assembled agent is recorded — deployment build records it on the Result, while core/runtime registers it in the live agent registry.
On failure, every component already constructed (engine and any wired hooks) is closed in reverse order so a partial assembly never leaks attached subscriptions or other resources.
func LoadLayers ¶
LoadLayers loads every layer with its own loader (file refs resolve against that layer's BaseDir), merges them in ascending priority order, and returns the merged document plus provenance.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder constructs a deployment's resources from a Document using an explicit resource.Registry. The registry is owned by the caller; Builder never touches global state.
func NewBuilder ¶
func NewBuilder(registry *resource.Registry, opts ...BuilderOption) *Builder
NewBuilder returns a Builder over registry. A nil registry yields an empty one.
func (*Builder) Build ¶
Build validates the document, resolves the resource DAG, and constructs every resource in dependency order. On failure, values already built are closed in reverse construction order (rollback).
func (*Builder) Deploy ¶
Deploy is the convenience entry point: Build, then Wire. On wire failure every built value is closed before returning.
func (*Builder) Wire ¶
Wire runs the post-build wiring phase: resource values implementing resource.Wireable attach themselves (observers to buses, hooks to streams), then every agent is bound from its engine and hooks, and finally values implementing resource.DeploymentBinder receive the assembled deployment (agents included). Wire never participates in the construction DAG, so observed values never depend on their observers.
type BuilderOption ¶
type BuilderOption func(*Builder)
BuilderOption configures a Builder.
func WithExternalResources ¶ added in v0.2.6
func WithExternalResources(externals []ExternalResource) BuilderOption
WithExternalResources configures the builder with caller-owned dependency values. Values are copied by reference: deploy never closes or mutates them. Multiple calls accumulate; duplicates are rejected at Build time.
func WithLoader ¶
func WithLoader(loader *resource.Loader) BuilderOption
WithLoader supplies the deployment-level loader used to materialize settings subtrees that are {"file":…} / {"embed":…} references, and passed to factories for their own source resolution.
func WithResolver ¶ added in v0.2.0
func WithResolver(resolver *resource.ReferenceResolver) BuilderOption
WithResolver adds custom schemes to the expansion used for inline ${scheme:ref} strings in every settings subtree (resources, agent engine, agent hooks) before a factory decodes them. The custom schemes are merged on top of the all-open default resolver (env + home, plus base when the loader declares a base directory); a custom scheme with the same name overrides the built-in one.
func WithSecretCacheTTL ¶ added in v0.2.0
func WithSecretCacheTTL(ttl time.Duration) BuilderOption
WithSecretCacheTTL sets how long lazy secret lookups reuse a cached value before hitting the backend again. Zero keeps the default (one minute); a negative value disables caching.
type Document ¶
type Document struct {
Version string `json:"version,omitempty"`
Resources resource.Resources `json:"resources,omitempty"`
Agents map[string]agent.Definition `json:"agents,omitempty"`
// Runtime is an application-runtime-owned configuration subtree.
// Parse preserves it verbatim so the runtime layer can decode it
// strictly without weakening strictness for the deployment schema.
Runtime *resource.Opaque `json:"runtime,omitempty"`
}
Document is the top-level deployment DTO: a versioned resource area (the DAG) plus an agent area binding resources.
func Parse ¶
Parse decodes one deployment document from YAML or JSON into a Document. It applies the shared strict semantics of core/utils: JSON is detected by the Kubernetes rule (first non-whitespace byte is an open brace), YAML is converted strictly, unknown fields are rejected, and a trailing document is an error. After decoding, Parse validates the document semantically (version, resources, agents).
type External ¶ added in v0.2.6
type External struct {
// Name is the resource-ref name used in document deps, e.g. "db".
Name string `json:"name"`
// Contract is the expected DepSpec.Type of consuming factories,
// e.g. "db.Pool".
Contract string `json:"contract"`
}
External declares one caller-owned dependency supplied to the deployment builder. Externals are visible to dependency resolution but are never constructed, wired, or closed by deploy.
type ExternalResource ¶ added in v0.2.6
ExternalResource pairs one External declaration with the caller-owned value that satisfies it.
func (ExternalResource) Validate ¶ added in v0.2.6
func (e ExternalResource) Validate() error
Validate checks the declaration and rejects nil values.
type Layer ¶
Layer is one configuration layer. Layers are merged in ascending Priority order, so a higher priority layer overrides a lower one. The lowest-priority layer must be a complete document (with version); later layers may be partial.
type Provenance ¶
type Provenance struct {
Resources map[string]LayerRef `json:"resources"`
Agents map[string]LayerRef `json:"agents"`
}
Provenance records which layer provided each top-level resource and agent in the merged document: the highest-priority layer that declared the key.
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result owns the built resource values in construction order. The caller closes it (or the runtime layer closes it) when done.
func (*Result) AgentNames ¶
AgentNames returns the sorted bound agent names.
func (*Result) Close ¶
Close closes every io.Closer resource value in reverse construction order, then closes every bound agent (engine and lifecycle hooks).
func (*Result) Detach ¶ added in v0.1.14
Detach marks resource names as caller-owned: Result.Close will not close them, and the caller takes over their lifecycle. It is used by the runtime to reject a reload whose event bus factory returned the current generation's bus without letting the aborted result close a bus another generation still uses.
Source Files