go-process/specs/process.md

process

Import: dappco.re/go/core/process Files: 11

Types

ActionProcessStarted

struct

Broadcast payload for a managed process that has successfully started.

Fields:

• ID string: Generated managed-process identifier.
• Command string: Executable name passed to the service.
• Args []string: Argument vector used to start the process.
• Dir string: Working directory supplied at start time.
• PID int: OS process ID of the child process.

ActionProcessOutput

struct

Broadcast payload for one scanned line of process output.

Fields:

• ID string: Managed-process identifier.
• Line string: One line from stdout or stderr, without the trailing newline.
• Stream Stream: Output source, using StreamStdout or StreamStderr.

ActionProcessExited

struct

Broadcast payload emitted after the service wait goroutine finishes.

Fields:

• ID string: Managed-process identifier.
• ExitCode int: Process exit code.
• Duration time.Duration: Time elapsed since StartedAt.
• Error error: Declared error slot for exit metadata. The current Service emitter does not populate it.

ActionProcessKilled

struct

Broadcast payload emitted by Service.Kill.

Fields:

• ID string: Managed-process identifier.
• Signal string: Signal name reported by the service. The current implementation emits "SIGKILL".

RingBuffer

struct

Fixed-size circular byte buffer used for captured process output. The implementation is mutex-protected and overwrites the oldest bytes when full.

Exported fields:

• None.

DaemonOptions

struct

Configuration for NewDaemon.

Fields:

• PIDFile string: PID file path. Empty disables PID-file management.
• ShutdownTimeout time.Duration: Grace period used by Stop. Zero is normalized to 30 seconds by NewDaemon.
• HealthAddr string: Listen address for the health server. Empty disables health endpoints.
• HealthChecks []HealthCheck: Additional /health checks to register on the health server.
• Registry *Registry: Optional daemon registry used for automatic register/unregister.
• RegistryEntry DaemonEntry: Base registry payload. Start fills in PID, Health, and Started behavior through Registry.Register.

Daemon

struct

Lifecycle wrapper around a PID file, optional health server, and optional registry entry.

Exported fields:

• None.

HealthCheck

type HealthCheck func() error

Named function type used by HealthServer and DaemonOptions. Returning nil marks the check healthy; returning an error makes /health respond with 503.

HealthServer

struct

HTTP server exposing /health and /ready endpoints.

Exported fields:

• None.

PIDFile

struct

Single-instance guard backed by a PID file on disk.

Exported fields:

• None.

ManagedProcess

struct

Service-owned process record for a started child process.

Fields:

• ID string: Managed-process identifier generated by core.ID().
• Command string: Executable name.
• Args []string: Command arguments.
• Dir string: Working directory used when starting the process.
• Env []string: Extra environment entries appended to the command environment.
• StartedAt time.Time: Timestamp recorded immediately before cmd.Start.
• Status Status: Current lifecycle state tracked by the service.
• ExitCode int: Exit status after completion.
• Duration time.Duration: Runtime duration set when the wait goroutine finishes.

Process

type alias of ManagedProcess

Compatibility alias that exposes the same fields and methods as ManagedProcess.

Program

struct

Thin helper for finding and running a named executable.

Fields:

• Name string: Binary name to look up or execute.
• Path string: Resolved absolute path populated by Find. When empty, Run and RunDir fall back to Name.

DaemonEntry

struct

Serialized daemon-registry record written as JSON.

Fields:

• Code string: Application or component code.
• Daemon string: Daemon name within that code.
• PID int: Running process ID.
• Health string: Health endpoint address, if any.
• Project string: Optional project label.
• Binary string: Optional binary label.
• Started time.Time: Start timestamp persisted in RFC3339Nano format.

Registry

struct

Filesystem-backed daemon registry that stores one JSON file per daemon entry.

Exported fields:

• None.

Runner

struct

Pipeline orchestrator that starts RunSpec processes through a Service.

Exported fields:

• None.

RunSpec

struct

One process specification for Runner.

Fields:

• Name string: Friendly name used for dependencies and result reporting.
• Command string: Executable name.
• Args []string: Command arguments.
• Dir string: Working directory.
• Env []string: Additional environment variables.
• After []string: Dependency names that must complete before this spec can run in RunAll.
• AllowFailure bool: When true, downstream work is not skipped because of this spec's failure.

RunResult

struct

Per-spec runner result.

Fields:

• Name string: Spec name.
• Spec RunSpec: Original spec payload.
• ExitCode int: Exit code from the managed process.
• Duration time.Duration: Process duration or start-attempt duration.
• Output string: Captured output returned from the managed process.
• Error error: Start or orchestration error. For a started process that exits non-zero, this remains nil.
• Skipped bool: Whether the spec was skipped instead of run.

RunAllResult

struct

Aggregate result returned by RunAll, RunSequential, and RunParallel.

Fields:

• Results []RunResult: Collected per-spec results.
• Duration time.Duration: End-to-end runtime for the orchestration method.
• Passed int: Count of results where Passed() is true.
• Failed int: Count of non-skipped results that did not pass.
• Skipped int: Count of skipped results.

Service

struct

Core service that owns managed processes and registers action handlers.

Fields:

• *core.ServiceRuntime[Options]: Embedded Core runtime used for lifecycle hooks and access to Core().

Options

struct

Service configuration.

Fields:

• BufferSize int: Ring-buffer capacity for captured output. Register currently initializes this from DefaultBufferSize.

Status

type Status string

Named lifecycle-state type for a managed process.

Exported values:

• StatusPending: queued but not started.
• StatusRunning: currently executing.
• StatusExited: completed and waited.
• StatusFailed: start or wait failure state.
• StatusKilled: terminated by signal.

Stream

type Stream string

Named output-stream discriminator for process output events.

Exported values:

• StreamStdout: stdout line.
• StreamStderr: stderr line.

RunOptions

struct

Execution settings accepted by Service.StartWithOptions and Service.RunWithOptions.

Fields:

• Command string: Executable name. Required by both start and run paths.
• Args []string: Command arguments.
• Dir string: Working directory.
• Env []string: Additional environment entries appended to the command environment.
• DisableCapture bool: Disables the managed-process ring buffer when true.
• Detach bool: Starts the child in a separate process group and replaces the parent context with context.Background().
• Timeout time.Duration: Optional watchdog timeout that calls Shutdown after the duration elapses.
• GracePeriod time.Duration: Delay between SIGTERM and fallback kill in Shutdown.
• KillGroup bool: Requests process-group termination. The current service only enables this when Detach is also true.

ProcessInfo

struct

Serializable snapshot returned by ManagedProcess.Info and Service action lookups.

Fields:

• ID string: Managed-process identifier.
• Command string: Executable name.
• Args []string: Command arguments.
• Dir string: Working directory.
• StartedAt time.Time: Start timestamp.
• Running bool: Convenience boolean derived from Status.
• Status Status: Current lifecycle state.
• ExitCode int: Exit status.
• Duration time.Duration: Runtime duration.
• PID int: Child PID, or 0 if no process handle is available.

Info

type alias of ProcessInfo

Compatibility alias that exposes the same fields as ProcessInfo.

Functions

Package Functions

• func Register(c *core.Core) core.Result: Builds a Service with a fresh core.Registry[*ManagedProcess], sets the buffer size to DefaultBufferSize, and returns the service in Result.Value.
• func NewRingBuffer(size int) *RingBuffer: Allocates a fixed-capacity ring buffer of exactly size bytes.
• func NewDaemon(opts DaemonOptions) *Daemon: Normalizes ShutdownTimeout, creates optional PIDFile and HealthServer helpers, and attaches any configured health checks.
• func NewHealthServer(addr string) *HealthServer: Returns a health server with the supplied listen address and readiness initialized to true.
• func WaitForHealth(addr string, timeoutMs int) bool: Polls http://<addr>/health every 200 ms until it gets HTTP 200 or the timeout expires.
• func NewPIDFile(path string) *PIDFile: Returns a PID-file manager for path.
• func ReadPID(path string) (int, bool): Reads and parses a PID file, then uses signal 0 to report whether that PID is still alive.
• func NewRegistry(dir string) *Registry: Returns a daemon registry rooted at dir.
• func DefaultRegistry() *Registry: Returns a registry at ~/.core/daemons, falling back to the OS temp directory if the home directory cannot be resolved.
• func NewRunner(svc *Service) *Runner: Returns a runner bound to a specific Service.

