zapclient

type AllowListVerifier ¶

type AllowListVerifier struct {
	// Allowed maps procedure name → set of NodeIDs permitted to call
	// it. Empty set = procedure disabled.
	Allowed map[string]map[string]struct{}
}

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

type Client ¶

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

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

type ClientOption ¶

type ClientOption func(*ClientOptions)

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 WithTLS(cfg *tls.Config) ClientOption

type ClientOptions ¶

type ClientOptions struct {
	// NodeID is the caller's identity in mDNS announcements. Empty
	// auto-generates a short suffix.
	NodeID string
	// MinPeers blocks Connect until at least N peers are discovered
	// (or DiscoverTimeout elapses). Default 1.
	MinPeers int
	// DiscoverTimeout caps the initial peer-discovery wait. Default
	// 10 * BrowseInterval.
	DiscoverTimeout time.Duration
	// BrowseInterval is how often the default mDNS Discovery
	// re-browses. Default 5 seconds.
	BrowseInterval time.Duration
	// CallTimeout caps each Call. Zero = no timeout. Default 30s.
	CallTimeout time.Duration
	// TLS configures mutual TLS. Nil = plaintext (dev only — local-
	// trust mode requires mTLS against the cluster CA).
	TLS *tls.Config
	// Logger for ZAP node + client. Defaults to slog.Default().
	Logger *slog.Logger

	// Pluggable wiring. nil means "use default for this concern."
	Discovery Discovery
	Picker    Picker
}

ClientOptions configure Connect. Construct via WithX options.

type Discovery ¶

type Discovery interface {
	// Peers returns the current peer snapshot. The returned slice is
	// freshly allocated; callers may retain it.
	Peers() []Peer

	// PeerCount returns len(Peers()) cheaply.
	PeerCount() int

	// ServiceType reports the service the Discovery is browsing.
	ServiceType() string

	// Start begins the discovery loop. Calling Start twice on the
	// same Discovery is a programmer error.
	Start() error

	// Stop releases all resources. Idempotent.
	Stop()
}

Discovery is the peer-enumeration contract.

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

type LocalTrustVerifier ¶

type LocalTrustVerifier struct{}

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

type Peer ¶

type Peer struct {
	NodeID      string
	ServiceType string
	Address     string
	Metadata    map[string]string
	LastSeen    time.Time
}

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.

type PeerInfo ¶

type PeerInfo struct {
	NodeID      string
	ServiceType string
	// TLSCertSubject is the Subject CN of the mTLS peer cert, when
	// the listener was configured with TLS. Empty under plaintext
	// (local-dev) transport.
	TLSCertSubject string
	// TLSCertSANs are the Subject Alternative Names from the peer
	// cert. Authorisation should prefer SANs over the legacy CN.
	TLSCertSANs []string
}

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

type PeerVerifier ¶

type PeerVerifier interface {
	// Verify returns nil on accept, ErrPeerUnauthorized (or wrapping
	// error) on reject. Implementations MUST NOT block — refer to
	// pre-built decision tables, not network calls.
	Verify(ctx context.Context, peer PeerInfo, procedure string) error
}

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.

type Picker ¶

type Picker interface {
	// Pick returns the chosen peer. ErrNoPeers if peers is empty.
	Pick(peers []Peer) (Peer, error)
}

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.

type ProcedureHandler ¶

type ProcedureHandler func(ctx context.Context, peer PeerInfo, req *zap.Message) (*zap.Message, error)

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.

type RoundRobinPicker ¶

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

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

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

type Server ¶

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

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) NodeID() string

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

func (s *Server) Start() error

func (s *Server) Stop()

type ServerOption ¶

type ServerOption func(*ServerOptions)

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 WithServerTLS(cfg *tls.Config) ServerOption

func WithVerifier(v PeerVerifier) ServerOption

type ServerOptions ¶

type ServerOptions struct {
	NodeID   string
	Port     int
	TLS      *tls.Config
	Verifier PeerVerifier
	Logger   *slog.Logger
	// Metadata is the mDNS TXT-record metadata advertised to peers.
	Metadata map[string]string
	// NoDiscovery disables mDNS advertisement entirely. Use for
	// stdio / unix-socket tests.
	NoDiscovery bool
}

ServerOptions configure NewServer.