engine

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 27, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package engine composes Yacht for a program to run — this repository's own cmd/yacht, or an application wrapping the engine with its own identity, chrome, notifications and orchestrator.

The engine's packages are internal, which is what keeps them free to change. This package is the one public surface: the four seams, as aliases of the internal types so a wrapping application can name and implement them, and the composition that cmd/yacht used to hold, so a wrapper runs the same engine the same way with overrides rather than a copy of main.

A wrapping application does: 

cfg, _ := engine.LoadConfig()
engine.Run(ctx, cfg, engine.Overrides{
	Slots:    myChrome{},          // brand, header tools, banner, extra nav
	Identity: myOrganisations,     // who a request acts as
	Extra:    engine.ExtraRoutes{Owner: mountBilling},
})

Everything the engine does — apps, deploys, builds, domains, certificates, storage, teams — is unchanged underneath.

Index

Constants

View Source 
const (
	RoleOwner  = account.RoleOwner
	RoleAdmin  = account.RoleAdmin
	RoleMember = account.RoleMember

	// SessionCookie is the cookie the engine's sessions live in.
	SessionCookie = web.SessionCookie

	// DefaultBrandName is the engine's own name, where its chrome puts it —
	// what a wrapper replaces.
	DefaultBrandName = web.DefaultBrandName
)

Variables

View Source 
var (
	// LoadConfig reads the engine's configuration from the environment.
	LoadConfig = config.Load
	// Layout draws a page inside the engine's chrome.
	Layout = web.Layout
	// OwnerFromContext reads the Owner identity middleware resolved.
	OwnerFromContext = identity.FromContext
	// MustOwnerFromContext is OwnerFromContext for a handler that is certainly
	// behind the middleware.
	MustOwnerFromContext = identity.MustFromContext
	// NewSingleOwner and NewStaticToken are the engine's own providers, for a
	// wrapper that wants one of them in some deployments.
	NewSingleOwner = identity.NewSingleOwner
	NewStaticToken = identity.NewStaticToken
)

Functions

func NewLogger 

func NewLogger(debug bool) *slog.Logger

NewLogger is the engine's own logger: text, to stdout, debug when asked.

func Run 

func Run(ctx context.Context, cfg Config, ov Overrides) error

Run composes the engine and serves it until ctx ends.

func ServeHTTP 

func ServeHTTP(
	ctx context.Context, addr string, handler http.Handler, shutdown time.Duration, log *slog.Logger,
) error

ServeHTTP serves handler on addr until ctx ends. Exposed for a wrapper that composes the engine's handler into a larger one and serves that instead.

Types

type Accounts 

type Accounts = account.Service

Accounts is the engine's teams, people, invitations and sessions. A wrapper's organisations build on it rather than beside it.

type Apps 

type Apps = app.Service

Apps is the engine's app service: everything about workloads.

type Config 

type Config = config.Config

Config is the engine's configuration, read from YACHT_* variables.

type Crumb 

type Crumb = web.Crumb

The seams, by their engine names. Aliases rather than copies: a value a wrapper builds against these is the same type the engine consumes.

type DefaultSlots 

type DefaultSlots = web.DefaultSlots

DefaultSlots is the engine's own chrome, to start from and adjust.

type Engine 

type Engine struct {
	Config Config
	Log    *slog.Logger
	Pool   *pgxpool.Pool

	Orchestrator Orchestrator
	// Accounts is nil when accounts are off (no YACHT_BASE_URL).
	Accounts *Accounts
	Mailer   Mailer
	Identity IdentityProvider
	// Keeper is non-nil only with YACHT_SECRET_KEY set; Keeper.Configured
	// reports which, and is safe on nil.
	Keeper *Keeper
	Apps   *Apps
	Server *Server
	// contains filtered or unexported fields
}

Engine is a composed, not yet running, Yacht.

func New 

func New(ctx context.Context, cfg Config, ov Overrides) (*Engine, error)

New composes the engine: migrates and connects the database, connects the cluster, and builds every service and the dashboard. Nothing runs yet; Start or Serve does that.

func (*Engine) Close 

func (e *Engine) Close()

Close releases the database pool. Run does this itself.

func (*Engine) Handler 

func (e *Engine) Handler() http.Handler

Handler is the dashboard, with the wrapper's extra routes mounted.

func (*Engine) Serve 

func (e *Engine) Serve(ctx context.Context) error

Serve starts the background work and serves the dashboard on the configured address until ctx ends, then shuts down within the configured timeout.

func (*Engine) Start 

func (e *Engine) Start(ctx context.Context)

Start runs the engine's background work until ctx ends: the operation worker that admits and executes deploys, the reconcilers, the domain checker, and request logging. Every loop is safe to run in several processes at once, so a wrapper may run replicas.

type ExtraRoutes 

type ExtraRoutes = web.ExtraRoutes

ExtraRoutes are routes a wrapper mounts inside the engine's role gates.

type IdentityProvider 

type IdentityProvider = identity.Provider

IdentityProvider resolves a request to an Owner — seam 2.

type Keeper 

type Keeper = secret.Keeper

Keeper seals secrets at rest.

type Mailer 

type Mailer = notify.Mailer

Mailer delivers the engine's messages — seam 4.

type Message 

type Message = notify.Message

The seams, by their engine names. Aliases rather than copies: a value a wrapper builds against these is the same type the engine consumes. 

type NavGroup = web.NavGroup

The seams, by their engine names. Aliases rather than copies: a value a wrapper builds against these is the same type the engine consumes. 

type NavItem = web.NavItem

The seams, by their engine names. Aliases rather than copies: a value a wrapper builds against these is the same type the engine consumes.

type Orchestrator 

type Orchestrator = orchestrator.Orchestrator

Orchestrator runs workloads — seam 1.

type Overrides 

type Overrides struct {
	// Version is what the dashboard reports. cmd/yacht sets it at build time.
	Version string

	// Logger, or the engine's own text logger at the configured level.
	Logger *slog.Logger

	// Slots is the chrome: brand, navigation, header tools, banner.
	Slots SlotProvider

	// Identity resolves who a request acts as. Given the engine so it can
	// build on Accounts, which exist by the time it is called.
	Identity func(e *Engine) (IdentityProvider, error)

	// Mailer delivers sign-in links and invitations.
	Mailer Mailer

	// Orchestrator runs workloads; nil connects to the configured cluster.
	Orchestrator Orchestrator

	// Extra is routes mounted inside the engine's role gates.
	Extra ExtraRoutes

	// AfterMigrate runs once the engine's schema is current, for a wrapper's
	// own migrations. They share the database; a wrapper keeps its own goose
	// version table so the two histories never collide.
	AfterMigrate func(ctx context.Context, pool *pgxpool.Pool) error
}

Overrides are what a wrapping application supplies. Every field is optional; nil means the engine's own.

type Owner 

type Owner = identity.Owner

Owner is the principal a request acts as. The engine treats ID as opaque; a wrapper may make it an organisation's.

type Role 

type Role = account.Role

Role is a team role, for a wrapper gating pages of its own.

type Server 

type Server = web.Server

Server is the engine's dashboard.

type SlotProvider 

type SlotProvider = web.SlotProvider

SlotProvider fills the chrome for one request.

type SlotProviderFunc 

type SlotProviderFunc = web.SlotProviderFunc

SlotProviderFunc is a SlotProvider from a function.

type Slots 

type Slots = web.Slots

Slots is the chrome around every page, as data — seam 3.

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.