kernel

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Feb 8, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package kernel provides the dependency injection container and module bootstrapping logic.

Index

Constants

This section is empty.

Variables

View Source 
var ErrExportAmbiguous = errors.New("export token is ambiguous across imports")

ErrExportAmbiguous is returned when a module tries to re-export a token that multiple imports provide.

View Source 
var ErrGraphNodeNotFound = errors.New("graph node not found")

ErrGraphNodeNotFound is returned when graph export references a missing node.

View Source 
var ErrNilApp = errors.New("app is nil")

ErrNilApp is returned when an operation requiring an app receives nil.

View Source 
var ErrNilGraph = errors.New("graph is nil")

ErrNilGraph is returned when BuildVisibility is called with a nil graph.

Functions

func ExportAppGraph added in v0.14.0 

func ExportAppGraph(app *App, format GraphFormat) (string, error)

ExportAppGraph exports the app's module graph in the requested format.

func ExportGraph added in v0.14.0 

func ExportGraph(g *Graph, format GraphFormat) (string, error)

ExportGraph exports a graph in Mermaid or DOT format.

Types

type App 

type App struct {
	Graph *Graph

	Controllers map[string]any
	// contains filtered or unexported fields
}

App represents a bootstrapped modkit application with its dependency graph, container, and instantiated controllers.

func Bootstrap 

func Bootstrap(root module.Module) (*App, error)

Bootstrap constructs a modkit application from a root module. It builds the module graph, validates dependencies, creates the DI container, and instantiates all controllers.

func BootstrapWithOptions added in v0.13.0 

func BootstrapWithOptions(root module.Module, opts ...BootstrapOption) (*App, error)

BootstrapWithOptions constructs a modkit application from a root module and explicit bootstrap options.

func (*App) CleanupHooks added in v0.4.0 

func (a *App) CleanupHooks() []func(context.Context) error

CleanupHooks returns provider cleanup hooks in LIFO order.

func (*App) Close added in v0.5.0 

func (a *App) Close() error

Close closes providers implementing io.Closer in reverse build order.

func (*App) CloseContext added in v0.7.0 

func (a *App) CloseContext(ctx context.Context) error

CloseContext closes providers implementing io.Closer in reverse build order.

func (*App) Closers added in v0.5.0 

func (a *App) Closers() []io.Closer

Closers returns provider closers in build order.

func (*App) Get 

func (a *App) Get(token module.Token) (any, error)

Get resolves a token from the root module scope.

func (*App) Resolver 

func (a *App) Resolver() module.Resolver

Resolver returns a root-scoped resolver that enforces module visibility.

type BootstrapOption added in v0.13.0 

type BootstrapOption interface {
	// contains filtered or unexported methods
}

BootstrapOption configures advanced bootstrap behavior.

func WithProviderOverrides added in v0.13.0 

func WithProviderOverrides(overrides ...ProviderOverride) BootstrapOption

WithProviderOverrides applies token-level provider overrides for bootstrap.

type BootstrapOptionConflictError added in v0.13.0 

type BootstrapOptionConflictError struct {
	Token   module.Token
	Options []string
}

BootstrapOptionConflictError is returned when multiple options mutate the same token.

func (*BootstrapOptionConflictError) Error added in v0.13.0 

func (e *BootstrapOptionConflictError) Error() string

type Container 

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

Container is the dependency injection container that manages provider instances, enforces visibility rules, and tracks cleanup hooks.

func (*Container) Get 

func (c *Container) Get(token module.Token) (any, error)

Get resolves a provider without module visibility checks. Visibility enforcement is applied via module-scoped resolvers.

type ControllerBuildError 

type ControllerBuildError struct {
	Module     string
	Controller string
	Err        error
}

ControllerBuildError wraps an error that occurred while building a controller instance.

func (*ControllerBuildError) Error 

func (e *ControllerBuildError) Error() string

func (*ControllerBuildError) Unwrap 

func (e *ControllerBuildError) Unwrap() error

type DuplicateControllerNameError 

type DuplicateControllerNameError struct {
	Module string
	Name   string
}

DuplicateControllerNameError is returned when a module has multiple controllers with the same name.

