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
- Variables
- func CheckDir(dir string, uid int) error
- func LastLogLine(dir string) string
- func OpenLock(dir string) (*os.File, error)
- func OpenLog(dir string) (*os.File, error)
- func PeerUID(c net.Conn) (uid int, ok bool, err error)
- func PrivateDir(dir string) error
- func SocketDir() string
- func StateDir() (string, error)
- func TryLock(f *os.File) error
- type Listener
- type Network
- type P2P
- func (p *P2P) Changed()
- func (p *P2P) Host() *p2p.Host
- func (p *P2P) InviteCode(name string, secret []byte, expires time.Time) (string, error)
- func (p *P2P) IsMember(id libp2ppeer.ID) bool
- func (p *P2P) Join(ctx context.Context, code, label string) (team.Team, error)
- func (p *P2P) Leave(name string) (team.Team, int, error)
- func (p *P2P) LeaveAll()
- func (p *P2P) LocalChanged()
- func (p *P2P) MemberOf(id libp2ppeer.ID, name string) bool
- func (p *P2P) OutboxChanged()
- func (p *P2P) RemoteAgents(topic string) []string
- func (p *P2P) Run(ctx context.Context)
- func (p *P2P) Self() (string, error)
- func (p *P2P) TeamChanged(name string)
- type P2PConfig
- type Server
Constants ¶
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" )
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" )
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 )
const MaxID = 128
MaxID is the most bytes the JSON text of a request id can have.
const MaxLine = 64 << 10
MaxLine is the most bytes a line can have without its newline.
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 ¶
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 ¶
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 ¶
LastLogLine is the last line of the log in dir, at most 512 bytes, or "" without one.
func OpenLog ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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.
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
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) InviteCode ¶ added in v0.5.0
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
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
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
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
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
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
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 (*Server) ExitWhenIdle ¶
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 ¶
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
SetNetwork gives the server its p2p side. Call it before Serve. The team methods need it.
func (*Server) SetPresence ¶ added in v0.5.0
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.