rpc

package
v0.0.0-...-a396176 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 23, 2024 License: BSD-3-Clause Imports: 21 Imported by: 0

Documentation

Overview

Package rpc provides a kernel message passing RPC system.

Index

Constants

View Source 
const (
	Who       = "who"       // call Message[None] → Message[string] (version)
	Configure = "configure" // call Message[any] → Message[string]
	Stop      = "stop"      // notify any → nil
)

Daemon methods.

View Source 
const (
	Call       = "call"       // call Message[Forward[any]] → Message[Message[any]]
	State      = "state"      // call Message[None] → Message[SysState]
	Notify     = "notify"     // notify Message[Forward[any]] → nil
	Unregister = "unregister" // notify Message[None] → nil
	Heartbeat  = "heartbeat"  // notify Message[Deadline] → nil
)

Kernel methods. Call methods that are invoked with notify are downgraded to notify and the downgrade is logged.

View Source 
const (
	ErrCodeInvalidMessage = 1 // an RPC message is invalid
	// Invalid message sub-codes:
	ErrCodeMessageSyntax       = 11 // syntax
	ErrCodeMessageUnknownField = 12 // unknown field
	ErrCodeShortMessage        = 13 // truncation
	ErrCodeMessageType         = 14 // type mismatch
	ErrCodeMethod              = 15 // method mismatch
	ErrCodeParameters          = 16 // invalid parameters

	ErrCodeDevice = 2 // an error was returned by a device

	ErrCodeInvalidData = 3 // data sent in a call was invalid
	// Invalid data sub-codes:
	ErrCodeNoDaemon  = 31 // missing daemon
	ErrCodeNoPage    = 32 // missing page
	ErrCodeNoDevice  = 33 // missing device
	ErrCodeNoDisplay = 34 // non-graphical device
	ErrCodeBounds    = 35 // out of bounds
	ErrCodeImage     = 36 // image data

	ErrCodeInternal = 4  // an internal error happened
	ErrCodeNoStore  = 41 // no data store
	ErrCodeStoreErr = 42 // store operation error
	ErrCodeProcess  = 43 // child process error
	ErrCodePath     = 44 // path error

	ErrCodeNotFound = 5 // a state key was not present
)

JSON RPC error codes.

View Source 
const RuntimeDir = "dex"

RuntimeDir is the path within XDG_RUNTIME_DIR that unix sockets are created in if the unix network is used for communication.

Variables

This section is empty.

Functions

func AddWireErrorDetail 

func AddWireErrorDetail(err error, details map[string]any) error

AddWireErrorDetail updates the Data field of a jsonrpc2.WireError with the fields in details, overwriting fields if they already exist. If err is not a jsonrpc2.WireError or the Data field does not encode a map, the error is returned unmodified.

func NewError 

func NewError(code int64, message string, data any) error

NewError returns an error that will be encoded correctly in the RPC protocol.

func UnmarshalMessage 

func UnmarshalMessage[T any](data []byte, v *Message[T]) error

UnmarshalMessage is a strict equivalent of json.Unmarshal.

Types

type Button 

type Button struct {
	Row  int    `json:"row"`
	Col  int    `json:"col"`
	Page string `json:"page,omitempty"`
}

Button indicates a button location.

type Connection 

type Connection interface {
	Call(ctx context.Context, method string, params any) *jsonrpc2.AsyncCall
	Respond(id jsonrpc2.ID, result any, err error) error
	Cancel(id jsonrpc2.ID)
	Notify(ctx context.Context, method string, params any) error
}

Connection is a connection to a managed daemon.

type Daemon 

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

Daemon is a kernel-managed process that communicates via JSON RPC 2 calls with the kernel.

func NewDaemon 

func NewDaemon(ctx context.Context, network, addr, uid string, dialer net.Dialer, binder jsonrpc2.Binder) (*Daemon, error)

NewDaemon returns a new daemon communicating on the provided network and managed by the kernel at the given address.

func (*Daemon) Call 

func (d *Daemon) Call(ctx context.Context, method string, params any) *jsonrpc2.AsyncCall

Call invokes the target method and returns an object that can be used to await the response. See jsonrpc2.Connection.Call.

func (*Daemon) Cancel 

func (d *Daemon) Cancel(id jsonrpc2.ID)

Cancel cancels the Context passed to the Handle call for the inbound message with the given ID. See jsonrpc2.Connection.Cancel.

func (*Daemon) Close 

func (d *Daemon) Close() error

Close sends an "unregister" notification to the daemon's managing kernel, stops listening to requests and closes its connection. See jsonrpc2.Connection.Close.

func (*Daemon) Notify 

func (d *Daemon) Notify(ctx context.Context, method string, params any) error

Notify invokes the target method but does not wait for a response. See jsonrpc2.Connection.Notify.

func (*Daemon) Respond 

func (d *Daemon) Respond(id jsonrpc2.ID, result any, err error) error

Respond delivers a response to an incoming Call. See jsonrpc2.Connection.Respond.

func (*Daemon) UID 

func (d *Daemon) UID() string

UID returns the daemons unique ID.

func (*Daemon) Wait 

func (d *Daemon) Wait()

Wait blocks until the connection is fully closed, but does not close it. See jsonrpc2.Connection.Wait.

type DaemonState 

