project

package
v0.3.1 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package project finds a project's Compose files and reads its x-mutti configuration.

Index

Constants

View Source
const (
	UserHost    = "host"
	UserService = "service"
)

User values with a special meaning.

Variables

View Source
var ErrNoComposeFile = errors.New("no Compose file found")

ErrNoComposeFile means no Compose file was found.

View Source
var ErrNoPlace = errors.New("no top-level key to put x-mutti before")

ErrNoPlace means a Compose file has no top-level block mapping to put x-mutti into.

Functions

func Insert

func Insert(src, block []byte) ([]byte, error)

Insert puts block before the first top-level key of a Compose file, leaving every other byte as it was: comments, blank lines and formatting are the user's.

func ValidRoutePath

func ValidRoutePath(p string) bool

ValidRoutePath reports whether p can be a route's path prefix.

Types

type Config

type Config struct {
	// The project's name, part of every hostname. Default: the main worktree's directory name.
	Name string `json:"name,omitempty"`
	// The service behind the instance's main hostname. Default: the service publishing or
	// exposing the most typical web port (80, 3000, 4200, 5173, 8000, 8080).
	Main string `json:"main,omitempty"`
	// HTTP routes per service. Default: the main service on the main hostname, every other
	// service publishing or exposing an HTTP port on <service>.<main hostname>.
	Routes map[string]Route `json:"routes,omitempty"`
	// Container ports to publish on a fixed host port, per service, for tools that keep a
	// connection setting, such as database GUIs. The port follows from instance, service and
	// port, so it stays the same across restarts.
	Ports map[string][]uint16 `json:"ports,omitempty"`
	// Settings for mutti worktree add.
	Worktree WorktreeConfig `json:"worktree,omitzero"`
	// How mutti exec, mutti shell and hooks run commands.
	Exec Exec `json:"exec,omitzero"`
	// Commands run inside services at points of an instance's life.
	Hooks Hooks `json:"hooks,omitzero"`
	// Named sets of extra Compose files, enabled with --overlay <name>. Without --overlay, commands
	// other than up and run use the overlays the instance was last started with.
	Overlays map[string][]string `json:"overlays,omitempty"`
}

Config is the x-mutti block of a Compose file. Every field is optional.

func ParseConfig

func ParseConfig(m *compose.Model) (Config, error)

ParseConfig reads and validates the x-mutti block of a model. Unknown keys are errors, so a typo never silently does nothing.

func (Config) HTTPRoutes

func (c Config) HTTPRoutes(m *compose.Model, mainHost string) []HTTPRoute

HTTPRoutes resolves the configured or default routes of a project under mainHost.

func (Config) MainService

func (c Config) MainService(m *compose.Model) string

MainService is x-mutti.main, or the service publishing or exposing the most typical web port.

type Draft

type Draft struct {
	Main     string              `json:"main,omitempty"`
	Routes   map[string]uint16   `json:"routes,omitempty"`   // service -> container port
	Overlays map[string][]string `json:"overlays,omitempty"` // name -> files relative to the project dir
	Ports    map[string][]uint16 `json:"ports,omitempty"`    // suggested fixed ports, written commented out
}

Draft is the x-mutti block mutti init writes: the main service and the overlays, plus the default routes and suggested fixed ports as comments to edit from.

func NewDraft

func NewDraft(m *compose.Model, files Files) (Draft, error)

NewDraft derives the draft from the project's model and the Compose files next to it.

func (Draft) Render

func (d Draft) Render() []byte

Render returns the draft as a top-level YAML block, ending in a newline.

type Exec

type Exec struct {
	// "host" (default): the host user's uid:gid, so files in bind mounts belong to you;
	// "service": the image's user; or an explicit user[:group].
	User string `json:"user,omitempty"`
	// $HOME for commands run as the host user, who has no home in the image. Default /tmp.
	Home string `json:"home,omitempty"`
}

Exec configures command execution inside services.

type Files

type Files struct {
	Dir   string
	Paths []string // absolute, in merge order
}

Files are the Compose files of a project and the directory Compose treats as project dir.

func Discover

func Discover(start, stop string, getenv func(string) string) (Files, error)

Discover finds the Compose files for start the way `docker compose` would: $COMPOSE_FILE if set, else the closest compose.yaml (or variant) in start or a parent, up to and including stop. An empty stop means up to the filesystem root.

type HTTPRoute

type HTTPRoute struct {
	Service string
	Hosts   []string // full hostnames
	Paths   []string // path prefixes on the main hostname
	Port    uint16
}

HTTPRoute is the resolved route of one service.

type Hook

type Hook struct {
	// Service to run the command in; it must be running.
	Service string `json:"service"`
	// Shell command, run with sh -c inside the service.
	Run string `json:"run"`
	// Like exec.user; empty means exec.user.
	User string `json:"user,omitempty"`
}

Hook is one command.

type Hooks

type Hooks struct {
	// Once per instance, after its first successful up.
	Bootstrap []Hook `json:"bootstrap,omitempty"`
	// After every up.
	PostUp []Hook `json:"post-up,omitempty"`
	// Before down, destroy and reset; a failure is reported but does not stop the teardown.
	PreDown []Hook `json:"pre-down,omitempty"`
	// Instead of bootstrap when the data was copied from another instance
	// (worktree add --data-from): the data needs no setup, the worktree may.
	AfterClone []Hook `json:"after-clone,omitempty"`
	// On mutti sweep, with MUTTI_SWEEP_OLDER_THAN in seconds: remove per-run resources the
	// project made inside services, such as test databases named after run ids.
	Sweep []Hook `json:"sweep,omitempty"`
}

Hooks are commands run inside services.

type Route

type Route struct {
	// Subdomain under the main hostname; "" is the main hostname itself. Default: the service
	// name, or "" for the main service.
	Host *string `json:"host,omitempty"`
	// Path prefix on the main hostname that also leads to the service, e.g. /api.
	Path string `json:"path,omitempty" jsonschema:"pattern=^/[A-Za-z0-9._~/-]*$"`
	// Container port to send traffic to. Default: the service's first published TCP port, else
	// its first exposed one.
	Port uint16 `json:"port,omitempty"`
}

Route is how the router reaches one service.

type WorktreeConfig

type WorktreeConfig struct {
	// Files and directories (globs allowed) that git does not track but a worktree needs, such
	// as .env.local; copied from the main worktree into new ones, never overwriting.
	Copy []string `json:"copy,omitempty"`
}

WorktreeConfig configures new worktrees.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL