Documentation
¶
Index ¶
- func Each[T any](ctx context.Context, p Point[T], r Resolver, policy Policy, ...) error
- func Fold[T, A any](ctx context.Context, p Point[T], r Resolver, policy Policy, acc A, ...) (A, error)
- func IsMetadataPoint(point PointID) bool
- func RegisterAll(registrar Registrar, exts ...Extension) error
- func ValidateExtensionID(id ExtensionID) error
- func ValidateExtensionIdentity(identity ExtensionIdentity) error
- func ValidatePointID(id PointID) error
- type Config
- type Declaration
- type Dependency
- type ExecutableOrigin
- type Extension
- type ExtensionID
- type ExtensionIdentity
- type ExtensionOrigin
- type ExtensionOriginKind
- type Point
- func (p Point[T]) All(r Resolver) ([]TypedProvider[T], error)
- func (p Point[T]) ByExtension(r Resolver, extension ExtensionID) (T, error)
- func (p Point[T]) Dependency() Dependency
- func (p Point[T]) Enabled(r Resolver) bool
- func (p Point[T]) ID() PointID
- func (p Point[T]) OptionalDependency() Dependency
- func (p Point[T]) Provide(impl T) Provider
- func (p Point[T]) Single(r Resolver) (T, error)
- type PointID
- type Policy
- type Provider
- type Registrar
- type ResolvedProvider
- type Resolver
- type TypedProvider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Each ¶
func Each[T any](ctx context.Context, p Point[T], r Resolver, policy Policy, fn func(context.Context, T) error) error
Each calls fn once per provider of p under policy. Use it for validation, veto, or notification points.
Fan-out order is unspecified. A point that needs a defined order must define it (see the guidance in the extensions authoring guide).
func Fold ¶
func Fold[T, A any](ctx context.Context, p Point[T], r Resolver, policy Policy, acc A, fn func(context.Context, T, A) (A, error)) (A, error)
Fold threads acc through every provider of p and returns the final value under policy. Each provider sees the value produced by its predecessors.
A provider that fails under a fail-closed policy aborts the fold and its partial value is discarded; under a fail-open one its contribution is dropped and the fold continues from the value it was given.
func IsMetadataPoint ¶
IsMetadataPoint reports whether point carries framework metadata rather than a callable capability. Host provider admission skips metadata points; the servicev0 marker controls publication. Currently the servicev0 offer marker is the only metadata point; its package tests keep this ID in sync with the point definition.
func RegisterAll ¶
RegisterAll registers exts with registrar.
func ValidateExtensionID ¶
func ValidateExtensionID(id ExtensionID) error
ValidateExtensionID reports whether id is well-formed before it is used as a configuration key or binary name.
func ValidateExtensionIdentity ¶
func ValidateExtensionIdentity(identity ExtensionIdentity) error
ValidateExtensionIdentity returns an error unless identity contains a valid extension ID and a recognized host-attested origin.
func ValidatePointID ¶
ValidatePointID reports whether id is a well-formed, versioned Point ID.
Types ¶
type Config ¶
Config is parsed per-extension configuration delivered by id to Init or the out-of-process startup handshake.
type Declaration ¶
type Declaration struct {
ID ExtensionID
Providers []Provider
Dependencies []Dependency
Conflicts []ExtensionID
Init func(context.Context, Config, Resolver) error
Shutdown func(context.Context) error
}
Declaration declares an extension, its providers and dependencies, and its optional lifecycle callbacks.
type Dependency ¶
type Dependency struct {
Point PointID
Extension ExtensionID
Optional bool
}
Dependency declares one extension dependency.
type ExecutableOrigin ¶
type ExecutableOrigin struct {
// Path is the exact path the host executed, as discovered from the
// extension directory. It is not normalized: a relative directory or a
// symlink yields that relative or symlink path.
Path string
}
ExecutableOrigin contains host-attested details for an executable origin.
type Extension ¶
type Extension interface {
// Declaration returns the extension's id, providers, dependencies, and
// conflicts, plus its optional Init and Shutdown.
Declaration() Declaration
}
Extension is a host-managed extension declaration.
type ExtensionIdentity ¶
type ExtensionIdentity struct {
ID ExtensionID
Origin ExtensionOrigin
}
ExtensionIdentity is the host-attested identity of an extension. The extension declares ID, but the host supplies and validates the complete identity, including Origin.
type ExtensionOrigin ¶
type ExtensionOrigin struct {
Kind ExtensionOriginKind
Executable *ExecutableOrigin
}
ExtensionOrigin identifies how the host obtained an extension and its kind-specific attested details.
type ExtensionOriginKind ¶
type ExtensionOriginKind string
ExtensionOriginKind identifies how the host obtained an extension.
const ( // ExtensionOriginBuiltin identifies an extension compiled into the host. ExtensionOriginBuiltin ExtensionOriginKind = "builtin" // ExtensionOriginExecutable identifies an extension launched as an // executable. ExtensionOriginExecutable ExtensionOriginKind = "executable" )
type Point ¶
type Point[T any] struct { // contains filtered or unexported fields }
Point binds a point ID to the Go interface implemented by its providers.
func DefinePoint ¶
DefinePoint binds id to provider interface T and panics for an invalid point id. Point ids are fixed in source, so invalid ids are programming errors.
func DefineSinglePoint ¶
DefineSinglePoint declares a point with one deciding provider instead of a fan-out. The wire generator carries this cardinality into ClientPoint so the host can reject multiple executable providers at startup.
func (Point[T]) All ¶
func (p Point[T]) All(r Resolver) ([]TypedProvider[T], error)
All returns all point providers, including built-in and executable providers.
func (Point[T]) ByExtension ¶
func (p Point[T]) ByExtension(r Resolver, extension ExtensionID) (T, error)
ByExtension returns the point provider implemented by extension.
func (Point[T]) Dependency ¶
func (p Point[T]) Dependency() Dependency
Dependency returns a required dependency declaration for the point: at least one provider must exist before the dependent initializes.
func (Point[T]) OptionalDependency ¶
func (p Point[T]) OptionalDependency() Dependency
OptionalDependency returns an optional dependency declaration for the point: the dependent still initializes, ordered after any providers, when none exist.
type Policy ¶
type Policy struct {
// Timeout bounds each provider call independently. Zero leaves the calls
// bounded only by the caller's context.
//
// It is enforced for out-of-process providers, which receive the deadline
// over gRPC. An in-process provider is passed the same context but only
// trusted to honor it: abandoning a direct Go call would leave the provider
// mutating shared engine state after the caller moved on. State a
// fail-closed point's guarantee accordingly.
Timeout time.Duration
// FailOpen continues with the remaining providers when one returns an error.
// Veto points should leave it false.
FailOpen bool
// Action names what the provider's error did to the operation, for the
// wrapped error: `<point> provider "<id>" <action>: <err>`. Leave it empty
// for a plain failure.
Action string
}
Policy controls provider deadlines and error handling for Each and Fold.
type ResolvedProvider ¶
type ResolvedProvider struct {
Identity ExtensionIdentity
Impl any
}
ResolvedProvider is a provider returned from a lookup with its host-attested extension identity.
func EffectiveProviders ¶
func EffectiveProviders(providers []ResolvedProvider) []ResolvedProvider
EffectiveProviders applies origin precedence for single-provider resolution. Built-ins are used only when no executable provider exists. Fan-out and by-id lookups do not apply this precedence.
type Resolver ¶
type Resolver interface {
Provider(PointID, ExtensionID) (any, error)
Providers(PointID) []ResolvedProvider
}
Resolver exposes provider lookup to extension initializers. Selection and cardinality are handled by the typed Point accessors.
type TypedProvider ¶
type TypedProvider[T any] struct { Identity ExtensionIdentity Impl T }
TypedProvider is a provider returned through a typed point handle.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package client provides typed, lazy clients for extension points.
|
Package client provides typed, lazy clients for extension points. |
|
Package clientpoint defines the host-side registration for generated out-of-process point providers.
|
Package clientpoint defines the host-side registration for generated out-of-process point providers. |
|
cmd
|
|
|
mobyextgen
command
Command mobyextgen generates an extension point or service's wire contract and transport code from a Go interface and pb-tagged message structs.
|
Command mobyextgen generates an extension point or service's wire contract and transport code from a Go interface and pb-tagged message structs. |
|
example
|
|
|
greeter/v0
Package greeterv0 is an example service point used to exercise socket exposure.
|
Package greeterv0 is an example service point used to exercise socket exposure. |
|
greeter/v0/protogen
Code generated by mobyextgen.
|
Code generated by mobyextgen. |
|
extpoints
|
|
|
service/v0
Package servicev0 defines metadata through which extensions offer ordinary Points for Host-controlled publication.
|
Package servicev0 defines metadata through which extensions offer ordinary Points for Host-controlled publication. |
|
Package grpcproxy forwards gRPC calls by service name without importing the service's proto.
|
Package grpcproxy forwards gRPC calls by service name without importing the service's proto. |
|
Package host runs extensions and resolves their point providers for a host process such as the Moby daemon.
|
Package host runs extensions and resolves their point providers for a host process such as the Moby daemon. |
|
internal
|
|
|
extensiondecl
Package extensiondecl converts and validates declarations reported by externally hosted extensions.
|
Package extensiondecl converts and validates declarations reported by externally hosted extensions. |
|
launcher/echo/v1
Package echov1 is the minimal extension point used by launcher tests.
|
Package echov1 is the minimal extension point used by launcher tests. |
|
launcher/echo/v1/protogen
Code generated by mobyextgen.
|
Code generated by mobyextgen. |
|
testutils
Package testutils provides test doubles for the extension framework.
|
Package testutils provides test doubles for the extension framework. |
|
internal/dependencyresolver
Package dependencyresolver resolves providers served through a gRPC connection.
|
Package dependencyresolver resolves providers served through a gRPC connection. |
|
sdkapi
Package sdkapi defines the runtime protocol served by every out-of-process extension.
|
Package sdkapi defines the runtime protocol served by every out-of-process extension. |
|
sdkapi/protogen
Code generated by mobyextgen.
|
Code generated by mobyextgen. |
|
Package serverpoint defines the SDK-side registration for generated out-of-process point providers.
|
Package serverpoint defines the SDK-side registration for generated out-of-process point providers. |
|
Package servicegrpc adapts published ordinary generated points to the gRPC transport without replacing their generated handlers.
|
Package servicegrpc adapts published ordinary generated points to the gRPC transport without replacing their generated handlers. |
|
Package stream defines typed, method-scoped streaming contracts.
|
Package stream defines typed, method-scoped streaming contracts. |