zapclient

import "github.com/luxfi/zap/zapclient"

Functions

MustOpcode

func MustOpcode(name string) uint16

MustOpcode is ProcedureOpcode that panics on error. Use in package-level var initialisers where a bad procedure name is a build-time bug.

ProcedureOpcode

func ProcedureOpcode(name string) (uint16, error)

ProcedureOpcode returns the uint16 opcode for a procedure name. The lower 8 bits are zero (matching the existing MsgType<<8 shape in lux/zap); the upper 8 bits are FNV-1a(name) modulo 254 + 1.

Returns ErrReservedOpcode if the hash lands on 0x00 or 0xFF.

Types

AllowListVerifier

AllowListVerifier accepts only peers whose NodeID appears in Allowed[procedure]. Empty Allowed[procedure] means the procedure is not exposed.

func (a AllowListVerifier) Verify(ctx context.Context, peer PeerInfo, procedure string) error

Client

Client is a native ZAP RPC client. Created by Connect; closed by Close (or returned stop function from MustConnect).

func Connect(ctx context.Context, serviceType string, opts ...ClientOption) (*Client, error)

func MustConnect(ctx context.Context, serviceType string, opts ...ClientOption) *Client

func (c *Client) Broadcast(ctx context.Context, procedure string, req *zap.Message) map[string]error

func (c *Client) Call(ctx context.Context, procedure string, req *zap.Message) (*zap.Message, error)

func (c *Client) Close() error

func (c *Client) Peers() []Peer

func (c *Client) Send(ctx context.Context, procedure string, req *zap.Message) error

ClientOption

ClientOption is the functional-option constructor knob.

func WithBrowseInterval(d time.Duration) ClientOption

func WithCallTimeout(d time.Duration) ClientOption

func WithDiscoverTimeout(d time.Duration) ClientOption

func WithDiscovery(d Discovery) ClientOption

func WithLogger(l *slog.Logger) ClientOption

func WithMinPeers(n int) ClientOption

func WithNodeID(id string) ClientOption

func WithPicker(p Picker) ClientOption

func WithStaticPeers(addrs ...string) ClientOption

func WithTLS(cfg *tls.Config) ClientOption

ClientOptions

ClientOptions configure Connect. Construct via WithX options.

Discovery

Discovery is the peer-enumeration contract.

Implementations MUST be goroutine-safe; the client may call Peers() from every in-flight Call and Send.

LocalTrustVerifier

LocalTrustVerifier accepts any peer presenting a valid mTLS cert from the cluster CA. The underlying TLS handshake already verified the chain; this verifier returns nil for every authenticated peer.

Use when:

• the peer is on the cluster-private network
• the listener was constructed with the cluster CA in ClientCAs
• all in-cluster services should be allowed to call all procedures (apply per-procedure RBAC in the handler if needed)

func (LocalTrustVerifier) Verify(ctx context.Context, peer PeerInfo, procedure string) error

Peer

Peer is the discovery view of one reachable instance of a service.

NodeID uniquely identifies the peer within ServiceType across discovery cycles. Address is the dial target (host:port). For in-cluster peers under mTLS, the authenticated peer identity comes from the TLS session — NodeID is a hint, not a trust anchor.

PeerInfo

PeerInfo is the authenticated peer identity surfaced to server-side handlers and PeerVerifier.

PeerVerifier

PeerVerifier is the server-side authorisation hook. Runs on every inbound message before procedure dispatch — return non-nil to reject the call.

The PeerInfo carries the authenticated peer identity (NodeID + mTLS cert chain if present). Procedure is the procedure name the caller requested. PeerVerifier should compare the (peer, procedure) pair against the service's authorisation policy.

Picker

Picker selects one peer from a Discovery snapshot for a single Call or Send. Implementations MUST be cheap (sub-microsecond) and goroutine-safe; the client invokes Pick from every concurrent op.

ProcedureHandler

ProcedureHandler runs server-side for one inbound procedure call. Return nil + nil-err to ack a fire-and-forget Send. Return a response + nil-err to reply to a Call. Return nil + non-nil err to signal failure; the client side observes the err on its Call.

RoundRobinPicker

RoundRobinPicker rotates through peers in registration order. Zero-value is ready to use; goroutine-safe.

func (p *RoundRobinPicker) Pick(peers []Peer) (Peer, error)

Server

Server is the native ZAP server side: procedure-name dispatch on top of *zap.Node. Construct with NewServer, Register procedures, Start to begin accepting, Stop to release.

func NewServer(serviceType string, opts ...ServerOption) (*Server, error)

func (s *Server) Dispatch(ctx context.Context, from string, msg *zap.Message) (*zap.Message, error)

func (s *Server) NodeID() string

func (s *Server) Register(procedure string, h ProcedureHandler) error

func (s *Server) Start() error

func (s *Server) Stop()

ServerOption

ServerOption is a functional-option knob.

func WithNoDiscovery() ServerOption

func WithServerLogger(l *slog.Logger) ServerOption

func WithServerMetadata(m map[string]string) ServerOption

func WithServerNodeID(id string) ServerOption

func WithServerPort(p int) ServerOption

func WithServerTLS(cfg *tls.Config) ServerOption

func WithVerifier(v PeerVerifier) ServerOption

ServerOptions

ServerOptions configure NewServer.