Documentation
¶
Overview ¶
Package application implements the device-independent Application Binding engine for CloudPath.
An Application Plugin declares Capability Requirements and binds them to stable Entity IDs. Matching and validation consider only Capability ID / version compatibility and tenant scope. The engine must never reference a Driver ID, a serial port, or any concrete hardware field. A binding persists the stable entity_id; renames, Edge reconnects and Driver restarts must not change an existing binding.
The design contract lives in docs/architecture/capability-model.md (Application Binding, Reference Application, Compatibility & Migration and Invariants).
Index ¶
Constants ¶
const ( // CodeMissingRequired means a required (one or one-or-more) requirement has // no bound entity. CodeMissingRequired = "missing_required_capability" // CodeCapabilityMismatch means the bound entity does not provide the // required capability family. CodeCapabilityMismatch = "capability_mismatch" // CodeVersionIncompatible means the entity provides the capability family // but an older/incompatible version. CodeVersionIncompatible = "version_incompatible" // CodeCardinalityViolation means more entities than the cardinality allows. CodeCardinalityViolation = "cardinality_violation" // CodeBelowMinItems means fewer than minItems distinct entities. CodeBelowMinItems = "below_min_items" // CodeDuplicateOccupation means an entity is occupied by multiple // requirements (or slots) while none of them allows reuse. CodeDuplicateOccupation = "duplicate_occupation" // CodeCrossTenant means a binding references an entity outside the // application instance's tenant. CodeCrossTenant = "cross_tenant" // CodeUnknownRequirement means a binding references a requirement id that // the manifest does not declare. CodeUnknownRequirement = "unknown_requirement" // CodeUnknownEntity means a binding references an entity id that is not a // known candidate. CodeUnknownEntity = "unknown_entity" // CodeAmbiguousEntity means an omitted device_id matched multiple providers. CodeAmbiguousEntity = "ambiguous_entity" // CodeEmptyRequirementID means a binding has no requirement id. CodeEmptyRequirementID = "empty_requirement_id" // CodeEmptyEntityID means a binding has no entity id. CodeEmptyEntityID = "empty_entity_id" // CodeInvalidCapability means a capability reference cannot be parsed. CodeInvalidCapability = "invalid_capability" // CodeInvalidRequirement means a declared requirement violates the contract. CodeInvalidRequirement = "invalid_requirement" )
Machine-readable issue codes.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Binder ¶
Binder carries the tenant scope and instance identity for a binding operation. Matching uses Capability, tenant and the Core-only provider identity. It never couples the Application Protocol to a Driver.
func (Binder) Match ¶
func (b Binder) Match(requirements []Requirement, candidates []Candidate) (BindingSet, error)
Match auto-selects a candidate for every requirement within the binder's tenant scope. The returned binding retains Candidate.DeviceID so later command effects can be routed to the exact provider selected here.
func (Binder) Validate ¶
func (b Binder) Validate(requirements []Requirement, candidates []Candidate, bindings []Binding) ValidationResult
type Binding ¶
type Binding struct {
RequirementID string `json:"requirement_id" yaml:"requirement_id"`
EntityID string `json:"entity_id" yaml:"entity_id"`
DeviceID string `json:"device_id,omitempty" yaml:"device_id,omitempty"`
}
Binding pairs a Requirement with the stable entity/provider that satisfies it. DeviceID is optional for backward compatibility: when omitted, legacy single-provider bindings remain valid only if EntityID resolves uniquely.
type BindingError ¶
type BindingError struct {
Result ValidationResult
}
BindingError wraps a failed binding validation so callers can branch on machine-readable codes. It implements error.
func (*BindingError) Error ¶
func (e *BindingError) Error() string
Error returns a compact summary of the failing codes.
type BindingSet ¶
type BindingSet struct {
ApplicationID string `json:"application_id"`
PluginInstanceID string `json:"plugin_instance_id"`
TenantID string `json:"tenant_id"`
Bindings []Binding `json:"bindings"`
}
BindingSet is the set of Bindings for one Application instance in a tenant.
type Candidate ¶
type Candidate struct {
EntityID string `json:"entity_id" yaml:"entity_id"`
Name string `json:"name,omitempty" yaml:"name,omitempty"`
TenantID string `json:"tenant_id" yaml:"tenant_id"`
Capabilities []string `json:"capabilities" yaml:"capabilities"`
// DeviceID is Core's stable device key ("<edge>/<device>"). It is carried
// with a binding but is not sent to Application Protocol v1.
DeviceID string `json:"device_id,omitempty" yaml:"device_id,omitempty"`
// DriverID is metadata only. Not used for matching.
DriverID string `json:"driver_id,omitempty" yaml:"driver_id,omitempty"`
}
Candidate is the bindable view of an Entity. EntityID, DeviceID, TenantID and Capabilities participate in matching and validation once an instance has been bound: DeviceID is opaque to the application protocol but is retained by Core so command effects can be routed to the exact provider selected at bind time. Name and DriverID remain observational metadata and never participate in matching.
type Cardinality ¶
type Cardinality string
Cardinality declares how many entities a Requirement accepts.
const ( // CardinalityOne requires exactly one bound entity. CardinalityOne Cardinality = "one" // CardinalityZeroOrOne accepts zero or one bound entity. CardinalityZeroOrOne Cardinality = "zero-or-one" // CardinalityOneOrMore requires at least one bound entity, and at least // minItems distinct entities when minItems is set. CardinalityOneOrMore Cardinality = "one-or-more" )
func (Cardinality) Valid ¶
func (c Cardinality) Valid() bool
Valid reports whether c is a supported cardinality.
type Issue ¶
type Issue struct {
Code string `json:"code"`
RequirementID string `json:"requirement_id,omitempty"`
EntityID string `json:"entity_id,omitempty"`
DeviceID string `json:"device_id,omitempty"`
Message string `json:"message"`
}
Issue is one validation finding with a machine-readable code. The code is stable and intended for Core/UI to branch on; the message is human-facing.
type Requirement ¶
type Requirement struct {
// ID is the requirement's stable identifier within the manifest.
ID string `json:"id" yaml:"id"`
// Capability is the full capability reference, e.g.
// cloudpath.dev/capability/alarm@1.
Capability string `json:"capability" yaml:"capability"`
// Cardinality is the number of entities this requirement accepts.
Cardinality Cardinality `json:"cardinality" yaml:"cardinality"`
// MinItems is the minimum number of distinct entities for one-or-more.
MinItems int `json:"minItems,omitempty" yaml:"minItems,omitempty"`
// AllowReuse permits the same entity to satisfy multiple requirements (or
// multiple slots of this requirement). Default false means an entity may be
// occupied by at most one requirement slot.
AllowReuse bool `json:"allow_reuse,omitempty" yaml:"allow_reuse,omitempty"`
}
Requirement is one Capability the Application needs. Matching resolves each Requirement to a Candidate Entity.
func (Requirement) Validate ¶
func (r Requirement) Validate() error
Validate checks a Requirement against the binding contract.
type ValidationResult ¶
ValidationResult aggregates binding validation findings.
func (ValidationResult) HasCode ¶
func (r ValidationResult) HasCode(code string) bool
HasCode reports whether any issue carries the given machine-readable code.
Source Files