Documentation
¶
Overview ¶
Package platform provides optional multi-Deployment catalog, routing, and governance capabilities above the Agent Engine.
Catalog snapshots contain exact immutable Deployment bindings and implement agent.DeploymentResolver without owning Process lifecycle. Mutable deployment commands and routing policy build on these snapshots; application persistence, product policy, and observation backends remain outside this package.
Index ¶
- Variables
- type Catalog
- type DeploymentCandidate
- type DeploymentConflictError
- type DeploymentSelector
- type DeploymentSelectorFunc
- type Platform
- func (p *Platform) Catalog() Catalog
- func (p *Platform) Deploy(deployment agent.Deployment) error
- func (p *Platform) DeploymentCandidates() []DeploymentCandidate
- func (p *Platform) Replace(deployment agent.Deployment) error
- func (p *Platform) Resolve(reference agent.DeploymentRef) (agent.Deployment, error)
- func (p *Platform) SelectDeployment(ctx context.Context, selector DeploymentSelector) (agent.Deployment, error)
- func (p *Platform) Undeploy(reference agent.DeploymentRef) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidCatalog = errors.New("platform: invalid deployment catalog") ErrDeploymentNotFound = errors.New("platform: deployment not found") )
Functions ¶
This section is empty.
Types ¶
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog is an immutable snapshot of exact Deployment bindings. It contains no active route, mutable registry, Process ownership, or remote discovery. The zero value is an empty catalog. Catalog values are safe for concurrent lookup and enumeration.
func NewCatalog ¶
func NewCatalog(deployments ...agent.Deployment) (Catalog, error)
NewCatalog indexes Deployments by exact reference so recovery resolves the Deployment a snapshot was taken from. Registration is all-or-nothing, which keeps a duplicate reference from leaving a catalog that resolves the same identity two ways.
Example ¶
package main
import (
"fmt"
"github.com/Tangerg/scope/agent/platform"
)
func main() {
catalog, err := platform.NewCatalog()
if err != nil {
panic(err)
}
fmt.Println(len(catalog.Deployments()))
}
Output: 0
func (Catalog) Deployments ¶
func (c Catalog) Deployments() []agent.Deployment
Deployments returns all exact bindings in stable Definition-name and Deployment-digest order. The returned slice is independently owned and may be modified by the caller.
func (Catalog) Resolve ¶
func (c Catalog) Resolve(reference agent.DeploymentRef) (agent.Deployment, error)
Resolve returns the Deployment bound to one exact reference. It performs no routing or name fallback and satisfies agent.DeploymentResolver.
type DeploymentCandidate ¶
type DeploymentCandidate struct {
// contains filtered or unexported fields
}
DeploymentCandidate is one non-executable active binding offered to a DeploymentSelector. It exposes the exact identity and static Definition contract, never Dispatcher or Process lifecycle capabilities.
func (DeploymentCandidate) DeploymentRef ¶
func (d DeploymentCandidate) DeploymentRef() agent.DeploymentRef
DeploymentRef returns the candidate's exact immutable Deployment identity.
func (DeploymentCandidate) Descriptor ¶
func (d DeploymentCandidate) Descriptor() agent.Descriptor
Descriptor returns the candidate's frozen static Definition contract.
type DeploymentConflictError ¶
type DeploymentConflictError struct {
// Active is the exact binding currently occupying the name slot.
Active agent.DeploymentRef
// Requested is the exact binding the caller attempted to deploy or undeploy.
Requested agent.DeploymentRef
}
DeploymentConflictError identifies the active and requested exact bindings that collided in one Definition-name slot.
func (*DeploymentConflictError) Error ¶
func (d *DeploymentConflictError) Error() string
func (*DeploymentConflictError) Unwrap ¶
func (*DeploymentConflictError) Unwrap() error
type DeploymentSelector ¶
type DeploymentSelector interface {
// Select chooses exactly one DeploymentRef from the detached candidate slice
// supplied for this call. It may perform caller-owned I/O, must honor ctx, and
// must be concurrency-safe when shared. Invalid or unoffered references are
// rejected by Platform after the call returns.
Select(ctx context.Context, candidates []DeploymentCandidate) (agent.DeploymentRef, error)
}
DeploymentSelector chooses one exact reference from a stable active candidate snapshot. Implementations may perform external I/O, must honor ctx, and must be safe for concurrent calls when shared. Request-specific routing input belongs to the implementation rather than a Framework payload type.
type DeploymentSelectorFunc ¶
type DeploymentSelectorFunc func( ctx context.Context, candidates []DeploymentCandidate, ) (agent.DeploymentRef, error)
DeploymentSelectorFunc adapts a plain function to the selector interface. Selection is a host policy — by tenant, cost, or availability — so the platform takes it as a value rather than owning a routing table.
func (DeploymentSelectorFunc) Select ¶
func (d DeploymentSelectorFunc) Select( ctx context.Context, candidates []DeploymentCandidate, ) (agent.DeploymentRef, error)
type Platform ¶
type Platform struct {
// contains filtered or unexported fields
}
Platform owns atomic deployment changes, active name slots, and an exact historical Catalog above Engine. It does not own Process lifecycle or Host persistence. Its zero value is an empty usable Platform. A Platform must not be copied after first use.
func New ¶
func New(deployments ...agent.Deployment) (*Platform, error)
New assembles the optional multi-Deployment container. It is separate from agent.Engine because routing, catalog, and governance are not needed to run a Process, and an embedded host should not have to accept them to get execution.
func (*Platform) Catalog ¶
Catalog returns the current immutable exact binding snapshot. Historical Deployments remain present after Replace and Undeploy.
func (*Platform) Deploy ¶
func (p *Platform) Deploy(deployment agent.Deployment) error
Deploy activates deployment in its Definition-name slot. Reapplying the exact active binding leaves the Platform unchanged; a different exact binding in the same slot returns ErrDeploymentConflict and requires Replace.
func (*Platform) DeploymentCandidates ¶
func (p *Platform) DeploymentCandidates() []DeploymentCandidate
DeploymentCandidates returns a stable snapshot of active, non-executable candidates. Replaced, undeployed, and other historical Catalog bindings are intentionally excluded. The returned slice is independently owned.
func (*Platform) Replace ¶
func (p *Platform) Replace(deployment agent.Deployment) error
Replace changes the active exact binding in deployment's existing name slot. The previous binding remains in Catalog for exact restoration.
func (*Platform) Resolve ¶
func (p *Platform) Resolve(reference agent.DeploymentRef) (agent.Deployment, error)
Resolve performs one exact lookup against the current immutable Catalog and satisfies agent.DeploymentResolver. Inactive historical bindings remain resolvable so Process restoration never follows an active route by mistake.
func (*Platform) SelectDeployment ¶
func (p *Platform) SelectDeployment( ctx context.Context, selector DeploymentSelector, ) (agent.Deployment, error)
SelectDeployment asks selector to choose from one stable active snapshot and returns the exact Deployment captured in that snapshot. Concurrent Replace or Undeploy cannot redirect the completed selection to a different binding.
func (*Platform) Undeploy ¶
func (p *Platform) Undeploy(reference agent.DeploymentRef) error
Undeploy removes reference only when it is the exact active binding in its name slot. A stale reference returns ErrDeploymentConflict instead of deactivating a replacement. The exact binding remains in Catalog.
Source Files