daemon

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package daemon serves the courier to the harness clients of one user over a local socket, with line-delimited JSON-RPC 2.0. design.md "Socket and wire protocol" is the protocol.

Index

Constants

View Source
const (
	// DefaultIdleGrace is how long the daemon runs with no connected client.
	DefaultIdleGrace = 60 * time.Second
	// IdleGraceEnv overrides DefaultIdleGrace with a Go duration, for example 5m.
	IdleGraceEnv = "AGENT_COURIER_IDLE_GRACE"
)
View Source
const (
	// SocketName is the file name of the socket in the socket directory.
	SocketName = "daemon.sock"
	// LockName is the file name of the lock in the socket directory. The
	// daemon holds it from before it listens until after it has closed the
	// store.
	LockName = "daemon.lock"
	// LockFDEnv is set to LockFD in a daemon that a client started.
	LockFDEnv = "AGENT_COURIER_LOCK_FD"
	// LockFD is the descriptor of the lock file that a daemon inherits from
	// the client that started it.
	LockFD = 3
	// SocketDirEnv replaces the socket directory with an absolute path. Tests
	// set it, so they never meet the user's daemon.
	SocketDirEnv = "AGENT_COURIER_SOCKET_DIR"
)
View Source
const (
	// LogName is the log of a daemon that a client started, in the state
	// directory beside the store.
	LogName = "daemon.log"
	// MaxLog is the size above which a starting daemon moves its log to
	// LogName.1 and begins a new one.
	MaxLog = 1 << 20
)
View Source
const MaxID = 128

MaxID is the most bytes the JSON text of a request id can have.

View Source
const MaxLine = 64 << 10

MaxLine is the most bytes a line can have without its newline.

View Source
const Protocol = `` /* 2732-byte string literal not displayed */

Protocol is the agent protocol of the inbound-safety spec. register returns it with the identity of the agent, and each client gives it to its agent at session start.

Variables

View Source
var ErrRunning = errors.New("another daemon runs for this user")

ErrRunning means that another daemon holds the lock of the socket directory.

Functions

func CheckDir

func CheckDir(dir string, uid int) error

CheckDir checks that dir is a real directory of uid with mode 0700, as PrivateDir leaves it. A client checks it before it connects, because another user could create the directory first and listen as a fake daemon. A missing dir gives an error that wraps fs.ErrNotExist.

func LastLogLine

func LastLogLine(dir string) string

LastLogLine is the last line of the log in dir, at most 512 bytes, or "" without one.

func OpenLock

func OpenLock(dir string) (*os.File, error)

OpenLock opens the lock file of dir, which must exist.

func OpenLog

func OpenLog(dir string) (*os.File, error)

OpenLog opens the log in dir for appending, with mode 0600. A log over MaxLog becomes LogName.1 first, which replaces the older one.

func PeerUID

func PeerUID(c net.Conn) (uid int, ok bool, err error)

PeerUID is the uid of the process at the other end of c, from SO_PEERCRED. ok is false where the system does not tell.

func PrivateDir

func PrivateDir(dir string) error

PrivateDir creates dir with mode 0700, or checks that an existing dir is a real directory of this user and sets its mode to 0700. In a shared temporary directory another user could create the directory first.

func SocketDir

func SocketDir() string

SocketDir depends only on the uid, so every process of the user finds the same daemon whatever its environment. On Linux it is /run/user/<uid>/agent-courier when /run/user/<uid> is a directory of the user, else /tmp/agent-courier-<uid>. Elsewhere it is agent-courier-<uid> in the temporary directory of the user. SocketDirEnv replaces it.

func StateDir

func StateDir() (string, error)

StateDir is $XDG_STATE_HOME/agent-courier, with ~/.local/state as the default of XDG_STATE_HOME.

func TryLock

func TryLock(f *os.File) error

TryLock takes the exclusive lock on f without waiting. It returns ErrRunning when another open file holds it. It succeeds on a file that already holds the lock.

Types

type Listener

type Listener struct {
	*net.UnixListener
	// contains filtered or unexported fields
}

Listener is the daemon's socket. It holds the lock of the socket directory until Unlock.

func Listen

func Listen(dir string) (*Listener, error)

Listen makes dir a private directory of the user, takes the daemon lock in it, and listens on the socket in it. It returns ErrRunning when another daemon holds the lock.

func ListenLocked

func ListenLocked(dir string, lock *os.File) (*Listener, error)

ListenLocked is Listen with a lock file that the daemon inherited from the client that started it. The client took the lock on that open file, so the lock passes to the daemon without a moment when it is free. lock must be the lock file of dir.

func (*Listener) Close

func (l *Listener) Close() error

Close removes the socket and closes it, once. It keeps the lock. Only the lock holder removes the socket, so neither a daemon that lost the start nor a second Close removes the socket of another daemon.

func (*Listener) Unlock

func (l *Listener) Unlock()

Unlock closes the listener when it is open and releases the lock, once. The daemon calls it last, after it has closed the store.

type Network added in v0.5.0

type Network interface {
	// Self is the peer id of this machine. The first call creates the
	// machine key.
	Self() (string, error)
	// InviteCode is the invite code of team with secret and expires: the peer
	// id and addresses of this machine with them.
	InviteCode(team string, secret []byte, expires time.Time) (string, error)
	// Join joins this machine with label to the team of code, as
	// p2p.JoinService.Join does, and returns the team.
	Join(ctx context.Context, code, label string) (team.Team, error)
	// TeamChanged runs after a local change of team, so the host follows
	// and the member list goes out to the members.
	TeamChanged(team string)
	// Leave marks the entry of this machine in team name left and forgets
	// the team, as team.Set.Leave does, then sends the list to the members
	// it can reach. It returns the team and how many of its other members
	// the leave did not reach.
	Leave(name string) (team.Team, int, error)
}

