pluginreg

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Ownership contracts for composed backend kind/prefix reservation.

Two-stage validation: ValidateManifestOwnership (check-config / pre-activation) and ValidateResolvedOwnership (post-activation, before GenerationRuntime publication). Composition wires these through runtimebundle.

Package pluginreg holds the registry and factory-contract types for plugin registration (backends, frontends, features). The standard distribution tables now live under internal/standardplugins; this package provides the registry mechanism itself.

Index

Constants

View Source 
const (
	CredentialStatic    = lipsdk.CredentialStatic
	CredentialWorkload  = lipsdk.CredentialWorkload
	CredentialOAuthUser = lipsdk.CredentialOAuthUser
	CredentialNone      = lipsdk.CredentialNone
	CredentialUnknown   = lipsdk.CredentialUnknown

	BackendAccessAny       = lipsdk.BackendAccessAny
	BackendAccessLocalOnly = lipsdk.BackendAccessLocalOnly

	BackendExecutionUnknown      = lipsdk.BackendExecutionUnknown
	BackendExecutionInference    = lipsdk.BackendExecutionInference
	BackendExecutionAgentRuntime = lipsdk.BackendExecutionAgentRuntime
)

Credential posture re-exports for call sites that register through Registry.

Variables

View Source 
var ErrDiscoveryFrozen = errors.New("pluginreg: discovery/trust catalog is startup-fixed")

ErrDiscoveryFrozen is returned when reload tries to rescan trusted plugin directories or install connector artifacts after the process-owned discovery catalog was fixed at startup (req 7.3, 8.7).

Functions

func EffectiveAPIKeys 

func EffectiveAPIKeys(yamlKey string, yamlKeys []string, defaults []string) []string

EffectiveAPIKeys merges YAML api_key (first), then api_keys in order: trims, drops empties, de-duplicates by secret string while preserving first-seen order. When the YAML side yields no credentials, defaults (typically from the environment) are used with the same normalization. The returned strings are secrets; callers must not log them.

func ResolveEnabledAgainstRegistry 

func ResolveEnabledAgainstRegistry(enabledFactoryIDs []string, reg *Registry) error

EnabledFactoryIDsFromRegistry reports whether each enabled factory is registered. Prefer this after InstallDiscoveredExports so the registry is the single source of truth.

func ResolveEnabledFactoryIDs 

func ResolveEnabledFactoryIDs(enabledFactoryIDs, availableKinds []string) error

ResolveEnabledFactoryIDs ensures every enabled factory id is present in the union of essential and discovered kinds before runtime construction. Missing kinds fail closed.

func ValidateManifestOwnership 

func ValidateManifestOwnership(in ManifestOwnershipInput) error

ValidateManifestOwnership validates the manifest-available ownership stage without process activation.

func ValidatePrefixSyntax 

func ValidatePrefixSyntax(prefix string) error

ValidatePrefixSyntax checks backend_prefix shape: non-empty after trim and containing neither '/' nor ':'.

func ValidateResolvedOwnership 

func ValidateResolvedOwnership(in ResolvedOwnershipInput) error

ValidateResolvedOwnership validates advertised external route prefixes against the composed catalog before generation publication.

Types

type BackendAccessScope 

type BackendAccessScope = lipsdk.BackendAccessScope

type BackendBuildResult 

type BackendBuildResult struct {
	Backend execbackend.Backend
	Cleanup func() error
}

BackendBuildResult is a composition-owned backend construction outcome. Cleanup is optional and owned by runtimebundle assembly, not by core Backend.

type BackendCredentialMode 

type BackendCredentialMode = lipsdk.BackendCredentialMode

BackendCredentialMode and BackendSecurityProfile are the public plugin registration contract (see lipsdk.BackendCredentialMode, lipsdk.BackendSecurityProfile).

type BackendExecutionClass 

type BackendExecutionClass = lipsdk.BackendExecutionClass

