arpcnet

README

ArpcNet

An RPC network based on hierachical groups of nodes written in Go. The network routes and transports remote procedure calls across a network of linked nodes and can potentially support different entry and exit protocols. However, currently only gRPC is supported.

Methods provided by gRPC servers can be registers at nodes of the network under hierarchical addresss. This address is like a file in a directory or a variable in a package. A gRPC client can call these methods from any other node on the network. The client just makes a regular gRPC call by connecting directly to an Arpc node, which functions as a gRPC gateway. The client must only provide the full ArpcNet address in gRPC metadata and the call is routed and tunneled by the network to the destination gRPC service.

Documentation

Index

• Constants
• Variables
• func SplitFullMethodName(fullMethodName string) ([]string, error)
• func ToFullMethodName(addr *rpc.Address) string
• func WriteConfig(w io.Writer, cfg *Config) error
• type Config
  • func ExampleConfig() (res *Config)
  • func LoadConfig(r io.Reader) (*Config, error)
  • func LoadConfigfromFile(name string) (*Config, error)
• type GRPCClient
  • func NewGRPCClient(core *rpc.Core, mountPrefixLen int, target string, insecure bool) *GRPCClient
  • func (gc *GRPCClient) Close()
  • func (gc *GRPCClient) Handler() rpc.Handler
• type GRPCMapping
• type GRPCServer
  • func NewGRPCServer(core *rpc.Core, port int) *GRPCServer
  • func (gs *GRPCServer) Serve()
  • func (gs *GRPCServer) Stop()
• type Link
  • func NewLink(core *rpc.Core, linkt LinkTransport, logString string) (res *Link)
  • func (lr *Link) ReceiveAndDispatch() (err error)
  • func (lr *Link) String() string
• type LinkClient
  • func NewLinkClient(conn *grpc.ClientConn, core *rpc.Core) (res *LinkClient)
  • func (lc *LinkClient) Close()
  • func (lc *LinkClient) Run()
  • func (lc *LinkClient) String() string
• type LinkClientConfig
• type LinkServer
  • func NewLinkServer(listen net.Listener, core *rpc.Core) *LinkServer
  • func (ls *LinkServer) Link(call pb.LinkService_LinkServer) error
  • func (ls *LinkServer) Run()
  • func (ls *LinkServer) Stop()
• type LinkServerConfig
• type LinkTransport
• type Node
  • func NewNode(config *Config) (n *Node, err error)
  • func (n *Node) AddCloseable(c func())
  • func (n *Node) Group() *rpc.Address
  • func (n *Node) ID() *rpc.Address
  • func (n *Node) Run()
  • func (n *Node) Stop()

Constants

const GRPCAddrKey = "arpcnet-addr"

GRPCAddrKey is the gRPC metadata key under which the destination ArpcNet address is stored.

Variables

var Version = "0.3.4"

Version is the version of the ArpcNet code.

Functions

func SplitFullMethodName

func SplitFullMethodName(fullMethodName string) ([]string, error)

SplitFullMethodName splits the full name of a gRPC method, including proto package, service name and method name, into their individual name components.

func ToFullMethodName

func ToFullMethodName(addr *rpc.Address) string

ToFullMethodName converts an rpc.Address into a gRPC full method name. Note that this should be a suffix from a global ArpcNet address and thus the actual gRPC method part must be sliced off before using this function.

func WriteConfig

func WriteConfig(w io.Writer, cfg *Config) error

WriteConfig writes a Config to a writer.

Types

type Config

type Config struct {
	Group      string `yaml:"group"`
	GRPCPort   int    `yaml:"grpcPort"`
	CoreMemory string `yaml:"coreMemory,omitempty"`

	GRPCMappings []GRPCMapping `yaml:"grpcMappings"`

	LinkServers []LinkServerConfig `yaml:"linkServers"`

	LinkClients []LinkClientConfig `yaml:"linkClients"`

	ServerCertificates []string `yaml:"serverCertificates"`
}

Config represents all parameters to initialize a Node.

func ExampleConfig

func ExampleConfig() (res *Config)

ExampleConfig returns a static configuration with example values.

func LoadConfig

func LoadConfig(r io.Reader) (*Config, error)

LoadConfig loads a Config from a reader.

func LoadConfigfromFile

func LoadConfigfromFile(name string) (*Config, error)

LoadConfigfromFile loads a Config from file system.

type GRPCClient

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

GRPCClient is an RPC exit module of a Node that relays RPCs as gRPC calls to an actual gRPC server.

func NewGRPCClient

func NewGRPCClient(core *rpc.Core, mountPrefixLen int, target string, insecure bool) *GRPCClient

NewGRPCClient creates a new instance of a GRPCClient and associates it with the given core. The mountPrefixLen parameter is used to split the actual gRPC full method name from the AprcNet address and must be set to the length of address where this route handler is mounted at the core.

func (*GRPCClient) Close

func (gc *GRPCClient) Close()