Network is the p2p side of the team methods: the daemon's libp2p host, with p2p.JoinService and p2p.MemberSync.

type P2P added in v0.5.0

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

P2P runs one libp2p host while this machine belongs to at least one team, or runs a join or a leave, and closes it when none holds. A machine without a team opens no network socket. P2P is the Network of the server. It reads and changes the server's team.Set, the one member set of the daemon.

func NewP2P added in v0.5.0

func NewP2P(st *store.Store, set *team.Set, log *slog.Logger, cfg P2PConfig) *P2P

NewP2P returns the host lifecycle of the daemon over set, the teams of the server. Run drives it.

func (*P2P) Changed added in v0.5.0

func (p *P2P) Changed()

Changed tells the lifecycle that the teams or a member list changed. It protects the connections of the members at once, and wakes the lifecycle without waiting for it. The member set drops the queued items of former members itself.

func (*P2P) Host added in v0.5.0

func (p *P2P) Host() *p2p.Host

Host is the running host, or nil.

func (*P2P) InviteCode added in v0.5.0

func (p *P2P) InviteCode(name string, secret []byte, expires time.Time) (string, error)

InviteCode is the Network method of team.invite: the code holds the peer id of this machine and its addresses for team name, its circuit addresses first. It waits, within limits, for the host and its first reservation.

func (*P2P) IsMember added in v0.5.0

func (p *P2P) IsMember(id libp2ppeer.ID) bool

IsMember reports whether id is a member of a team this machine belongs to.

func (*P2P) Join added in v0.5.0

func (p *P2P) Join(ctx context.Context, code, label string) (team.Team, error)

Join is the Network method of team.join. On a machine with no team, it creates the machine key and keeps a host for the join until the join ends, at most joinHold.

func (*P2P) Leave added in v0.5.0

func (p *P2P) Leave(name string) (team.Team, int, error)

Leave is the Network method of team.leave: it marks the entry of this machine in team name left, forgets the team, and sends the list to the members it can reach. It returns the team and how many of its other members the leave did not reach. The host stops after the sends when name was the last team.

func (*P2P) LeaveAll added in v0.5.0

func (p *P2P) LeaveAll()

LeaveAll leaves every team of this machine, as team.leave does, before the daemon stops. The leaves run in parallel, each within the leave timeout of p2p.MemberSync.SendLeft.

func (*P2P) LocalChanged added in v0.5.0

func (p *P2P) LocalChanged()

LocalChanged sends the presence of this machine to every connected member, after a session took or left an agent name.

func (*P2P) MemberOf added in v0.5.0

func (p *P2P) MemberOf(id libp2ppeer.ID, name string) bool

MemberOf reports whether id is a member of the team name of this machine.

func (*P2P) OutboxChanged added in v0.5.0

func (p *P2P) OutboxChanged()

OutboxChanged wakes the worker of the send queue: a send queued a message, or a member list changed.

func (*P2P) RemoteAgents added in v0.5.0

func (p *P2P) RemoteAgents(topic string) []string

RemoteAgents lists, sorted, the agents online on topic on the machines of the members of its team, as <label>/<agent>, the first presenceListed of each member. A member's presence ends when its last connection closes, after presenceTTL without a frame, or when it leaves the team: remoteSender checks the member list.

func (*P2P) Run added in v0.5.0

func (p *P2P) Run(ctx context.Context)

Run checks the teams at start, after each Changed and every resync, until ctx ends. Then it closes the host. Every resync also sends the member lists again, so a member that missed a change learns it.

func (*P2P) Self added in v0.5.0

func (p *P2P) Self() (string, error)

Self is the Network method that returns the peer id of this machine. It creates the machine key on the first call.

func (*P2P) TeamChanged added in v0.5.0

func (p *P2P) TeamChanged(name string)

TeamChanged is the Network method that runs after a local change of team name: it sends a change notice, and the member list to the members.

type P2PConfig added in v0.5.0

type P2PConfig struct {
	// Key creates the machine key. P2P calls it once, when the machine
	// creates or joins its first team, and keeps the key in memory until the
	// daemon exits.
	Key func() (crypto.PrivKey, error)
	// Listen are the listen multiaddrs of the host.
	Listen []string
	// DefaultRelays is the relay list of a team that sets none.
	DefaultRelays []string
}

P2PConfig configures the libp2p host of the daemon.

type Server

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

Server is the daemon. One connection is one session.

func New

func New(st *store.Store, log *slog.Logger) *Server

func (*Server) ExitWhenIdle

func (s *Server) ExitWhenIdle(grace time.Duration)

ExitWhenIdle makes Serve return when no client has been connected for grace, counted from the start of Serve and from each moment the last connection closes or the machine leaves its last team. A client that connects in that time cancels the exit, and so does a team that the machine creates or joins. Call it before Serve.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, ln net.Listener) error

Serve accepts connections on ln until ctx ends, then closes ln and every connection and returns nil.

func (*Server) SetNetwork added in v0.5.0

func (s *Server) SetNetwork(n Network)

SetNetwork gives the server its p2p side. Call it before Serve. The team methods need it.

func (*Server) SetPresence added in v0.5.0

func (s *Server) SetPresence(p *P2P)

SetPresence connects the server and the p2p side for remote presence: the server lists the remote agents of p in agents and tells p when its live agents change; p sends them to the members and stores the onlines of remote agents through the server. Call it before Serve and Run.

func (*Server) Teams added in v0.5.0

func (s *Server) Teams() *team.Set

Teams is the one member set of the daemon. The p2p side reads and changes it too.

Jump to

Keyboard shortcuts

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