jsonrpc

Documentation

Index

• Constants
• func Mount(target route.Target, server *Server, options ...MountOption)
• func Provider(server *Server, options ...Option) runaprovider.Provider
• type Config
• type Context
  • func (ctx *Context) Context() context.Context
  • func (ctx *Context) Method() string
  • func (ctx *Context) Request() Request
  • func (ctx *Context) Scope() *scope.Scope
  • func (ctx *Context) Server() *Server
  • func (ctx *Context) SetContext(value context.Context)
  • func (ctx *Context) Transport() string
• type Error
  • func (err *Error) Error() string
• type Handler
• type ID
• type Middleware
• type MountConfig
• type MountOption
  • func WebSocket(path string, options ...WSOption) MountOption
• type Option
  • func Path(value string) Option
  • func WSPath(value string, options ...WSOption) Option
• type Registry
  • func (registry *Registry) Add(servers ...*Server)
  • func (registry *Registry) Servers() []*Server
• type Request
• type Response
  • func (response Response) MarshalJSON() ([]byte, error)
• type Server
  • func Method[Input any, Output any](server *Server, name string, handler TypedHandler[Input, Output]) *Server
  • func New() *Server
  • func (server *Server) Call(ctx context.Context, method string, params any) (any, error)
  • func (server *Server) HTTP() route.Handler
  • func (server *Server) Register(name string, handler Handler) *Server
  • func (server *Server) Use(middlewares ...Middleware) *Server
  • func (server *Server) WS(options ...WSOption) route.Handler
• type TypedHandler
• type WSConfig
• type WSOption
  • func MaxMessageSize(value int64) WSOption
  • func Origin(patterns ...string) WSOption
  • func ReadTimeout(value time.Duration) WSOption
  • func WriteTimeout(value time.Duration) WSOption

Constants

const (
	CodeParseError     = -32700
	CodeInvalidRequest = -32600
	CodeMethodNotFound = -32601
	CodeInvalidParams  = -32602
	CodeInternalError  = -32603
)

Functions

func Mount

func Mount(target route.Target, server *Server, options ...MountOption)

Mount mounts a JSON-RPC server on a route target.

func Provider

func Provider(server *Server, options ...Option) runaprovider.Provider

Provider mounts JSON-RPC HTTP and optional WebSocket endpoints.

Types

type Config

type Config struct {
	Path      string     `toml:"path"`
	WSPath    string     `toml:"ws_path"`
	WSOptions []WSOption `toml:"-"`
}

Config configures JSON-RPC route mounting.

type Context

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

Context stores one JSON-RPC call context.

func (*Context) Context

func (ctx *Context) Context() context.Context

Context returns the underlying context.

func (*Context) Method

func (ctx *Context) Method() string

Method returns the current method name.

func (*Context) Request

func (ctx *Context) Request() Request

Request returns the current JSON-RPC request object.

func (*Context) Scope

func (ctx *Context) Scope() *scope.Scope

Scope returns the current call scope.

func (*Context) Server

func (ctx *Context) Server() *Server

Server returns the current JSON-RPC server.

func (*Context) SetContext

func (ctx *Context) SetContext(value context.Context)

SetContext replaces the current call context.

func (*Context) Transport

func (ctx *Context) Transport() string

Transport returns the current call transport.

type Error

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

Error is a JSON-RPC 2.0 error object.

func (*Error) Error

func (err *Error) Error() string

type Handler

type Handler func(*Context) (any, error)

Handler handles one JSON-RPC method call.

type ID

type ID = json.RawMessage

ID is a JSON-RPC request identifier.

type Middleware

type Middleware func(Handler) Handler

Middleware wraps JSON-RPC method execution.

type MountConfig

type MountConfig struct {
	WSPath    string
	WSOptions []WSOption
}

MountConfig configures JSON-RPC mounting on a route target.

type MountOption

type MountOption func(*MountConfig)

MountOption configures JSON-RPC route mounting.

func WebSocket

func WebSocket(path string, options ...WSOption) MountOption

WebSocket mounts a JSON-RPC WebSocket endpoint under target.

type Option

type Option func(*Config)

Option configures the JSON-RPC provider.

func Path

func Path(value string) Option

Path sets the HTTP JSON-RPC endpoint.

func WSPath

func WSPath(value string, options ...WSOption) Option

WSPath sets the WebSocket JSON-RPC endpoint.

type Registry

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

Registry stores app-scoped JSON-RPC servers.

func (*Registry) Add

func (registry *Registry) Add(servers ...*Server)

func (*Registry) Servers

func (registry *Registry) Servers() []*Server

type Request

type Request struct {
	Version string          `json:"jsonrpc,omitempty"`
	Method  string          `json:"method,omitempty"`
	Params  json.RawMessage `json:"params,omitempty"`
	ID      ID              `json:"id,omitempty"`
}

Request is a JSON-RPC 2.0 request object.

type Response

type Response struct {
	Version string `json:"jsonrpc"`
	Result  any    `json:"-"`
	Error   *Error `json:"error,omitempty"`
	ID      ID     `json:"id"`
}

Response is a JSON-RPC 2.0 response object.

func (Response) MarshalJSON

func (response Response) MarshalJSON() ([]byte, error)

type Server

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

Server stores JSON-RPC methods.

func Method

func Method[Input any, Output any](server *Server, name string, handler TypedHandler[Input, Output]) *Server

Method registers a typed JSON-RPC method.

func New

func New() *Server

New creates a JSON-RPC server.

func (*Server) Call

func (server *Server) Call(ctx context.Context, method string, params any) (any, error)

Call calls one method directly.

func (*Server) HTTP

func (server *Server) HTTP() route.Handler

HTTP returns a Runa handler that serves JSON-RPC 2.0 over HTTP POST.

func (*Server) Register

func (server *Server) Register(name string, handler Handler) *Server

Register registers a method handler.

func (*Server) Use

func (server *Server) Use(middlewares ...Middleware) *Server

Use adds JSON-RPC method middleware.

func (*Server) WS

func (server *Server) WS(options ...WSOption) route.Handler

WS returns a Runa handler that serves JSON-RPC 2.0 over WebSocket.

type TypedHandler

type TypedHandler[Input any, Output any] func(*Context, *Input) (*Output, error)

TypedHandler handles a typed JSON-RPC method call.

type WSConfig

type WSConfig struct {
	Origin         []string
	MaxMessageSize int64
	ReadTimeout    time.Duration
	WriteTimeout   time.Duration
}

WSConfig configures JSON-RPC over WebSocket.

type WSOption

type WSOption func(*WSConfig)

WSOption configures JSON-RPC WebSocket transport.

func MaxMessageSize

func MaxMessageSize(value int64) WSOption

MaxMessageSize sets max WebSocket message size.

func Origin

func Origin(patterns ...string) WSOption

Origin sets accepted WebSocket origins.

func ReadTimeout

func ReadTimeout(value time.Duration) WSOption

ReadTimeout sets WebSocket read timeout.

func WriteTimeout

func WriteTimeout(value time.Duration) WSOption

WriteTimeout sets WebSocket write timeout.