daemon

type App struct {
	// API serves /api/ routes on the app transport, behind its
	// authentication, Host and Origin checks.
	API http.Handler
	// Assets serves the browser application under the session namespace.
	Assets http.Handler
	// Sample serves the API of the sample project the tour shows when there
	// is no local data yet, under /s/<namespace>/sample/.
	Sample http.Handler
	// Run does background work until its context ends.
	Run func(ctx context.Context)
	// Shutdown stops work that must be recorded when it is cut short (the
	// generation queue records running jobs as interrupted). It is given
	// Options.ShutdownTimeout.
	Shutdown func(ctx context.Context) error
	// Close releases resources once nothing is served.
	Close func()
	// Drain stops accepting paid work and reports true when none is queued
	// or running, atomically with accepting work, so nothing confirmed can
	// slip in between; when work is pending it changes nothing and reports
	// false. Without it the daemon is always idle.
	Drain func() bool
	// DrainRunning is Drain for a restart into a newer version, which
	// waits only for running work: it starts no queued work, and reports
	// true once none runs, stopping accepting paid work in the same step.
	// Queued work stays for the new daemon. While it reports false, it
	// keeps holding queued work until Resume. Without it a restart waits for
	// Drain.
	DrainRunning func() bool
	// Resume accepts paid work again after a Drain or DrainRunning that led
	// nowhere, and starts queued work again.
	Resume func()
	// Methods registers further control requests the application serves,
	// beside Options.Methods; they require the client's protocol to match.
	Methods map[string]Method
	// Waits registers further control requests that may wait for as long as
	// their client stays connected, beside Options.Waits.
	Waits map[string]Method
}

type Client struct {
	Paths Paths
	// Version is this baum's version, compared with the daemon's.
	Version string
	Start   StartOptions
	// Spawn starts a daemon; nil starts this executable as "baum daemon run".
	Spawn        Spawner
	ReadyTimeout time.Duration
	StopTimeout  time.Duration
	// Restarted is told when Ensure stops an older daemon to replace it.
	Restarted func(old Status)
	// Deferred is told when Ensure keeps an older daemon that is running jobs
	// and has asked it to restart as this version once they finish.
	Deferred func(old Status)
	// Executable is what an older daemon restarts into; empty is this
	// process's executable.
	Executable string
}

type Credential struct {
	URL string `json:"url"`
}

type Delivery struct {
	Result  any
	Written func(error)
}

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type IncompatibleError struct {
	Daemon Status
	Client string
}

type Method func(ctx context.Context, params json.RawMessage) (any, error)

type Options struct {
	Paths   Paths
	Version string
	// Port is the app transport's loopback port; zero picks a free one.
	Port int
	// Prepare runs once this process owns the daemon lock, before Start. The
	// command line resolves the login shell environment here.
	Prepare func(ctx context.Context) error
	// Start builds the application once this process owns the daemon lock.
	// The server is not listening yet; Publish may be called at any time.
	Start func(ctx context.Context, server *uiserver.Server) (App, error)
	// Methods registers further control requests; they require the client's
	// protocol to match.
	Methods map[string]Method
	// Waits registers control requests that may wait for as long as their
	// client stays connected, such as a hook holding its agent until the app
	// answers: neither the method timeout nor the idle timeout applies, and
	// the method's context ends when the client disconnects (or sends
	// anything more) or the daemon stops. The connection closes after the
	// answer. They require the client's protocol to match; clients send them
	// with Client.Wait.
	Waits map[string]Method
	// Respawn starts the daemon executable a newer client named, detached,
	// to take over once this daemon exits (see StopParams). The daemon gives
	// it only an executable it trusts (see executablePolicy), with symbolic
	// links resolved, checked when it is requested and again just before.
	// Without it such requests stop the daemon only when it is idle, and are
	// refused while it is not.
	Respawn func(executable string, status Status) error
	// OpenLogger opens the log once the lock is held, so a daemon that loses
	// the race never rotates the winner's log. It replaces Logger.
	OpenLogger func() (*slog.Logger, func(), error)
	// ShutdownTimeout bounds App.Shutdown; zero is DefaultShutdownTimeout.
	ShutdownTimeout time.Duration
	// LockTimeout is how long to wait for a previous daemon to release the
	// lock; zero is DefaultLockTimeout.
	LockTimeout time.Duration
	Logger      *slog.Logger
	// contains filtered or unexported fields
}

type Paths struct {
	// State is the private directory holding the lock, credential, status
	// file and logs.
	State string
	// Socket is the control socket, in a private directory.
	Socket string
}

type Request struct {
	Protocol int             `json:"protocol"`
	Method   string          `json:"method"`
	Client   string          `json:"client,omitempty"`
	Params   json.RawMessage `json:"params,omitempty"`
}

type Response struct {
	OK     bool            `json:"ok"`
	Status *Status         `json:"status,omitempty"`
	Result json.RawMessage `json:"result,omitempty"`
	Error  *Error          `json:"error,omitempty"`
	// contains filtered or unexported fields
}

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

type Spawner func(paths Paths, start StartOptions) (done <-chan struct{}, err error)

type StartOptions struct {
	Port int
	// Env, when not nil, is the environment the daemon process starts with;
	// nil passes the caller's.
	Env []string
}

type Status struct {
	Protocol  int       `json:"protocol"`
	Version   string    `json:"version"`
	PID       int       `json:"pid"`
	StartedAt time.Time `json:"started_at"`
	// App is the loopback origin of the app transport.
	App    string `json:"app,omitempty"`
	Socket string `json:"socket,omitempty"`
	State  string `json:"state,omitempty"`
	// Stopping is set once the daemon has been asked to stop.
	Stopping bool `json:"stopping,omitempty"`
	// RestartPending is set once a newer client asked the daemon to restart
	// as its version when no job is running; until then no queued job
	// starts, and the queued ones wait for the new daemon.
	RestartPending bool `json:"restart_pending,omitempty"`
}

type StopParams struct {
	// WhenIdle asks the daemon to restart as Executable once no job is
	// running, starting no queued job meanwhile (the new daemon runs them);
	// a daemon with no job queued or running stops at once.
	WhenIdle   bool   `json:"when_idle,omitempty"`
	Executable string `json:"executable,omitempty"`
}