Documentation
¶
Overview ¶
Package server provides RPC server functionality for multiplexed connections.
Index ¶
- Constants
- Variables
- type BiDirHandler
- type BiDirStream
- type Handler
- type HandlerInfo
- type Option
- func WithCompression(alg msgs.Compression) Option
- func WithMaxConcurrentRPCs(max int) Option
- func WithMaxConnections(max int) Option
- func WithMaxRecvMsgSize(size int) Option
- func WithMaxSendMsgSize(size int) Option
- func WithPacking(enabled bool) Option
- func WithStreamInterceptor(interceptors ...interceptor.StreamServerInterceptor) Option
- func WithUnaryInterceptor(interceptors ...interceptor.UnaryServerInterceptor) Option
- type RecvHandler
- type RecvStream
- type Registry
- type SendHandler
- type SendStream
- type Server
- func (s *Server) IsDraining() bool
- func (s *Server) Register(ctx context.Context, pkg, service, call string, handler Handler) error
- func (s *Server) Registry() *Registry
- func (s *Server) Serve(ctx context.Context, transport io.ReadWriteCloser) error
- func (s *Server) Shutdown(ctx context.Context) error
- type ServerConn
- type SyncHandler
Constants ¶
const ( ProtocolMajor = 1 ProtocolMinor = 0 )
Protocol version constants.
Variables ¶
var ( ErrClosed = errors.New("server closed") ErrSessionClosed = errors.New("session closed") ErrMessageTooLarge = errors.New("message size exceeds limit") ErrTooManyConnections = errors.New("too many connections") )
Common errors.
var ErrHandlerExists = errors.New("handler already registered")
ErrHandlerExists is returned when trying to register a handler that already exists.
Functions ¶
This section is empty.
Types ¶
type BiDirHandler ¶
type BiDirHandler struct {
HandleFunc func(ctx context.Context, stream *BiDirStream) error
}
BiDirHandler handles bidirectional streaming RPCs.
func (BiDirHandler) Type ¶
func (h BiDirHandler) Type() msgs.RPCType
Type returns the RPC type this handler handles.
type BiDirStream ¶
type BiDirStream struct {
// contains filtered or unexported fields
}
BiDirStream provides bidirectional communication for handlers.
func (*BiDirStream) Context ¶
func (s *BiDirStream) Context() context.Context
Context returns the context for this stream.
func (*BiDirStream) Err ¶
func (s *BiDirStream) Err() error
Err returns any error that occurred during the stream.
func (*BiDirStream) Recv ¶
func (s *BiDirStream) Recv() iter.Seq[[]byte]
Recv returns an iterator over received payloads. When context is cancelled, it drains and yields any buffered messages before returning.
func (*BiDirStream) Send ¶
func (s *BiDirStream) Send(payload []byte) error
Send sends a payload to the client.
func (*BiDirStream) SetTrailer ¶
func (s *BiDirStream) SetTrailer(md metadata.MD)
SetTrailer sets metadata to be sent with the Close message. This can be called multiple times; subsequent calls will merge metadata.
func (*BiDirStream) Trailer ¶
func (s *BiDirStream) Trailer() metadata.MD
Trailer returns the trailer metadata that was set.
type HandlerInfo ¶
HandlerInfo contains information about a registered handler.
type Option ¶
type Option func(*Server)
Option configures a Server.
func WithCompression ¶
func WithCompression(alg msgs.Compression) Option
WithCompression sets the default compression algorithm for server responses. Use msgs.CmpNone to disable compression (default).
func WithMaxConcurrentRPCs ¶
WithMaxConcurrentRPCs sets the maximum number of concurrent RPC handlers. This uses a limited worker pool to restrict concurrency. Default is 0 (no limit, uses the context's pool directly).
func WithMaxConnections ¶
WithMaxConnections sets the maximum number of concurrent connections. New connections are rejected with ErrTooManyConnections when at limit. Default is 0 (no limit).
func WithMaxRecvMsgSize ¶
WithMaxRecvMsgSize sets the maximum size for received messages. Messages larger than this will be rejected with ErrMessageTooLarge. Default is 4 MiB.
func WithMaxSendMsgSize ¶
WithMaxSendMsgSize sets the maximum size for sent messages. Messages larger than this will cause the send to fail with ErrMessageTooLarge. Default is 4 MiB.
func WithPacking ¶
WithPacking enables Cap'n Proto-style message packing for connections. When enabled, the server will agree to packing if requested by the client. Packing can significantly reduce message size by eliminating zero bytes.
func WithStreamInterceptor ¶
func WithStreamInterceptor(interceptors ...interceptor.StreamServerInterceptor) Option
WithStreamInterceptor adds stream interceptors to the server. Multiple calls chain the interceptors; they execute in the order provided.
func WithUnaryInterceptor ¶
func WithUnaryInterceptor(interceptors ...interceptor.UnaryServerInterceptor) Option
WithUnaryInterceptor adds unary interceptors to the server. Multiple calls chain the interceptors; they execute in the order provided.
type RecvHandler ¶
type RecvHandler struct {
HandleFunc func(ctx context.Context, stream *SendStream) error
}
RecvHandler handles server-send streaming RPCs (server sends, client receives).
func (RecvHandler) Type ¶
func (h RecvHandler) Type() msgs.RPCType
Type returns the RPC type this handler handles.
type RecvStream ¶
type RecvStream struct {
// contains filtered or unexported fields
}
RecvStream allows the server to receive messages from the client. Used by SendHandler (client sends, server receives).
func (*RecvStream) Context ¶
func (s *RecvStream) Context() context.Context
Context returns the context for this stream.
func (*RecvStream) Err ¶
func (s *RecvStream) Err() error
Err returns any error that occurred during the stream.
func (*RecvStream) Recv ¶
func (s *RecvStream) Recv() iter.Seq[[]byte]
Recv returns an iterator over received payloads. When context is cancelled, it drains and yields any buffered messages before returning.
func (*RecvStream) SetTrailer ¶
func (s *RecvStream) SetTrailer(md metadata.MD)
SetTrailer sets metadata to be sent with the Close message. This can be called multiple times; subsequent calls will merge metadata.
func (*RecvStream) Trailer ¶
func (s *RecvStream) Trailer() metadata.MD
Trailer returns the trailer metadata that was set.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages handler registration for RPC services.
func (*Registry) Handlers ¶
func (r *Registry) Handlers() iter.Seq[HandlerInfo]
Handlers returns an iterator over all registered handlers.
func (*Registry) LookupByDescr ¶
LookupByDescr finds a handler using a Descr message.
type SendHandler ¶
type SendHandler struct {
HandleFunc func(ctx context.Context, stream *RecvStream) error
}
SendHandler handles client-send streaming RPCs (client sends, server receives).
func (SendHandler) Type ¶
func (h SendHandler) Type() msgs.RPCType
Type returns the RPC type this handler handles.
type SendStream ¶
type SendStream struct {
// contains filtered or unexported fields
}
SendStream allows the server to send messages to the client. Used by RecvHandler (server sends, client receives).
func (*SendStream) Context ¶
func (s *SendStream) Context() context.Context
Context returns the context for this stream.
func (*SendStream) Send ¶
func (s *SendStream) Send(payload []byte) error
Send sends a payload to the client.
func (*SendStream) SetTrailer ¶
func (s *SendStream) SetTrailer(md metadata.MD)
SetTrailer sets metadata to be sent with the Close message. This can be called multiple times; subsequent calls will merge metadata.
func (*SendStream) Trailer ¶
func (s *SendStream) Trailer() metadata.MD
Trailer returns the trailer metadata that was set.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server handles RPC connections and dispatches to registered handlers.
func (*Server) IsDraining ¶
IsDraining returns true if the server is shutting down (no new connections accepted).
func (*Server) Register ¶
Register registers a handler for a specific package/service/call combination.
func (*Server) Registry ¶
Registry returns the server's handler registry. This is useful for reflection and introspection of registered services.
func (*Server) Serve ¶
Serve handles a single connection, spawning session goroutines via context.Pool(ctx). This blocks until the connection is closed or an error occurs.
func (*Server) Shutdown ¶
Shutdown gracefully shuts down the server. It stops accepting new connections, sends GoAway to all active connections, waits for in-flight RPCs to complete, then closes all connections. The context controls how long to wait; if cancelled, remaining connections are forcefully closed.
type ServerConn ¶
type ServerConn struct {
// contains filtered or unexported fields
}
ServerConn handles a single client connection.
func (*ServerConn) Close ¶
func (c *ServerConn) Close() error
Close closes the connection immediately without waiting for handlers.
func (*ServerConn) GracefulClose ¶
func (c *ServerConn) GracefulClose(ctx context.Context) error
GracefulClose gracefully closes the connection, waiting for in-flight handlers to complete. The context controls how long to wait; if it's cancelled or times out, remaining handlers are forcefully terminated.
Returns nil if all handlers completed gracefully, or an error if the context was cancelled before all handlers finished.
func (*ServerConn) IsDraining ¶
func (c *ServerConn) IsDraining() bool
IsDraining returns true if the connection is draining (no new sessions allowed).
type SyncHandler ¶
type SyncHandler struct {
HandleFunc func(ctx context.Context, req []byte, md []msgs.Metadata) ([]byte, error)
}
SyncHandler handles synchronous request/response RPCs.
func (SyncHandler) Type ¶
func (h SyncHandler) Type() msgs.RPCType
Type returns the RPC type this handler handles.
Source Files