loader

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 2026 License: MIT Imports: 40 Imported by: 0

README

Extension Loaders

The loader package reads schema, function, verb, rule, and OCI extension inputs.

The loader prepares declarations and executor configuration. The compiler still checks rule sources before activation.

Supported inputs

  • Static Go declarations for trusted embedded applications
  • JSON verb and schema manifests
  • Protobuf verb declarations
  • Extension directories
  • Digest-pinned OCI bundles
  • .eff and .effx rule sources inside extension snapshots

Read Extension System for manifest fields and executor targets.

Extension manager

ExtensionManager combines one or more loaders. Registry helpers apply the loaded declarations to candidate schema and verb registries.

Duplicate behavior depends on the configured policy. Production startup uses strict validation and fails on unsupported conflicts.

Static loaders

Static loaders register Go values directly. They are useful in trusted embedded applications and tests.

Static executors can contain arbitrary Go behavior. They do not become serializable checked IR.

Production effectusd rejects in-process Go plugins.

JSON manifests

A verb manifest declares contracts and executor targets:

{
  "name": "payments",
  "version": "1.0.0",
  "verbs": [
    {
      "name": "ReservePayment",
      "argTypes": {
        "orderId": "string",
        "amount": "float"
      },
      "requiredArgs": ["orderId", "amount"],
      "returnType": "PaymentReservation",
      "target": {
        "type": "http",
        "config": {
          "url": "https://payments.example/reservations",
          "method": "POST"
        }
      }
    }
  ]
}

The extension compiler validates type declarations, required arguments, capabilities, resources, and target configuration.

Executor targets

Production checked plans support configured HTTP, gRPC, stream, Kafka, and OCI-resolved executors.

HTTP execution applies URL, host, redirect, DNS, response-size, and timeout controls.

Invocation metadata includes stable identity, idempotency key, attempt, contract, and fencing values.

The destination must enforce idempotency or fencing when correctness requires it.

Extension snapshots

Effectusd builds an immutable extension snapshot for each candidate generation.

The runtime retains a snapshot while an execution uses it. Retirement waits for active references.

A failed candidate releases its resources without changing the active generation.

OCI loading

Production OCI references must use a digest. Effectusd also requires an operator-provided signature verifier.

The shared archive extractor rejects traversal, links, device entries, excessive file counts, and excessive expanded sizes.

The verifier command defines the trust policy. A successful pull without successful verification is not accepted.

Rule compilation

The daemon compiles extension .eff and .effx sources through compiler.CompileChecked.

A schema or verb refresh recompiles the source against the candidate environment. A failed compile prevents publication.

Directory loading

Directory loaders discover supported extension files under configured roots.

Use directory refresh for controlled local development or mounted configuration. Do not use it as a substitute for signed artifact distribution.

Test

go test ./loader

Use race tests when you change snapshot activation or retirement:

go test -race ./loader ./runtime

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CommandOCISignatureVerifier

type CommandOCISignatureVerifier struct{ Path string }

CommandOCISignatureVerifier delegates trust verification to a fixed executable. No shell is used. The executable receives reference and digest.

func (CommandOCISignatureVerifier) Verify

func (verifier CommandOCISignatureVerifier) Verify(ctx context.Context, reference, digest string) error

type DescriptorLoadTarget

type DescriptorLoadTarget interface {
	RegisterVerbDescriptor(VerbSpec, ExecutorDescriptor) error
}

DescriptorLoadTarget accepts transport declarations without constructing transport resources. Production staging and compilation use this boundary.

type ExecutorDescriptor

type ExecutorDescriptor struct {
	Type     string
	VerbName string
	Config   map[string]interface{}
}

ExecutorDescriptor is immutable loader output. It contains no sockets, clients, goroutines, or callbacks.

type ExtensionManager

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

ExtensionManager provides a unified way to extend Effectus with verbs and schemas

func NewExtensionManager

func NewExtensionManager() *ExtensionManager

NewExtensionManager creates a new extension manager

func (*ExtensionManager) AddLoader

func (em *ExtensionManager) AddLoader(loader Loader)

AddLoader registers a loader for static or dynamic extensions

func (*ExtensionManager) GetLoaders

func (em *ExtensionManager) GetLoaders() []Loader

GetLoaders returns a copy of the registered loader list.

func (*ExtensionManager) LoadExtensions

func (em *ExtensionManager) LoadExtensions(ctx context.Context, target LoadTarget) error

LoadExtensions loads all registered extensions into the provided registries

