Help us shape the future of Go! Take the 2026 Go Developer Survey

capability

package
v0.4.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 19, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source
const ProviderProtocolV1 = "baseharbor.provider/v1"
View Source
const RegistryVersion = 1

Variables

View Source
var (
	PostgreSQL = Provider{Kind: ProviderPostgreSQL, Capabilities: []Kind{SQL}}
	Valkey     = Provider{Kind: ProviderValkey, Capabilities: []Kind{KeyValue}}
	OpenBao    = Provider{Kind: ProviderOpenBao, Capabilities: []Kind{Secrets}}
	Caddy      = Provider{Kind: ProviderCaddy, Capabilities: []Kind{ExposureHTTP}}
	SeaweedFS  = Provider{Kind: ProviderSeaweedFS, Capabilities: []Kind{ObjectStorageS3}}
)

Reference providers describe the capability products already used by the current Compose implementation. They are descriptors only: existing provisioning remains authoritative while the shared capability and provider registry layers describe portable intent, placement and ownership.

View Source
var (
	PostgreSQLIntegration = IntegrationDescriptor{
		Protocol: ProviderProtocolV1, Provider: PostgreSQL,
		Capabilities: []SpecificationID{SQLV1.ID},
	}
	ValkeyIntegration = IntegrationDescriptor{
		Protocol: ProviderProtocolV1, Provider: Valkey,
		Capabilities: []SpecificationID{KeyValueV1.ID},
	}
	OpenBaoIntegration = IntegrationDescriptor{
		Protocol: ProviderProtocolV1, Provider: OpenBao,
		Capabilities: []SpecificationID{SecretsV1.ID},
		Optional:     OptionalLifecycleSupport{Status: true, Update: true, Backup: true, Restore: true, Destroy: true},
	}
	CaddyIntegration = IntegrationDescriptor{
		Protocol: ProviderProtocolV1, Provider: Caddy,
		Capabilities: []SpecificationID{ExposureHTTPV1.ID},
		Optional:     OptionalLifecycleSupport{Status: true, Update: true, Destroy: true},
	}
	SeaweedFSIntegration = IntegrationDescriptor{
		Protocol: ProviderProtocolV1, Provider: SeaweedFS,
		Capabilities: []SpecificationID{ObjectStorageS3V1.ID},
		Optional:     OptionalLifecycleSupport{Status: true, Update: true, Destroy: true},
	}
)
View Source
var (
	SQLV1             = CapabilitySpecification{ID: "database.sql/v1", Kind: SQL, Version: SpecificationV1}
	KeyValueV1        = CapabilitySpecification{ID: "cache.key-value/v1", Kind: KeyValue, Version: SpecificationV1}
	SecretsV1         = CapabilitySpecification{ID: "secrets/v1", Kind: Secrets, Version: SpecificationV1}
	ExposureHTTPV1    = CapabilitySpecification{ID: "exposure.http/v1", Kind: ExposureHTTP, Version: SpecificationV1}
	ObjectStorageS3V1 = CapabilitySpecification{ID: "object-storage.s3/v1", Kind: ObjectStorageS3, Version: SpecificationV1}
)

Functions

func Prepare added in v0.4.4

func Prepare(ctx context.Context, application string, requests []Request) (*Execution, Result, error)

func RequireIntegrationContract added in v0.4.3

func RequireIntegrationContract(descriptor IntegrationDescriptor) error

Types

type AuthorizationMetadata added in v0.4.5

type AuthorizationMetadata struct {
	Audience string   `json:"audience,omitempty"`
	Scopes   []string `json:"scopes,omitempty"`
}

type Binding

type Binding struct {
	Resource        Resource                `json:"resource"`
	Workload        string                  `json:"workload"`
	HTTPExposure    *HTTPExposureBinding    `json:"http_exposure,omitempty"`
	ObjectStorageS3 *ObjectStorageS3Binding `json:"object_storage_s3,omitempty"`
	Security        *SecureBinding          `json:"security,omitempty"`
}

type CapabilitySpecification added in v0.4.3

type CapabilitySpecification struct {
	ID      SpecificationID      `json:"id"`
	Kind    Kind                 `json:"kind"`
	Version SpecificationVersion `json:"version"`
}

func ParseSpecificationID added in v0.4.3

func ParseSpecificationID(id SpecificationID) (CapabilitySpecification, error)

func SpecificationForKind added in v0.4.3

func SpecificationForKind(kind Kind) (CapabilitySpecification, error)

type ConformanceCheck added in v0.4.3

type ConformanceCheck struct {
	Name    string            `json:"name"`
	Status  ConformanceStatus `json:"status"`
	Message string            `json:"message,omitempty"`
}

type ConformanceReport added in v0.4.3

