runtime

Documentation

Overview

Package runtime is the stdlib-only service runtime library.

Index

• type Code
  • func CodeOf(err error) Code
• type Config
• type Error
  • func AlreadyExists(format string, args ...any) *Error
  • func As(err error) (*Error, bool)
  • func Internal(format string, args ...any) *Error
  • func InvalidArgument(format string, args ...any) *Error
  • func NotFound(format string, args ...any) *Error
  • func PermissionDenied(format string, args ...any) *Error
  • func Unavailable(format string, args ...any) *Error
  • func Wrap(code Code, cause error, format string, args ...any) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type Interceptor
  • func Chain(interceptors ...Interceptor) Interceptor
  • func LoggingInterceptor(logger *slog.Logger) Interceptor
• type Invoker
• type Server
  • func New(cfg Config, transports ...Transport) *Server
  • func (s *Server) Run(ctx context.Context) error
• type Transport

Types

type Code

type Code string

Code is a wire-stable error code carried in the error envelope.

const (
	CodeNotFound         Code = "not_found"
	CodeInvalidArgument  Code = "invalid_argument"
	CodeAlreadyExists    Code = "already_exists"
	CodePermissionDenied Code = "permission_denied"
	CodeInternal         Code = "internal"
	CodeUnavailable      Code = "unavailable"
)

func CodeOf

func CodeOf(err error) Code

CodeOf returns the Code of err if it is or wraps a *Error; otherwise it returns CodeInternal (matching how the HTTP transport treats unclassified errors).

type Config

type Config struct {
	// ShutdownTimeout bounds how long Run waits for transports to drain
	// after the run context is canceled or a transport fails fatally.
	// Zero means defaultShutdownTimeout (applied by New).
	ShutdownTimeout time.Duration

	// Logger receives lifecycle events. Nil means slog.Default() (applied
	// by New).
	Logger *slog.Logger
}

Config configures a Server's lifecycle.

type Error

type Error struct {
	Code    Code
	Message string
	// contains filtered or unexported fields
}

Error is the runtime error type returned by generated handlers and decoded by generated clients. Code and Message are serialized on the wire; err is unexported and never serialized — it exists only to preserve the causal chain for errors.Is/errors.As on the server side.

func AlreadyExists

func AlreadyExists(format string, args ...any) *Error

AlreadyExists builds an Error with CodeAlreadyExists.

func As

func As(err error) (*Error, bool)

As reports whether err is or wraps a *Error, returning it.

func Internal

func Internal(format string, args ...any) *Error

Internal builds an Error with CodeInternal.

func InvalidArgument

func InvalidArgument(format string, args ...any) *Error

InvalidArgument builds an Error with CodeInvalidArgument.

func NotFound

func NotFound(format string, args ...any) *Error

NotFound builds an Error with CodeNotFound.

func PermissionDenied

func PermissionDenied(format string, args ...any) *Error

PermissionDenied builds an Error with CodePermissionDenied.

func Unavailable

func Unavailable(format string, args ...any) *Error

Unavailable builds an Error with CodeUnavailable.

func Wrap

func Wrap(code Code, cause error, format string, args ...any) *Error

Wrap builds an Error with the given code and message, preserving cause for errors.Is/errors.As. The cause is never included in Error()'s output.

func (*Error) Error

func (e *Error) Error() string

Error returns the message. It never includes the wrapped cause.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap exposes the wrapped cause, if any, for errors.Is/errors.As.

type Interceptor

type Interceptor func(next Invoker) Invoker

Interceptor wraps an Invoker to add cross-cutting behavior (logging, auth, tracing, etc.) around the call it wraps.

func Chain

func Chain(interceptors ...Interceptor) Interceptor

Chain composes interceptors into a single Interceptor. The first interceptor passed is the outermost: its code before calling next runs first, and its code after calling next runs last. Chain() with no interceptors returns a pass-through Interceptor.

func LoggingInterceptor

func LoggingInterceptor(logger *slog.Logger) Interceptor

LoggingInterceptor returns an Interceptor that emits exactly one structured log record per call, containing the RPC method, its duration, and (when present) the error it returned. The wrapped call's response and error are returned unchanged.

type Invoker

type Invoker func(ctx context.Context, method string, req any) (any, error)

Invoker is a single call in a transport-agnostic RPC pipeline. method identifies the target as "Service.Method", e.g. "Orders.GetOrder".

type Server

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

Server hosts one or more Transports and coordinates their lifecycle: starting them concurrently, watching for OS interrupt signals or a fatal transport error, and draining every transport gracefully on shutdown.

func New

func New(cfg Config, transports ...Transport) *Server

New builds a Server for the given transports. Zero-value fields in cfg are replaced by defaults: ShutdownTimeout defaults to 15s, Logger defaults to slog.Default().

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts every transport in its own goroutine and blocks until ctx is canceled, an OS interrupt/SIGTERM signal is received, or any transport's Start returns a fatal (non-nil) error. It then drains all transports within cfg.ShutdownTimeout and returns the first fatal error encountered, or nil on clean shutdown.

type Transport

type Transport interface {
	// Name identifies the transport for logging.
	Name() string

	// Start blocks until ctx is canceled or a fatal error occurs. A clean
	// stop (ctx canceled, Shutdown called) returns nil; any non-nil return
	// is treated as a fatal error that triggers shutdown of all
	// transports.
	Start(ctx context.Context) error

	// Shutdown drains the transport gracefully, respecting ctx's deadline.
	Shutdown(ctx context.Context) error
}

Transport hosts a service over a specific protocol (e.g. HTTP, gRPC). A Server coordinates the lifecycle of one or more Transports.