owner

package
v0.7.26 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package owner labels the docker objects a run creates with the process that created them, and tells a live owner from a dead one, so a later run on the same host can remove what a crashed run left behind without touching a sibling run that is still going.

Every run-scoped object is keyed by a random run id and nothing else, and several `agentry run` processes can share one docker daemon at once (a person's two terminals, a sandbox host taking several hosted runs). So "not this process's run id" is no test of abandonment; "its owner is dead" is, provided the owner can be identified across pid reuse — a pid and its start time, judged only by a process in the same boot, pid namespace and uid (Identity). Where that cannot be established (off Linux, an unreadable /proc), nothing is labelled and nothing is swept: a leftover is litter, a sibling's container removed mid-turn is a broken run.

Index

Constants

View Source
const (
	LabelHost  = "agentry.owner.host"  // Identity() of the creating process
	LabelPID   = "agentry.owner.pid"   // its pid
	LabelStart = "agentry.owner.start" // its StartTime
)

The labels an owned object carries.

Variables

View Source
var Identity = sync.OnceValues(func() (string, bool) {
	if self, err := os.Readlink("/proc/self"); err != nil || self != strconv.Itoa(os.Getpid()) {
		return "", false
	}
	boot, err := os.ReadFile("/proc/sys/kernel/random/boot_id")
	if err != nil {
		return "", false
	}
	b := strings.TrimSpace(string(boot))
	pidNS, ok := nsInode("pid")
	if b == "" || !ok {
		return "", false
	}

	timeNS, ok := nsInode("time")
	if !ok {
		if _, err := os.Lstat("/proc/self/ns/time"); !errors.Is(err, fs.ErrNotExist) {
			return "", false
		}
		timeNS = "-"
	}
	return b + "." + pidNS + "." + timeNS + "." + strconv.Itoa(os.Getuid()), true
})

Identity names the scope inside which a pid and a start time identify a process: the kernel's boot id (pids and start times restart at boot), the pid namespace (a container's pids are its own), the time namespace (the start time is reported as the reader's time namespace sees it), and the uid (a /proc mounted with hidepid shows a process only its own user's processes). Two processes with the same Identity can judge each other's liveness by pid and start time; nothing else can. ok is false where any part cannot be read, or where /proc is not this process's own (a pid namespace entered without remounting /proc), and then nothing is labelled.

View Source
var Labels = func() func() map[string]string {
	once := sync.OnceValue(func() map[string]string {
		id, ok := Identity()
		if !ok {
			return nil
		}
		pid := os.Getpid()
		start, ok := StartTime(pid)
		if !ok {
			return nil
		}
		return map[string]string{
			LabelHost:  id,
			LabelPID:   strconv.Itoa(pid),
			LabelStart: strconv.FormatUint(start, 10),
		}
	})
	return func() map[string]string { return maps.Clone(once()) }
}()

Labels are this process's owner labels, or nil where Identity or the process's own start time cannot be read. Read once: none of it changes for the life of the process.

Functions

func CommandLine

func CommandLine(pid int) (argv []string, ok bool)

CommandLine reads a process's own argv from /proc/<pid>/cmdline. ok is false when the process is gone or the record cannot be read; a sweep that would signal the process treats that as "not the one it expects".

func Dead

func Dead(labels map[string]string) bool

Dead reports whether the owner a set of labels names is provably gone: labelled from this process's Identity, with a pid and start time that parse, and either no process with that pid or one with another start time. Anything it cannot prove — another identity, a missing or malformed label, a process record that exists but cannot be read, a pid that is still the same process — is not dead.

func StartTime

func StartTime(pid int) (v uint64, ok bool)

StartTime reads a process's start time in clock ticks since boot — field 22 of /proc/<pid>/stat. With the pid it identifies a process across a pid reuse, which is what makes signalling a process group by id safe to attempt at all (the engine's host_unix.go). ok is false when the process is gone or the record cannot be read.

func With

func With(labels map[string]string) map[string]string

With returns labels plus this process's owner labels, as a new map.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL