ctl

package

v0.2.7 Latest Latest Go to latest Published: Nov 10, 2026 License: MIT Imports: 16 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Anonyfox/lfr

Links

Open Source Insights

Documentation ¶

Overview ¶

Package ctl is the local control protocol between the lfr CLI and the running server: one JSON request per connection over a unix socket that only the server's user (and group) can open. There is no network API.

Index ¶

Constants
Variables
func Listen(path string, mode os.FileMode) (net.Listener, error)
func Proxy(ctx context.Context, path string, in io.Reader, out io.Writer) error
func SSH(target, remoteData string) func(ctx context.Context) (net.Conn, error)
type Client
- func (c Client) Call(ctx context.Context, op string, args, out any) error
- func (c Client) Stream(ctx context.Context, op string, args any, fn func(json.RawMessage) error) error
type Error
- func (e *Error) Error() string
type Handler
type Request
type Response
type Server
type StreamHandler

Constants ¶

View Source

const (
	CodeNotFound = "not_found"
	CodeInvalid  = "invalid"
	CodeConflict = "conflict"
	CodeInternal = "internal"
)

Codes.

Variables ¶

View Source

var ErrNotRunning = errors.New("lfr server is not running")

ErrNotRunning means nothing listens on the socket.

Functions ¶

func Listen ¶

func Listen(path string, mode os.FileMode) (net.Listener, error)

Listen opens the socket at path with the given permissions, replacing a stale one.

func Proxy ¶

func Proxy(ctx context.Context, path string, in io.Reader, out io.Writer) error

Proxy copies between in/out and the control socket at path until either side closes: the remote end of SSH.

func SSH ¶

func SSH(target, remoteData string) func(ctx context.Context) (net.Conn, error)

SSH returns a Dial that reaches the control socket of the lfr server at target ("user@host" or an ssh config alias) by running `lfr proxy` there over ssh. Connections share one ssh session for a minute, so a command that makes many calls pays the handshake once.

Types ¶

type Client ¶

type Client struct {
	Path    string
	Timeout time.Duration
	// Dial replaces the unix socket, e.g. with a pipe through ssh.
	Dial func(ctx context.Context) (net.Conn, error)
}

Client calls a server.

func (Client) Call ¶

func (c Client) Call(ctx context.Context, op string, args, out any) error

Call runs op and decodes its result into out (which may be nil).

func (Client) Stream ¶

func (c Client) Stream(ctx context.Context, op string, args any, fn func(json.RawMessage) error) error

Stream runs a streaming op, calling fn for each value until ctx ends.

type Error ¶

type Error struct {
	Code string
	Msg  string
}

Error carries a machine-readable code.

func (*Error) Error ¶

func (e *Error) Error() string

type Handler ¶

type Handler func(ctx context.Context, args json.RawMessage) (any, error)

Handler answers a call.

type Request ¶

type Request struct {
	Op   string          `json:"op"`
	Args json.RawMessage `json:"args,omitempty"`
}

Request is one call.

type Response ¶

type Response struct {
	OK    bool            `json:"ok"`
	Data  json.RawMessage `json:"data,omitempty"`
	Error string          `json:"error,omitempty"`
	Code  string          `json:"code,omitempty"` // not_found, invalid, conflict, internal
	Done  bool            `json:"done,omitempty"`
}

Response is the answer; streams send several Data lines, then a final one with Done.

type Server ¶

type Server struct {
	Log      *slog.Logger
	Classify func(error) string // maps errors to codes
	// contains filtered or unexported fields
}

Server dispatches calls.

func (*Server) Handle ¶

func (s *Server) Handle(op string, h Handler)

Handle registers an operation.

func (*Server) Ops ¶

func (s *Server) Ops() []string

Ops lists every registered operation.

func (*Server) Serve ¶

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

Serve answers connections until ctx ends.

func (*Server) Stream ¶

func (s *Server) Stream(op string, h StreamHandler)

Stream registers a streaming operation.

type StreamHandler ¶

type StreamHandler func(ctx context.Context, args json.RawMessage, send func(any) error) error

StreamHandler sends values until ctx ends or it returns.

Source Files ¶

View all Source files

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