type BackendExecutionProfile 

type BackendExecutionProfile = lipsdk.BackendExecutionProfile

type BackendFactory 

type BackendFactory func(n yaml.Node, upstreamHTTP *http.Client, deps BackendFactoryDeps) (execbackend.Backend, error)

BackendFactory builds a backend from opaque per-plugin YAML, the composition-root HTTP client, and explicit composition-root runtime dependencies.

type BackendFactoryDeps 

type BackendFactoryDeps = GenericBackendFactoryDeps

BackendFactoryDeps is the host dependency surface for in-process backend factories. It aliases GenericBackendFactoryDeps. External executable plugins do not receive this type.

type BackendOwner 

type BackendOwner struct {
	Origin      OriginKind
	FactoryKind string
	InstanceID  string
	Prefix      string
	SourceID    string
}

BackendOwner is an immutable bounded owner descriptor used in collision diagnostics. It never carries secrets or opaque YAML.

type BackendRegistrationSource 

type BackendRegistrationSource string

BackendRegistrationSource is the provenance of a registered backend factory. 

const (
	// BackendSourceBuiltin marks essential in-process composition-root registrations.
	BackendSourceBuiltin BackendRegistrationSource = "builtin"
	// BackendSourceBuiltinCompatible marks dependency-free configurable protocol aliases.
	BackendSourceBuiltinCompatible BackendRegistrationSource = "built_in_compatible"
	// BackendSourceDiscovered marks factories installed from trusted plugin artifacts.
	BackendSourceDiscovered BackendRegistrationSource = "discovered"
)

type BackendReloadPolicy 

type BackendReloadPolicy struct {
	// AllowsCandidateOverlap is true when old and new configured instance
	// handles may coexist. False marks shared-process exclusive kinds that
	// require restart_required before publication when a live instance exists.
	AllowsCandidateOverlap bool
}

BackendReloadPolicy describes whether a factory kind may own concurrent candidate/active instance handles under runtime reload (req 8.8).

type BackendSecurityProfile 

type BackendSecurityProfile = lipsdk.BackendSecurityProfile

type FeatureFactory 

type FeatureFactory func(n yaml.Node) (lipfeature.FeatureBundle, error)

FeatureFactory builds a versioned feature bundle from opaque plugin YAML.

type FrontendMount 

type FrontendMount = lipsdk.FrontendMount

FrontendMount is the stable SDK-named contract (see pkg/lipsdk).

type GenericBackendFactoryDeps 

type GenericBackendFactoryDeps struct {
	Identity identity.Config
}

GenericBackendFactoryDeps is the host dependency surface for essential in-process backend factories. It must not name Codex, OpenCode, ACP-product, or other provider-specific collaborators.

External executable plugins do not receive this type: they receive opaque YAML, secrets, and pkg/lipsdk/backendplugin.RuntimePolicy only.

type LifecycleBackendFactory 

type LifecycleBackendFactory func(instanceID string, n yaml.Node, upstreamHTTP *http.Client, deps BackendFactoryDeps) (BackendBuildResult, error)

LifecycleBackendFactory builds a backend with optional composition-owned cleanup. instanceID is the configured backend row id (routing/executor key); discovered host-backed factories use it for Activate/Configure. Static factories may ignore it.

type ManifestOwnershipInput 

type ManifestOwnershipInput struct {
	BuiltIns       []BackendOwner
	GenericEnabled []BackendOwner
	ManifestKinds  []BackendOwner
}

ManifestOwnershipInput is the check-config / pre-activation stage: built-ins, enabled generic instances, and manifest-discovered external factory kinds without launching plugin processes.

type OriginKind 

type OriginKind string

OriginKind identifies how a backend owner entered the composed catalog. 

const (
	OriginBuiltIn           OriginKind = "built_in"
	OriginBuiltInCompatible OriginKind = "built_in_compatible"
	OriginExternalManifest  OriginKind = "external_manifest"
	OriginExternalResolved  OriginKind = "external_resolved"
)

