trpc

Documentation

Overview

Package trpc provides an HTTP handler that serves trpcgo procedures using the tRPC wire format. Use NewHandler to create an http.Handler from a trpcgo.Router.

Index

• type CORSConfig
• type Handler
  • func NewHandler(r *trpcgo.Router, basePath string, opts ...HandlerOption) *Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandlerOption
  • func WithCORS(config CORSConfig) HandlerOption
  • func WithCSRFProtection(enabled bool) HandlerOption
  • func WithCSRFRequireOrigin(enabled bool) HandlerOption
  • func WithContentTypeEnforcement(enabled bool) HandlerOption
  • func WithPublicOrigin(origin string) HandlerOption
  • func WithPublicOrigins(origins ...string) HandlerOption
  • func WithSubscriptionOriginCheck(enabled bool) HandlerOption
  • func WithTrustedOrigins(origins ...string) HandlerOption

Types

type CORSConfig

type CORSConfig struct {
	// AllowedOrigins contains exact scheme+host origins such as
	// "https://app.example.com". The wildcard "*" is allowed only for
	// non-credentialed CORS responses and does not grant CSRF trust.
	AllowedOrigins []string
	// AllowedMethods defaults to GET and POST when empty.
	AllowedMethods []string
	// AllowedHeaders defaults to Authorization, Content-Type, Last-Event-Id,
	// and trpc-accept when empty. When set, it replaces that default list.
	AllowedHeaders []string
	// ExposedHeaders lists response headers visible to browser JavaScript.
	ExposedHeaders []string
	// AllowCredentials controls Access-Control-Allow-Credentials. Do not use it
	// with wildcard origins.
	AllowCredentials bool
	// MaxAge controls Access-Control-Max-Age for preflight responses.
	MaxAge time.Duration
}

CORSConfig configures Cross-Origin Resource Sharing for the tRPC handler. CORS is disabled unless WithCORS is supplied. CORS origins control browser read access only; use WithTrustedOrigins for cross-origin POST trust.

type Handler

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

Handler is an http.Handler that serves trpcgo procedures over the tRPC wire protocol. Create one via NewHandler.

func NewHandler

func NewHandler(r *trpcgo.Router, basePath string, opts ...HandlerOption) *Handler

NewHandler creates a tRPC HTTP handler from a trpcgo Router. basePath is the URL prefix stripped before procedure lookup (e.g., "/trpc" means /trpc/user.getById → procedure "user.getById").

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type HandlerOption

type HandlerOption func(*handlerOptions)

HandlerOption configures the HTTP tRPC handler.

func WithCORS

func WithCORS(config CORSConfig) HandlerOption

WithCORS enables CORS for the configured origins. CORS does not grant CSRF trust; use WithTrustedOrigins for cross-origin POSTs. If AllowedHeaders is set, it replaces the default CORS header allow-list.

func WithCSRFProtection

func WithCSRFProtection(enabled bool) HandlerOption

WithCSRFProtection controls the built-in Origin/Referer CSRF protection for POST requests. Protection is enabled by default. Same-origin requests and origins added with WithTrustedOrigins are allowed.

func WithCSRFRequireOrigin

func WithCSRFRequireOrigin(enabled bool) HandlerOption

WithCSRFRequireOrigin controls whether CSRF protection rejects every POST request that lacks both Origin and Referer. By default, missing Origin and Referer are allowed for non-browser API clients, but cookie-bearing POSTs are still rejected when both headers are absent.

func WithContentTypeEnforcement

func WithContentTypeEnforcement(enabled bool) HandlerOption

WithContentTypeEnforcement controls whether POST requests with bodies must use Content-Type: application/json. Charset parameters are accepted and empty-body POST requests are not checked. Enforcement is enabled by default.

func WithPublicOrigin

func WithPublicOrigin(origin string) HandlerOption

WithPublicOrigin adds public origins that should be considered same-origin for CSRF and subscription origin checks. This is useful behind TLS-terminating reverse proxies where the Go server receives internal http requests while browsers use a public https origin. Origins must be exact scheme+host values such as "https://api.example.com".

func WithPublicOrigins

func WithPublicOrigins(origins ...string) HandlerOption

WithPublicOrigins adds public origins that should be considered same-origin for CSRF and subscription origin checks. Invalid origins are ignored.

func WithSubscriptionOriginCheck

func WithSubscriptionOriginCheck(enabled bool) HandlerOption

WithSubscriptionOriginCheck controls an opt-in Origin/Referer check for subscription requests. It targets browser GET/SSE subscriptions, which are not covered by the POST-only CSRF check. When enabled, a subscription request carrying an Origin or Referer must be same-origin, a configured public or trusted origin, or allowed by CORS. Cookie-bearing subscription requests without those headers are rejected; non-cookie requests without those headers are allowed for non-browser clients. Subscriptions sent via POST pass through the normal CSRF check first, which honors same-origin, public, and trusted origins.

func WithTrustedOrigins

func WithTrustedOrigins(origins ...string) HandlerOption

WithTrustedOrigins adds origins that may send cross-origin POST requests. Origins must be exact scheme+host values such as "https://app.example.com". Invalid origins are ignored.