service

package
v2.6.0 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Overview

Package service runs groundwork as one long-lived server that hosts many projects (repositories), each with its own checks, runs and watchers.

Index

Constants

View Source
const RegistryFormat = 1

RegistryFormat is the layout version of projects.json. A file written by a newer groundwork with a higher format is refused rather than misread; this build will still read every format up to this one.

Variables

This section is empty.

Functions

func Home

func Home() (string, error)

Home returns the service's data directory: $GROUNDWORK_HOME, else <user config dir>/groundwork (~/Library/Application Support on macOS, ~/.config on Linux). Per-project state stays in each repo's .groundwork/.

func Install

func Install(home string) (string, error)

Install registers groundwork to start at login and starts it now. It records the current PATH, since login services otherwise get a minimal one and wouldn't find terraform, ansible or the linters.

func Installed

func Installed() bool

Installed reports whether a login service unit exists.

func LogPath

func LogPath(home string) string

LogPath is where a background service writes its output.

func LoginServiceHome added in v2.1.0

func LoginServiceHome() string

LoginServiceHome is the data directory the installed login service uses ("" when none is installed or it can't be read).

func NewLogger

func NewLogger(w io.Writer, level, format string) *slog.Logger

NewLogger builds the service logger. level is debug|info|warn|error (default info; GROUNDWORK_LOG is read by the CLI), format text|json.

func NotifyPath

func NotifyPath(home string) string

NotifyPath is the file holding the notification settings for every project: a notify: block, as in groundwork.yaml, which a project's own block overrides key by key.

func ProjectID

func ProjectID(path string) string

ProjectID is a URL-safe id that is stable for a path: the directory name plus a short hash, so two checkouts named "infra" don't collide.

func ProjectPath

func ProjectPath(id string) string

ProjectPath is where a project's UI lives.

func Run

func Run(ctx context.Context, o Options) error

Run starts the service and blocks until interrupted. If a service is already running for this home, the folders in o.Add are imported into it.

func StartInstalled

func StartInstalled(home string) (bool, error)

StartInstalled starts the login service if one is installed for home.

func Stop

func Stop(home string) error

Stop asks a running service to shut down (SIGTERM: runs stop gracefully). When the login service is installed its unit is stopped first, so launchd/systemd don't start it again. A service started outside the unit (a plain `groundwork` runs one in the background) isn't the unit's to stop, so whatever still answers is then signalled directly.

func TailLog

func TailLog(ctx context.Context, out io.Writer, home string, n int, follow bool) error

TailLog writes the last n lines of the service log to out and, with follow, keeps printing new lines until ctx is done. Rotation is handled: when the file shrinks or is replaced, reading restarts from the new file.

func URLFor

func URLFor(host string, si ServerInfo, path string) string

func Uninstall

func Uninstall() (string, error)

Types

type Client

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

Client talks to a running service on behalf of the CLI.

func NewClient

func NewClient(si ServerInfo) *Client

func (*Client) AddPath

func (c *Client) AddPath(path string) (Project, error)

AddPath resolves path against the caller's working directory before sending it: the service runs elsewhere (often with / as its working directory).

func (*Client) AddURL

func (c *Client) AddURL(u string) (Project, error)

func (*Client) List

func (c *Client) List() ([]ProjectView, error)

func (*Client) Remove

func (c *Client) Remove(id string) error

func (*Client) Status

func (c *Client) Status() (Status, error)

Status is what the service says about itself (GET /api/service).

type DirSuggestion added in v2.1.0

type DirSuggestion struct {
	Path string `json:"path"` // as typed: "~/…" stays "~/…"
	Git  bool   `json:"git"`  // has a .git: importing it imports that repository
}

DirSuggestion is one folder offered while typing a path to import.

func SuggestDirs added in v2.1.0

func SuggestDirs(typed string) []DirSuggestion

SuggestDirs lists the folders a partly typed path could continue into: "~/go/" lists ~/go's folders, "~/go/sr" those starting with "sr". Only "~/…" and absolute paths are completed; hidden folders only when the typed name starts with a dot. Names of folders only, never files.

type Options

type Options struct {
	Home        string // default Home()
	Host        string
	Port        int
	NoOpen      bool
	AllowRemote bool
	Version     string
	Commit      string
	// Log overrides the service logger (tests). When nil, Run logs to
	// <home>/groundwork.log through a size-capped, rotating writer, at
	// LogLevel in LogFormat, and also to stderr when LogToStderr is set.
	Log         *slog.Logger
	LogLevel    string // debug | info | warn | error (default info)
	LogFormat   string // text | json (default text)
	LogToStderr bool
	Add         []string  // folders to import at startup; the browser opens the first
	Out         io.Writer // startup messages; default os.Stdout
}

type Project

type Project struct {
	ID     string    `json:"id"`
	Name   string    `json:"name"`
	Path   string    `json:"path"`
	Remote string    `json:"remote,omitempty"` // set when groundwork cloned it
	Added  time.Time `json:"added"`
}

Project is one imported repository.

type ProjectNotification

type ProjectNotification struct {
	Project     string `json:"project"`
	ProjectName string `json:"project_name"`
	store.Notification
}

ProjectNotification is a notification on the service-wide list: the project's own, with the project it came from.

type ProjectView

type ProjectView struct {
	Project
	Status string `json:"status"` // ok | unavailable
	Error  string `json:"error,omitempty"`
	*api.Summary
}

ProjectView is one entry of GET /api/projects.

type Registry

type Registry struct {

	// Quarantined is set when projects.json was unreadable and moved aside.
	Quarantined string
	// contains filtered or unexported fields
}

Registry is the persisted project list (<home>/projects.json).

func OpenRegistry

func OpenRegistry(home string) (*Registry, error)

func (*Registry) Add

func (r *Registry) Add(path, remote string) (Project, bool, error)

Add registers path (absolute) and returns the project; a path already registered returns the existing entry.

func (*Registry) Get

func (r *Registry) Get(id string) (Project, bool)

func (*Registry) List

func (r *Registry) List() []Project

func (*Registry) Remove

func (r *Registry) Remove(id string) (Project, bool, error)

type ServerInfo

type ServerInfo struct {
	PID     int    `json:"pid"`
	Port    int    `json:"port"`
	Version string `json:"version,omitempty"` // the binary serving; the CLI warns when it differs from its own
	Token   string `json:"-"`
}

ServerInfo is persisted to <home>/server.json so other invocations (the CLI, a second `serve`) can find the running service. The CLI's token is not part of the file: Running reads it from <home>/token.

func Running

func Running(home string) (ServerInfo, bool)

Running reports whether <home>/server.json points at a live service.

func StartBackground

func StartBackground(home string, port int) (ServerInfo, error)

StartBackground launches `groundwork serve` detached from this terminal and waits until it answers.

func (ServerInfo) Base

func (si ServerInfo) Base() string

func (ServerInfo) URL

func (si ServerInfo) URL(path string) string

URL is the console's address for path. It carries no credentials: the browser signs in with a password or passkey. It names localhost, the one origin passkeys and the session cookie are bound to.

type Service

type Service struct {
	Home    string
	Version string
	Commit  string
	Port    int       // the port being served (0 until Run binds)
	Started time.Time // when Run bound the port
	LogFile string    // the service log, for `groundwork service logs`
	Log     *slog.Logger
	Reg     *Registry
	// contains filtered or unexported fields
}

Service owns every open project. Each project gets the same machinery the single-repo binary had: its own store, event bus, checks, runner, drift schedule and file watcher.

func New

func New(ctx context.Context, home, version string, log *slog.Logger) (*Service, error)

func (*Service) Active

func (s *Service) Active() int

Active is the number of runs in progress across all projects.

func (*Service) AddPath

func (s *Service) AddPath(path, remote string) (Project, bool, error)

AddPath imports a local folder. A folder inside a git repository imports the repository root, matching what running groundwork there used to do.

func (*Service) Clone

func (s *Service) Clone(ctx context.Context, url string) (Project, bool, error)

Clone clones url into <home>/repos/<name> with the user's own git, so SSH keys and credential helpers work as they do in a terminal, then imports it. A URL that was already cloned imports the existing checkout.

func (*Service) FirstUse added in v2.3.0

func (s *Service) FirstUse() bool

FirstUse reports whether the tour and checklist haven't been shown yet, and records that they now have been.

func (*Service) MachineNotify

func (s *Service) MachineNotify() *config.Notify

MachineNotify returns the notification settings for every project (nil when notify.yaml is missing, empty or broken; a broken file is logged and reported on the settings page).

func (*Service) Notifications

func (s *Service) Notifications(limit int) (items []ProjectNotification, unread int)

Notifications merges every open project's notifications, newest first.

func (*Service) OpenAll

func (s *Service) OpenAll()

OpenAll starts every registered project. A project that fails to open is kept (and reported) so a missing folder doesn't take the service down.

func (*Service) Remove

func (s *Service) Remove(id string) error

func (*Service) Routes

func (s *Service) Routes(r chi.Router)

Routes mounts the service API: the project list and, under /p/{id}, each project's own API (the same endpoints the single-repo server had).

func (*Service) Shutdown

func (s *Service) Shutdown(ctx context.Context)

func (*Service) Status

func (s *Service) Status() Status

type Status

type Status struct {
	Version   string    `json:"version"`
	Commit    string    `json:"commit,omitempty"`
	GoVersion string    `json:"go_version"`
	Home      string    `json:"home"`
	ReposDir  string    `json:"repos_dir"`
	LogFile   string    `json:"log_file,omitempty"`
	Port      int       `json:"port"`
	PID       int       `json:"pid"`
	StartedAt time.Time `json:"started_at"`
	UptimeSec int64     `json:"uptime_seconds"`
	Projects  struct {
		Available   int `json:"available"`
		Unavailable int `json:"unavailable"`
	} `json:"projects"`
	RunningJobs int `json:"running_jobs"`
}

Status is GET /api/service: what the running service is and is doing.

Jump to

Keyboard shortcuts

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