clusterrpc

Documentation

Overview

Package clusterrpc is Narad's node-to-node RPC transport: length-framed request/reply frames (internal/protocol/clusterwire) multiplexed over pooled QUIC streams. The client correlates replies by RequestID so many in-flight RPCs share one stream; the server answers each frame on the stream it arrived on.

Index

• func ServeQUIC(ctx context.Context, addr, secret string, logger *slog.Logger, ...) error
• func ServeStreamConn(conn streamConn, reader io.Reader, secret string, logger *slog.Logger, ...)
• type QUICFrameClient
  • func NewQUICFrameClient(timeout time.Duration, secret string) *QUICFrameClient
  • func (c *QUICFrameClient) Request(ctx context.Context, addr string, frameType clusterwire.StreamFrameType, ...) (clusterwire.StreamFrame, error)
  • func (c *QUICFrameClient) RequestOnLane(ctx context.Context, addr, lane string, frameType clusterwire.StreamFrameType, ...) (clusterwire.StreamFrame, error)
• type StreamFrameHandler

Functions

func ServeQUIC

func ServeQUIC(ctx context.Context, addr, secret string, logger *slog.Logger, handlers ...StreamFrameHandler) error

ServeQUIC listens for cluster-RPC connections over QUIC and dispatches each request frame to the supplied handlers (e.g. the cluster RPC server). When secret is non-empty, every stream must present a valid auth frame first or it is closed unserved. It blocks until ctx is cancelled.

func ServeStreamConn

func ServeStreamConn(conn streamConn, reader io.Reader, secret string, logger *slog.Logger, handlers ...StreamFrameHandler)

ServeStreamConn serves cluster-RPC frames on a single stream. When secret is non-empty, the stream's first frame must be a valid auth proof or the stream is closed without serving any request.

Types

type QUICFrameClient

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

QUICFrameClient sends cluster-RPC request frames to peer nodes over pooled QUIC streams and returns the matching reply frames. It is safe for concurrent use; a nil client fails every request instead of panicking.

func NewQUICFrameClient

func NewQUICFrameClient(timeout time.Duration, secret string) *QUICFrameClient

NewQUICFrameClient returns a client whose reply waits and dials fall back to timeout when the caller's context carries no deadline. A non-positive timeout selects the package default. secret, when non-empty, is presented on every new stream to authenticate to peers that require a cluster secret.

func (*QUICFrameClient) Request

func (c *QUICFrameClient) Request(ctx context.Context, addr string, frameType clusterwire.StreamFrameType, payload []byte) (clusterwire.StreamFrame, error)

Request sends one request frame to addr on the lane implied by the frame type and waits for the correlated reply.

func (*QUICFrameClient) RequestOnLane

func (c *QUICFrameClient) RequestOnLane(ctx context.Context, addr, lane string, frameType clusterwire.StreamFrameType, payload []byte) (clusterwire.StreamFrame, error)

RequestOnLane is Request with an explicit lane ("produce", "consume", "ack", or "control"; anything else falls back to "control"). Lanes keep bulk traffic from head-of-line blocking control RPCs.

type StreamFrameHandler

type StreamFrameHandler interface {
	HandleStreamFrame(frame clusterwire.StreamFrame, respond func(clusterwire.StreamFrame)) bool
}

StreamFrameHandler handles a decoded cluster-RPC request frame and writes its reply via respond. It returns true if it handled the frame.