RingBuffer Methods

• func (rb *RingBuffer) Write(p []byte) (n int, err error): Appends bytes one by one, advancing the circular window and overwriting the oldest bytes when capacity is exceeded.
• func (rb *RingBuffer) String() string: Returns the current buffer contents in logical order as a string.
• func (rb *RingBuffer) Bytes() []byte: Returns a copied byte slice of the current logical contents, or nil when the buffer is empty.
• func (rb *RingBuffer) Len() int: Returns the number of bytes currently retained.
• func (rb *RingBuffer) Cap() int: Returns the configured capacity.
• func (rb *RingBuffer) Reset(): Clears the buffer indexes and full flag.

Daemon Methods

• func (d *Daemon) Start() error: Acquires the PID file, starts the health server, marks the daemon running, and auto-registers it when Registry is configured. If a later step fails, it rolls back earlier setup.
• func (d *Daemon) Run(ctx context.Context) error: Requires a started daemon, waits for ctx.Done(), and then calls Stop.
• func (d *Daemon) Stop() error: Sets readiness false, shuts down the health server, releases the PID file, unregisters the daemon, and joins health or PID teardown errors with core.ErrorJoin.
• func (d *Daemon) SetReady(ready bool): Forwards readiness changes to the health server when one exists.
• func (d *Daemon) HealthAddr() string: Returns the bound health-server address or "" when health endpoints are disabled.

HealthServer Methods

• func (h *HealthServer) AddCheck(check HealthCheck): Appends a health-check callback under lock.
• func (h *HealthServer) SetReady(ready bool): Updates the readiness flag used by /ready.
• func (h *HealthServer) Start() error: Installs /health and /ready handlers, listens on addr, stores the listener and http.Server, and serves in a goroutine.
• func (h *HealthServer) Stop(ctx context.Context) error: Calls Shutdown on the underlying http.Server when started; otherwise returns nil.
• func (h *HealthServer) Addr() string: Returns the actual bound listener address after Start, or the configured address before startup.

PIDFile Methods

• func (p *PIDFile) Acquire() error: Rejects a live existing PID file, deletes stale state, creates the parent directory when needed, and writes the current process ID.
• func (p *PIDFile) Release() error: Deletes the PID file.
• func (p *PIDFile) Path() string: Returns the configured PID-file path.

ManagedProcess Methods

• func (p *ManagedProcess) Info() ProcessInfo: Returns a snapshot containing public fields plus the current child PID.
• func (p *ManagedProcess) Output() string: Returns captured output as a string, or "" when capture is disabled.
• func (p *ManagedProcess) OutputBytes() []byte: Returns captured output as bytes, or nil when capture is disabled.
• func (p *ManagedProcess) IsRunning() bool: Reports running state by checking whether the done channel has closed.
• func (p *ManagedProcess) Wait() error: Blocks for completion and then returns a wrapped error for failed-start, killed, or non-zero-exit outcomes.
• func (p *ManagedProcess) Done() <-chan struct{}: Returns the completion channel.
• func (p *ManagedProcess) Kill() error: Sends SIGKILL to the child, or to the entire process group when group killing is enabled.
• func (p *ManagedProcess) Shutdown() error: Sends SIGTERM, waits for the configured grace period, and falls back to Kill. With no grace period configured, it immediately calls Kill.
• func (p *ManagedProcess) SendInput(input string) error: Writes to the child's stdin pipe while the process is running.
• func (p *ManagedProcess) CloseStdin() error: Closes the stdin pipe and clears the stored handle.
• func (p *ManagedProcess) Signal(sig os.Signal) error: Sends an arbitrary signal while the process is in StatusRunning.

