rpc

package
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 10, 2026 License: MIT Imports: 8 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	HandlerKindExecute = "execute"
	HandlerKindQuery   = "query"
)

Variables

This section is empty.

Functions

func Resolver 

func Resolver(server *Server) command.Resolver

Resolver returns a command.Resolver that registers endpoint providers into this server.

Types

type Endpoint 

type Endpoint struct {
	Method       string        `json:"method"`
	MessageType  string        `json:"messageType"`
	HandlerKind  string        `json:"handlerKind"`
	RequestType  *TypeRef      `json:"requestType,omitempty"`
	ResponseType *TypeRef      `json:"responseType,omitempty"`
	Timeout      time.Duration `json:"timeout"`
	Streaming    bool          `json:"streaming"`
	Idempotent   bool          `json:"idempotent"`
	Permissions  []string      `json:"permissions,omitempty"`
	Roles        []string      `json:"roles,omitempty"`
	Summary      string        `json:"summary,omitempty"`
	Description  string        `json:"description,omitempty"`
	Tags         []string      `json:"tags,omitempty"`
	Deprecated   bool          `json:"deprecated,omitempty"`
	Since        string        `json:"since,omitempty"`
}

Endpoint describes a registered RPC method.

type EndpointDefinition 

type EndpointDefinition interface {
	Spec() EndpointSpec
	NewRequest() any
	RequestType() reflect.Type
	ResponseType() reflect.Type
	Invoke(context.Context, any) (any, error)
}

EndpointDefinition is the explicit endpoint contract registered in the RPC server.

func NewEndpoint 

func NewEndpoint[Req any, Res any](
	spec EndpointSpec,
	handler func(context.Context, RequestEnvelope[Req]) (ResponseEnvelope[Res], error),
) EndpointDefinition

NewEndpoint builds an explicit typed endpoint definition.

type EndpointSpec 

type EndpointSpec struct {
	Method      string
	MessageType string
	Kind        MethodKind
	Timeout     time.Duration
	Streaming   bool
	Idempotent  bool
	Permissions []string
	Roles       []string
	Summary     string
	Description string
	Tags        []string
	Deprecated  bool
	Since       string
}

EndpointSpec declares endpoint metadata independent from handler implementation details.

type EndpointsProvider 

type EndpointsProvider interface {
	RPCEndpoints() []EndpointDefinition
}

EndpointsProvider can expose one or more endpoint definitions for resolver registration.

type Error 

type Error struct {
	Code      string         `json:"code"`
	Message   string         `json:"message"`
	Category  string         `json:"category,omitempty"`
	Retryable bool           `json:"retryable,omitempty"`
	Details   map[string]any `json:"details,omitempty"`
}

Error is a transport-friendly error envelope.

type FailureEvent 

type FailureEvent struct {
	Stage  FailureStage
	Method string
	Err    error
	Panic  any
}

FailureEvent carries context for strategy/logging decisions.

type FailureLogger 

type FailureLogger func(FailureEvent)

FailureLogger receives failure events when configured.

type FailureMode 

type FailureMode int

FailureMode controls how the server reacts to registration/invocation failures. 

const (
	// FailureModeReject returns registration errors and re-panics invoke panics.
	FailureModeReject FailureMode = iota
	// FailureModeRecover returns registration errors and converts invoke panics to errors.
	FailureModeRecover
	// FailureModeLogAndContinue suppresses failures after logging them.
	// For register, the endpoint is skipped. For invoke panic, call returns an error.
	FailureModeLogAndContinue
)

type FailureStage 

type FailureStage string

FailureStage identifies where a failure happened. 

const (
	FailureStageRegister FailureStage = "register"
	FailureStageInvoke   FailureStage = "invoke"
)

type FailureStrategy 

type FailureStrategy func(FailureEvent) FailureMode

FailureStrategy decides how to handle a failure event.

type InvokeHandler added in v0.16.1 

type InvokeHandler func(context.Context, InvokeRequest) (any, error)

InvokeHandler executes one RPC invoke step in a middleware chain.

type InvokeRequest added in v0.16.1 

type InvokeRequest struct {
	Method   string
	Endpoint Endpoint
	Payload  any
}

InvokeRequest carries method metadata and payload through middleware.

type MethodKind 

type MethodKind string

MethodKind describes endpoint invocation shape. 

