Documentation
¶
Overview ¶
Package extension implements an explicit, immutable linked registry and reference-preserving module configuration. It never loads runtime code.
The candidate protected value contracts are Descriptor, Error (Code, ModuleID, Field and Error), Manifest, Registration, Factory, Resource, Envelope, PreparedConfig, Snapshot, Lease, Persistence, Registry and Manager. Their exported fields and callback signatures form part of their contracts. The designated functions/methods are NewRegistry, NewManager; Registry.Manifest, Registry.Validate, Registry.ExpandConfig; Snapshot.Config, Snapshot.Resource, Snapshot.Context; Lease.Release; Manager.Acquire, Manager.List, Manager.Manifest, Manager.Put, Manager.Delete, Manager.Health, Manager.Close and Manager.SetPublisher. Other exported helpers are not designated. F5 designates StatefulResource and Snapshot.Sequence. Reconciliation only changes unpublished candidate identity; reset metadata is emitted after commit. F4 also designates AdminRoute, OwnedAdminRoute, AdminDependencies, AdminContributor, WriteAdminError, Registry.AdminRoutes, Manager.AdminRoutes and Manager.AdminPublisher. Factory.AdminRoutes is an immutable declaration set; only prepared resources handle requests, with leases and the same generation lifecycle. Release protection requires a published tag with the consumer contract gates described in docs/design/enterprise-extension-contract.md.
A metadata-only registration has no Factory and cannot accept configuration. Validation-only factories may omit Prepare; a server rejects their envelopes. Validate and Dependencies receive a context and must perform strict module schema checks without resolving references or exposing arbitrary diagnostics. Prepare receives reference-preserving JSON, a separate resolved-secret map, and only declared dependency resources prepared for the candidate generation. Preparation never mutates the live generation. Its context has a five-second maximum; Snapshot.Context is the separate resource lifetime.
Successful persistence precedes infallible publication. Requests retain their generation with Acquire/Release. Retirement closes resources in reverse order after drain or deadline. Close stops admissions and cancels ongoing preparation before waiting for a mutation. Already committed writes finalize and retire their generation without reopening admissions. Close shares its bounded deadline with all generations. Lifecycle errors and panics report bounded diagnostics. Callbacks must honor cancellation; a deadline cannot make invalid module code terminate. Such code is nonconforming and Close reports failure.
Index ¶
- Constants
- func DecodeObject(raw json.RawMessage) (any, error)
- func ValidID(s string) bool
- func WriteAdminError(w http.ResponseWriter, status int, code string)
- type AdminContributor
- type AdminDependencies
- type AdminRoute
- type Descriptor
- type Envelope
- type Error
- type Factory
- type Lease
- type Manager
- func (m *Manager) Acquire() (*Lease, error)
- func (m *Manager) AdminPublisher(id string) func(context.Context) event.Publisher
- func (m *Manager) AdminRoutes() []OwnedAdminRoute
- func (m *Manager) Close(ctx context.Context) error
- func (m *Manager) Delete(ctx context.Context, id string) (result error)
- func (m *Manager) Health(ctx context.Context) error
- func (m *Manager) List() []Envelope
- func (m *Manager) Manifest() Manifest
- func (m *Manager) Put(ctx context.Context, e Envelope) (result error)
- func (m *Manager) SetPublisher(p event.Publisher)
- type Manifest
- type OwnedAdminRoute
- type Persistence
- type PreparedConfig
- type Registration
- type Registry
- type Resource
- type Snapshot
- type StatefulResource
Constants ¶
const LifecycleBudget = 5 * time.Second
Variables ¶
This section is empty.
Functions ¶
func DecodeObject ¶
func DecodeObject(raw json.RawMessage) (any, error)
DecodeObject enforces the common size/depth boundary before module decoding.
func WriteAdminError ¶
func WriteAdminError(w http.ResponseWriter, status int, code string)
WriteAdminError writes bounded JSON without arbitrary callback diagnostics.
Types ¶
type AdminContributor ¶
type AdminContributor interface {
ServeAdminHTTP(http.ResponseWriter, *http.Request, AdminDependencies)
}
AdminContributor is implemented by a prepared Resource whose factory declares AdminRoutes. Handlers use r.Pattern/PathValue to dispatch; they must honor request cancellation, be concurrency-safe and use WriteAdminError for bounded errors. Health and Close are inherited from Resource. The generation lease covers the whole handler call and its context is canceled on bounded generation retirement.
type AdminDependencies ¶
type AdminDependencies struct {
Config Envelope
Logger *zap.Logger
Attribution func(context.Context) (attribution.Value, bool)
Events event.Publisher
}
AdminDependencies is request-scoped. Config is an owned, reference-preserving copy, never resolved secrets. Events accepts only this owner's typed mutation events and stamps the current trusted attribution. No gateway/store is exposed.
type AdminRoute ¶
AdminRoute declares a method/path owned by its registration's module. Paths are absolute, with literal segments or single-segment {name} wildcards. Subtree, host, multi-segment wildcard and root-envelope routes are unsupported. GET also owns HEAD. Overlapping declarations are rejected, even if one would be more specific in net/http's mux.
type Descriptor ¶
type Descriptor struct {
ID string `json:"id"`
Version string `json:"version"`
SchemaVersion int `json:"schema_version"`
Capabilities []string `json:"capabilities,omitempty"`
Dependencies []string `json:"dependencies,omitempty"`
Roles []string `json:"roles,omitempty"`
}
Descriptor describes a module explicitly linked by a distribution's main. It contains no factory pointers, secrets, entitlement or customer state.
type Envelope ¶
type Envelope struct {
ModuleID string `json:"module_id"`
SchemaVersion int `json:"schema_version"`
Config json.RawMessage `json:"config"`
}
Envelope retains ConfigStore-owned module JSON and unresolved secret references.
type Error ¶
type Error struct {
Code string `json:"code"`
ModuleID string `json:"module_id,omitempty"`
Field string `json:"field,omitempty"`
}
Error carries bounded, secret-free diagnostics. Codes are stable; Error never incorporates errors returned by module callbacks.
type Factory ¶
type Factory struct {
AdminRoutes []AdminRoute
SecretFields []string
Validate func(context.Context, json.RawMessage) (json.RawMessage, error)
Dependencies func(context.Context, json.RawMessage) ([]string, error)
Prepare func(context.Context, PreparedConfig, Snapshot) (Resource, error)
}
Factory validates reference-preserving JSON and prepares owned resources. Callbacks must honor cancellation and must never mutate a live snapshot. Validate may apply defaults, but must retain every declared secret reference.
type Lease ¶
type Lease struct {
Snapshot Snapshot
// contains filtered or unexported fields
}
Lease retains an admitted generation until Release. Release is idempotent.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager serializes mutations and publishes complete immutable generations. It never resolves registries or reads storage during snapshot acquisition.
func NewManager ¶
NewManager loads persisted configuration and prepares a complete generation before returning. Startup failure closes all resources already prepared.
func (*Manager) Acquire ¶
Acquire performs only generation ownership bookkeeping. No registry/storage reads or callback invocations occur on this path.
func (*Manager) AdminPublisher ¶
AdminPublisher binds a validated owner once during HTTP assembly and returns a request binder. Each invocation captures the trusted request context without registry/configuration reads. Publish's context controls cancellation/delivery only: a contributor cannot replace the captured request actor or correlation.
func (*Manager) AdminRoutes ¶
func (m *Manager) AdminRoutes() []OwnedAdminRoute
AdminRoutes snapshots the linked registry declarations once during HTTP assembly.
func (*Manager) Close ¶
Close stops admissions, retires all generations, and waits within caller and five-second deadlines. Module cancellation violations return deadline errors.
func (*Manager) Put ¶
Put prepares a complete dependency generation, persists only the changed envelope, then performs an infallible in-memory publication.
func (*Manager) SetPublisher ¶
SetPublisher binds the existing pipeline authority during bootstrap.
type Manifest ¶
type Manifest struct {
Modules []Descriptor `json:"modules"`
}
Manifest is a deterministic metadata projection, with no executable pointers.
type OwnedAdminRoute ¶
type OwnedAdminRoute struct {
ModuleID string
AdminRoute
}
OwnedAdminRoute is the immutable registry projection used at Admin assembly.
type Persistence ¶
type Persistence interface {
List(context.Context) ([]Envelope, error)
Put(context.Context, Envelope, bool) error
Delete(context.Context, string) error
}
Persistence is implemented by the existing schema-bound ConfigStore adapter. Operations must honor context; failed writes must leave persisted state intact.
type PreparedConfig ¶
PreparedConfig carries tokens separately from resolved secrets. Only Prepare receives Secrets; they must never be copied into envelopes or diagnostics.
type Registration ¶
type Registration struct {
Descriptor Descriptor
Factory *Factory
}
Registration binds a descriptor to optional configuration behavior. A nil Factory is valid for metadata-only modules; their envelopes are rejected.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is immutable after construction and owns all descriptor slices.
func NewRegistry ¶
func NewRegistry(registrations ...Registration) (*Registry, error)
NewRegistry validates all registrations and resolves dependencies before any callback executes. Empty registries are valid; nil registrations are not.
func (*Registry) AdminRoutes ¶
func (r *Registry) AdminRoutes() []OwnedAdminRoute
AdminRoutes returns copies of the complete, validated declaration set. The literal module namespace makes contributions disjoint from all Community route families, including the separate AgentRoute mux and envelope roots.
func (*Registry) ExpandConfig ¶
ExpandConfig classifies every declared reference before expanding ordinary ${NAME} values. Reference objects survive unchanged, set or unset. This is for local declarative files, not server secret resolution.
type Resource ¶
Resource belongs to a generation. All reads must be concurrency-safe and Health/Close must honor their context. Close is called once per preparation.
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot gives module preparation immutable access to already prepared dependencies. Resource values are module-owned concurrency-safe handles.
type StatefulResource ¶
StatefulResource reconciles candidate domain state before persistence. It may copy an identity from previous into the unpublished receiver, but must never change previous or any active state. true reports a reset on successful commit. Removal of such a resource also reports a reset. Panics fail preparation.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package contracttest supplies reusable candidate extension contract suites.
|
Package contracttest supplies reusable candidate extension contract suites. |