Documentation
¶
Overview ¶
Package shared implements mini's local service protocol and transports.
Index ¶
- Variables
- func On[API, Event any](peer *RpcPeer, token ServiceToken[API, Event], handler func(Event))
- func Provide[API, Event any](peer *RpcPeer, token ServiceToken[API, Event], implementation API) error
- func Use[API, Event any](peer *RpcPeer, token ServiceToken[API, Event], options CallOptions) (API, error)
- func Yield(ctx context.Context)
- type AuthEventPayload
- type AuthPromptOption
- type AuthPromptRequest
- type CallOptions
- type CommandResult
- type Connection
- type Forward
- type Handler
- type JSONConnection
- type LaneEvent
- type LaneServiceApi
- type LaneSubscription
- type Listener
- type ModelRef
- type ModelSummary
- type ModelsEvent
- type ModelsServiceApi
- type ModelsState
- type PeerOptions
- type ProviderAccount
- type Remote
- type RpcPeer
- func (p *RpcPeer) Announced() []string
- func (p *RpcPeer) Call(ctx context.Context, method string, args ...any) (json.RawMessage, error)
- func (p *RpcPeer) CallWith(ctx context.Context, options CallOptions, method string, args ...any) (json.RawMessage, error)
- func (p *RpcPeer) Close() error
- func (p *RpcPeer) Emit(token Token, event any) error
- func (p *RpcPeer) EmitRaw(service string, payload any, to *string) error
- func (p *RpcPeer) EmitTo(token Token, event any, to string) error
- func (p *RpcPeer) Err() error
- func (p *RpcPeer) On(token Token, handler func(json.RawMessage))
- func (p *RpcPeer) OnClose(handler func())
- func (p *RpcPeer) OnEvent(handler func(service string, payload json.RawMessage, to *string))
- func (p *RpcPeer) Provide(token Token, implementation any) error
- func (p *RpcPeer) Provided() []string
- func (p *RpcPeer) Use(token Token, options CallOptions) *Remote
- func (p *RpcPeer) Wait()
- type Service
- type ServiceToken
- type SessionSnapshot
- type SessionSummary
- type SessionsServiceApi
- type Token
- type UnixTransport
- type WorkerDescription
- type WorkerServiceApi
Constants ¶
This section is empty.
Variables ¶
var ( Lane = DefineService[LaneServiceApi, LaneEvent]("lane") Models = DefineService[ModelsServiceApi, ModelsEvent]("models") Worker = DefineService[WorkerServiceApi, struct{}]("worker") Sessions = DefineService[SessionsServiceApi, struct{}]("sessions") )
Functions ¶
func On ¶
func On[API, Event any](peer *RpcPeer, token ServiceToken[API, Event], handler func(Event))
func Provide ¶
func Provide[API, Event any](peer *RpcPeer, token ServiceToken[API, Event], implementation API) error
func Use ¶
func Use[API, Event any](peer *RpcPeer, token ServiceToken[API, Event], options CallOptions) (API, error)
Use binds each API function field to the same named remote method. Go has no generic methods or dynamic property proxy, so the typed form is a package function.
func Yield ¶
Yield ends an incoming handler's synchronous prefix so the reader can deliver subsequent frames. Call it immediately before a blocking wait corresponding to an upstream await. Call and CallWith yield automatically after sending. Yield does not detach work: the peer owns the entire handler until it returns. It is a no-op outside a handler or after the first yield.
Types ¶
type AuthEventPayload ¶
type AuthEventPayload struct {
Type string `json:"type"`
RequestID *string `json:"requestId,omitempty"`
Request *AuthPromptRequest `json:"request,omitempty"`
Notice json.RawMessage `json:"notice,omitempty"`
}
AuthEventPayload is the prompt/notice half of the models event channel.
type AuthPromptOption ¶
type AuthPromptRequest ¶
type AuthPromptRequest struct {
Type string `json:"type"`
Message string `json:"message"`
Placeholder *string `json:"placeholder,omitempty"`
Options *[]AuthPromptOption `json:"options,omitempty"`
}
AuthPromptRequest carries the prompt without its process-local cancellation signal.
type CallOptions ¶
type CallOptions struct {
// TimeoutMs bounds the call only when present. The context passed to CallWith supplies cancellation.
TimeoutMs *float64
}
type CommandResult ¶
CommandResult reports command failure as data rather than an RPC error.
type Connection ¶
type Connection interface {
Send(any) error
OnMessage(func(json.RawMessage))
OnClose(func())
Close() error
}
Connection carries ordered JSON messages. Callbacks run serially on the reader; they must return promptly. Send queues a frame without waiting for the remote reader.
type Forward ¶
Forward routes calls for services not provided by this peer. Its context carries the dispatch turn for Yield and nested calls, but no cancellation signal from this hop.
type Handler ¶
Handler receives wire arguments and the process-local cancellation signal. Its synchronous prefix runs before the next frame. Before blocking, it must call Yield or an RPC Call with this context; completion may then overlap later handlers.
type JSONConnection ¶
type JSONConnection struct {
// contains filtered or unexported fields
}
JSONConnection owns its reader, writer, and their shutdown. Wait joins both pumps after Close. Incomplete final lines are not messages.
func ChildConnection ¶
func ChildConnection(stdin io.WriteCloser, stdout io.ReadCloser, kill func() error) (*JSONConnection, error)
ChildConnection connects the parent's view of a spawned child's pipes. The caller owns starting and waiting for the process; closing this connection also invokes kill.
func JsonConnection ¶
func JsonConnection(input io.ReadCloser, output io.WriteCloser, closeConnection func() error) *JSONConnection
JsonConnection frames JSON over an existing duplex pair. The first OnMessage registration starts delivery, allowing the owner to install its callbacks before any frame arrives.
func ParentConnection ¶
func ParentConnection() *JSONConnection
ParentConnection connects a child's standard input/output. Closing stops reading from the parent.
func (*JSONConnection) Close ¶
func (c *JSONConnection) Close() error
func (*JSONConnection) Err ¶
func (c *JSONConnection) Err() error
Err reports a fatal framing or IO failure. An orderly EOF or explicit close has no error.
func (*JSONConnection) OnClose ¶
func (c *JSONConnection) OnClose(handler func())
func (*JSONConnection) OnMessage ¶
func (c *JSONConnection) OnMessage(handler func(json.RawMessage))
func (*JSONConnection) Send ¶
func (c *JSONConnection) Send(message any) error
func (*JSONConnection) Wait ¶
func (c *JSONConnection) Wait()
type LaneEvent ¶
type LaneEvent struct {
SubscriptionID string `json:"subscriptionId"`
// Event is the harness-owned event, forwarded without decoding or losing fields.
Event json.RawMessage `json:"event"`
}
type LaneServiceApi ¶
type LaneServiceApi struct {
Watch func(context.Context, string) (LaneSubscription, error)
Start func(context.Context, string) error
Unwatch func(context.Context, string) error
Prompt func(context.Context, string) (CommandResult, error)
Steer func(context.Context, string) (CommandResult, error)
FollowUp func(context.Context, string) (CommandResult, error)
Compact func(context.Context) (CommandResult, error)
Abort func(context.Context) (CommandResult, error)
SetModel func(context.Context, ModelRef) (CommandResult, error)
}
Service APIs use function fields so the same shape can describe local implementations and remote calls. Context is process-local and never enters the wire args.
type LaneSubscription ¶
type LaneSubscription struct {
SubscriptionID string `json:"subscriptionId"`
Snapshot SessionSnapshot `json:"snapshot"`
}
type Listener ¶
type Listener struct {
// contains filtered or unexported fields
}
Listener stops accepting on Close and waits for existing connections to close, as node:net Server.close does.
type ModelSummary ¶
type ModelsEvent ¶
type ModelsEvent struct {
Type string `json:"type"`
State *ModelsState `json:"state,omitempty"`
RequestID *string `json:"requestId,omitempty"`
Request *AuthPromptRequest `json:"request,omitempty"`
Notice json.RawMessage `json:"notice,omitempty"`
}
ModelsEvent is state, prompt, or notice; only the corresponding payload is present.
type ModelsServiceApi ¶
type ModelsState ¶
type ModelsState struct {
Models []ModelSummary `json:"models"`
Accounts []ProviderAccount `json:"accounts"`
Refreshing bool `json:"refreshing"`
}
type PeerOptions ¶
type ProviderAccount ¶
type Remote ¶
type Remote struct {
// contains filtered or unexported fields
}
Remote addresses one service without a compile-time API shape.
type RpcPeer ¶
type RpcPeer struct {
// contains filtered or unexported fields
}
RpcPeer is a bidirectional peer. Call blocks until the answer, cancellation, timeout, or connection close. Incoming handlers enter in frame order and may complete concurrently after Yield; Wait joins them after Close. Handlers must respect their contexts to permit shutdown to finish.
func CreatePeer ¶
func CreatePeer(connection Connection, options PeerOptions) *RpcPeer
func (*RpcPeer) CallWith ¶
func (p *RpcPeer) CallWith(ctx context.Context, options CallOptions, method string, args ...any) (json.RawMessage, error)
func (*RpcPeer) Err ¶
Err returns a fatal protocol or send error. Remote method errors belong to their Call result instead.
func (*RpcPeer) OnEvent ¶
func (p *RpcPeer) OnEvent(handler func(service string, payload json.RawMessage, to *string))
type ServiceToken ¶
ServiceToken attaches a service's call and event types to its globally unique name.
func DefineService ¶
func DefineService[API, Event any](name string) ServiceToken[API, Event]
func (ServiceToken[API, Event]) ServiceName ¶
func (t ServiceToken[API, Event]) ServiceName() string
type SessionSnapshot ¶
type SessionSnapshot struct {
SessionID string `json:"sessionId"`
Cwd string `json:"cwd"`
SessionPath string `json:"sessionPath"`
// Lane is the harness-owned snapshot, forwarded without decoding or losing fields.
Lane json.RawMessage `json:"lane"`
Models ModelsState `json:"models"`
}
type SessionSummary ¶
type SessionsServiceApi ¶
type Token ¶
type Token interface{ ServiceName() string }
Token is the name-bearing half of a service token used by the RPC router.
type UnixTransport ¶
type UnixTransport struct {
// contains filtered or unexported fields
}
UnixTransport negotiates local connections at a filesystem socket path.
func SocketTransport ¶
func SocketTransport(path string) *UnixTransport
func (*UnixTransport) Connect ¶
func (t *UnixTransport) Connect(ctx context.Context) (*JSONConnection, error)
func (*UnixTransport) Listen ¶
func (t *UnixTransport) Listen(onConnection func(*JSONConnection)) (*Listener, error)
Listen removes a stale file or socket, but never a directory, before binding the local endpoint.
type WorkerDescription ¶
type WorkerDescription struct {
SessionID string `json:"sessionId"`
}
type WorkerServiceApi ¶
type WorkerServiceApi struct {
Describe func(context.Context) (WorkerDescription, error)
}