type ConformanceReport struct {
	Protocol string             `json:"protocol"`
	Provider ProviderKind       `json:"provider"`
	Status   ConformanceStatus  `json:"status"`
	Checks   []ConformanceCheck `json:"checks"`
}

func CheckIntegrationContract added in v0.4.3

func CheckIntegrationContract(descriptor IntegrationDescriptor) ConformanceReport

CheckIntegrationContract performs transport-independent static conformance. Runtime capability conformance remains provider/capability specific and will build on this report as reference providers are added.

type ConformanceStatus added in v0.4.3

type ConformanceStatus string
const (
	ConformancePass ConformanceStatus = "pass"
	ConformanceFail ConformanceStatus = "fail"
)

type CredentialReference added in v0.4.5

type CredentialReference struct {
	Name      string `json:"name"`
	Reference string `json:"reference"`
}

type Diagnostic

type Diagnostic struct {
	Code     string   `json:"code"`
	Severity Severity `json:"severity"`
	Message  string   `json:"message"`
}

type Driver

type Driver interface {
	Descriptor() Provider
	Preflight(context.Context, Resource, Binding) error
	Provision(context.Context, Resource, Binding) error
	Bind(context.Context, Resource, Binding) error
	Verify(context.Context, Resource, Binding) error
}

type DriverAdapter added in v0.4.3

type DriverAdapter struct {
	// contains filtered or unexported fields
}

DriverAdapter lets current built-in drivers participate in the integration contract without changing their implementation or introducing a second lifecycle engine.

func NewDriverAdapter added in v0.4.3

func NewDriverAdapter(driver Driver, descriptor IntegrationDescriptor) (*DriverAdapter, error)

func (*DriverAdapter) Bind added in v0.4.3

func (a *DriverAdapter) Bind(ctx context.Context, resource Resource, binding Binding) error

func (*DriverAdapter) Descriptor added in v0.4.3

func (a *DriverAdapter) Descriptor() Provider

func (*DriverAdapter) IntegrationDescriptor added in v0.4.3

func (a *DriverAdapter) IntegrationDescriptor() IntegrationDescriptor

func (*DriverAdapter) Preflight added in v0.4.3

func (a *DriverAdapter) Preflight(ctx context.Context, resource Resource, binding Binding) error

func (*DriverAdapter) Provision added in v0.4.3

func (a *DriverAdapter) Provision(ctx context.Context, resource Resource, binding Binding) error

func (*DriverAdapter) Verify added in v0.4.3

func (a *DriverAdapter) Verify(ctx context.Context, resource Resource, binding Binding) error

type Execution added in v0.4.4

type Execution struct {
	// contains filtered or unexported fields
}

Execution is one prepared provider lifecycle. Prepare performs all resolution/preflight work without mutation. ProvisionAndBind and Verify can then be coordinated around runtime/workload convergence without duplicating provider lifecycle semantics.

func (*Execution) ProvisionAndBind added in v0.4.4

func (e *Execution) ProvisionAndBind(ctx context.Context) (Result, error)

func (*Execution) Verify added in v0.4.4

func (e *Execution) Verify(ctx context.Context) (Result, error)

type HTTPExposureBinding added in v0.4.4

type HTTPExposureBinding struct {
	Service    string `json:"service"`
	TargetPort int    `json:"target_port"`
	Protocol   string `json:"protocol"`
	Visibility string `json:"visibility"`
}

type IntegrationDescriptor added in v0.4.3

type IntegrationDescriptor struct {
	Protocol     string                   `json:"protocol"`
	Provider     Provider                 `json:"provider"`
	Capabilities []SpecificationID        `json:"capabilities"`
	Optional     OptionalLifecycleSupport `json:"optional_lifecycle"`
}

func ReferenceIntegration added in v0.4.3

func ReferenceIntegration(provider ProviderKind) (IntegrationDescriptor, error)

func (IntegrationDescriptor) Validate added in v0.4.3

func (d IntegrationDescriptor) Validate() error

type IntegrationDriver added in v0.4.3

type IntegrationDriver interface {
	Driver
	IntegrationDescriptor() IntegrationDescriptor
}

IntegrationDriver is the semantic boundary shared by built-in providers and future external provider adapters. The existing Driver lifecycle remains the required mutation path; this interface adds a versioned integration contract.

type Kind

type Kind string

Kind identifies portable application behavior. It describes what an application needs, never which product or runtime satisfies that need.

const (
	SQL             Kind = "database.sql"
	KeyValue        Kind = "cache.key-value"
	Secrets         Kind = "secrets"
	ExposureHTTP    Kind = "exposure.http"
	ObjectStorageS3 Kind = "object-storage.s3"
)

type LifecycleAction added in v0.4.2

