trpc

Documentation

Overview

Package trpc provides RPC functionality over HTTP.

Index

• Constants
• Variables
• func Sleep(ctx context.Context, d time.Duration)
• type AuthContext
• type AuthFunc
• type BatchCall
• type EventEmitter
  • func NewEventEmitter() *EventEmitter
  • func (ee *EventEmitter) Emit(event string, data any)
  • func (ee *EventEmitter) On(event string, ctx context.Context) <-chan any
• type HTTPError
  • func (e *HTTPError) Error() string
• type Procedure
  • func NewProcedure(handler func(context.Context, any) (any, error)) *Procedure
• type StreamHandler
• type StreamMessage
• type StreamProcedure
  • func NewStreamProcedure(handler StreamHandler) *StreamProcedure
• type Subscription
  • func NewSubscription(handler SubscriptionHandler) *Subscription
• type SubscriptionHandler
• type SubscriptionInput
• type SubscriptionOptions
• type TrackedEvent
  • func Tracked(id string, data any) TrackedEvent
• type TrpcClient
  • func NewTrpcClient(baseURL string) *TrpcClient
  • func (c *TrpcClient) Call(ctx context.Context, procedure string, input, output any) error
  • func (c *TrpcClient) CallBatch(ctx context.Context, calls []BatchCall) error
• type TrpcServer
  • func NewTrpcServer() *TrpcServer
  • func (s *TrpcServer) GetProcedure(path string) (*Procedure, bool)
  • func (s *TrpcServer) GetStreamProcedure(path string) (*StreamProcedure, bool)
  • func (s *TrpcServer) GetSubscription(path string) (*Subscription, bool)
  • func (s *TrpcServer) HandleSSE(responseWriter http.ResponseWriter, request *http.Request, path string)
  • func (s *TrpcServer) HandleWebSocket(responseWriter http.ResponseWriter, request *http.Request, path string)
  • func (s *TrpcServer) ListProcedures() []string
  • func (s *TrpcServer) RegisterProcedure(path string, procedure *Procedure)
  • func (s *TrpcServer) RegisterStreamProcedure(path string, procedure *StreamProcedure)
  • func (s *TrpcServer) RegisterSubscription(path string, subscription *Subscription)
  • func (s *TrpcServer) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *TrpcServer) Start(addr string) error
  • func (s *TrpcServer) StartTLS(addr, certFile, keyFile string) error
  • func (s *TrpcServer) Stop(ctx context.Context) error
  • func (s *TrpcServer) WithAuth(authFunc AuthFunc) *TrpcServer

Constants

const (
	DefaultBasePath = "/trpc"
	DefaultTimeout  = 30 * time.Second
	DefaultBodySize = 1024 * 1024
)

Variables

var (
	ErrInvalidContentType   = errors.New("invalid content type")
	ErrInvalidMethod        = errors.New("invalid method")
	ErrMissingProcedure     = errors.New("missing procedure")
	ErrProcedureNotFound    = errors.New("procedure not found")
	ErrAuthenticationFailed = errors.New("authentication failed")
	ErrInvalidToken         = errors.New("invalid token")
	ErrRequestFailed        = errors.New("request failed")
	ErrResponseParseFailed  = errors.New("parse failed")
	ErrServerError          = errors.New("server error")
	ErrBatchCallsEmpty      = errors.New("batch calls cannot be empty")
	ErrMissingResponse      = errors.New("missing response for call")
	ErrBatchCallFailed      = errors.New("batch call failed")
	ErrMissingResult        = errors.New("missing result for call")
)

Functions

func Sleep

func Sleep(ctx context.Context, d time.Duration)

Sleep helper for polling subscriptions.

Types

type AuthContext

type AuthContext struct {
	ProcedureName string
	Request       *http.Request
	AuthHeader    string
	Cookies       map[string]string
}

type AuthFunc

type AuthFunc func(ctx context.Context, authCtx *AuthContext) error

type BatchCall

type BatchCall struct {
	Procedure string
	Input     any
	Output    any
}

type EventEmitter

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

EventEmitter provides a simple event emitter for subscriptions.

func NewEventEmitter

func NewEventEmitter() *EventEmitter

NewEventEmitter creates a new event emitter.

func (*EventEmitter) Emit

func (ee *EventEmitter) Emit(event string, data any)

Emit sends an event to all listeners.

func (*EventEmitter) On

func (ee *EventEmitter) On(event string, ctx context.Context) <-chan any

On registers a listener for an event.

type HTTPError

type HTTPError struct {
	StatusCode int
	Message    string
}

func (*HTTPError) Error

func (e *HTTPError) Error() string

type Procedure

type Procedure struct {
	Handler      func(context.Context, any) (any, error)
	Input        reflect.Type
	Output       reflect.Type
	AuthRequired bool
	AuthFunc     AuthFunc
}

func NewProcedure

func NewProcedure(handler func(context.Context, any) (any, error)) *Procedure

