Documentation
¶
Overview ¶
Package devserver implements a development server supervision loop that watches Go sources and declared configuration inputs, settles file change bursts, rebuilds the application binary with link-time optimizations, and gracefully restarts the child process while keeping the previous server running on build failure. On Unix, remaining process-group descendants are terminated whenever their child leader exits, including successful and failed exits.
Index ¶
Constants ¶
View Source
const ( DefaultPollInterval = 500 * time.Millisecond DefaultSettleInterval = 200 * time.Millisecond DefaultWaitDelay = 5 * time.Second )
Default timing intervals for filesystem monitoring and child process lifecycle.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run starts the development loop:
- Validates options and streams, snapshotting configuration.
- Traps SIGHUP to stop child process groups when the controlling terminal disconnects.
- Starts all configured Helpers concurrently in their own process groups.
- Performs initial compilation of Target via `go build -ldflags=-w -o <Binary> <Target>`, inheriting GOFLAGS from the environment.
- Starts the server child executable in its own process group.
- Enters filesystem watch loop with debounce settling.
- On change: executes OnChange hook, rebuilds binary, and gracefully restarts server child on success while preserving the existing server on build failure.
- On shutdown: drains work, cancels child process groups with SIGTERM, waits up to 5s, and forcefully reaps remaining processes with SIGKILL.
Types ¶
type Helper ¶
type Helper struct {
// Name identifies the helper process and prefixes its output lines (e.g. "admin" -> "[admin] ").
Name string
// Executable is the binary or script to run (e.g. "npm").
Executable string
// Args contains command line arguments (e.g. ["--prefix", "web", "run", "dev", ...]).
Args []string
// Dir is the working directory for the command. If empty, defaults to Options.Root.
Dir string
// Env contains optional additional environment variables.
Env []string
// Banner is an optional startup announcement line printed to the status stream
// when all children are ready (e.g. "admin: http://127.0.0.1:8080/ (Vite on 5173)").
Banner string
}
Helper specifies a persistent auxiliary background process to supervise, such as a frontend Vite portal dev server.
type Options ¶
type Options struct {
// Root is the project root directory. Required.
Root string
// Target is the Go package to build (default: "./cmd/artisan").
Target string
// Binary is the path where the built executable is placed.
// Optional; defaults to filepath.Join(Root, "bin", "dev-server").
Binary string
// Args contains arguments passed to the server binary (e.g. ["serve", ...]).
Args []string
// Env contains environment variables added to the server child (e.g. ["WEB__ENABLED=true", ...]).
Env []string
// Watched contains additional file, directory, or glob paths to watch beyond the defaults.
// Default watched paths include cmd/, internal/, root .go files, go.mod, and go.sum.
// Glob patterns and relative paths are evaluated relative to Root.
Watched []string
// PollInterval is the polling frequency for filesystem changes (default: 500ms).
PollInterval time.Duration
// SettleInterval is the debounce duration after a detected change (default: 200ms).
SettleInterval time.Duration
// Helpers defines persistent child processes to run alongside the server
// (e.g. Vite dev servers for frontend portals).
Helpers []Helper
// OnChange is an optional validation callback executed after a file change settles,
// before rebuilding the server binary. If it returns an error or panics, the loop
// halts cleanly and returns a safe framework error.
OnChange func() error
// StatusWriter optionally overrides where dev lifecycle status messages are written.
// If nil, defaults to Streams.Err.
StatusWriter io.Writer
}
Options configures the development server supervision loop.
Source Files
Click to show internal directories.
Click to hide internal directories.