handoff

Documentation

Overview

Package handoff hands the gateway's listening socket from the magpie restarting to update to the version it started, so the port is never closed between them: the new one serves on the same socket, and the old one stops accepting and finishes what it has.

The magpie handing over opens an Offer: a unix socket in a folder only its user can enter, named in a pointer file in magpie's config folder. The new magpie Takes it: it connects, says hello, and is sent the listening socket (SCM_RIGHTS) with a Meta; once its gateway serves on it, it Acks, and the one before lets go. Only Unix has this (darwin and linux); elsewhere Open says ErrUnsupported (Take finds nothing), and a restart waits for the gateway to be idle as before.

Index

• Variables
• type Conn
  • func (c *Conn) AwaitAck(timeout time.Duration) error
  • func (c *Conn) Close()
  • func (c *Conn) Give(f *os.File, m Meta) error
• type Hello
• type Meta
• type Offer
  • func Open(dir, exe string) (*Offer, error)
  • func (o *Offer) Accept(ctx context.Context) (*Conn, error)
  • func (o *Offer) Close()
  • func (o *Offer) Dir() string
  • func (o *Offer) Withdraw()
• type Taken
  • func Take(dir, exe string, hello Hello, timeout time.Duration) (*Taken, error)
  • func (t *Taken) Ack() error
  • func (t *Taken) Close()

Variables

var ErrUnsupported = errors.New("handing the gateway over isn't supported here")

ErrUnsupported is Open's error where a socket can't be handed to another process (Windows).

Types

type Conn

type Conn struct {
	Hello Hello
	// contains filtered or unexported fields
}

Conn is the new magpie, connected to an Offer.

func (*Conn) AwaitAck

func (c *Conn) AwaitAck(timeout time.Duration) error

AwaitAck waits, timeout at most, for the new magpie to say its gateway serves on the socket given. An error is the new one gone or not ready in time: the socket is then still this one's to serve.

func (*Conn) Close

func (c *Conn) Close()

Close ends the connection; the new magpie reads it as the one before gone.

func (*Conn) Give

func (c *Conn) Give(f *os.File, m Meta) error

Give sends the listening socket f, with m.

type Hello

type Hello struct {
	PID     int    `json:"pid"`
	Version string `json:"version"`
}

Hello is what the new magpie says it is.

type Meta

type Meta struct {
	// Addr is where the socket listens.
	Addr string `json:"addr"`
	// Callbacks is the unix socket where the magpie handing over answers
	// its own Claude Code runs' tool calls until it ends.
	Callbacks string `json:"callbacks,omitempty"`
	// PID is the magpie handing over.
	PID int `json:"pid"`
}

Meta comes with the socket handed over.

type Offer

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

Offer is a socket waiting to be handed to the new magpie.

func Open

func Open(dir, exe string) (*Offer, error)

Open offers the gateway's socket to the next magpie to run exe on the config folder dir.

func (*Offer) Accept

func (o *Offer) Accept(ctx context.Context) (*Conn, error)

Accept waits for the new magpie to connect and say hello, until ctx ends.

func (*Offer) Close

func (o *Offer) Close()

Close takes the Offer back: its pointer and sockets are removed.

func (*Offer) Dir

func (o *Offer) Dir() string

Dir is a folder of the Offer's own, only this user's, for another unix socket beside it (Meta.Callbacks); it is removed with the Offer.

func (*Offer) Withdraw

func (o *Offer) Withdraw()

Withdraw removes the pointer, so no later magpie takes the Offer, and stops taking connections; the folder stays for sockets still in use.

type Taken

type Taken struct {
	Listener net.Listener
	Meta     Meta
	// contains filtered or unexported fields
}

Taken is the socket handed over, with its Meta.

func Take

func Take(dir, exe string, hello Hello, timeout time.Duration) (*Taken, error)

Take takes the socket the magpie before this one offers, when it runs exe on dir: nil, nil when none does. It waits timeout at most.

func (*Taken) Ack

func (t *Taken) Ack() error

Ack tells the magpie before that this one serves on the socket.

func (*Taken) Close

func (t *Taken) Close()

Close drops the connection without an ack: the magpie before keeps serving.