type StreamHandler

type StreamHandler func(ctx context.Context, input any, send func(msg StreamMessage) error) error

type StreamMessage

type StreamMessage struct {
	Data  any       `json:"data"`
	Event string    `json:"event,omitempty"`
	ID    string    `json:"id,omitempty"`
	Time  time.Time `json:"time"`
}

type StreamProcedure

type StreamProcedure struct {
	Handler      StreamHandler
	AuthRequired bool
	AuthFunc     AuthFunc
}

func NewStreamProcedure

func NewStreamProcedure(handler StreamHandler) *StreamProcedure

type Subscription

type Subscription struct {
	Handler      SubscriptionHandler
	AuthRequired bool
	AuthFunc     AuthFunc
}

Subscription represents a tRPC-style subscription procedure.

func NewSubscription

func NewSubscription(handler SubscriptionHandler) *Subscription

NewSubscription creates a new subscription procedure.

type SubscriptionHandler

type SubscriptionHandler func(opts SubscriptionOptions) <-chan any

SubscriptionHandler is an async generator function that yields events This matches tRPC's subscription pattern: async function* (opts).

type SubscriptionInput

type SubscriptionInput struct {
	LastEventID string         `json:"lastEventId,omitempty"`
	Input       map[string]any `json:"input,omitempty"`
}

SubscriptionInput represents the input to a subscription with lastEventId support.

type SubscriptionOptions

type SubscriptionOptions struct {
	Context context.Context //nolint:containedctx // Intentional: matches tRPC subscription pattern
	Signal  context.Context //nolint:containedctx // Intentional: AbortSignal equivalent
	Input   SubscriptionInput
}

SubscriptionOptions provides context and signal for subscriptions.

type TrackedEvent

type TrackedEvent struct {
	ID   string `json:"id"`
	Data any    `json:"data"`
}

TrackedEvent represents an event with an ID for tracking and resumption.

func Tracked

func Tracked(id string, data any) TrackedEvent

Tracked creates a tracked event with ID for client resumption This matches tRPC's tracked() helper.

type TrpcClient

type TrpcClient struct {
	BaseURL    string
	HTTPClient *http.Client
	Headers    map[string]string
	AuthToken  string
	MaxRetries int
	RetryDelay time.Duration
}

func NewTrpcClient

func NewTrpcClient(baseURL string) *TrpcClient

func (*TrpcClient) Call

func (c *TrpcClient) Call(ctx context.Context, procedure string, input, output any) error

func (*TrpcClient) CallBatch

func (c *TrpcClient) CallBatch(ctx context.Context, calls []BatchCall) error

type TrpcServer

type TrpcServer struct {
	BasePath         string
	Middleware       []func(http.Handler) http.Handler
	Timeout          time.Duration
	MaxBodySize      int64
	Procedures       map[string]*Procedure
	StreamProcedures map[string]*StreamProcedure
	Subscriptions    map[string]*Subscription
	AuthHandler      AuthFunc
	// contains filtered or unexported fields
}

func NewTrpcServer

func NewTrpcServer() *TrpcServer

func (*TrpcServer) GetProcedure

func (s *TrpcServer) GetProcedure(path string) (*Procedure, bool)

func (*TrpcServer) GetStreamProcedure

func (s *TrpcServer) GetStreamProcedure(path string) (*StreamProcedure, bool)

func (*TrpcServer) GetSubscription

func (s *TrpcServer) GetSubscription(path string) (*Subscription, bool)

GetSubscription retrieves a subscription procedure.

func (*TrpcServer) HandleSSE

func (s *TrpcServer) HandleSSE(
	responseWriter http.ResponseWriter,
	request *http.Request,
	path string,
)

func (*TrpcServer) HandleWebSocket

func (s *TrpcServer) HandleWebSocket(
	responseWriter http.ResponseWriter,
	request *http.Request,
	path string,
)

func (*TrpcServer) ListProcedures

func (s *TrpcServer) ListProcedures() []string

func (*TrpcServer) RegisterProcedure

func (s *TrpcServer) RegisterProcedure(path string, procedure *Procedure)

func (*TrpcServer) RegisterStreamProcedure

func (s *TrpcServer) RegisterStreamProcedure(path string, procedure *StreamProcedure)

func (*TrpcServer) RegisterSubscription

func (s *TrpcServer) RegisterSubscription(path string, subscription *Subscription)

RegisterSubscription registers a subscription procedure.

func (*TrpcServer) ServeHTTP

func (s *TrpcServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*TrpcServer) Start

func (s *TrpcServer) Start(addr string) error

func (*TrpcServer) StartTLS

func (s *TrpcServer) StartTLS(addr, certFile, keyFile string) error

func (*TrpcServer) Stop

func (s *TrpcServer) Stop(ctx context.Context) error

func (*TrpcServer) WithAuth

func (s *TrpcServer) WithAuth(authFunc AuthFunc) *TrpcServer