type LifecycleAction struct {
	ProviderInstanceID string             `json:"provider_instance_id"`
	Scope              ProviderScope      `json:"scope"`
	Ownership          ProviderOwnership  `json:"ownership"`
	Operation          LifecycleOperation `json:"operation"`
	MutateProvider     bool               `json:"mutate_provider"`
	RemoveBinding      bool               `json:"remove_binding"`
}

type LifecycleOperation added in v0.4.2

type LifecycleOperation string
const (
	LifecycleUpdate  LifecycleOperation = "update"
	LifecycleBackup  LifecycleOperation = "backup"
	LifecycleDestroy LifecycleOperation = "destroy"
)

type ObjectStorageS3Binding added in v0.4.6

type ObjectStorageS3Binding struct {
	Bucket string `json:"bucket"`
}

type OptionalLifecycleSupport added in v0.4.3

type OptionalLifecycleSupport struct {
	Status  bool `json:"status"`
	Update  bool `json:"update"`
	Backup  bool `json:"backup"`
	Restore bool `json:"restore"`
	Destroy bool `json:"destroy"`
}

type Phase

type Phase string
const (
	PhaseResolve   Phase = "resolve"
	PhasePreflight Phase = "preflight"
	PhaseApply     Phase = "apply"
	PhaseBind      Phase = "bind"
	PhaseVerify    Phase = "verify"
)

type Plan

type Plan struct {
	Application string     `json:"application"`
	Items       []PlanItem `json:"items"`
}

func BuildPlan

func BuildPlan(application string, requests []Request) (Plan, error)

type PlanItem

type PlanItem struct {
	Resource Resource `json:"resource"`
	Binding  Binding  `json:"binding"`
}

type Provider

type Provider struct {
	Kind         ProviderKind `json:"kind"`
	Capabilities []Kind       `json:"capabilities"`
}

Provider describes the capability surface of one provider implementation. Placement and ownership stay outside portable capability intent and are represented separately by the provider registry.

func (Provider) Supports

func (p Provider) Supports(kind Kind) bool

type ProviderBinding added in v0.4.2

type ProviderBinding struct {
	Resource           Resource `json:"resource"`
	ProviderInstanceID string   `json:"provider_instance_id"`
}

type ProviderInstance added in v0.4.2

type ProviderInstance struct {
	ID               string            `json:"id"`
	Provider         Provider          `json:"provider"`
	Scope            ProviderScope     `json:"scope"`
	Ownership        ProviderOwnership `json:"ownership"`
	OwnerApplication string            `json:"owner_application,omitempty"`
	Reference        string            `json:"reference,omitempty"`
}

type ProviderKind

type ProviderKind string

ProviderKind identifies a capability implementation. Capability providers are independent from runtime providers such as Compose.

const (
	ProviderPostgreSQL ProviderKind = "postgresql"
	ProviderValkey     ProviderKind = "valkey"
	ProviderOpenBao    ProviderKind = "openbao"
	ProviderCaddy      ProviderKind = "caddy"
	ProviderSeaweedFS  ProviderKind = "seaweedfs"
)

type ProviderOperation added in v0.4.3

type ProviderOperation string
const (
	OperationDescribe  ProviderOperation = "describe"
	OperationPreflight ProviderOperation = "preflight"
	OperationProvision ProviderOperation = "provision"
	OperationBind      ProviderOperation = "bind"
	OperationVerify    ProviderOperation = "verify"
	OperationStatus    ProviderOperation = "status"
	OperationUpdate    ProviderOperation = "update"
	OperationBackup    ProviderOperation = "backup"
	OperationRestore   ProviderOperation = "restore"
	OperationDestroy   ProviderOperation = "destroy"
)

type ProviderOwnership added in v0.4.2

type ProviderOwnership string
const (
	OwnershipBaseHarbor ProviderOwnership = "baseharbor"
	OwnershipExternal   ProviderOwnership = "external"
)

type ProviderScope added in v0.4.2

type ProviderScope string
const (
	ScopeShared      ProviderScope = "shared"
	ScopeApplication ProviderScope = "application"
	ScopeExternal    ProviderScope = "external"
)

type Registry added in v0.4.2

type Registry struct {
	Version   int                `json:"version"`
	Instances []ProviderInstance `json:"instances,omitempty"`
	Bindings  []ProviderBinding  `json:"bindings,omitempty"`
}

func NewRegistry added in v0.4.2

func NewRegistry() Registry

func (Registry) ApplicationLifecycle added in v0.4.2

func (r Registry) ApplicationLifecycle(application string, operation LifecycleOperation) ([]LifecycleAction, error)

func (*Registry) Bind added in v0.4.2

func (r *Registry) Bind(resource Resource, providerInstanceID string) error

func (*Registry) Register added in v0.4.2