func (*DuplicateControllerNameError) Error 

func (e *DuplicateControllerNameError) Error() string

type DuplicateModuleNameError 

type DuplicateModuleNameError struct {
	Name string
}

DuplicateModuleNameError is returned when multiple modules have the same name.

func (*DuplicateModuleNameError) Error 

func (e *DuplicateModuleNameError) Error() string

type DuplicateOverrideTokenError added in v0.13.0 

type DuplicateOverrideTokenError struct {
	Token module.Token
}

DuplicateOverrideTokenError is returned when the same override token is declared more than once.

func (*DuplicateOverrideTokenError) Error added in v0.13.0 

func (e *DuplicateOverrideTokenError) Error() string

type DuplicateProviderTokenError 

type DuplicateProviderTokenError struct {
	Token   module.Token
	Modules []string
}

DuplicateProviderTokenError is returned when the same provider token is registered in multiple modules.

func (*DuplicateProviderTokenError) Error 

func (e *DuplicateProviderTokenError) Error() string

type ExportAmbiguousError added in v0.6.0 

type ExportAmbiguousError struct {
	Module  string
	Token   module.Token
	Imports []string
}

ExportAmbiguousError is returned when a module re-exports a token that multiple imports provide.

func (*ExportAmbiguousError) Error added in v0.6.0 

func (e *ExportAmbiguousError) Error() string

func (*ExportAmbiguousError) Unwrap added in v0.6.0 

func (e *ExportAmbiguousError) Unwrap() error

type ExportNotVisibleError 

type ExportNotVisibleError struct {
	Module string
	Token  module.Token
}

ExportNotVisibleError is returned when a module exports a token it cannot access.

func (*ExportNotVisibleError) Error 

func (e *ExportNotVisibleError) Error() string

type Graph 

type Graph struct {
	Root    string
	Modules []ModuleNode
	Nodes   map[string]*ModuleNode
}

Graph represents the complete module dependency graph with all nodes and import relationships.

func BuildGraph 

func BuildGraph(root module.Module) (*Graph, error)

BuildGraph constructs the module dependency graph starting from the root module. It validates module metadata, checks for cycles, and ensures all imports are valid.

type GraphFormat added in v0.14.0 

type GraphFormat string

GraphFormat selects the serialization format for graph export. 

const (
	// GraphFormatMermaid exports the graph as Mermaid flowchart text.
	GraphFormatMermaid GraphFormat = "mermaid"
	// GraphFormatDOT exports the graph as Graphviz DOT text.
	GraphFormatDOT GraphFormat = "dot"
)

type GraphNodeNotFoundError added in v0.14.0 

type GraphNodeNotFoundError struct {
	Node string
}

GraphNodeNotFoundError is returned when graph export cannot find a node by name.

func (*GraphNodeNotFoundError) Error added in v0.14.0 

func (e *GraphNodeNotFoundError) Error() string

func (*GraphNodeNotFoundError) Unwrap added in v0.14.0 

func (e *GraphNodeNotFoundError) Unwrap() error

type InvalidModuleDefError 

type InvalidModuleDefError struct {
	Module string
	Reason string
}

InvalidModuleDefError is returned when a module's Definition() returns invalid metadata.

func (*InvalidModuleDefError) Error 

func (e *InvalidModuleDefError) Error() string

func (*InvalidModuleDefError) Unwrap 

func (e *InvalidModuleDefError) Unwrap() error

type InvalidModuleNameError 

type InvalidModuleNameError struct {
	Name string
}

InvalidModuleNameError is returned when a module has an empty or invalid name.

func (*InvalidModuleNameError) Error 

func (e *InvalidModuleNameError) Error() string

type ModuleCycleError 

type ModuleCycleError struct {
	Path []string
}

ModuleCycleError is returned when a circular dependency exists in module imports.

func (*ModuleCycleError) Error 

func (e *ModuleCycleError) Error() string

type ModuleNode 

type ModuleNode struct {
	Name    string
	Module  module.Module
	Def     module.ModuleDef
	Imports []string
}

ModuleNode represents a module in the dependency graph with its definition and import names.

type ModuleNotPointerError 

type ModuleNotPointerError struct {
	Module string
}