type OwnershipCollisionError 

type OwnershipCollisionError struct {
	Key    string
	Owners [2]BackendOwner
}

OwnershipCollisionError names both owners of a conflicting kind or prefix.

func (*OwnershipCollisionError) Error 

func (e *OwnershipCollisionError) Error() string

type Registry 

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

Registry holds bundled plugin factories for one composition root. The zero value is an empty registry: lookups behave like an empty bundle, and the first Register* call lazily allocates internal maps (same observable behavior as NewRegistry). Use NewRegistry and [InstallStandardBundleOn] to assemble isolated bundles for each composition root.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) AuthErrorRenderers 

func (r *Registry) AuthErrorRenderers() map[string]lipsdk.AuthErrorRenderer

AuthErrorRenderers returns a defensive copy of optional per-wire-frontend auth error renderers.

func (*Registry) BackendExecutionProfile 

func (r *Registry) BackendExecutionProfile(factoryID string) (BackendExecutionProfile, bool)

BackendExecutionProfile returns execution metadata for a registered backend factory.

func (*Registry) BackendExecutionProfiles 

func (r *Registry) BackendExecutionProfiles() map[string]BackendExecutionProfile

BackendExecutionProfiles returns a defensive copy of all registered backend execution profiles.

func (*Registry) BackendFactoryIDs 

func (r *Registry) BackendFactoryIDs() []string

BackendFactoryIDs returns sorted registered backend factory ids.

func (*Registry) BackendRegistrationSource 

func (r *Registry) BackendRegistrationSource(factoryID string) (BackendRegistrationSource, bool)

BackendRegistrationSource returns bounded provenance for a registered factory.

func (*Registry) BackendReloadPolicy 

func (r *Registry) BackendReloadPolicy(factoryID string) (BackendReloadPolicy, bool)

BackendReloadPolicy returns the reload/overlap policy for a factory kind. Built-in RegisterBackend kinds default to AllowsCandidateOverlap=true.

func (*Registry) BackendSecurityProfile 

func (r *Registry) BackendSecurityProfile(factoryID string) (BackendSecurityProfile, bool)

BackendSecurityProfile returns credential posture metadata for a registered backend factory.

func (*Registry) BuildBackend 

func (r *Registry) BuildBackend(
	factoryID string,
	n yaml.Node,
	upstreamHTTP *http.Client,
	deps BackendFactoryDeps,
) (execbackend.Backend, error)

BuildBackend constructs a backend from r using the factory id (plugin kind). upstreamHTTP is the shared outbound client from the composition root; nil is passed through to factories, which apply defaults where HTTP is required (e.g. Bedrock, ACP).

func (*Registry) BuildBackendWithLifecycle 

func (r *Registry) BuildBackendWithLifecycle(
	factoryID string,
	instanceID string,
	n yaml.Node,
	upstreamHTTP *http.Client,
	deps BackendFactoryDeps,
) (BackendBuildResult, error)

BuildBackendWithLifecycle constructs a backend and optional cleanup for assembly. instanceID is the configured backend instance id for the enabled row.

func (*Registry) BuildFeatureBundle 

func (r *Registry) BuildFeatureBundle(factoryKey string, n yaml.Node) (lipfeature.FeatureBundle, error)

BuildFeatureBundle constructs one feature bundle from YAML by dispatching to the registered feature factory. The featurebundle package provides MergeFeatureSurfaceGenerated and MergeFeatureSurfacesWithHost for merging multiple bundles into generated merge surfaces.

func (*Registry) BuiltinBackendFactoryIDs 

func (r *Registry) BuiltinBackendFactoryIDs() []string

BuiltinBackendFactoryIDs returns sorted factory ids registered as builtins. Discovered artifact exports are omitted so inspect/catalog cannot self-collide.

func (*Registry) DiscoveredBackendIDs 