Close terminates operation of this client.

func (*GRPCClient) Handler

func (gc *GRPCClient) Handler() rpc.Handler

Handler returns the rpc.Handler interface of this client instance for hooking it into a Core.

type GRPCMapping

type GRPCMapping struct {
	Target string `yaml:"target"`
	Mount  string `yaml:"mount,omitempty"`
	// TODO doublecheck how this should work
	Methods []string `yaml:"methods,omitempty"`
}

GRPCMapping configures one registration of a gRPC service at a node to map the service into the ArpcNet namespace.

type GRPCServer

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

GRPCServer is a rpc.Core module for gRPCs entering the Arpc network. Arbitrary gRPC calls can be handled by this gRPC server and are routed via an rpc.Core.

func NewGRPCServer

func NewGRPCServer(core *rpc.Core, port int) *GRPCServer

NewGRPCServer creates a new GRPCServer instance and associates it to the given rpc.Core.

func (*GRPCServer) Serve

func (gs *GRPCServer) Serve()

Serve blocks and must be called to operate the gRPC server.

func (*GRPCServer) Stop

func (gs *GRPCServer) Stop()

Stop terminates operation of the gRPC server.

type Link

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

Link is a communication channel between a local core and a remote core. RPC frames and routing queries are transported over this channel.

func NewLink

func NewLink(core *rpc.Core, linkt LinkTransport, logString string) (res *Link)

NewLink creates a new instance of a Link and associates it with the given local core.

func (*Link) ReceiveAndDispatch

func (lr *Link) ReceiveAndDispatch() (err error)

ReceiveAndDispatch uses and blocks the calling goroutine to receive and dispatch messages comming in over the link transport. The link is only established while this function is running. An error is returned when the link has failed.

func (*Link) String

func (lr *Link) String() string

type LinkClient

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

LinkClient is used to establish a link between this node and a remote node with a running LinkServer.

func NewLinkClient

func NewLinkClient(conn *grpc.ClientConn, core *rpc.Core) (res *LinkClient)

NewLinkClient creates a new LinkClient instance and associates it with the given rpc.Core.

func (*LinkClient) Close

func (lc *LinkClient) Close()

Close closes this link and the underlying grpc.ClientConn.

func (*LinkClient) Run

func (lc *LinkClient) Run()

Run uses and blocks the calling goroutine to establish the link and to receive and dispatch incomming messages to the core. Until Close is called, it will continously block retry with a delay to establish the connection.

func (*LinkClient) String

func (lc *LinkClient) String() string

type LinkClientConfig

type LinkClientConfig struct {
	Target   string `yaml:"target"`
	Insecure bool   `yaml:"insecure"`
}

LinkClientConfig configures a link connection from one node to another node that must have a link server.

type LinkServer

type LinkServer struct {
	pb.UnimplementedLinkServiceServer
	// contains filtered or unexported fields
}

LinkServer is used to establish a links between this node and remote nodes with a LinkClients.

func NewLinkServer

func NewLinkServer(listen net.Listener, core *rpc.Core) *LinkServer

NewLinkServer creates a new instance of a LinkServer.

func (*LinkServer) Link

func (ls *LinkServer) Link(call pb.LinkService_LinkServer) error

Link implements v1.LinkServiceServer.Link.

func (*LinkServer) Run

func (ls *LinkServer) Run()

Run blocks the calling goroutine to operate the server and handle incomming connections. The call ends when Stop is called.

func (*LinkServer) Stop

func (ls *LinkServer) Stop()

Stop closes the server and terminates all open links.

type LinkServerConfig

type LinkServerConfig struct {
	Port int `yaml:"port"`
}

LinkServerConfig configures that a node can receive link client connections from other nodes.

type LinkTransport

type LinkTransport interface {
	Send(*pb.LinkFrame) error
	Recv() (*pb.LinkFrame, error)
}

LinkTransport describes a bidirectional communication channel for LinkFrames to another Arpc node.

type Node

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

A Node is the runtime data structure for a node in the Arpc network.

func NewNode

func NewNode(config *Config) (n *Node, err error)

NewNode creates a Node from the parameters in a Config struct. Returns an error if any configuration values are invalid or incompatible. Note that the Node is only fully operational when the Run()-function is called.

func (*Node) AddCloseable

func (n *Node) AddCloseable(c func())

AddCloseable adds a function call to this node that is called when the node is stopped. It can be used to link the lifetime of any module that depends on this node with its lifetime.

func (*Node) Group

func (n *Node) Group() *rpc.Address

Group returns the identifier of the group this node belongs to.

func (*Node) ID

func (n *Node) ID() *rpc.Address

ID returns the identifier of this node. It has the group as a prefix.

func (*Node) Run

func (n *Node) Run()

Run blocks the goroutine and takes the node fully operational.

func (*Node) Stop

func (n *Node) Stop()

Stop ends the operation of this node and terminates any associated modules.