const (
	MethodKindCommand MethodKind = HandlerKindExecute
	MethodKindQuery   MethodKind = HandlerKindQuery
)

type Middleware added in v0.16.1 

type Middleware func(next InvokeHandler) InvokeHandler

Middleware wraps invoke execution with cross-cutting behavior.

type Option 

type Option func(*Server)

Option customizes server behavior.

func WithFailureLogger 

func WithFailureLogger(logger FailureLogger) Option

WithFailureLogger sets an optional callback for failure events.

func WithFailureMode 

func WithFailureMode(mode FailureMode) Option

WithFailureMode sets a fixed strategy mode.

func WithFailureStrategy 

func WithFailureStrategy(strategy FailureStrategy) Option

WithFailureStrategy sets a custom failure strategy function.

func WithMiddleware added in v0.16.1 

func WithMiddleware(mw ...Middleware) Option

WithMiddleware appends invoke middleware in registration order.

type RequestEnvelope 

type RequestEnvelope[T any] struct {
	Data T           `json:"data"`
	Meta RequestMeta `json:"meta,omitempty"`
}

RequestEnvelope is the canonical method request shape for transport adapters.

type RequestMeta 

type RequestMeta struct {
	ActorID       string              `json:"actorId,omitempty"`
	Roles         []string            `json:"roles,omitempty"`
	Tenant        string              `json:"tenant,omitempty"`
	RequestID     string              `json:"requestId,omitempty"`
	CorrelationID string              `json:"correlationId,omitempty"`
	Permissions   []string            `json:"permissions,omitempty"`
	Scope         map[string]any      `json:"scope,omitempty"`
	Headers       map[string]string   `json:"headers,omitempty"`
	Params        map[string]string   `json:"params,omitempty"`
	Query         map[string][]string `json:"query,omitempty"`
}

RequestMeta carries method-agnostic execution metadata.

type ResponseEnvelope 

type ResponseEnvelope[T any] struct {
	Data  T      `json:"data,omitempty"`
	Error *Error `json:"error,omitempty"`
}

ResponseEnvelope is the canonical method response shape for transport adapters.

type Server 

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

Server provides a lightweight in memory RPC method registry and invoker. Transport adapters can use this server to register and invoke command/query handlers.

func NewServer 

func NewServer(opts ...Option) *Server

NewServer creates an empty RPC server registry.

func (*Server) Endpoint 

func (s *Server) Endpoint(method string) (Endpoint, bool)

Endpoint returns endpoint metadata for the method.

func (*Server) EndpointMeta 

func (s *Server) EndpointMeta(method string) (Endpoint, bool)

EndpointMeta returns enriched endpoint metadata for the method.

func (*Server) Endpoints 

func (s *Server) Endpoints() []Endpoint

Endpoints returns all endpoint metadata sorted by method.

func (*Server) EndpointsMeta 

func (s *Server) EndpointsMeta() []Endpoint

EndpointsMeta returns enriched metadata for all endpoints sorted by method.

func (*Server) Invoke 

func (s *Server) Invoke(ctx context.Context, method string, payload any) (any, error)

Invoke executes a registered RPC method using the provided payload. payload should already be transport-decoded into the expected message type.

func (*Server) NewMessageForMethod 

func (s *Server) NewMessageForMethod(method string) (any, error)

NewMessageForMethod creates a zero-value message instance for transport decoding.

func (*Server) NewRequestForMethod 

func (s *Server) NewRequestForMethod(method string) (any, error)

NewRequestForMethod creates a zero-value request envelope instance for transport decoding.

func (*Server) RegisterEndpoint 

func (s *Server) RegisterEndpoint(def EndpointDefinition) error

RegisterEndpoint stores an explicit endpoint definition.

func (*Server) RegisterEndpoints 

func (s *Server) RegisterEndpoints(defs ...EndpointDefinition) error

RegisterEndpoints stores explicit endpoint definitions in registration order.

type TypeRef 

type TypeRef struct {
	GoType  string `json:"goType"`
	PkgPath string `json:"pkgPath,omitempty"`
	Name    string `json:"name,omitempty"`
	Kind    string `json:"kind,omitempty"`
	Pointer bool   `json:"pointer,omitempty"`
}

TypeRef describes a Go type in endpoint metadata for codegen/doc discovery.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.