func (r *Registry) DiscoveredBackendIDs() []string

DiscoveredBackendIDs returns discovered factory kind ids in sorted order.

func (*Registry) DiscoveryFrozen 

func (r *Registry) DiscoveryFrozen() bool

DiscoveryFrozen reports whether the discovery/trust catalog is startup-fixed.

func (*Registry) FreezeDiscovery 

func (r *Registry) FreezeDiscovery()

FreezeDiscovery marks the discovery/trust catalog as process-owned and startup-fixed. Idempotent.

func (*Registry) HasBackend 

func (r *Registry) HasBackend(factoryID string) bool

HasBackend reports whether factoryID is registered on r without exposing the factory.

func (*Registry) IsDiscoveredBackend 

func (r *Registry) IsDiscoveredBackend(factoryID string) bool

IsDiscoveredBackend reports whether factoryID was registered via discovery.

func (*Registry) MountFrontend 

func (r *Registry) MountFrontend(id string, mux *http.ServeMux, opts lipsdk.FrontendMountOptions) error

MountFrontend registers routes for one enabled frontend plugin on r.

func (*Registry) RegisterAuthErrorRenderer 

func (r *Registry) RegisterAuthErrorRenderer(authWireFrontendID string, renderer lipsdk.AuthErrorRenderer) error

RegisterAuthErrorRenderer records an optional transport auth error renderer keyed by the auth wire frontend id (same strings as stdhttp/auth [DefaultFrontendIDFromRequest], e.g. anthropic, openai_compatible, gemini). Nil renderer is a no-op registration attempt (returns nil). Keys are normalized to lowercase. Duplicate wire ids return an error.

func (*Registry) RegisterBackend 

func (r *Registry) RegisterBackend(id string, fn BackendFactory) error

RegisterBackend records a backend factory on r. Duplicate ids return an error: the standard bundle must register each id exactly once.

func (*Registry) RegisterBackendWithProfile 

func (r *Registry) RegisterBackendWithProfile(id string, fn BackendFactory, profile BackendSecurityProfile) error

RegisterBackendWithProfile records a builtin backend factory with credential posture metadata.

func (*Registry) RegisterBackendWithProfiles 

func (r *Registry) RegisterBackendWithProfiles(id string, fn BackendFactory, secProfile BackendSecurityProfile, execProfile BackendExecutionProfile) error

RegisterBackendWithProfiles records a builtin backend factory with credential and execution posture metadata.

func (*Registry) RegisterBackendWithProfilesAndSource 

func (r *Registry) RegisterBackendWithProfilesAndSource(
	id string,
	fn BackendFactory,
	profile BackendSecurityProfile,
	execProfile BackendExecutionProfile,
	source BackendRegistrationSource,
) error

RegisterBackendWithProfilesAndSource records a backend factory with security and execution metadata and provenance.

func (*Registry) RegisterBackendWithSource 

func (r *Registry) RegisterBackendWithSource(id string, fn BackendFactory, profile BackendSecurityProfile, source BackendRegistrationSource) error

RegisterBackendWithSource records a backend factory with bounded composition provenance.

func (*Registry) RegisterDiscoveredBackend 

func (r *Registry) RegisterDiscoveredBackend(
	id string,
	fn BackendFactory,
	profile BackendSecurityProfile,
	policy BackendReloadPolicy,
) error

RegisterDiscoveredBackend records an executable/factory kind discovered at process startup. After FreezeDiscovery, no further discovery registration, directory rescan, or artifact installation is permitted.

func (*Registry) RegisterDiscoveredBackendWithProfiles 

func (r *Registry) RegisterDiscoveredBackendWithProfiles(
	id string,
	fn BackendFactory,
	profile BackendSecurityProfile,
	execProfile BackendExecutionProfile,
	policy BackendReloadPolicy,
) error

RegisterDiscoveredBackendWithProfiles records a discovered backend factory with security and execution metadata.

