server

Documentation

Overview

Package server exposes sessions over HTTP with SSE, on a Unix domain socket.

HTTP rather than gRPC: no codegen step, reachable from a future web surface, and debuggable with `curl --unix-socket`. The bottleneck is the model, not serialisation, so optimising the wire would be optimising the wrong place.

The socket is the trust boundary. There is no authentication in the protocol because there is no network surface; exposing it over TCP would be a contract change, not a configuration one.

Spec: docs/specs/architecture/client-server-protocol/202608072240-*.

Index

• type Builder
• type Config
• type Server
  • func New(cfg Config) *Server
  • func (s *Server) Addr() string
  • func (s *Server) Handler() http.Handler
  • func (s *Server) Listen() error
  • func (s *Server) Serve(ctx context.Context) error

Types

type Builder

type Builder func(req protocol.CreateSessionRequest) (*session.Session, error)

Builder creates a session for a request. Injected so the server does not depend on the wiring package, which would be a cycle.

type Config

type Config struct {
	SocketPath  string
	Manager     *session.Manager
	Build       Builder
	PingEvery   time.Duration
	MaxSessions int
	// DefaultMode and DefaultPolicy are what a session gets when the request
	// does not say. They are here so the boundary warning can be raised once,
	// at boot, rather than on every session that inherits them.
	DefaultMode   policy.SandboxMode
	DefaultPolicy policy.ApprovalPolicy
	// RecordDir is where transcripts live, so a conversation can be named
	// without being live. The rail lists what a workspace has recorded, and
	// almost none of it is loaded — a rename that only worked on the open
	// session would work on the one row nobody needs it for.
	RecordDir string
	// CommitDone measures what a qualifying session proposed and writes it
	// into the spec folder, returning what a person reads.
	//
	// Injected for the same reason Specs is: measuring means running criteria,
	// which is the app's business rather than the server's.
	CommitDone func(ctx context.Context, sessionID string) (protocol.CommitDoneResponse, error)
	// Specs lists a workspace's spec folders and which of them are pending.
	//
	// Injected because deciding "pending" means running criteria, which is the
	// app's business and not the server's. Nil answers an empty list rather
	// than an error: a client asking a daemon that cannot look should get "I
	// know of none", not a failure it has to interpret.
	Specs func(ctx context.Context, workspace string, measure bool) []protocol.SpecFolder
	// Log receives operational notices. Nil silences them, which is what a
	// test wants and what a daemon must not do.
	Log func(string)
}

Config tunes the server.

type Server

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

Server serves the protocol.

func New

func New(cfg Config) *Server

New builds a server.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the socket path.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler exposes the routes, for tests that do not want a socket.

func (*Server) Listen

func (s *Server) Listen() error

Listen binds the Unix socket with owner-only permissions.

A stale socket from a crashed daemon is removed only after a connection attempt fails: deleting it blindly would evict a healthy daemon that happens to be running.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context) error

Serve blocks until the context is cancelled, then shuts down and removes the socket so the next start does not have to reason about a stale one.