sdk

Documentation

Index

• type BusinessError
  • func (e *BusinessError) Error() string
• type Config
• type Handler
• type HandlerFunc
• type Node
  • func New(cfg Config) (*Node, error)
  • func (c *Node) Call(serviceName, method string, payload []byte) (*Response, error)
  • func (c *Node) CallContext(ctx context.Context, serviceName, method string, payload []byte) (*Response, error)
  • func (c *Node) CallWithData(serviceName, method string, payload []byte) (*Response, error)
  • func (c *Node) CallWithDataContext(ctx context.Context, serviceName, method string, payload []byte) (*Response, error)
  • func (c *Node) Close() error
  • func (c *Node) Handle(method string, handler Handler)
  • func (c *Node) HandleFunc(method string, fn func(req *Request) (*Response, error))
  • func (c *Node) Serve(ctx context.Context) error
• type Request
• type Response

Types

type BusinessError

type BusinessError struct {
	Message string
}

BusinessError wraps errors returned by the remote handler (not transport failures).

func (*BusinessError) Error

func (e *BusinessError) Error() string

type Config

type Config struct {
	// Name is the service name to register.
	Name string
	// ID is the unique instance id; defaults to Name.
	ID string
	// Capabilities lists discovery capability tags.
	Capabilities []string
	// UDSAddr is the service UDS listen address.
	UDSAddr string
	// TCPAddr is the service TCP listen address.
	TCPAddr string
	// NoisePrivateKey is the optional 32-byte Noise static private key for TCP.
	NoisePrivateKey []byte
	// NoisePublicKey is the optional 32-byte Noise static public key for TCP.
	NoisePublicKey []byte
	// TrustedNoiseKeys limits accepted remote Noise server public keys (hex-encoded).
	// When empty, all authenticated Noise peers are accepted.
	TrustedNoiseKeys []string
	// Network controls exposure mode such as uds, tcp, or dual.
	Network string
	// AllowInsecureTCP permits non-loopback plaintext TCP calls.
	AllowInsecureTCP bool
	// RequestTimeout bounds a single outbound call.
	RequestTimeout time.Duration
	// ServeTimeout bounds server-side request handling per connection cycle.
	ServeTimeout time.Duration
	// LargePayloadThreshold enables fd path for payloads at or above this size.
	LargePayloadThreshold int
	// CallRetries is the number of retry attempts for outbound calls.
	CallRetries int
	// RetryBackoff is the delay between retries.
	RetryBackoff time.Duration
	// RegisterRetries is the number of registration attempts before Serve fails.
	RegisterRetries int
	// MaxInboundConns bounds concurrently served inbound connections.
	MaxInboundConns int
	// Registry is the service registry backend.
	Registry *registry.Registry
	// RegistryAddr points to daemon control socket for cross-process discovery.
	// When set and Registry is nil, SDK uses remote registry over this socket.
	RegistryAddr string
	// Router is the transport router used for outbound dials.
	// Serve/listen paths use built-in UDS/TCP transports based on Network.
	Router *transport.Router
	// Logger receives SDK logs.
	Logger *slog.Logger
	// AuthFunc is an optional hook called before dispatching each request.
	// Return a non-nil error to reject the request.
	// When nil, all requests are accepted (default: no auth).
	AuthFunc func(req *Request) error
}

Config controls SDK node behavior.

type Handler

type Handler func(*Request) (*Response, error)

Handler handles one rpc invocation.

type HandlerFunc

type HandlerFunc = Handler

HandlerFunc is an adapter alias to allow ordinary functions as handlers.

type Node

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

Node provides service registration, serving, and rpc invocation.

func New

func New(cfg Config) (*Node, error)

New creates a new SDK node instance.

func (*Node) Call

func (c *Node) Call(serviceName, method string, payload []byte) (*Response, error)

Call invokes a method on one service instance picked by discovery.

func (*Node) CallContext

func (c *Node) CallContext(ctx context.Context, serviceName, method string, payload []byte) (*Response, error)

CallContext invokes a method with caller-provided context for cancellation and deadlines.

func (*Node) CallWithData

func (c *Node) CallWithData(serviceName, method string, payload []byte) (*Response, error)

CallWithData attempts fd-based transfer on local UDS and falls back to Call.

func (*Node) CallWithDataContext

func (c *Node) CallWithDataContext(ctx context.Context, serviceName, method string, payload []byte) (*Response, error)

CallWithDataContext attempts fd-based transfer with caller-provided context.

func (*Node) Close

func (c *Node) Close() error

Close unregisters this instance and closes server listener.

func (*Node) Handle

func (c *Node) Handle(method string, handler Handler)

Handle registers a handler for one method.

func (*Node) HandleFunc

func (c *Node) HandleFunc(method string, fn func(req *Request) (*Response, error))

HandleFunc registers a handler function for the given method. It is a convenience wrapper around Handle that accepts a plain function instead of requiring a Handler type conversion at call sites.

func (*Node) Serve

func (c *Node) Serve(ctx context.Context) error

Serve starts serving requests from configured endpoint.

type Request

type Request struct {
	// Method is the invoked method name.
	Method string
	// Payload is the request body.
	Payload []byte
	// Headers contains optional request metadata.
	Headers map[string]string
}

Request represents an incoming method invocation.

type Response

type Response struct {
	// Payload is the response body.
	Payload []byte
	// Headers contains optional response metadata.
	Headers map[string]string
}

Response represents handler output.