type DaemonState struct {
	UID           string     `json:"uid"`
	Version       string     `json:"version"`
	Command       *string    `json:"command,omitempty"` // Command used to start the daemon.
	Builtin       *string    `json:"builtin,omitempty"` // UID of a built-in.
	LastHeartbeat *time.Time `json:"last_heartbeat,omitempty"`
	Deadline      *time.Time `json:"deadline,omitempty"`
	HasDrop       bool       `json:"has_drop"` // Whether the daemon has a drop function registered.
}

DaemonState is the state of individual daemons in the system

type Deadline 

type Deadline struct {
	Deadline *time.Time `json:"deadline"`
}

Deadline is the response expected for a heartbeat. The Deadline field indicates when the daemon expects to be able to provide the next beat.

type Duration 

type Duration struct {
	time.Duration
}

Duration is a helper for duration fields.

func (*Duration) MarshalJSON 

func (d *Duration) MarshalJSON() ([]byte, error)

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(data []byte) error

type Forward 

type Forward[T any] struct {
	UID    UID         `json:"uid,omitempty"`
	Method string      `json:"method,omitempty"`
	Params *Message[T] `json:"params,omitempty"`
}

Forward is a message body for call and notify methods that are to be passed on to another daemon. UID is the destination daemon, Method is the call or notify method and Params is the call or notify parameters.

type Funcs 

type Funcs map[string]func(context.Context, jsonrpc2.ID, json.RawMessage) (*Message[any], error)

Funcs is a mapping from method names to insertable functions. A name with a nil function removes the mapping.

If the ID is valid, the function must return either a non-nil, JSON-marshalable result, or a non-nil error. If it is not valid, the functions must return a nil result.

type Kernel 

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

Kernel is a JSON RPC 2 based message passing kernel.

func NewKernel 

func NewKernel(ctx context.Context, network string, options jsonrpc2.NetListenOptions, log *slog.Logger) (*Kernel, error)

NewKernel returns a new Kernel communicating over the provided network which may be either "unix" or "tcp".

func (*Kernel) Addr 

func (k *Kernel) Addr() net.Addr

Addr returns the listener address of the kernel.

func (*Kernel) Bind 

func (k *Kernel) Bind(ctx context.Context, conn *jsonrpc2.Connection) jsonrpc2.ConnectionOptions

Bind binds the kernel's handler to a connection and the reverse connection to a daemon's UID.

func (*Kernel) Builtin 

func (k *Kernel) Builtin(ctx context.Context, uid string, dialer net.Dialer, binder jsonrpc2.Binder) error

Builtin starts a new virtual client daemon with the provided UID using the provided binder.

func (*Kernel) Close 

func (k *Kernel) Close() error

Close closes the kernel, terminating all spawned daemons.

func (*Kernel) Conn 

func (k *Kernel) Conn(ctx context.Context, uid string) (Connection, time.Time, bool)

Conn returns a connection to the daemon with the given UID.

func (*Kernel) Funcs 

func (k *Kernel) Funcs(funcs Funcs)

Funcs inserts the provided functions into the kernel's handler. If funcs is nil the entire kernel mapping table is reset.

func (*Kernel) Handle 

func (k *Kernel) Handle(ctx context.Context, req *jsonrpc2.Request) (any, error)

Handle is the kernel's message handler.

func (*Kernel) Kill 

func (k *Kernel) Kill(uid string)

Kill terminates the daemon identified by uid. If no corresponding daemon exists, it is a no-op.

func (*Kernel) SetDrop 

func (k *Kernel) SetDrop(uid string, drop func() error) error

SetDrop sets a call-back that will be called when the daemon with the specified UID is unregistered. This should be used if the daemon uses any kernel-adjacent storage that needs to be released when the daemon terminates. Conventionally, the kernel-adjacent store will insert a "register" method using the Funcs method that will accept the data to be stored and set the drop call-back. Subsequent calls to SetDrop will over-write previous drop call-backs, and a nil drop is a no-op.

func (*Kernel) Spawn 

func (k *Kernel) Spawn(ctx context.Context, stdout, stderr io.Writer, done func(), uid, name string, args ...string) error

Spawn starts a new client daemon with the provided UID. The daemon executable is started by executing name with the provided args. The new process is given stdout and stderr as redirects for those output streams. Spawned daemons are expected to send a "register" JSON RPC 2 call to the kernel on start and a "deregister" notification before exiting. The child process is passed the read end of a pipe on stdin. No writes are ever made by the parent, but the child may use the pipe to detect termination of the parent.

type Message 

type Message[T any] struct {
	Time time.Time `json:"time"`
	UID  UID       `json:"uid,omitempty"`
	Body T         `json:"body,omitempty"`
}

Message is the message passing container.

func NewMessage 

func NewMessage[T any](uid UID, body T) *Message[T]

NewMessage is a convenience Message constructor. It populates the Time field and ensures that the daemon's UID is included in the message.

type None 

type None struct{}

None is an empty parameter or response slot.

type SysState 

type SysState struct {
	Network string                 `json:"network"`
	Addr    string                 `json:"addr"`
	Sock    *string                `json:"sock,omitempty"`
	Daemons map[string]DaemonState `json:"daemons,omitempty"`
	Funcs   []string               `json:"funcs,omitempty"`
}

SysState is the system state returned by a state call.

type UID 

type UID struct {
	Module  string `json:"module,omitempty"`
	Service string `json:"service,omitempty"`
}

UID is a component's UID.

func (UID) IsKernel 

func (u UID) IsKernel() bool

IsKernel returns whether the UID refers to a kernel service or component.

func (UID) IsZero 

func (u UID) IsZero() bool

func (UID) String 

func (u UID) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.