kernel

type APIContract ¶

type APIContract struct {
	SuccessStatuses    []int
	RequestContentType string
	MaxBodyBytes       int64
	Limits             map[string]any
	Errors             []APIErrorResponse
}

APIContract describes transport details that cannot be inferred from Go types.

type APIErrorResponse ¶

type APIErrorResponse struct {
	Status            int
	Code, Description string
}

type APIOperation ¶

type APIOperation struct {
	Method, Path, Summary string
	Tags                  []string
	Scopes                []string
	Request, Response     any
	Params                []APIParam
	Handler               http.HandlerFunc
	Contract              *APIContract
}

APIOperation is one REST operation; Path is relative to the API mount ("/v1/content"). Request/Response are example values for OpenAPI schemas.

type APIParam ¶

type APIParam struct {
	Name, In, Type, Description string
	Required                    bool
}

APIParam documents a path/query/header parameter.

type APIRegistry ¶

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

APIRegistry collects REST operations (consumed by the api module for routing and OpenAPI generation).

func NewAPIRegistry() *APIRegistry

func (r *APIRegistry) Add(op APIOperation)

func (r *APIRegistry) Operations() []APIOperation

type AdminRegistry ¶

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

AdminRegistry collects admin navigation and dashboard widgets.

func NewAdminRegistry() *AdminRegistry

func (a *AdminRegistry) AddCanvasWidget(widget CanvasWidget)

func (a *AdminRegistry) AddNav(item NavItem)

func (a *AdminRegistry) AddNavProvider(fn func(ctx context.Context) []NavItem)

func (a *AdminRegistry) AddWidget(id string, render func(ctx context.Context, r *http.Request) (template.HTML, error))

func (a *AdminRegistry) CanvasWidgets() []CanvasWidget

func (a *AdminRegistry) Nav(ctx context.Context) []NavItem

func (a *AdminRegistry) NavIDs() []string

func (a *AdminRegistry) SetNavFilter(fn func(ctx context.Context, items []NavItem) []NavItem)

func (a *AdminRegistry) SetPermissionCheck(can func(ctx context.Context, perm string) bool)

func (a *AdminRegistry) Widgets() []Widget

type App ¶

type App struct {
	Deps    *Deps
	Handler http.Handler
	Close   func()
}

App is a booted GoRun instance. Close stops the job workers, waits for them, then closes the database; it is safe to call more than once.

func Boot(ctx context.Context, cfg config.Config, mods []Module) (*App, error)

func BootWithOptions(ctx context.Context, cfg config.Config, mods []Module, opts BootOptions) (*App, error)

type BootOptions ¶

type BootOptions struct {
	// StartJobs starts the job workers and cron scheduler (Boot does). CLI
	// commands that may run beside a live server (reindex --no-jobs) leave
	// it false: workers would requeue the server's running jobs as stale
	// and duplicate its cron ticks. Jobs enqueued meanwhile wait for the
	// server's workers.
	//
	// A process that starts job workers first takes the exclusive
	// data-directory lock (<data>/gorun.lock, see LockDataDir) and refuses
	// to boot when another process holds it; App.Close releases it.
	StartJobs bool
}

BootOptions tunes BootWithOptions.

type CanvasMetric ¶

type CanvasMetric struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

type CanvasWidget ¶

type CanvasWidget struct {
	ID, Href, Permission, NavID string
	Load                        func(*http.Request) (CanvasWidgetData, error)
}

CanvasWidget is an optional module-owned read-only projection. The admin validates board ownership, permission and visible navigation before Load.

type CanvasWidgetData ¶

type CanvasWidgetData struct {
	ID        string            `json:"id"`
	Title     string            `json:"title"`
	Href      string            `json:"href"`
	Metrics   []CanvasMetric    `json:"metrics"`
	Rows      []CanvasWidgetRow `json:"rows"`
	UpdatedAt string            `json:"updated_at"`
}

type CanvasWidgetRow ¶

type CanvasWidgetRow struct {
	Title  string `json:"title"`
	Detail string `json:"detail"`
	Href   string `json:"href"`
}

type CatalogProvider ¶

type CatalogProvider interface {
	Catalogs() fs.FS
}

