kernel

Documentation

Overview

Package kernel boots the application.

It is the single place where an application is composed. One difference matters: the Kernel boots ONCE, at process start, not per request, so nothing here may assume request scope.

This package is a bridge. It is removed in v1.0.0; import github.com/arandu-io/framework/foundation directly.

The boot sequence moved to github.com/arandu-io/framework/foundation, and this package is now the old names pointing at it. Unlike every other bridge in the collection, this one does not point at github.com/arandu-io/hesape: it points one directory across.

The death date above is what keeps this from being a second way to import one type. Nothing here holds an implementation: where the name and the signature survived the move it is a Go alias, and where the design diverged it is an envelope that translates and nothing more.

The one rename, and the two wrappers

Kernel        is foundation.Application; the old name stays here as an alias
New           a wrapper and not an alias, because Go has no alias form for a
              function. It answers *Kernel and takes the settings
              bootstrap.LoadConfiguration builds, one struct per component
FormatRoutes  the same, and what it now calls through to is
              hesape/routing.FormatRoutes

Everything else is an alias, and most of them are aliases of aliases: the module vocabulary that foundation forwards to github.com/arandu-io/hesape/foundation arrives here under the old names unchanged, so a module compiled against kernel.Migratable and one compiled against hesape/foundation.Migratable satisfy the same interface.

Two names foundation declares rather than forwards, and they keep their old meaning here exactly: Module, whose Routes still takes a *http.Router, and Locker, which is retired and which the events bridge kept because github.com/arandu-io/kv asserts against it.

Index

• Constants
• func FormatRoutes(routes []*http.Route) string
• type Background
• type Bootable
• type Closable
• type Diagnostic
• type Health
• type Kernel
  • func New(cfg bootstrap.Configuration) *Kernel
• type Locker
• type Migratable
• type Migration
• type Module
• type ReloadTagger
• type RendererProvider
• type Schedulable
• type Scope
• type Task

Constants

const (
	// Global runs the task once for the whole instance.
	//
	// It gets the zero Grant, because SystemGrant refuses an empty tenant -- so
	// a global task cannot pass any Check and cannot reach a repository. That
	// is a constraint rather than an oversight: global work is cleaning
	// temporary files, warming a cache, checking a certificate. Work that reads
	// a customer's rows is PerTenant, and having to say so is the point.
	Global = foundation.Global
	// PerTenant expands the task to every active tenant, each with its own
	// Grant and its own lock.
	PerTenant = foundation.PerTenant
)

Functions

func FormatRoutes

func FormatRoutes(routes []*http.Route) string

FormatRoutes renders the route table for the terminal, grouped by module and sorted by pattern. It is here, and not in the CLI, so that every project prints the same table.

A wrapper for the same reason New is. What it reaches is hesape/routing.FormatRoutes, through foundation.

Types

type Background

type Background = foundation.Background

Background is optional: the module runs a loop of its own -- the scheduler and the outbox relay do.

Start is called by Run, never by Boot, and that distinction is the difference between a process that serves and a process that does something else.

It no longer embeds Module: hesape/foundation.Background declares Start alone. Nothing changes at a call site, because Register takes a Module and anything the kernel asks for a loop is already one.

type Bootable

type Bootable = foundation.Bootable

Bootable is optional: implement it when the module needs to prepare state at boot -- open a pool, warm a cache, register codecs.

Boot wires; it does not run. A module that needs a loop of its own implements Background instead, and validates in Boot whatever would make that loop fail.

type Closable

type Closable = foundation.Closable

Closable is optional: implement it to release resources on shutdown.

type Diagnostic

type Diagnostic = foundation.Diagnostic

Diagnostic is optional: the module reports what it knows about the state of the system, in sentences a person can act on.

It feeds the error page. The most useful hint is often about something that happened outside the failing request -- the outbox stuck for four minutes, a job that has not run -- and a page that only looks at the request cannot see any of it.

type Health

type Health = foundation.Health

Health is optional and feeds `aru doctor` and the /_arandu/health endpoint.

type Kernel

type Kernel = foundation.Application

Kernel holds the composed application: configuration, modules, the global middleware pipeline and the router.

It is foundation.Application under its old name. The alias is what keeps it one type rather than two: a *Kernel handed to something written against *foundation.Application is the same value, with the same methods -- Boot, Run, Handler, Shutdown, Register, Use, Migrations, Tasks, Diagnose, Routes, Recorder, Config, Logger -- and none of them are restated here.

func New

func New(cfg bootstrap.Configuration) *Kernel

New assembles the kernel. It opens no connection and listens on no port -- that is Boot and Run.

A wrapper and not an alias: Go has no alias form for a function.

It takes the settings LoadConfiguration answers, one struct per component. The single struct it used to take is gone from the boot path, and keeping the old signature here would have meant a translation between the two -- a second answer to what an application is configured with, which is the thing this bridge exists to retire rather than to preserve.

type Locker

type Locker = foundation.Locker

Locker is a distributed lock, for work that must happen once across replicas.

It lives in foundation because two things need it -- the outbox relay and the scheduler -- and two identical interfaces in two packages is the duplication that the second one would create. github.com/arandu-io/kv implements it, and events.Locker is an alias to this name.

Nil is correct for a single replica and wrong for two. What it costs is duplicate work, which every task here has to tolerate anyway.

type Migratable

type Migratable = foundation.Migratable

Migratable is optional: the module declares its migrations, and the Kernel collects them from every registered module in registration order.

type Migration

type Migration = foundation.Migration

Migration is a versioned, immutable-once-published schema change.

It is an alias, not a copy: the migration runner lives in hesape, and a module must be able to hand its migrations straight to it. It is an interface -- embed migrations.BaseMigration and only GetName and Up are left to write.

type Module

type Module = foundation.Module

Module is the only unit of composition in the framework.

A module is a directory. It registers its own routes, its own migrations and its own dependency graph. There is no injection container and no reflection based resolution: the wiring is explicit, and the CLI generates the file that instantiates everything.

Every third-party module implements this interface and nothing else. It is the public contract of the framework -- change it and the whole ecosystem breaks, so change it with great care.

type ReloadTagger

type ReloadTagger = foundation.ReloadTagger

ReloadTagger is what a module implements to supply the development live-reload tag.

Optional, and asked for the same way the renderer is: the kernel cannot import the view package -- that package imports this one in order to be a Module -- so what it needs arrives through an interface declared there and satisfied here. The kernel supplies the address of its own endpoint, because the route is its own, and two constants for one address is how a client and a server come to disagree about it.

type RendererProvider

type RendererProvider = foundation.RendererProvider

RendererProvider is optional: the module supplies the view renderer.

The view package implements it. The kernel cannot import that package -- it implements Module, so the import would be a cycle -- and an application calling a wiring function by hand is a line somebody forgets. An optional interface solves both: the kernel asks every module whether it brings a renderer, before any route is registered.

Two modules providing one is a wiring mistake, and the kernel refuses to boot rather than pick one.

type Schedulable

type Schedulable = foundation.Schedulable

Schedulable is optional: the module declares its scheduled work.

type Scope

type Scope = foundation.Scope

Scope says whether a task runs once or once per tenant.

type Task

type Task = foundation.Task

Task is scheduled work.

The shape mirrors Migrations(): the module declares, the kernel collects, and nothing runs until something asks. What a module never does is start its own goroutine.