Documentation
¶
Overview ¶
Package pluginruntime provides the production local socket transport that binds a plugin process to its host for one launch, plus the handshake and RPC bridges used by the A4 Plugin Host and SDK service layers.
The first Windows version uses loopback TCP on a random port; Linux/macOS use a Unix domain socket. The wire format is a length-prefixed JSON transport.Message stream. Before any RPC frame is accepted, the dialing side sends a single authentication frame carrying the launch id and proof; the serving side validates it in constant time and never passes a bad proof through to an RPC handler.
Index ¶
Constants ¶
const ( DefaultMaxFrameSize = 4 << 20 // 4 MiB DefaultMaxConnections = 64 DefaultHandshakeTimeout = 5 * time.Second DefaultReadTimeout = 30 * time.Second DefaultWriteTimeout = 30 * time.Second )
Default transport limits. These are deliberately small enough to bound memory and idle time but generous enough for a local plugin connection.
Variables ¶
var ( // ErrAuthenticationFailed reports a rejected launch identity. It is // intentionally generic: the proof must never be echoed back. ErrAuthenticationFailed = errors.New("pluginruntime: authentication failed") // ErrFrameTooLarge reports a frame over Config.MaxFrameSize. ErrFrameTooLarge = errors.New("pluginruntime: frame exceeds limit") )
Functions ¶
func Dial ¶
func Dial(ctx context.Context, endpoint string, creds Credentials, cfg Config) (transport.Transport, error)
Dial connects to a local endpoint, authenticates with creds as the first frame and returns an established transport.Transport ready for the SDK rpc client. The returned transport must be closed by the caller.
Types ¶
type Config ¶
type Config struct {
// MaxFrameSize is the maximum JSON frame payload in bytes, both directions.
MaxFrameSize int
// MaxConnections bounds concurrent accepted connections on a listener.
MaxConnections int
// HandshakeTimeout bounds the first authentication frame exchange.
HandshakeTimeout time.Duration
// ReadTimeout is the per-frame read deadline on an established connection.
ReadTimeout time.Duration
// WriteTimeout is the per-frame write deadline on an established connection.
WriteTimeout time.Duration
}
Config bounds the socket transport. A zero value is not valid; callers use DefaultConfig and override the fields they need.
type Credentials ¶
Credentials is the per-launch identity shared by host and plugin through the process environment. Proof is treated as an opaque secret: it is compared in constant time and never logged.
func (Credentials) Validate ¶
func (c Credentials) Validate() error
Validate reports whether both fields are present.
type Endpoint ¶
Endpoint is a validated local transport endpoint. Addr is a host:port for tcp and an absolute filesystem path for unix.
func ParseEndpoint ¶
ParseEndpoint parses and structurally validates a local endpoint. It rejects userinfo, query, fragment, unknown schemes, non-loopback TCP hosts and relative or escaping Unix paths.
type Handler ¶
Handler runs one authenticated plugin connection. The host/plugin caller typically wraps the returned transport.Transport with an SDK rpc.Client or rpc.Server and then calls Serve on it.
type Listener ¶
type Listener struct {
// contains filtered or unexported fields
}
Listener is a bound local socket listener together with its resolved endpoint and expected launch credentials.
func Listen ¶
Listen binds a local endpoint and returns a ready listener. For tcp://127.0.0.1:0 the OS assigns a random loopback port, exposed through Listener.Endpoint.
func (*Listener) Endpoint ¶
Endpoint returns the resolved endpoint, including an OS-assigned TCP port.
func (*Listener) Serve ¶
Serve accepts connections until ctx is canceled or the listener closes. Each accepted connection is authenticated against the listener's launch credentials before its handler runs, so a wrong proof never reaches an RPC handler. Connections are handled concurrently up to Config.MaxConnections; excess connections are rejected. On ctx cancellation Serve closes the listener and every active connection, removes the Unix socket file and returns ctx.Err.
Source Files