CatalogProvider is optionally implemented by modules that ship translations. The FS holds "catalog/<module>.<locale>.json" files; they are loaded before any non-settings module registers.

type DataLock ¶

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

DataLock is a held data-directory lock. The OS releases it when the process exits, even after a crash, so a leftover gorun.lock file never blocks a restart.

func LockDataDir(dir string) (*DataLock, error)

func (l *DataLock) Path() string

func (l *DataLock) Release() error

type Deps ¶

type Deps struct {
	DB       *sql.DB
	Hooks    *hooks.Registry
	Jobs     *jobs.Queue
	Settings *settings.Store
	I18n     *i18n.Bundle // nil only while the settings module registers
	Log      *slog.Logger
	Config   config.Config
	Router   *Router
	Admin    *AdminRegistry
	Theme    *ThemeRegistry
	API      *APIRegistry
	MCP      *MCPRegistry
	Perms    *PermissionRegistry
	Audit    *audit.Writer
	Services *ServiceRegistry // Set(name, v) / Get[T](d, name): reach earlier modules' services without import cycles
}

Deps is the set of shared services handed to every module's Register.

type KindRequest ¶

type KindRequest struct{ Kind, Type, Slug, Template, Purpose, Taxonomy, Term string }

KindRequest describes what the theme should render; candidate functions map it to an ordered list of template names (most specific first). KindRequest asks the theme for a template. Purpose is a page's validated purpose (theme.PagePurposes), tried after its template.

type MCPRegistry ¶

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

MCPRegistry collects MCP tools.

func NewMCPRegistry() *MCPRegistry

func (r *MCPRegistry) AddTool(t MCPTool)

func (r *MCPRegistry) Tools() []MCPTool

type MCPTool ¶

type MCPTool struct {
	Name, Description string
	Input             any
	Scopes            []string
	Sensitive         bool
	Handler           func(ctx context.Context, args json.RawMessage) (any, error)
}

MCPTool is one MCP tool. Sensitive tools require human approval.

type Module ¶

type Module interface {
	Name() string
	Migrations() fs.FS
	Register(d *Deps) error
}

Module is a pluggable domain. Migrations returns an FS whose files live at "migrations/NNNN_name.sql" (nil when the module has no tables). Register wires the module into Deps; it runs once, in BootOrder.

type ModuleRegistration ¶ added in v0.16.0

type ModuleRegistration struct {
	Permissions       []string `json:"permissions" doc:"Declared by this module during Register (a name may also be declared by the auth base catalog)"`
	APIOperations     []string `json:"api_operations" doc:"METHOD /v1/path"`
	MCPTools          []string `json:"mcp_tools"`
	JobKinds          []string `json:"job_kinds"`
	Crons             []string `json:"crons"`
	Nav               []string `json:"nav" doc:"Static admin navigation item IDs"`
	Widgets           []string `json:"widgets"`
	ThemeFuncs        []string `json:"theme_funcs"`
	ThemeKinds        []string `json:"theme_kinds"`
	ServicesPublished []string `json:"services_published"`
	ServicesConsumed  []string `json:"services_consumed" doc:"Service names looked up during Register"`
	HookSubscriptions []string `json:"hook_subscriptions"`
	Catalog           bool     `json:"catalog" doc:"Ships ar/en translations"`
	Migrations        int      `json:"migrations" doc:"Migration files this build knows for the module"`
}

ModuleRegistration is what one module registered while its Register ran, observed by the kernel as the difference of every registry before and after the call. It is evidence of this boot, not a declaration: a module that registers lazily at request time is not seen here.

type ModuleState ¶ added in v0.14.0

type ModuleState struct {
	Name      string `json:"name"`
	Available bool   `json:"available"`
	Enabled   bool   `json:"enabled"`
	Optional  bool   `json:"optional"`
	Mode      string `json:"mode" doc:"Requested addon mode, or empty when not configured"`
	// Registered is what the module registered during this boot (nil when it
	// did not boot). LastKnownJobKinds are the job kinds it registered at its
	// last enabled boot, the basis for parking its queued work while it is off.
	Registered        *ModuleRegistration `json:"registered,omitempty"`
	LastKnownJobKinds []string            `json:"last_known_job_kinds,omitempty"`
}

