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
- func Home() (string, error)
- func Install(home string) (string, error)
- func Installed() bool
- func LogPath(home string) string
- func LoginServiceHome() string
- func NewLogger(w io.Writer, level, format string) *slog.Logger
- func NotifyPath(home string) string
- func ProjectID(path string) string
- func ProjectPath(id string) string
- func Run(ctx context.Context, o Options) error
- func StartInstalled(home string) (bool, error)
- func Stop(home string) error
- func TailLog(ctx context.Context, out io.Writer, home string, n int, follow bool) error
- func URLFor(host string, si ServerInfo, path string) string
- func Uninstall() (string, error)
- type Client
- type DirSuggestion
- type Options
- type Project
- type ProjectNotification
- type ProjectView
- type Registry
- type ServerInfo
- type Service
- func (s *Service) Active() int
- func (s *Service) AddPath(path, remote string) (Project, bool, error)
- func (s *Service) Clone(ctx context.Context, url string) (Project, bool, error)
- func (s *Service) FirstUse() bool
- func (s *Service) MachineNotify() *config.Notify
- func (s *Service) Notifications(limit int) (items []ProjectNotification, unread int)
- func (s *Service) OpenAll()
- func (s *Service) Remove(id string) error
- func (s *Service) Routes(r chi.Router)
- func (s *Service) Shutdown(ctx context.Context)
- func (s *Service) Status() Status
- type Status
Constants ¶
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 ¶
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 ¶
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 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 ¶
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 ¶
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 ¶
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 Run ¶
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 ¶
StartInstalled starts the login service if one is installed for home.
func Stop ¶
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.
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 ¶
AddPath resolves path against the caller's working directory before sending it: the service runs elsewhere (often with / as its working directory).
func (*Client) List ¶
func (c *Client) List() ([]ProjectView, error)
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 ¶
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 (*Service) AddPath ¶
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 ¶
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
FirstUse reports whether the tour and checklist haven't been shown yet, and records that they now have been.
func (*Service) MachineNotify ¶
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.
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.