func (*Registry) RegisterDiscoveredLifecycleBackendWithProfile 

func (r *Registry) RegisterDiscoveredLifecycleBackendWithProfile(id string, fn LifecycleBackendFactory, profile BackendSecurityProfile) error

RegisterDiscoveredLifecycleBackendWithProfile records a lifecycle-aware factory installed from a trusted discovered artifact. Inspect treats these as non-builtins.

func (*Registry) RegisterDiscoveredLifecycleBackendWithProfiles 

func (r *Registry) RegisterDiscoveredLifecycleBackendWithProfiles(id string, fn LifecycleBackendFactory, profile BackendSecurityProfile, execProfile BackendExecutionProfile) error

RegisterDiscoveredLifecycleBackendWithProfiles records a lifecycle-aware factory with security and execution profiles installed from a trusted discovered artifact.

func (*Registry) RegisterFeature 

func (r *Registry) RegisterFeature(id string, fn FeatureFactory) error

RegisterFeature records a feature factory on r.

func (*Registry) RegisterFrontend 

func (r *Registry) RegisterFrontend(id string, fn FrontendMount) error

RegisterFrontend records a frontend mount on r.

func (*Registry) RegisterLifecycleBackend 

func (r *Registry) RegisterLifecycleBackend(id string, fn LifecycleBackendFactory) error

RegisterLifecycleBackend records a lifecycle-aware builtin backend factory.

func (*Registry) RegisterLifecycleBackendWithProfile 

func (r *Registry) RegisterLifecycleBackendWithProfile(id string, fn LifecycleBackendFactory, profile BackendSecurityProfile) error

RegisterLifecycleBackendWithProfile records a lifecycle-aware builtin factory with security profile.

func (*Registry) RegisterLifecycleBackendWithProfiles 

func (r *Registry) RegisterLifecycleBackendWithProfiles(id string, fn LifecycleBackendFactory, profile BackendSecurityProfile, execProfile BackendExecutionProfile) error

RegisterLifecycleBackendWithProfiles records a lifecycle-aware builtin factory with security and execution profiles.

func (*Registry) RegisterLifecycleBackendWithProfilesAndSource 

func (r *Registry) RegisterLifecycleBackendWithProfilesAndSource(id string, fn LifecycleBackendFactory, profile BackendSecurityProfile, execProfile BackendExecutionProfile, source BackendRegistrationSource) error

RegisterLifecycleBackendWithProfilesAndSource records a lifecycle-aware factory with security, execution profile, and provenance.

func (*Registry) RegisterLifecycleBackendWithSource 

func (r *Registry) RegisterLifecycleBackendWithSource(id string, fn LifecycleBackendFactory, profile BackendSecurityProfile, source BackendRegistrationSource) error

RegisterLifecycleBackendWithSource records a lifecycle-aware builtin factory with provenance.

func (*Registry) SetBackendReloadPolicy 

func (r *Registry) SetBackendReloadPolicy(factoryID string, policy BackendReloadPolicy) error

SetBackendReloadPolicy updates reload/overlap policy for an already-registered factory.

func (*Registry) ValidateBundledFactories 

func (r *Registry) ValidateBundledFactories(required []lipsdk.Requirement) error

ValidateBundledFactories ensures every mandatory plugin has a registered factory for its kind on r.

func (*Registry) WrapLifecycleBackend 

func (r *Registry) WrapLifecycleBackend(factoryID string, wrap func(orig LifecycleBackendFactory) LifecycleBackendFactory) error

WrapLifecycleBackend decorates an already-registered lifecycle backend factory before construction.

type ResolvedOwnershipInput 

type ResolvedOwnershipInput struct {
	Base             ManifestOwnershipInput
	ResolvedPrefixes []BackendOwner
}

ResolvedOwnershipInput is the post-activation stage: advertised route prefixes from a (possibly fake) resolved profile, checked before generation publication.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.