Program Methods

• func (p *Program) Find() error: Resolves Name through exec.LookPath, stores the absolute path in Path, and wraps ErrProgramNotFound when lookup fails.
• func (p *Program) Run(ctx context.Context, args ...string) (string, error): Executes the program in the current working directory by delegating to RunDir("", args...).
• func (p *Program) RunDir(ctx context.Context, dir string, args ...string) (string, error): Runs the program with combined stdout/stderr capture, trims the combined output, and returns that output even when the command fails.

Registry Methods

• func (r *Registry) Register(entry DaemonEntry) error: Ensures the registry directory exists, defaults Started when zero, marshals the entry with the package's JSON writer, and writes one <code>-<daemon>.json file.
• func (r *Registry) Unregister(code, daemon string) error: Deletes the registry file for the supplied daemon key.
• func (r *Registry) Get(code, daemon string) (*DaemonEntry, bool): Reads one entry, prunes invalid or stale files, and returns (nil, false) when the daemon is missing or dead.
• func (r *Registry) List() ([]DaemonEntry, error): Lists all JSON files in the registry directory, prunes invalid or stale entries, and returns only live daemons. A missing registry directory returns nil, nil.

RunResult and RunAllResult Methods

• func (r RunResult) Passed() bool: Returns true only when the result is not skipped, has no Error, and has ExitCode == 0.
• func (r RunAllResult) Success() bool: Returns true when Failed == 0, regardless of skipped count.

Runner Methods

• func (r *Runner) RunAll(ctx context.Context, specs []RunSpec) (*RunAllResult, error): Executes dependency-aware waves of specs, skips dependents after failing required dependencies, and marks circular or missing dependency sets as failed results with ExitCode 1.
• func (r *Runner) RunSequential(ctx context.Context, specs []RunSpec) (*RunAllResult, error): Runs specs in order and marks remaining specs skipped after the first disallowed failure.
• func (r *Runner) RunParallel(ctx context.Context, specs []RunSpec) (*RunAllResult, error): Runs all specs concurrently and aggregates counts after all goroutines finish.

Service Methods

• func (s *Service) OnStartup(ctx context.Context) core.Result: Registers the Core actions process.run, process.start, process.kill, process.list, and process.get.
• func (s *Service) OnShutdown(ctx context.Context) core.Result: Iterates all managed processes and calls Kill on each one.
• func (s *Service) Start(ctx context.Context, command string, args ...string) core.Result: Convenience wrapper that builds RunOptions and delegates to StartWithOptions.
• func (s *Service) StartWithOptions(ctx context.Context, opts RunOptions) core.Result: Starts a managed process, configures pipes, optional capture, detach and timeout behavior, stores it in the registry, emits ActionProcessStarted, streams stdout/stderr lines, and emits ActionProcessExited after completion.
• func (s *Service) Get(id string) (*ManagedProcess, error): Returns one managed process or ErrProcessNotFound.
• func (s *Service) List() []*ManagedProcess: Returns all managed processes currently stored in the service registry.
• func (s *Service) Running() []*ManagedProcess: Returns only processes whose done channel has not closed yet.
• func (s *Service) Kill(id string) error: Kills the managed process by ID and emits ActionProcessKilled.
• func (s *Service) Remove(id string) error: Deletes a completed process from the registry and rejects removal while it is still running.
• func (s *Service) Clear(): Deletes every completed process from the registry.
• func (s *Service) Output(id string) (string, error): Returns the managed process's captured output.
• func (s *Service) Run(ctx context.Context, command string, args ...string) core.Result: Convenience wrapper around RunWithOptions.
• func (s *Service) RunWithOptions(ctx context.Context, opts RunOptions) core.Result: Executes an unmanaged one-shot command with CombinedOutput. On success it returns the output string in Value; on failure it returns a wrapped error in Value and sets OK false.