func (*ExtensionManager) Stage

func (manager *ExtensionManager) Stage(ctx context.Context, options StageOptions) (*ExtensionSnapshot, error)

type ExtensionSnapshot

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

ExtensionSnapshot contains immutable loader output. Compilation reads only this snapshot and cannot invoke file, OCI, DNS, or HTTP loaders.

func NewResourceSnapshot

func NewResourceSnapshot(closers ...io.Closer) (*ExtensionSnapshot, error)

NewResourceSnapshot creates snapshot ownership for resources reconstructed from an immutable execution artifact.

func (*ExtensionSnapshot) Acquire

func (snapshot *ExtensionSnapshot) Acquire() (*ExtensionSnapshotHandle, error)

func (*ExtensionSnapshot) AttachCloser

func (snapshot *ExtensionSnapshot) AttachCloser(closer io.Closer) error

AttachCloser adds a runtime-constructed resource to snapshot retirement. It must be called before the snapshot is published or acquired.

func (*ExtensionSnapshot) Closed

func (snapshot *ExtensionSnapshot) Closed() bool

func (*ExtensionSnapshot) Load

func (snapshot *ExtensionSnapshot) Load(ctx context.Context, target LoadTarget) error

func (*ExtensionSnapshot) Name

func (snapshot *ExtensionSnapshot) Name() string

func (*ExtensionSnapshot) Retire

func (snapshot *ExtensionSnapshot) Retire() error

type ExtensionSnapshotHandle

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

func (*ExtensionSnapshotHandle) Release

func (handle *ExtensionSnapshotHandle) Release() error

func (*ExtensionSnapshotHandle) Snapshot

func (handle *ExtensionSnapshotHandle) Snapshot() *ExtensionSnapshot

type ExtensionSnapshotManager

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

ExtensionSnapshotManager is retained for embedded compatibility. Deprecated: ExecutionRuntime publishes the active snapshot with its checked generation.

func (*ExtensionSnapshotManager) Acquire

func (*ExtensionSnapshotManager) Close

func (manager *ExtensionSnapshotManager) Close() error

func (*ExtensionSnapshotManager) Publish

func (manager *ExtensionSnapshotManager) Publish(snapshot *ExtensionSnapshot) error

type FunctionDef

type FunctionDef struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description"`
	Type        string                 `json:"type"` // "builtin", "expression", etc.
	Config      map[string]interface{} `json:"config,omitempty"`
}

FunctionDef defines a function for dynamic loading

type GRPCExecutor

type GRPCExecutor struct {
	Address    string
	Method     string
	Timeout    time.Duration
	Metadata   map[string]string
	UseTLS     bool
	Insecure   bool
	ServerName string
	// contains filtered or unexported fields
}

GRPCExecutor executes verbs via gRPC calls.

func NewGRPCExecutor

func NewGRPCExecutor(config map[string]interface{}) (*GRPCExecutor, error)

func (*GRPCExecutor) Close

func (ge *GRPCExecutor) Close() error

func (*GRPCExecutor) Execute

func (ge *GRPCExecutor) Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)

func (*GRPCExecutor) InvocationResolverDescriptor

func (ge *GRPCExecutor) InvocationResolverDescriptor() any

func (*GRPCExecutor) Invoke

func (ge *GRPCExecutor) Invoke(ctx context.Context, request invocation.Request) invocation.Outcome

func (*GRPCExecutor) SourceInfo

func (ge *GRPCExecutor) SourceInfo() verb.SourceInfo

type HTTPExecutor

type HTTPExecutor struct {
	URL     string
	Method  string
	Headers map[string]string
	Timeout time.Duration
	Policy  OutboundNetworkPolicy
	// contains filtered or unexported fields
}

HTTPExecutor executes verbs via HTTP calls

func NewHTTPExecutor

func NewHTTPExecutor(config map[string]interface{}) (*HTTPExecutor, error)

func (*HTTPExecutor) Close

func (he *HTTPExecutor) Close() error

func (*HTTPExecutor) Execute

func (he *HTTPExecutor) Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)

func (*HTTPExecutor) InvocationResolverDescriptor

func (he *HTTPExecutor) InvocationResolverDescriptor() any

func (*HTTPExecutor) Invoke

func (he *HTTPExecutor) Invoke(ctx context.Context, request invocation.Request) invocation.Outcome

func (*HTTPExecutor) SourceInfo

func (he *HTTPExecutor) SourceInfo() verb.SourceInfo