ModuleState records the actual selection made for this process. Availability means the module was supplied to Boot; enabled means it passed the existing OptionalModule gate. Configuration alone never proves activation.

func Modules(d *Deps) []ModuleState

type NavItem ¶

type NavItem struct {
	ID, LabelKey, Icon, Href, Permission, Group string
	Position                                    int
}

NavItem is an admin navigation entry. LabelKey is an i18n key.

type NavigationPins ¶

type NavigationPins interface {
	PinnedNavigation(context.Context) ([]string, error)
}

NavigationPins provides personal dashboard placements without coupling auth to the optional admin module's tables. Pins remain hidden after preference reset.

type OptionalModule ¶

type OptionalModule interface {
	Enabled(context.Context, *sql.DB) (bool, error)
}

OptionalModule is evaluated before any module migrations, catalog loading or route registration. Disabled modules retain their existing data untouched. Enabled must only read the database; an empty database is valid.

The operator's config (config.Config.Addons, from the site config or GORUN_ADDONS) can only restrict: mode "disabled" turns an optional module off without calling Enabled; "enabled", "auto" or no entry leave the decision to the module, so configuration alone never proves activation. Modules that do not implement this interface are always booted; a mode configured for them is reported in the module inventory, warned about and ignored.

type Permission ¶

type Permission struct {
	Name  string
	Label map[string]string
}

Permission is a declared permission with labels by locale.

type PermissionRegistry ¶

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

PermissionRegistry collects permissions declared by modules. A name may be declared by more than one module (the auth base catalog lists the names default roles grant, and the owning module declares it again), so the registry also records which module declared what for the inventory.

func NewPermissionRegistry() *PermissionRegistry

func (p *PermissionRegistry) All() []Permission

func (p *PermissionRegistry) Declare(perm string, label map[string]string)

type Router ¶

type Router struct {
	Public, Admin, API, Webhooks chi.Router
	// contains filtered or unexported fields
}

Router holds the chi sub-routers modules register on during Register. Use may be called on any of them at any point during Register, even after earlier modules added routes: middlewares are collected and wrap every route of that router, in Use order, from the first request on (Use after serving starts panics). Boot mounts the routers on the root mux after every module has registered.

Mount prefixes: Public "/", Admin "/admin", API "/api" (modules add "/v1/..."; the spec's "/api/docs" sits outside v1), Webhooks "/webhooks". Session/CSRF/permission middleware on Admin and key-or-session on API are installed by the auth module via Admin.Use / API.Use; Webhooks stays raw. Admin and API deny every request (503) until SetAuthenticator is called. The root mux also serves GET /healthz (liveness), GET /readyz (DB ping), and optionally GET /metrics (Prometheus text when GORUN_METRICS is on), outside every sub-router.

func (r *Router) Authenticator() string

func (r *Router) SetAuthenticator(name string)

type SchemaInspector ¶

type SchemaInspector func(context.Context) (db.SchemaInspection, error)

SchemaInspector compares the live schema_migrations table with the migrations this binary ships. Boot publishes one under ServiceSchema; System Health calls it per request, so it sees a newer binary migrating the database while this one runs.

type ServiceRegistry ¶

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

ServiceRegistry lets later modules reach earlier modules' services by name (e.g. "content" → content.Service) without import cycles.

func NewServiceRegistry() *ServiceRegistry

func (s *ServiceRegistry) Names() []string

func (s *ServiceRegistry) Set(name string, v any)

type ThemeRegistry ¶

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

ThemeRegistry collects template funcs and template-hierarchy kinds.

func NewThemeRegistry() *ThemeRegistry

func (t *ThemeRegistry) AddFunc(name string, fn any)

func (t *ThemeRegistry) AddKind(kind string, candidates func(req KindRequest) []string)

func (t *ThemeRegistry) Candidates(req KindRequest) []string

func (t *ThemeRegistry) Funcs() template.FuncMap

func (t *ThemeRegistry) Kinds() []string

type Widget ¶

type Widget struct {
	ID     string
	Render func(ctx context.Context, r *http.Request) (template.HTML, error)
}

Widget is an admin dashboard widget.