extensions

package module
v0.0.0-...-2b6b3bd Latest Latest
Warning

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

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

README

Extensions

[!WARNING] This project is still a work in progress.

Moby extensions provide a common model for extending engine behavior. They are intended to replace the separate plugin systems currently used by network, volume, and logging drivers.

An extension can run inside the Host process or as a separate process. In both cases, it implements the same Go interface.

See the authoring guide for examples and setup instructions. For details about the architecture, wire protocol, current limitations, and discovery security, see the design guide.

How it works

Extensions are built around Points. A Point is an interface that describes a capability, such as running a workload. Providers implement Points, and consumers call them. The Host registers these components, connects consumers to providers, and manages their lifecycle.

For example, a daemon can expose its workload runtime as a Point. An extension can then use that capability without depending on the daemon's internal runtime implementation. The same mechanism is used for daemon-owned capabilities and communication between extensions.

To add an extension:

  1. Define the contract.

    A Point assigns a namespaced, versioned identity to a Go interface and its message types.

  2. Declare what the extension provides and depends on.

    Providers implement Points. Consumers declare their dependencies using Point.Dependency().

  3. Register the extension with the Host.

    The daemon or application decides which extensions to load and supplies any generated wiring required for cross-process calls. Merely importing an extension package does not activate it.

  4. Resolve dependencies during initialization.

    In Declaration.Init, consumers resolve their declared dependencies using Point.Single, Point.All, or Point.ByExtension. The resolved implementation is not automatically assigned to a field.

  5. Call the Point interface.

    Consumers retain and call the resolved interface rather than a concrete Host or daemon type. Calls go directly to an in-process provider or through generated gRPC code when the provider runs in another process.

The Host initializes providers before their consumers and shuts them down in the opposite order. A provider must be ready for use when its Init method returns.

Keep the Host returned by host.New and call Shutdown when the application exits so that lifecycle resources are released.

Breaking changes require a new Point version. The .v0 suffix identifies an experimental contract. For fan-out calls, provider order is unspecified unless the Point defines its own ordering rules.

Running extensions

A Point defines an interface, not where its implementation runs. In-process consumers call the Go implementation directly. Cross-process consumers use generated gRPC wiring.

Because the same contract may cross a process boundary, Point interfaces and messages should not contain Host types, internal backend structures, callbacks, or channels.

The mobyextgen generator creates the required wire code:

  • ServerPoint exposes a Point implementation over gRPC.
  • ClientPoint presents the remote implementation through the same typed Go interface.

The exact setup depends on where the consumer and provider run:

  • Register in-process extensions with host.WithExtensions.
  • When the Host calls a provider in a launched process, configure the Host with host.WithClientProviders and the generated ClientPoint. The provider registers its generated ServerPoint with the SDK.
  • When a launched consumer calls a Host provider, configure the Host with host.WithDependencyProviders and the generated ServerPoint. In the consumer, pass the generated ClientPoint to Server.Depends.

The last case exposes an existing Host provider to the launched process. The consumer must still declare the dependency itself.

A dependency callback currently exposes one effective provider for each Point. Do not retain and call that dependency during Shutdown, because the SDK closes the connection before shutdown begins.

For launched processes, the ready\n handshake only confirms that the listener is ready. It does not mean that the extension's Init method has completed.

See the authoring guide for complete examples covering code generation, SDK registration, dependency resolution, and deployment.

Publishing services

Implementing a Point makes it available within the extension system, but does not automatically expose it to external callers.

Publishing a Point requires three things:

  • The extension offers it using servicev0.Offer.
  • Host policy permits it through host.WithProviderPolicy.
  • The generated server wiring is registered.

For an in-process provider, supply the server wiring through host.WithPointServers. A provider running in a separate process registers its ServerPoint with the SDK.

An offer is only a request to publish a Point; it does not grant access or register the transport. If no provider policy is configured, external publication is disabled, while providers remain available to internal consumers.

Published services are responsible for enforcing their own access control.

See the publication examples for complete configurations and generated client usage.

Glossary

Point

A named and versioned Go interface, together with its message types. It describes a capability independently of its implementation or location.

Extension

A component that can provide Points, depend on other Points or extensions, and perform initialization and shutdown work. It may run inside the Host or in a separate process.

Host

The framework component embedded in a daemon or application. It registers extensions, resolves their dependencies, and manages their lifecycle.

Provider

An extension that implements a Point.

Consumer

Code that resolves and calls a Point. An extension may be both a consumer and a provider.

Dependency

A declared requirement for a Point provider or another extension. The Host uses dependencies to verify that requirements are available and to determine initialization order.

Host capability

Functionality owned by the daemon or application and exposed as a Point through an in-process extension.

ClientPoint / ServerPoint

Generated code used to call a Point across a process boundary. ClientPoint presents the Point's Go interface to the consumer, while ServerPoint forwards incoming calls to the implementation.

Offer

A request from an extension to make one or more of its Points available to external callers.

Publication

The Host exposing an offered Point to external callers after applying its policy and registering the required server wiring.

License

Licensed under the Apache License, Version 2.0.

Documentation

Index

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

func IsMetadataPoint(point PointID) bool

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

func RegisterAll(registrar Registrar, exts ...Extension) error

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

func ValidatePointID(id PointID) error

ValidatePointID reports whether id is a well-formed, versioned Point ID.

Types

type Config

type Config = map[string]any

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.

func New

func New(d Declaration) Extension

New wraps a static Declaration as an Extension.

type ExtensionID

type ExtensionID string

ExtensionID identifies a deployable extension.

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

func DefinePoint[T any](id PointID) Point[T]

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

func DefineSinglePoint[T any](id PointID) Point[T]

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]) Enabled

func (p Point[T]) Enabled(r Resolver) bool

Enabled reports whether any extension provides the point.

func (Point[T]) ID

func (p Point[T]) ID() PointID

ID returns the point identifier.

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.

func (Point[T]) Provide

func (p Point[T]) Provide(impl T) Provider

Provide returns a provider declaration for impl.

func (Point[T]) Single

func (p Point[T]) Single(r Resolver) (T, error)

Single returns the only point provider, after origin precedence (EffectiveProviders): a built-in provider does not count against the one-provider limit, it stands in when no executable provider exists.

type PointID

type PointID string

PointID identifies an extension point contract.

func (PointID) Name

func (id PointID) Name() string

Name returns the point's short name, the segment before its version.

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 Provider

type Provider struct {
	Point PointID
	Impl  any
}

Provider declares an in-process implementation for a point.

type Registrar

type Registrar interface {
	Register(Extension) error
}

Registrar registers extensions.

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.
sdk
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.

Jump to

Keyboard shortcuts

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