type IPResolver

type IPResolver interface {
	LookupIPAddr(context.Context, string) ([]net.IPAddr, error)
}

type JSONResourceSpec

type JSONResourceSpec struct {
	Resource     string   `json:"resource"`
	Capabilities []string `json:"capabilities"`
}

JSONResourceSpec defines resource requirements in JSON

func (*JSONResourceSpec) GetCapabilities

func (jrs *JSONResourceSpec) GetCapabilities() []string

func (*JSONResourceSpec) GetResource

func (jrs *JSONResourceSpec) GetResource() string

type JSONSchemaLoader

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

JSONSchemaLoader loads schemas from JSON Schema files

func NewJSONSchemaLoader

func NewJSONSchemaLoader(name, filePath string) *JSONSchemaLoader

NewJSONSchemaLoader creates a JSON schema loader from file

func (*JSONSchemaLoader) Load

func (jsl *JSONSchemaLoader) Load(ctx context.Context, target LoadTarget) error

func (*JSONSchemaLoader) Name

func (jsl *JSONSchemaLoader) Name() string

type JSONVerbLoader

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

JSONVerbLoader loads verbs from JSON files

func NewJSONVerbLoader

func NewJSONVerbLoader(name, filePath string) *JSONVerbLoader

NewJSONVerbLoader creates a JSON verb loader from file

func (*JSONVerbLoader) Load

func (jvl *JSONVerbLoader) Load(ctx context.Context, target LoadTarget) error

func (*JSONVerbLoader) Name

func (jvl *JSONVerbLoader) Name() string

type JSONVerbSpec

type JSONVerbSpec struct {
	Name         string             `json:"name"`
	Description  string             `json:"description"`
	Capabilities []string           `json:"capabilities"`
	Resources    []JSONResourceSpec `json:"resources"`
	ArgTypes     map[string]string  `json:"argTypes"`
	RequiredArgs []string           `json:"requiredArgs"`
	ReturnType   string             `json:"returnType"`
	InverseVerb  string             `json:"inverseVerb,omitempty"`
	Target       *VerbTarget        `json:"target,omitempty"`
}

JSONVerbSpec defines a verb specification in JSON

func (*JSONVerbSpec) GetArgTypes

func (jvs *JSONVerbSpec) GetArgTypes() map[string]string

func (*JSONVerbSpec) GetCapabilities

func (jvs *JSONVerbSpec) GetCapabilities() []string

func (*JSONVerbSpec) GetDescription

func (jvs *JSONVerbSpec) GetDescription() string

func (*JSONVerbSpec) GetInverseVerb

func (jvs *JSONVerbSpec) GetInverseVerb() string

func (*JSONVerbSpec) GetName

func (jvs *JSONVerbSpec) GetName() string

func (*JSONVerbSpec) GetRequiredArgs

func (jvs *JSONVerbSpec) GetRequiredArgs() []string

func (*JSONVerbSpec) GetResources

func (jvs *JSONVerbSpec) GetResources() []ResourceSpec

func (*JSONVerbSpec) GetReturnType

func (jvs *JSONVerbSpec) GetReturnType() string

type LoadTarget

type LoadTarget interface {
	RegisterVerb(spec VerbSpec, executor VerbExecutor) error
	RegisterFunction(name string, fn interface{}) error
	LoadData(path string, value interface{}) error
	RegisterType(name string, typeDef TypeDefinition) error
}

LoadTarget defines what can be loaded into

type Loader

type Loader interface {
	Name() string
	Load(ctx context.Context, target LoadTarget) error
}

Loader defines the interface for extension loaders

func LoadExtensionsFromReader

func LoadExtensionsFromReader(r io.Reader, extension string) (Loader, error)

LoadExtensionsFromReader loads extensions from an io.Reader (for testing)

func LoadFromDirectory

func LoadFromDirectory(dirPath string) ([]Loader, error)

LoadFromDirectory scans a directory for extension files and creates loaders

type MockExecutor

type MockExecutor struct {
	Name string
}

MockExecutor provides a simple mock executor for testing

func (*MockExecutor) Execute

func (me *MockExecutor) Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)

func (*MockExecutor) SourceInfo

func (me *MockExecutor) SourceInfo() verb.SourceInfo

type NoOpExecutor

type NoOpExecutor struct{}

NoOpExecutor provides a no-operation executor

func (*NoOpExecutor) Execute

func (noe *NoOpExecutor) Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)

func (*NoOpExecutor) SourceInfo

