rpc

README

Astral RPC

Basic extension to lib astral. Provides a convenient wrapper for RPC protocol with customizable encoding.

Usage

Implementing and running a service:

package main

import rpc "github.com/cryptopunkscc/go-apphost-jrpc"

type service struct{}

func (s service) Sum(a int, b int) (c int, err error) {
	c = a + b
	return
}

func main() {
	err := rpc.NewApp("simple_calc").Run(service{})
	if err != nil {
		panic(err)   
	}
}

Calling method on the service:

package main

import (
	"github.com/cryptopunkscc/astrald/auth/id"
	rpc "github.com/cryptopunkscc/go-apphost-jrpc"
)

func main() {
	conn, _ := astral.Query(id.Identity{}, "simple_calc")
	r, _ := rpc.Query[int](conn, "sum", 2, 2)
	println(r)
}

See more comprehensive example.

Protocol

The general format of request is a command name followed byt arguments in a know format.

example method:

<method name><arguments>

Clir

The client can request data from Service by sending a method followed by commandline arguments.

methodName 1 true "string arg" -name "object arg"

Json

The client can request data from Service by sending a method followed by positional arguments packed in array.

methodName[1, true, "string arg", {"name": "object arg"}]

The service can respond by sending:

• null if there is nothing to send.
• One error object.
• N amount of JSON objects.

example error:

{"error": "some error message"}

The client can request a list of API methods provided by service by sending reserved method:

["api"]

In response the service should send a JSON array containing method names:

["api", "method1", "method2", "methodN"]

Documentation

Index

• Variables
• func Await(conn Conn) (err error)
• func Call(conn Conn, name string, args ...any) (err error)
• func Command(conn Conn, method string, args ...any) (err error)
• func Decode[R any](conn Conn) (r R, err error)
• func JsonCodecs(rw io.ReadWriter) (e Encoder, d Decoder, m Marshal, u Unmarshal)
• func Query[R any](conn Conn, method string, args ...any) (r R, err error)
• func Subscribe[R any](conn Conn, method string, args ...any) (c <-chan R, err error)
• type App
  • func NewApp(port string) (s *App)
• type ArgsDecoder
  • func NewClirArgsDecoder() ArgsDecoder
  • func NewJsonArgsDecoder() ArgsDecoder
• type ByteScannerReader
  • func NewByteScannerReader(reader io.Reader) ByteScannerReader
• type Caller
  • func NewCaller(name string) (c *Caller)
  • func (c *Caller) Call(args ByteScannerReader) (out []any, err error)
  • func (c *Caller) Decoder(decoders ...ArgsDecoder) *Caller
  • func (c *Caller) Decoders(decoders []ArgsDecoder) *Caller
  • func (c *Caller) Func(function any) *Caller
  • func (c *Caller) With(env ...any) *Caller
• type Codecs
• type Conn
  • func NewRequest(identity id.Identity, service string) Conn
  • func QueryFlow(identity id.Identity, service string) (s Conn, err error)
• type ConnLogger
  • func NewConnLogger(conn io.ReadWriteCloser, logger *log.Logger) *ConnLogger
  • func (cl *ConnLogger) Read(b []byte) (n int, err error)
  • func (cl *ConnLogger) Write(b []byte) (n int, err error)
• type Decoder
• type Encoder
• type Failure
• type Flow
  • func NewFlow(conn io.ReadWriteCloser) *Flow
  • func (conn *Flow) Call(method string, value any) (err error)
  • func (conn *Flow) Copy() Conn
  • func (conn *Flow) Flush()
• type Handlers
• type Marshal
• type Module
  • func NewModule(node node.Node, port string) (r *Module)
  • func (m Module) RouteQuery(ctx context.Context, query net.Query, caller net.SecureWriteCloser, ...) (s net.SecureWriteCloser, err error)
• type Registry
  • func NewRegistry[V any]() *Registry[V]
  • func (n *Registry[V]) Add(str string, v V)
  • func (n *Registry[V]) All() map[string]V
  • func (n *Registry[V]) Get() V
  • func (n *Registry[V]) IsEmpty() bool
  • func (n *Registry[V]) Scan(scanner io.ByteScanner) (rr *Registry[V], err error)
  • func (n *Registry[V]) Unfold(str string) (*Registry[V], string)
