contract

type CliModule ¶

type CliModule interface {
	Module
	RegisterCliCommands(kernelInstance kernelcontract.Kernel) []clicontract.Command
}

type ConfigModule ¶ added in v1.8.0

type ConfigModule interface {
	Module
	RegisterConfigurations(registrar ConfigRegistrar)
}

type ConfigRegistrar ¶ added in v1.8.0

type ConfigRegistrar interface {
	RegisterConfiguration(name string, configuration any)
}

type EventModule ¶

type EventModule interface {
	Module
	RegisterEventSubscribers(kernelInstance kernelcontract.Kernel)
}

type HttpMiddlewareModule ¶ added in v1.6.2

type HttpMiddlewareModule interface {
	Module
	RegisterHttpMiddlewares(kernelInstance kernelcontract.Kernel, registrar HttpMiddlewareRegistrar)
}

type HttpMiddlewareRegistrar ¶ added in v1.6.2

type HttpMiddlewareRegistrar interface {
	Use(middlewares ...httpcontract.Middleware)

	UseWithPriority(priority int, middlewares ...httpcontract.Middleware)
}

type HttpModule ¶

type HttpModule interface {
	Module
	RegisterHttpRoutes(kernelInstance kernelcontract.Kernel)
}

HttpModule registers routes on the kernel's router. The application's own routes — the ones RegisterHttpRoute queued — are already registered when this hook runs, so where a module route and a root route meet at dispatch, the root route wins the registration-order tie-break.

type Module ¶

type Module interface {
	Name() string

	Description() string
}

Module is one unit of wiring, booted through the optional hook interfaces beside this one (ConfigModule, ParameterModule, ServiceModule, ScopedServiceModule, SecurityModule, EventModule, HttpMiddlewareModule, HttpModule, CliModule), each implemented only where the module has something to register.

The hooks run grouped by hook, not by module: every registered module's instance of one hook runs before any module's next hook, with the modules visited in registration order inside each group. A module ordering itself against a sibling therefore orders against the same hook, never against the sibling's whole boot; the application's own http routes register before any module's.

No framework service exists inside any hook. The container is built after the module phases on purpose: the framework claims a default only for a name no module registered — the logger, the cache backend, the session storage, the firewall — so the modules must have spoken first. A hook that needs a framework service registers a provider and resolves it there, at resolution time, when the container is complete; resolving in the hook body finds an empty container.

A module's identity is its instance: the same instance reached through two providers or two registrations boots once. Name and Description identify it in diagnostics and do not participate in that identity.

type ModuleProvider ¶

type ModuleProvider interface {
	Modules() []Module
}

ModuleProvider hands the application a set of modules to register. A provider that itself implements Module is registered as that module, its own hooks included, and its children follow it; whatever arrives more than once — through either door — boots once.

type ParameterModule ¶ added in v1.6.1

type ParameterModule interface {
	Module
	RegisterParameters(registrar ParameterRegistrar)
}

type ParameterRegistrar ¶ added in v1.6.1

type ParameterRegistrar interface {
	RegisterParameter(name string, value any)

	/* RegisterSecretParameter declares a parameter holding a credential, so the commands that render the configuration redact it and every parameter whose template reads it. */
	RegisterSecretParameter(name string, value any)

	/* MarkParameterSecret marks a parameter that already exists, which is how the credentials melody registers automatically from the .env artifacts are covered. */
	MarkParameterSecret(name string)
}

type ProcessContext ¶ added in v1.19.0

type ProcessContext interface {
	ProcessId() string

	StartedAt() time.Time
}

ProcessContext is the console counterpart of the http request context: the identity of one cli run — the generated process id every log record of the run is correlated under, and the moment the run started. It lives on the run's scope, installed by the cli entry point, so a scoped service resolves it exactly the way a request-scoped service resolves the request context; the root container never carries it, and an http process carries the request context instead.

type ScopedServiceModule ¶ added in v1.19.0

type ScopedServiceModule interface {
	Module

	RegisterScopedServices(kernelInstance kernelcontract.Kernel, registrar ScopedServiceRegistrar)
}

ScopedServiceModule is the hook for services whose lifetime is one scope — one http request, one command run. What it registers is built on the first resolution through a scope and closed when that scope closes, so a service may hold the request it was built for without holding it for the life of the process. A long-running command that processes many units of work under its one run scope creates a child runtime per unit — a fresh scope, a runtime over it, closed with the unit, the cron runner's shape — so what is registered here stays unit-lifetime there too.

It is a separate interface rather than a second method on ServiceModule because every module that exists implements the latter, and a hook nobody asked for must not be a compile break.

Like RegisterServices, the hook runs before the framework's own container boot: no framework service is resolvable inside it, and a scoped provider that needs one resolves it at resolution time, through the scope it is built in.

type ScopedServiceRegistrar ¶ added in v1.19.0

type ScopedServiceRegistrar interface {
	RegisterScopedService(
		serviceName string,
		provider any,
		options ...containercontract.RegisterOption,
	)
}

ScopedServiceRegistrar registers the services a scope owns.

It shares no method with ServiceRegistrar on purpose. The two registrations differ only in lifetime, and a provider handed to the wrong one is a mistake the compiler cannot see when both spell the same verb: a container provider registered as scoped is rebuilt and torn down once per request without ever failing. A container provider handed to this hook, or a scoped provider handed to RegisterServices, is therefore a compile error at the call site.

type SecurityModule ¶ added in v1.19.0

type SecurityModule interface {
	Module

	RegisterSecurity(builder *securityconfig.Builder)
}

SecurityModule is the hook through which a module contributes firewalls, providers and access rules to the one security configuration the application compiles. Every module's contribution lands on the same builder, in registration order, and the compiled result exists only after all of them ran.

type ServiceModule ¶ added in v1.6.1

type ServiceModule interface {
	Module
	RegisterServices(kernelInstance kernelcontract.Kernel, registrar ServiceRegistrar)
}

ServiceModule registers process-lifetime services. The hook runs before the framework's own container boot, so no framework service is resolvable inside it — Has answers false even for the logger, because the framework claims a default only for a name no module registered. A provider registered here resolves its dependencies at resolution time, when the container is complete.

type ServiceRegistrar ¶ added in v1.6.1

type ServiceRegistrar interface {
	RegisterService(
		serviceName string,
		provider any,
		options ...containercontract.RegisterOption,
	)
}