socket

type Frame struct {
	Payload []byte
	Peer    PeerCred
}

type Handler func(ctx context.Context, f Frame) error

type Listener struct {
	// contains filtered or unexported fields
}

type Options struct {
	// Path is the socket path. Required. The parent directory is created with
	// 0750 if missing. Any pre-existing socket file at Path is removed first
	// (a stale socket from a previous run is the common case).
	Path string

	// Handler is called for each received frame. Required.
	Handler Handler

	// ErrorLog logs non-fatal errors (handler errors, malformed frames). When
	// nil, errors are silently discarded.
	ErrorLog func(format string, args ...any)
}

type PeerCred struct {
	// Platform discriminates which fields are populated. One of
	// "linux", "darwin". A future Windows port will introduce additional
	// values and fields (user_sid, integrity_level).
	Platform string

	// PID is the connecting process's process id. Signed because POSIX pid_t
	// is signed (and -1 is a valid sentinel).
	PID int32

	// UID, GID are POSIX credentials. uid_t and gid_t are unsigned 32-bit on
	// every platform we support, so widen-and-format via uint64 to preserve
	// the full range — narrowing into int32 here would wrap UIDs above
	// 2^31 to negative values and corrupt the recorded peer.
	UID uint32
	GID uint32

	// ExePath is the absolute path to the connecting process's executable,
	// or "" when the daemon could not resolve it. On Linux this is read from
	// /proc/<pid>/exe; on macOS via the SYS_PROC_INFO(PROC_PIDPATHINFO)
	// syscall (the call libproc's proc_pidpath() wraps). Failure is
	// non-fatal — the daemon still records pid/uid/gid.
	ExePath string
}