func (noe *NoOpExecutor) SourceInfo() verb.SourceInfo

type OCIBundleLoader

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

func NewOCIBundleLoader

func NewOCIBundleLoader(name, ref string) *OCIBundleLoader

NewOCIBundleLoader creates an OCI bundle loader

func NewOCIBundleLoaderWithPolicy

func NewOCIBundleLoaderWithPolicy(name, ref string, policy OCIVerificationPolicy) *OCIBundleLoader

func (*OCIBundleLoader) Load

func (obl *OCIBundleLoader) Load(ctx context.Context, target LoadTarget) error

func (*OCIBundleLoader) Name

func (obl *OCIBundleLoader) Name() string

type OCIExecutor

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

OCIExecutor resolves a verb executor from an OCI extension bundle.

func NewOCIExecutor

func NewOCIExecutor(verbName string, config map[string]interface{}) (*OCIExecutor, error)

func (*OCIExecutor) Close

func (oe *OCIExecutor) Close() error

func (*OCIExecutor) Execute

func (oe *OCIExecutor) Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)

func (*OCIExecutor) InvocationResolverDescriptor

func (oe *OCIExecutor) InvocationResolverDescriptor() any

func (*OCIExecutor) Invoke

func (oe *OCIExecutor) Invoke(ctx context.Context, request invocation.Request) invocation.Outcome

func (*OCIExecutor) SourceInfo

func (oe *OCIExecutor) SourceInfo() verb.SourceInfo

func (*OCIExecutor) Warmup

func (oe *OCIExecutor) Warmup(ctx context.Context) error

type OCISignatureVerifier

type OCISignatureVerifier interface {
	Verify(context.Context, string, string) error
}

OCIBundleLoader loads extensions from OCI registry bundles

type OCIVerificationPolicy

type OCIVerificationPolicy struct {
	RequireSignature bool
	Verifier         OCISignatureVerifier
}

type OutboundNetworkPolicy

type OutboundNetworkPolicy struct {
	AllowPrivate bool
	Resolver     IPResolver
	MaxRedirects int
	DialTimeout  time.Duration
}

func (OutboundNetworkPolicy) HTTPClient

func (policy OutboundNetworkPolicy) HTTPClient(timeout time.Duration, sensitiveHeaders map[string]string) *http.Client

func (OutboundNetworkPolicy) ValidateURL

func (policy OutboundNetworkPolicy) ValidateURL(raw string) (*url.URL, error)

type ProtoSchemaLoader

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

ProtoSchemaLoader loads schemas from Protocol Buffer messages

func NewProtoSchemaLoader

func NewProtoSchemaLoader(name string, message proto.Message) *ProtoSchemaLoader

NewProtoSchemaLoader creates a protobuf schema loader

func (*ProtoSchemaLoader) Load

func (psl *ProtoSchemaLoader) Load(ctx context.Context, target LoadTarget) error

func (*ProtoSchemaLoader) Name

func (psl *ProtoSchemaLoader) Name() string

type ProtoVerbLoader

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

ProtoVerbLoader loads verbs from Protocol Buffer messages

func NewProtoVerbLoader

func NewProtoVerbLoader(name string, message proto.Message) *ProtoVerbLoader

NewProtoVerbLoader creates a protobuf verb loader

func (*ProtoVerbLoader) Load

func (pvl *ProtoVerbLoader) Load(ctx context.Context, target LoadTarget) error

func (*ProtoVerbLoader) Name

func (pvl *ProtoVerbLoader) Name() string

type ResourceSpec

type ResourceSpec interface {
	GetResource() string
	GetCapabilities() []string
}

ResourceSpec defines resource requirements

type SchemaManifest

type SchemaManifest struct {
	Name        string                    `json:"name"`
	Version     string                    `json:"version"`
	Description string                    `json:"description"`
	Types       map[string]TypeDefinition `json:"types"`
	Functions   map[string]FunctionDef    `json:"functions"`
	InitialData map[string]interface{}    `json:"initialData,omitempty"`
}

SchemaManifest defines the structure for dynamic schema loading

type SourceFile

type SourceFile struct {
	Path string
	Data []byte
}

SourceFile is one immutable .eff or .effx compiler input.

type SourceLoadTarget

type SourceLoadTarget interface {
	RegisterSource(SourceFile) error
}

SourceLoadTarget receives checked-compiler source files from extensions.

type StageOptions

type StageOptions struct {
	Timeout        time.Duration
	MaxLoaders     int
	MaxSources     int
	MaxSourceBytes int
	MaxTotalBytes  int
	MaxVerbs       int
	MaxFunctions   int
	MaxTypes       int
	MaxDataEntries int
}

type StaticSchemaLoader

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

StaticSchemaLoader loads schemas and functions from code

func NewStaticSchemaLoader

func NewStaticSchemaLoader(name string) *StaticSchemaLoader

NewStaticSchemaLoader creates a static schema loader

func (*StaticSchemaLoader) AddData

func (ssl *StaticSchemaLoader) AddData(path string, value interface{}) *StaticSchemaLoader

AddData registers data for fact access

func (*StaticSchemaLoader) AddFunction

func (ssl *StaticSchemaLoader) AddFunction(name string, fn interface{}) *StaticSchemaLoader

AddFunction registers a function for expressions

func (*StaticSchemaLoader) AddType

func (ssl *StaticSchemaLoader) AddType(name string, typeDef TypeDefinition) *StaticSchemaLoader

AddType registers a type definition

func (*StaticSchemaLoader) Load

func (ssl *StaticSchemaLoader) Load(ctx context.Context, target LoadTarget) error

func (*StaticSchemaLoader) Name

func (ssl *StaticSchemaLoader) Name() string

type StaticSourceLoader

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

StaticSourceLoader loads one in-memory .eff or .effx source file.

func NewStaticSourceLoader

func NewStaticSourceLoader(name, path string, data []byte) *StaticSourceLoader

func (*StaticSourceLoader) Load

func (loader *StaticSourceLoader) Load(_ context.Context, target LoadTarget) error

func (*StaticSourceLoader) Name

func (loader *StaticSourceLoader) Name() string

type StaticVerbLoader

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

StaticVerbLoader loads verbs from code (compile-time registration)

func NewStaticVerbLoader

func NewStaticVerbLoader(name string, verbs []VerbDefinition) *StaticVerbLoader

NewStaticVerbLoader creates a static verb loader

func (*StaticVerbLoader) Load

func (svl *StaticVerbLoader) Load(ctx context.Context, target LoadTarget) error

func (*StaticVerbLoader) Name

func (svl *StaticVerbLoader) Name() string

type StreamExecutor

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

StreamExecutor emits verbs to a stream publisher.

func NewStreamExecutor

func NewStreamExecutor(config map[string]interface{}) (*StreamExecutor, error)

func (*StreamExecutor) Close

func (se *StreamExecutor) Close() error

func (*StreamExecutor) Execute

func (se *StreamExecutor) Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)

func (*StreamExecutor) InvocationResolverDescriptor

func (se *StreamExecutor) InvocationResolverDescriptor() any

func (*StreamExecutor) Invoke

func (*StreamExecutor) SourceInfo

func (se *StreamExecutor) SourceInfo() verb.SourceInfo

type TypeDefinition

type TypeDefinition struct {
	Name        string      `json:"name"`
	Type        string      `json:"type"` // "object", "array", "string", etc.
	Properties  interface{} `json:"properties,omitempty"`
	Required    []string    `json:"required,omitempty"`
	Description string      `json:"description,omitempty"`
}

TypeDefinition defines a type for the schema system

type VerbDefinition

type VerbDefinition struct {
	Spec     VerbSpec
	Executor VerbExecutor
}

VerbDefinition defines a verb that can be registered

type VerbExecutor

type VerbExecutor = verb.Executor

VerbExecutor is an alias for the core verb executor interface.

type VerbManifest

type VerbManifest struct {
	Name        string                 `json:"name"`
	Version     string                 `json:"version"`
	Description string                 `json:"description"`
	Verbs       []JSONVerbSpec         `json:"verbs"`
	Executors   map[string]interface{} `json:"executors,omitempty"`
}

VerbManifest defines the structure for dynamic verb loading

type VerbSpec

type VerbSpec interface {
	GetName() string
	GetDescription() string
	GetCapabilities() []string
	GetResources() []ResourceSpec
	GetArgTypes() map[string]string
	GetRequiredArgs() []string
	GetReturnType() string
	GetInverseVerb() string
}

VerbSpec defines a verb specification interface

type VerbTarget

type VerbTarget struct {
	Type   string                 `json:"type"`
	Ref    string                 `json:"ref,omitempty"`
	Config map[string]interface{} `json:"config,omitempty"`
}

VerbTarget defines how a verb should be executed.

Jump to

Keyboard shortcuts

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