ModuleNotPointerError is returned when a module is not passed by pointer.

func (*ModuleNotPointerError) Error 

func (e *ModuleNotPointerError) Error() string

type NilBootstrapOptionError added in v0.13.0 

type NilBootstrapOptionError struct {
	Index int
}

NilBootstrapOptionError is returned when a nil bootstrap option is passed.

func (*NilBootstrapOptionError) Error added in v0.13.0 

func (e *NilBootstrapOptionError) Error() string

type NilImportError 

type NilImportError struct {
	Module string
	Index  int
}

NilImportError is returned when a module has a nil entry in its Imports slice.

func (*NilImportError) Error 

func (e *NilImportError) Error() string

type OverrideBuildNilError added in v0.13.0 

type OverrideBuildNilError struct {
	Token module.Token
}

OverrideBuildNilError is returned when an override has a nil Build function.

func (*OverrideBuildNilError) Error added in v0.13.0 

func (e *OverrideBuildNilError) Error() string

type OverrideTokenNotFoundError added in v0.13.0 

type OverrideTokenNotFoundError struct {
	Token module.Token
}

OverrideTokenNotFoundError is returned when an override token does not exist in the provider graph.

func (*OverrideTokenNotFoundError) Error added in v0.13.0 

func (e *OverrideTokenNotFoundError) Error() string

type OverrideTokenNotVisibleFromRootError added in v0.13.0 

type OverrideTokenNotVisibleFromRootError struct {
	Root  string
	Token module.Token
}

OverrideTokenNotVisibleFromRootError is returned when an override token is not visible from root scope.

func (*OverrideTokenNotVisibleFromRootError) Error added in v0.13.0 

func (e *OverrideTokenNotVisibleFromRootError) Error() string

type ProviderBuildError 

type ProviderBuildError struct {
	Module string
	Token  module.Token
	Err    error
}

ProviderBuildError wraps an error that occurred while building a provider instance.

func (*ProviderBuildError) Error 

func (e *ProviderBuildError) Error() string

func (*ProviderBuildError) Unwrap 

func (e *ProviderBuildError) Unwrap() error

type ProviderCycleError 

type ProviderCycleError struct {
	Token module.Token
}

ProviderCycleError is returned when a circular dependency exists in provider resolution.

func (*ProviderCycleError) Error 

func (e *ProviderCycleError) Error() string

type ProviderNotFoundError 

type ProviderNotFoundError struct {
	Module string
	Token  module.Token
}

ProviderNotFoundError is returned when attempting to resolve a token that has no registered provider.

func (*ProviderNotFoundError) Error 

func (e *ProviderNotFoundError) Error() string

type ProviderOverride added in v0.13.0 

type ProviderOverride struct {
	Token   module.Token
	Build   func(module.Resolver) (any, error)
	Cleanup func(context.Context) error
}

ProviderOverride replaces provider build/cleanup behavior for a token at bootstrap time.

type RootModuleNilError 

type RootModuleNilError struct{}

RootModuleNilError is returned when Bootstrap is called with a nil root module.

func (*RootModuleNilError) Error 

func (e *RootModuleNilError) Error() string

type TokenNotVisibleError 

type TokenNotVisibleError struct {
	Module string
	Token  module.Token
}

TokenNotVisibleError is returned when a module attempts to resolve a token that isn't visible to it.

func (*TokenNotVisibleError) Error 

func (e *TokenNotVisibleError) Error() string

type UnsupportedGraphFormatError added in v0.14.0 

type UnsupportedGraphFormatError struct {
	Format GraphFormat
}

UnsupportedGraphFormatError is returned when graph export receives an unsupported format.

func (*UnsupportedGraphFormatError) Error added in v0.14.0 

func (e *UnsupportedGraphFormatError) Error() string

type Visibility 

type Visibility map[string]map[module.Token]bool

Visibility represents which provider tokens are accessible from each module. The outer map key is the module name, the inner map contains visible tokens.

func BuildVisibility added in v0.6.0 

func BuildVisibility(graph *Graph) (Visibility, error)

BuildVisibility constructs the visibility map for all modules in the graph, ensuring exports are valid and detecting ambiguous re-exports.

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.