kernel

Documentation

Overview

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

Index

• Variables
• type App
  • func Bootstrap(root module.Module) (*App, error)
  • func (a *App) CleanupHooks() []func(context.Context) error
  • func (a *App) Close() error
  • func (a *App) CloseContext(ctx context.Context) error
  • func (a *App) Closers() []io.Closer
  • func (a *App) Get(token module.Token) (any, error)
  • func (a *App) Resolver() module.Resolver
• type Container
  • func (c *Container) Get(token module.Token) (any, error)
• type ControllerBuildError
  • func (e *ControllerBuildError) Error() string
  • func (e *ControllerBuildError) Unwrap() error
• type DuplicateControllerNameError
  • func (e *DuplicateControllerNameError) Error() string
• type DuplicateModuleNameError
  • func (e *DuplicateModuleNameError) Error() string
• type DuplicateProviderTokenError
  • func (e *DuplicateProviderTokenError) Error() string
• type ExportAmbiguousError
  • func (e *ExportAmbiguousError) Error() string
  • func (e *ExportAmbiguousError) Unwrap() error
• type ExportNotVisibleError
  • func (e *ExportNotVisibleError) Error() string
• type Graph
  • func BuildGraph(root module.Module) (*Graph, error)
• type InvalidModuleDefError
  • func (e *InvalidModuleDefError) Error() string
  • func (e *InvalidModuleDefError) Unwrap() error
• type InvalidModuleNameError
  • func (e *InvalidModuleNameError) Error() string
• type ModuleCycleError
  • func (e *ModuleCycleError) Error() string
• type ModuleNode
• type ModuleNotPointerError
  • func (e *ModuleNotPointerError) Error() string
• type NilImportError
  • func (e *NilImportError) Error() string
• type ProviderBuildError
  • func (e *ProviderBuildError) Error() string
  • func (e *ProviderBuildError) Unwrap() error
• type ProviderCycleError
  • func (e *ProviderCycleError) Error() string
• type ProviderNotFoundError
  • func (e *ProviderNotFoundError) Error() string
• type RootModuleNilError
  • func (e *RootModuleNilError) Error() string
• type TokenNotVisibleError
  • func (e *TokenNotVisibleError) Error() string
• type Visibility
  • func BuildVisibility(graph *Graph) (Visibility, error)

Variables

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.

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

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

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 (*App) CleanupHooks

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

CleanupHooks returns provider cleanup hooks in LIFO order.

func (*App) Close

func (a *App) Close() error

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

func (*App) CloseContext

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

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

func (*App) Closers

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

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

func (e *ExportAmbiguousError) Error() string

func (*ExportAmbiguousError) Unwrap

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

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.