README
¶
svcroot
Service instance roots, runtime file layout, project-root discovery, and known-instance registries for long-running local services.
Install
From pkg.go.dev:
go get github.com/brandonkramer/svcroot
Configure once with Service
svc := &svcroot.Service{
EnvVar: "MYAPP_HOME",
DefaultDir: ".myapp",
RegistryFile: "sessions/known-instances.json", // optional
Layout: svcroot.Layout{
SessionsDir: "sessions",
SocketName: "rpc.sock",
LockName: "service.lock",
},
}
root, err := svc.Resolve()
h := svc.Open(root)
socket := h.Socket()
lock := h.Lock()
tasksDir := h.Join("tasks")
registry := h.RuntimeJoin("state.json")
Legacy helpers
layout := &svcroot.DefaultLayout
socket := svcroot.Socket(root, layout)
lock := svcroot.Lock(root, layout)
Development
make check # race tests + linux compile + golangci-lint
make install-hooks # lefthook pre-commit/pre-push
Documentation
¶
Overview ¶
Package svcroot resolves service instance roots, runtime file layout, project-root discovery, and optional known-instance registries.
Configure a Service once, then call Service.Resolve and Service.Open for path helpers. Use Layout directly when you prefer functional helpers.
Examples ¶
svc := &svcroot.Service{
EnvVar: "MYAPP_HOME",
DefaultDir: ".myapp",
Layout: svcroot.DefaultLayout,
}
root, err := svc.Resolve()
socket := svc.Open(root).Socket()
Index ¶
- Variables
- func CandidateHomes(registryPath, envVar, envHome, defaultHome string) ([]string, error)
- func DefaultHomeDir(defaultDirName string) (string, error)
- func FindProjectRoot(from, markerDir string) (string, bool)
- func Lock(root string, layout *Layout) string
- func ObserveSocket(root string, layout *Layout) string
- func RegisterKnownHome(registryPath, home, now string) error
- func ResolveHome(envVar, defaultDirName string) (string, error)
- func Sessions(root string, layout *Layout) string
- func Socket(root string, layout *Layout) string
- type Home
- func (h *Home) Join(elem ...string) string
- func (h *Home) Lock() string
- func (h *Home) ObserveSocket() (string, bool)
- func (h *Home) PipePrefix() (string, bool)
- func (h *Home) Root() string
- func (h *Home) Runtime() string
- func (h *Home) RuntimeJoin(elem ...string) string
- func (h *Home) Socket() string
- type HomeEntry
- type KnownHomes
- type Layout
- type Service
- func (s *Service) Candidates(explicitRoot string) ([]string, error)
- func (s *Service) DefaultHome() (string, error)
- func (s *Service) Open(root string) *Home
- func (s *Service) Register(root, seenAt string) error
- func (s *Service) RegistryPath() (string, error)
- func (s *Service) Resolve() (string, error)
Constants ¶
This section is empty.
Variables ¶
var DefaultLayout = Layout{
SessionsDir: defaultSessionsDir,
SocketName: defaultSocketName,
ObserveSocketName: defaultObserveSocketName,
LockName: defaultLockName,
PipePrefix: defaultPipePrefix,
}
DefaultLayout fills empty Layout fields with conventional names.
var ErrEmptyHome = errors.New("svcroot: empty home path")
ErrEmptyHome is returned when a service root path resolves to an empty string.
var ErrRegistryNotConfigured = errors.New("svcroot: registry file not configured")
ErrRegistryNotConfigured is returned when registry operations run without RegistryFile.
Functions ¶
func CandidateHomes ¶
CandidateHomes returns deduplicated service roots from envVar, envHome, defaultHome, and the registry file.
func DefaultHomeDir ¶
DefaultHomeDir returns ~/.defaultDirName under the user home directory.
func FindProjectRoot ¶
FindProjectRoot walks upward from from to find markerDir as a subdirectory.
func ObserveSocket ¶
ObserveSocket returns the read-only observe HTTP socket path under root.
func RegisterKnownHome ¶
RegisterKnownHome records root in the registry at registryPath.
func ResolveHome ¶
ResolveHome returns the envVar value when set, otherwise ~/.defaultDirName.
Types ¶
type Home ¶
type Home struct {
// contains filtered or unexported fields
}
Home resolves paths under one service root directory.
func (*Home) ObserveSocket ¶
ObserveSocket returns the observe socket path and whether this layout defines one.
func (*Home) PipePrefix ¶
PipePrefix returns the Windows named-pipe prefix and whether this layout defines one.
func (*Home) Runtime ¶
Runtime returns the runtime state directory under root (typically root/sessions).
func (*Home) RuntimeJoin ¶
RuntimeJoin joins path elements under the runtime directory.
type HomeEntry ¶
type HomeEntry struct {
// Path is the absolute service root directory.
Path string `json:"path"`
// LastSeen is an optional RFC3339 timestamp from the last registration.
LastSeen string `json:"last_seen,omitempty"`
}
HomeEntry records one known service root.
type KnownHomes ¶
type KnownHomes struct {
// Homes lists previously registered service roots.
Homes []HomeEntry `json:"homes"`
}
KnownHomes is the on-disk known-instance registry.
func LoadKnownHomes ¶
func LoadKnownHomes(path string) KnownHomes
LoadKnownHomes reads the registry at path, returning an empty file when missing.
type Layout ¶
type Layout struct {
// SessionsDir is the runtime state directory name under the service root.
SessionsDir string
// SocketName is the primary RPC socket file name inside SessionsDir.
SocketName string
// ObserveSocketName is the observe socket file name; leave empty to disable.
ObserveSocketName string
// LockName is the service lock file name inside SessionsDir.
LockName string
// PipePrefix is the Windows named-pipe prefix; leave empty to disable.
PipePrefix string
}
Layout names runtime files under a service root directory.
func (*Layout) At ¶
At joins path elements under root. When underRuntime is true, the runtime directory is inserted first.
func (*Layout) ObserveSocketPath ¶
ObserveSocketPath returns the observe socket path when ObserveSocketName is set.
func (*Layout) PipePrefixName ¶
PipePrefixName returns the configured Windows pipe prefix when set.
func (*Layout) RuntimeDir ¶
RuntimeDir returns root joined with the runtime directory name.
func (*Layout) WithDefaults ¶
WithDefaults returns layout with empty core fields filled from DefaultLayout.
type Service ¶
type Service struct {
// EnvVar overrides DefaultDir when set in the process environment.
EnvVar string
// DefaultDir is appended to the user home when EnvVar is unset (e.g. ".myapp").
DefaultDir string
// Layout names runtime files under each service root.
Layout Layout
// RegistryFile is joined with DefaultHome() for known-instance registry paths.
// Leave empty when the service does not persist known instances.
RegistryFile string
}
Service describes how one long-running service resolves its root directory, lays out runtime files, and optionally tracks known instances on disk.
func (*Service) Candidates ¶
Candidates returns deduplicated service roots from explicitRoot, EnvVar, DefaultHome, and the registry.
func (*Service) DefaultHome ¶
DefaultHome returns ~/.DefaultDir regardless of EnvVar.
func (*Service) RegistryPath ¶
RegistryPath returns the absolute known-instance registry path, or ("", nil) when unset.
Source Files