• type RemoteIdInfo
• type Request
  • func (r *Request) Call(method string, value any) (err error)
  • func (r *Request) Copy() Conn
  • func (r *Request) Flush()
• type Router
  • func NewRouter(port string) *Router
  • func (r *Router) Authorize(ctx context.Context, query any) bool
  • func (r *Router) Call() (result []any, err error)
  • func (r *Router) Caller(caller *Caller) *Router
  • func (r *Router) Command(cmd string) *Router
  • func (r *Router) Conn(conn io.ReadWriteCloser) *Router
  • func (r *Router) Func(name string, function any) *Router
  • func (r *Router) Handle(ctx context.Context, query any, remoteId id.Identity, conn io.ReadWriteCloser) (err error)
  • func (r *Router) Interface(srv any) *Router
  • func (r *Router) Logger(logger *log.Logger) *Router
  • func (r *Router) Query(query string) *Router
  • func (r *Router) RouteFunc(name string, function any) *Router
  • func (r *Router) Routes(routes ...string) *Router
  • func (r *Router) Run(ctx context.Context) (err error)
  • func (r *Router) With(env ...any) *Router
• type Serializer
  • func (s *Serializer) Codecs(codecs Codecs)
  • func (s *Serializer) Decode(value any) (err error)
  • func (s *Serializer) Encode(value any) (err error)
  • func (s *Serializer) Logger(logger *log.Logger)
  • func (s *Serializer) RemoteIdentity() (i id.Identity)
• type Unmarshal

Variables

var EmptyResponse = struct{}{}

var ErrMalformedRequest = errors.New("malformed request")

var ErrUnauthorized = errors.New("unauthorized")

Functions

func Await

func Await(conn Conn) (err error)

func Call

func Call(conn Conn, name string, args ...any) (err error)

func Command

func Command(conn Conn, method string, args ...any) (err error)

func Decode

func Decode[R any](conn Conn) (r R, err error)

func JsonCodecs

func JsonCodecs(rw io.ReadWriter) (e Encoder, d Decoder, m Marshal, u Unmarshal)

func Query

func Query[R any](conn Conn, method string, args ...any) (r R, err error)

func Subscribe

func Subscribe[R any](conn Conn, method string, args ...any) (c <-chan R, err error)

Types

type App

type App struct {
	Router
}

func NewApp

func NewApp(port string) (s *App)

type ArgsDecoder

type ArgsDecoder interface {
	Test([]byte) bool
	TestScan(scanner io.ByteScanner) bool
	Unmarshal(bytes []byte, args []any) error
	Decode(conn ByteScannerReader, args []any) error
}

func NewClirArgsDecoder

func NewClirArgsDecoder() ArgsDecoder

func NewJsonArgsDecoder

func NewJsonArgsDecoder() ArgsDecoder

type ByteScannerReader

type ByteScannerReader interface {
	io.Reader
	io.ByteScanner
	Append(bytes []byte)
	Clear()
	IsEmpty() bool
	Buffer() []byte
}

func NewByteScannerReader

func NewByteScannerReader(reader io.Reader) ByteScannerReader

type Caller

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

func NewCaller

func NewCaller(name string) (c *Caller)

func (*Caller) Call

func (c *Caller) Call(args ByteScannerReader) (out []any, err error)

func (*Caller) Decoder

func (c *Caller) Decoder(decoders ...ArgsDecoder) *Caller

func (*Caller) Decoders

func (c *Caller) Decoders(decoders []ArgsDecoder) *Caller

func (*Caller) Func

func (c *Caller) Func(function any) *Caller

func (*Caller) With

func (c *Caller) With(env ...any) *Caller

type Codecs

type Codecs func(io.ReadWriter) (Encoder, Decoder, Marshal, Unmarshal)

type Conn

type Conn interface {
	io.WriteCloser
	ByteScannerReader
	Logger(logger *log.Logger)
	Copy() Conn
	Call(method string, value any) (err error)
	Encode(value any) (err error)
	Decode(value any) (err error)
	Flush()
}

func NewRequest

func NewRequest(
	identity id.Identity,
	service string,
) Conn

func QueryFlow

func QueryFlow(identity id.Identity, service string) (s Conn, err error)

type ConnLogger

type ConnLogger struct {
	io.ReadWriteCloser
	*log.Logger
}

func NewConnLogger