func (r *Registry) Register(instance ProviderInstance) error

func (*Registry) ReleaseApplication added in v0.4.2

func (r *Registry) ReleaseApplication(application string)

func (*Registry) ReleaseManagedApplication added in v0.4.2

func (r *Registry) ReleaseManagedApplication(application string)

func (Registry) Resolve added in v0.4.2

func (r Registry) Resolve(provider ProviderKind, scope ProviderScope, application, externalID string) (ProviderInstance, error)

func (Registry) Validate added in v0.4.2

func (r Registry) Validate() error

type RegistryStore added in v0.4.2

type RegistryStore struct{ Path string }

func (RegistryStore) Load added in v0.4.2

func (s RegistryStore) Load() (Registry, error)

func (RegistryStore) Save added in v0.4.2

func (s RegistryStore) Save(registry Registry) error

func (RegistryStore) Update added in v0.4.2

func (s RegistryStore) Update(mutate func(*Registry) error) error

type Request

type Request struct {
	Requirement     Requirement
	Workload        string
	HTTPExposure    *HTTPExposureBinding
	ObjectStorageS3 *ObjectStorageS3Binding
	Security        *SecureBinding
	Driver          Driver
}

type Requirement

type Requirement struct {
	Kind Kind   `json:"kind"`
	Name string `json:"name"`
}

Requirement is one application-owned logical capability request.

type Resource

type Resource struct {
	Application string       `json:"application"`
	Kind        Kind         `json:"kind"`
	Name        string       `json:"name"`
	Provider    ProviderKind `json:"provider"`
}

Resource is the provider-backed representation of one stable logical application resource. Provider-specific object names, ports and credentials are intentionally absent.

func Resolve

func Resolve(application string, requirement Requirement, provider Provider) (Resource, error)

Resolve validates capability negotiation before any provider mutation occurs. It intentionally performs no discovery or provider selection policy; those belong to the later registry layer.

type Result

type Result struct {
	Application string       `json:"application"`
	Status      Status       `json:"status"`
	Plan        Plan         `json:"plan"`
	Steps       []StepResult `json:"steps"`
}

func Run

func Run(ctx context.Context, application string, requests []Request) (Result, error)

Run executes one deterministic capability lifecycle. It is implemented in terms of the staged API so application orchestration and provider tests share exactly one lifecycle implementation.

type SecretReference added in v0.4.5

type SecretReference struct {
	Name      string `json:"name"`
	Reference string `json:"reference"`
}

type SecureBinding added in v0.4.5

type SecureBinding struct {
	Identity      *WorkloadIdentityBinding `json:"identity,omitempty"`
	Credentials   []CredentialReference    `json:"credentials,omitempty"`
	Trust         []TrustMaterialReference `json:"trust,omitempty"`
	Authorization []AuthorizationMetadata  `json:"authorization,omitempty"`
	Secrets       []SecretReference        `json:"secrets,omitempty"`
	Lifecycle     SecurityLifecycleSupport `json:"lifecycle"`
	Diagnostics   []Diagnostic             `json:"diagnostics,omitempty"`
}

SecureBinding carries provider-neutral security metadata required to bind one logical capability resource to one workload. Secret material itself is never represented here; only stable references may cross this boundary.

func (SecureBinding) Validate added in v0.4.5

func (b SecureBinding) Validate() error

Validate rejects ambiguous or unsafe secure-binding metadata before provider mutation. It validates references and metadata shape, not referenced secret values, which are resolved only at the trusted provider/runtime boundary.

type SecurityLifecycleSupport added in v0.4.5

type SecurityLifecycleSupport struct {
	Renewable bool `json:"renewable"`
	Rotatable bool `json:"rotatable"`
	Revocable bool `json:"revocable"`
}

type Severity

type Severity string
const (
	SeverityInfo  Severity = "info"
	SeverityError Severity = "error"
)

type SpecificationID added in v0.4.3

type SpecificationID string

type SpecificationVersion added in v0.4.3

type SpecificationVersion string
const SpecificationV1 SpecificationVersion = "v1"

type Status

type Status string
const (
	StatusReady  Status = "ready"
	StatusFailed Status = "failed"
)

type StepResult

type StepResult struct {
	Phase       Phase        `json:"phase"`
	Status      Status       `json:"status"`
	Resource    Resource     `json:"resource"`
	Binding     Binding      `json:"binding"`
	Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
}

type TrustMaterialReference added in v0.4.5

type TrustMaterialReference struct {
	Name      string `json:"name"`
	Reference string `json:"reference"`
	Format    string `json:"format,omitempty"`
}

type WorkloadIdentityBinding added in v0.4.5

type WorkloadIdentityBinding struct {
	Subject   string `json:"subject"`
	Reference string `json:"reference"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL