index

package
v1.1.0 Latest Latest
Warning

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

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

Documentation

Overview

Package index owns the immutable bootstrap map from protocol identities to authored component sources. Building the map does not load Go types, compile execution plans, open connectors, or create a paths.yaml file.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrClosed      = errors.New("bootstrap component generation is closed")
	ErrStaleSource = errors.New("bootstrap component source changed after indexing")
)

Functions

This section is empty.

Types

type Builder

type Builder struct{ Config Config }

func (Builder) Build

func (b Builder) Build(ctx context.Context) (*Snapshot, error)

Build scans selected packages once at bootstrap and publishes routing-only metadata. It creates no persistent sidecar; callers explicitly persist a snapshot if their deployment chooses to own that resource.

type Config

type Config struct {
	BaseDir       string
	ModuleDirs    []string
	Include       []string
	Exclude       []string
	Workspace     *xmodule.Workspace
	Types         *typecatalog.Catalog
	Holders       []any
	RequireLinked bool
}

type Entry

type Entry struct {
	Component *spec.Component
	// Warmup indicates that the component has root or child warmup declarations
	// discoverable during indexed bootstrap, before executable readers exist.
	Warmup bool
	// Owner identifies the authored component that materializes this entry when
	// the entry is a derived report component.
	Owner       spec.Key
	Sources     []Source
	Fingerprint string
}

Entry is the immutable routing metadata and source authority for one component. Contract fields and executable plans are intentionally absent.

func (*Entry) Clone

func (e *Entry) Clone() *Entry

func (*Entry) Key

func (e *Entry) Key() spec.Key

type Gate

type Gate func(context.Context, *Entry, *spec.Route) error

Gate runs against indexed route metadata before component materialization. Protocol adapters use it for route/API authorization; canonical binding and handler authorization continue against the loaded registration.

type Generation

type Generation struct {
	ID       uint64
	Snapshot *Snapshot
	// contains filtered or unexported fields
}

func (*Generation) Load

func (g *Generation) Load(ctx context.Context, key spec.Key) (*Loaded, error)

type Lease

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

func (*Lease) Close

func (l *Lease) Close()

func (*Lease) GenerationID

func (l *Lease) GenerationID() uint64

func (*Lease) LoadComponent

func (l *Lease) LoadComponent(ctx context.Context, key spec.Key) (*Loaded, error)

func (*Lease) LoadMCP

func (l *Lease) LoadMCP(ctx context.Context, identity MCPIdentity, gate Gate) (*Loaded, error)

func (*Lease) LoadRoute

func (l *Lease) LoadRoute(ctx context.Context, method, path string, gate Gate) (*Loaded, map[string]string, error)

func (*Lease) MaterializeAll

func (l *Lease) MaterializeAll(ctx context.Context) ([]*Loaded, error)

MaterializeAll is the explicit opt-in for schema/documentation consumers that require full contracts. Normal bootstrap and metadata listing use the index and never call this method.

func (*Lease) Snapshot

func (l *Lease) Snapshot() *Snapshot

type Loaded

type Loaded struct {
	Registration *registry.RegisteredComponent
	// Related registrations are materialized coherently with the primary (for
	// example report-generated subcomponents) and become exact-key load hits in
	// this generation.
	Related []*registry.RegisteredComponent
	Release func(context.Context) error
}

Loaded is one generation-owned executable component and its cleanup hook. Release must close only resources owned by this materialization.

type MCPIdentity

type MCPIdentity struct {
	Kind spec.MCPExposureKind
	Name string
}

type MaterializeFunc

type MaterializeFunc func(context.Context, *Entry, Resolver) (*Loaded, error)

func (MaterializeFunc) Materialize

func (f MaterializeFunc) Materialize(ctx context.Context, entry *Entry, resolver Resolver) (*Loaded, error)

type Materializer

type Materializer interface {
	Materialize(context.Context, *Entry, Resolver) (*Loaded, error)
}

type Registry

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

Registry atomically publishes complete bootstrap index generations. A Lease pins one generation for the full request, including lazy dependency loads.

func (*Registry) Pin

func (r *Registry) Pin() (*Lease, error)

func (*Registry) Publish

func (r *Registry) Publish(snapshot *Snapshot, materializer Materializer) (*Generation, error)

func (*Registry) Shutdown

func (r *Registry) Shutdown(ctx context.Context) error

type Resolver

type Resolver interface {
	Load(context.Context, spec.Key) (*Loaded, error)
}

Resolver lets a materializer load component dependencies from the same immutable generation. Cycles fail before waiting on an existing load.

type Snapshot

type Snapshot struct {
	Fingerprint       string
	SelectionIdentity string
	// contains filtered or unexported fields
}

Snapshot is a deterministic, immutable bootstrap index. Public accessors detach metadata so callers cannot mutate the published generation.

func (*Snapshot) Component

func (s *Snapshot) Component(key spec.Key) (*Entry, bool)

func (*Snapshot) Entries

func (s *Snapshot) Entries() []*Entry

func (*Snapshot) MCP

func (s *Snapshot) MCP(identity MCPIdentity) (*Entry, bool)

func (*Snapshot) Route

func (s *Snapshot) Route(method, path string) (*Entry, *spec.Route, map[string]string, bool)

func (*Snapshot) Transform

func (s *Snapshot) Transform(apply func(*spec.Component)) (*Snapshot, error)

Transform returns a new snapshot with detached component metadata changed by apply. Source fingerprints and selection identity remain authoritative.

type Source

type Source struct {
	Kind        SourceKind
	Path        string
	Dir         string
	PackagePath string
	Fingerprint string
}

Source identifies one selected file and its bootstrap-time content digest.

type SourceKind

type SourceKind string
const (
	SourceGo       SourceKind = "go"
	SourceDQL      SourceKind = "dql"
	SourceResource SourceKind = "resource"
)

Jump to

Keyboard shortcuts

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