func NewConnLogger(conn io.ReadWriteCloser, logger *log.Logger) *ConnLogger

func (*ConnLogger) Read

func (cl *ConnLogger) Read(b []byte) (n int, err error)

func (*ConnLogger) Write

func (cl *ConnLogger) Write(b []byte) (n int, err error)

type Decoder

type Decoder interface{ Decode(v any) error }

type Encoder

type Encoder interface{ Encode(v any) error }

type Failure

type Failure struct {
	Error string `json:"error"`
}

type Flow

type Flow struct{ *Serializer }

func NewFlow

func NewFlow(conn io.ReadWriteCloser) *Flow

func (*Flow) Call

func (conn *Flow) Call(method string, value any) (err error)

func (*Flow) Copy

func (conn *Flow) Copy() Conn

func (*Flow) Flush

func (conn *Flow) Flush()

type Handlers

type Handlers map[string]any

type Marshal

type Marshal func(v any) ([]byte, error)

type Module

type Module struct {
	Router
	// contains filtered or unexported fields
}

func NewModule

func NewModule(node node.Node, port string) (r *Module)

func (Module) RouteQuery

func (m Module) RouteQuery(ctx context.Context, query net.Query, caller net.SecureWriteCloser, hints net.Hints) (s net.SecureWriteCloser, err error)

type Registry

type Registry[V any] struct {
	// contains filtered or unexported fields
}

func NewRegistry

func NewRegistry[V any]() *Registry[V]

func (*Registry[V]) Add

func (n *Registry[V]) Add(str string, v V)

func (*Registry[V]) All

func (n *Registry[V]) All() map[string]V

func (*Registry[V]) Get

func (n *Registry[V]) Get() V

func (*Registry[V]) IsEmpty

func (n *Registry[V]) IsEmpty() bool

func (*Registry[V]) Scan

func (n *Registry[V]) Scan(scanner io.ByteScanner) (rr *Registry[V], err error)

func (*Registry[V]) Unfold

func (n *Registry[V]) Unfold(str string) (*Registry[V], string)

type RemoteIdInfo

type RemoteIdInfo interface{ RemoteIdentity() id.Identity }

type Request

type Request struct {
	*Serializer
	// contains filtered or unexported fields
}

func (*Request) Call

func (r *Request) Call(method string, value any) (err error)

func (*Request) Copy

func (r *Request) Copy() Conn

func (*Request) Flush

func (r *Request) Flush()

type Router

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

func NewRouter

func NewRouter(port string) *Router

func (*Router) Authorize

func (r *Router) Authorize(ctx context.Context, query any) bool

func (*Router) Call

func (r *Router) Call() (result []any, err error)

func (*Router) Caller

func (r *Router) Caller(caller *Caller) *Router

func (*Router) Command

func (r *Router) Command(cmd string) *Router

func (*Router) Conn

func (r *Router) Conn(conn io.ReadWriteCloser) *Router

func (*Router) Func

func (r *Router) Func(name string, function any) *Router

func (*Router) Handle

func (r *Router) Handle(ctx context.Context, query any, remoteId id.Identity, conn io.ReadWriteCloser) (err error)

func (*Router) Interface

func (r *Router) Interface(srv any) *Router

func (*Router) Logger

func (r *Router) Logger(logger *log.Logger) *Router

func (*Router) Query

func (r *Router) Query(query string) *Router

func (*Router) RouteFunc

func (r *Router) RouteFunc(name string, function any) *Router

func (*Router) Routes

func (r *Router) Routes(routes ...string) *Router

func (*Router) Run

func (r *Router) Run(ctx context.Context) (err error)

func (*Router) With

func (r *Router) With(env ...any) *Router

type Serializer

type Serializer struct {
	io.WriteCloser
	ByteScannerReader
	// contains filtered or unexported fields
}

func (*Serializer) Codecs

func (s *Serializer) Codecs(codecs Codecs)

func (*Serializer) Decode

func (s *Serializer) Decode(value any) (err error)

func (*Serializer) Encode

func (s *Serializer) Encode(value any) (err error)

func (*Serializer) Logger

func (s *Serializer) Logger(logger *log.Logger)

func (*Serializer) RemoteIdentity

func (s *Serializer) RemoteIdentity() (i id.Identity)

type Unmarshal

type Unmarshal func(data []byte, v any) error