Retracted: these held pkg/ and internal/, now a module per pkg/v1 family and github.com/kitsunium/sdk/internal (ADR 0171): go get github.com/kitsunium/sdk@latest && go mod tidy
README
¶
proc
import "github.com/kitsunium/sdk/pkg/v1/proc"
Package proc is the capability-preflight facade for the process-supervision domain. Some proc primitives have no native, secure mechanic on every OS (cgroup is Linux/Windows-only, rlimit/sd_notify are Unix-only, …); the SDK honours those gaps by returning the typed UnsupportedPlatform error and NEVER panicking on its own. This package lets a CONSUMER instead choose to fail fast at its own startup — the idiomatic Go MustX pattern (regexp.MustCompile / text/template.Must): the library offers the panic, it never imposes it.
Why preflight instead of recover
A process supervisor (a PID1) cannot rely on a recover() in its hot path: an unrecovered panic in pid 1 orphans every supervised service, and a panic that crosses a CGO/FFI boundary is undefined behaviour. The safe pattern is to reject an unsupported configuration up front — assert the required capabilities once, at startup, then route only to capabilities that Supported reports present.
func main() {
// crash-at-launch, clearly, if this host cannot supervise at all:
proc.MustSupport(proc.CapProcessSpawn, proc.CapReaper)
os.Exit(run())
}
// elsewhere, branch instead of crash for an optional capability:
if proc.Supported(proc.CapCgroup) {
// confine via cgroup / Job Object
}
Capability × platform matrix
Capability linux darwin windows freebsd openbsd netbsd dragonfly illumos solaris
CapProcessSpawn ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
CapSignalRelay ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
CapReaper ✅ ✅ ✅¹ ✅ ✅ ✅ ✅ ✅⁴ ✅⁴
CapCgroup ✅ ❌ ✅² ❌ ❌ ❌ ❌ ❌ ❌
CapRlimit ✅ ✅ ❌³ ✅ ✅ ✅ ✅ ✅ ✅
CapUmaskNiceOOM ✅ ✅ ❌ ✅ ✅ ✅ ✅ ✅ ✅
CapSdNotify ✅ ✅ ❌ ✅ ✅ ✅ ✅ ✅ ✅
CapSocketActivation ✅ ✅ ❌ ✅ ✅ ✅ ✅ ✅ ✅
¹ Windows has no zombies; the reaper is a correct no-op there. ² Windows cgroup is the Job Object backend. ³ the Unix setrlimit-on-self model has no Windows analogue; Windows resource limits are applied through the cgroup (Job Object) container or at spawn via the process Spec, not a standalone rlimit. ⁴ illumos and Solaris have no reparent-here facility, like darwin, OpenBSD and NetBSD: SetChildSubreaper returns UnsupportedPlatform. Their reaper also sweeps once a second, because the Go runtime forks every child there with FORK_NOSIGCHLD and its exit posts no SIGCHLD. Both columns are proven on OmniOS r151054 and Oracle Solaris 11.4 (amd64) by the SDK's cross-platform runtime lane.
Supported consults runtime.GOOS only — it is the platform-level matrix, not a runtime probe. A capability that is native on the GOOS may still be unavailable at runtime (e.g. cgroup present but not delegated); use the per-facade probe for that (e.g. cgroup.Available()).
Index
Variables
var (
// UnsupportedPlatform is the central sentinel a missing capability surfaces. A
// recover() of a [MustSupport] panic yields an error carrying this error's code.
UnsupportedPlatform = coreproc.UnsupportedPlatform
)
func MustSupport
func MustSupport(caps ...Capability)
MustSupport panics when any requested capability is missing on the current platform, and is a no-op otherwise. It is the consumer's OPT-IN fail-fast: the SDK never calls it. The panic value is the typed [errs] UnsupportedPlatform error (code 0.2.6.1), so a top-level recover() can classify it via errs.CodeOf / HasCode rather than a bare string.
func Supported
func Supported(c Capability) bool
Supported reports whether cap has a native backend on the current GOOS. It is pure, allocation-free and race-clean: it consults runtime.GOOS only, never a runtime delegation probe (see the package doc on cgroup.Available()).
type Capability
Capability identifies one process-supervision capability whose native backend is present on some platforms and absent on others.
type Capability int
The supervisable capabilities, one per platform-sensitive proc primitive.
const (
// CapProcessSpawn is spawning + supervising a child process (process.Start).
CapProcessSpawn Capability = iota
// CapRlimit is applying per-process setrlimit-style limits (rlimit.Apply).
CapRlimit
// CapUmaskNiceOOM is the spawn-time umask / nice / oom_score_adj knobs.
CapUmaskNiceOOM
// CapCgroup is a kernel-enforced resource container (cgroup.Create).
CapCgroup
// CapReaper is zombie reaping / subreaping (reaper.New).
CapReaper
// CapSignalRelay is forwarding signals to a pid / process group (signal.Relay).
CapSignalRelay
// CapSdNotify is the service-manager readiness/watchdog protocol (systemd/notify).
CapSdNotify
// CapSocketActivation is inheriting a pre-opened listening socket (systemd/listen).
CapSocketActivation
)
func MissingCapabilities
func MissingCapabilities(caps ...Capability) []Capability
MissingCapabilities returns the subset of caps with no native backend on the current platform; an empty (nil) result means every capability is present.
func (Capability) String
func (c Capability) String() string
String returns the capability's stable name, or its integer form when the value is out of range.
Generated by gomarkdoc
Documentation
¶
Overview ¶
Package proc is the capability-preflight facade for the process-supervision domain. Some proc primitives have no native, secure mechanic on every OS (cgroup is Linux/Windows-only, rlimit/sd_notify are Unix-only, …); the SDK honours those gaps by returning the typed UnsupportedPlatform error and NEVER panicking on its own. This package lets a CONSUMER instead choose to fail fast at its own startup — the idiomatic Go MustX pattern (regexp.MustCompile / text/template.Must): the library offers the panic, it never imposes it.
Why preflight instead of recover ¶
A process supervisor (a PID1) cannot rely on a recover() in its hot path: an unrecovered panic in pid 1 orphans every supervised service, and a panic that crosses a CGO/FFI boundary is undefined behaviour. The safe pattern is to reject an unsupported configuration up front — assert the required capabilities once, at startup, then route only to capabilities that Supported reports present.
func main() {
// crash-at-launch, clearly, if this host cannot supervise at all:
proc.MustSupport(proc.CapProcessSpawn, proc.CapReaper)
os.Exit(run())
}
// elsewhere, branch instead of crash for an optional capability:
if proc.Supported(proc.CapCgroup) {
// confine via cgroup / Job Object
}
Capability × platform matrix ¶
Capability linux darwin windows freebsd openbsd netbsd dragonfly illumos solaris CapProcessSpawn ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ CapSignalRelay ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ CapReaper ✅ ✅ ✅¹ ✅ ✅ ✅ ✅ ✅⁴ ✅⁴ CapCgroup ✅ ❌ ✅² ❌ ❌ ❌ ❌ ❌ ❌ CapRlimit ✅ ✅ ❌³ ✅ ✅ ✅ ✅ ✅ ✅ CapUmaskNiceOOM ✅ ✅ ❌ ✅ ✅ ✅ ✅ ✅ ✅ CapSdNotify ✅ ✅ ❌ ✅ ✅ ✅ ✅ ✅ ✅ CapSocketActivation ✅ ✅ ❌ ✅ ✅ ✅ ✅ ✅ ✅
¹ Windows has no zombies; the reaper is a correct no-op there. ² Windows cgroup is the Job Object backend. ³ the Unix setrlimit-on-self model has no Windows analogue; Windows resource limits are applied through the cgroup (Job Object) container or at spawn via the process Spec, not a standalone rlimit. ⁴ illumos and Solaris have no reparent-here facility, like darwin, OpenBSD and NetBSD: SetChildSubreaper returns UnsupportedPlatform. Their reaper also sweeps once a second, because the Go runtime forks every child there with FORK_NOSIGCHLD and its exit posts no SIGCHLD. Both columns are proven on OmniOS r151054 and Oracle Solaris 11.4 (amd64) by the SDK's cross-platform runtime lane.
Supported consults runtime.GOOS only — it is the platform-level matrix, not a runtime probe. A capability that is native on the GOOS may still be unavailable at runtime (e.g. cgroup present but not delegated); use the per-facade probe for that (e.g. cgroup.Available()).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // UnsupportedPlatform is the central sentinel a missing capability surfaces. A // recover() of a [MustSupport] panic yields an error carrying this error's code. UnsupportedPlatform = coreproc.UnsupportedPlatform )
Functions ¶
func MustSupport ¶
func MustSupport(caps ...Capability)
MustSupport panics when any requested capability is missing on the current platform, and is a no-op otherwise. It is the consumer's OPT-IN fail-fast: the SDK never calls it. The panic value is the typed errs UnsupportedPlatform error (code 0.2.6.1), so a top-level recover() can classify it via errs.CodeOf / HasCode rather than a bare string.
func Supported ¶
func Supported(c Capability) bool
Supported reports whether cap has a native backend on the current GOOS. It is pure, allocation-free and race-clean: it consults runtime.GOOS only, never a runtime delegation probe (see the package doc on cgroup.Available()).
Types ¶
type Capability ¶
type Capability int
Capability identifies one process-supervision capability whose native backend is present on some platforms and absent on others.
const ( // CapProcessSpawn is spawning + supervising a child process (process.Start). CapProcessSpawn Capability = iota // CapRlimit is applying per-process setrlimit-style limits (rlimit.Apply). CapRlimit // CapUmaskNiceOOM is the spawn-time umask / nice / oom_score_adj knobs. CapUmaskNiceOOM // CapCgroup is a kernel-enforced resource container (cgroup.Create). CapCgroup // CapReaper is zombie reaping / subreaping (reaper.New). CapReaper // CapSignalRelay is forwarding signals to a pid / process group (signal.Relay). CapSignalRelay // CapSdNotify is the service-manager readiness/watchdog protocol (systemd/notify). CapSdNotify // CapSocketActivation is inheriting a pre-opened listening socket (systemd/listen). CapSocketActivation )
The supervisable capabilities, one per platform-sensitive proc primitive.
func MissingCapabilities ¶
func MissingCapabilities(caps ...Capability) []Capability
MissingCapabilities returns the subset of caps with no native backend on the current platform; an empty (nil) result means every capability is present.
func (Capability) String ¶
func (c Capability) String() string
String returns the capability's stable name, or its integer form when the value is out of range.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cgroup creates and manages cgroup v2 control groups to confine a process tree's memory, CPU, pids, and IO.
|
Package cgroup creates and manages cgroup v2 control groups to confine a process tree's memory, CPU, pids, and IO. |
|
Package ipc is a private socket between processes of one machine — a daemon and the short-lived clients that talk to it, a product and the tool that attaches to it (ADR 0148).
|
Package ipc is a private socket between processes of one machine — a daemon and the short-lived clients that talk to it, a product and the tool that attaches to it (ADR 0148). |
|
Package memlimit derives the Go runtime soft memory limit from the control group allowance governing this process, and installs it.
|
Package memlimit derives the Go runtime soft memory limit from the control group allowance governing this process, and installs it. |
|
Package process is the public facade for the SDK's keystone process-spawn primitive: it starts a child process under explicit credentials, in its own process group and session, and returns a handle that can wait for exit, signal the leader or its whole group, and stop the group gracefully with a SIGTERM→SIGKILL escalation.
|
Package process is the public facade for the SDK's keystone process-spawn primitive: it starts a child process under explicit credentials, in its own process group and session, and returns a handle that can wait for exit, signal the leader or its whole group, and stop the group gracefully with a SIGTERM→SIGKILL escalation. |
|
Package reaper is the PID1 / subreaper zombie-collector facade.
|
Package reaper is the PID1 / subreaper zombie-collector facade. |
|
Package rlimit applies per-process resource ceilings via setrlimit(2) / prlimit64(2).
|
Package rlimit applies per-process resource ceilings via setrlimit(2) / prlimit64(2). |
|
Package signal is the typed signal toolbox: parse, subscribe, and forward OS signals through one ergonomic surface.
|
Package signal is the typed signal toolbox: parse, subscribe, and forward OS signals through one ergonomic surface. |
|
systemd
|
|
|
listen
Package listen is the public facade for systemd-style socket activation (sd_listen_fds(3)): a service recovers already-bound listening sockets handed to it by an activator, and an activator hands sockets to a child it spawns.
|
Package listen is the public facade for systemd-style socket activation (sd_listen_fds(3)): a service recovers already-bound listening sockets handed to it by an activator, and an activator hands sockets to a child it spawns. |
|
notify
Package notify is the public facade for the systemd sd_notify(3) readiness/watchdog protocol.
|
Package notify is the public facade for the systemd sd_notify(3) readiness/watchdog protocol. |