Documentation ¶
Index ¶
- Variables
- func SelfyNewKey(createKeyPairNamed, odir string) error
- type Call
- type Client
- func (c *Client) Call(serviceMethod string, args any, reply any) error
- func (c *Client) Close() error
- func (c *Client) Err() error
- func (c *Client) GetOneRead(seqno uint64, ch chan *Message)
- func (c *Client) GetReadIncomingCh() (ch chan *Message)
- func (c *Client) GetReads(ch chan *Message)
- func (c *Client) Go(serviceMethod string, args any, reply any, done chan *Call) *Call
- func (c *Client) LocalAddr() string
- func (c *Client) Name() string
- func (c *Client) OneWaySend(msg *Message, doneCh <-chan struct{}) (err error)
- func (c *Client) SendAndGetReply(req *Message, doneCh <-chan struct{}) (reply *Message, err error)
- func (c *Client) SendAndGetReplyWithTimeout(timeout time.Duration, req *Message) (reply *Message, err error)
- func (c *Client) UngetReads(ch chan *Message)
- type ClientCodec
- type Config
- type HDR
- func (hdr *HDR) AsGreenpack(scratch []byte) (o []byte, err error)
- func (m *HDR) Bytes() []byte
- func (m *HDR) Compact() string
- func (z *HDR) DecodeMsg(dc *msgp.Reader) (err error)
- func (z *HDR) EncodeMsg(en *msgp.Writer) (err error)
- func (a *HDR) Equal(b *HDR) bool
- func (m *HDR) JSON() []byte
- func (z *HDR) MarshalMsg(b []byte) (o []byte, err error)
- func (z *HDR) Msgsize() (s int)
- func (m *HDR) OpaqueURLFriendly() string
- func (m *HDR) Pretty() string
- func (m *HDR) String() string
- func (z *HDR) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *HDR) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type Message
- func (m *Message) AsGreenpack(scratch []byte) (o []byte, err error)
- func (z *Message) DecodeMsg(dc *msgp.Reader) (err error)
- func (z *Message) EncodeMsg(en *msgp.Writer) (err error)
- func (z *Message) MarshalMsg(b []byte) (o []byte, err error)
- func (z *Message) Msgsize() (s int)
- func (msg *Message) String() string
- func (z *Message) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Message) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type NetConnWrapper
- type OneWayFunc
- type Request
- type Response
- type Server
- func (s *Server) Close() error
- func (s *Server) Register(rcvr any) error
- func (s *Server) Register1Func(callme1 OneWayFunc)
- func (s *Server) Register2Func(callme2 TwoWayFunc)
- func (s *Server) RegisterName(name string, rcvr any) error
- func (s *Server) SendMessage(callID, subject, destAddr string, data []byte, seqno uint64) error
- func (s *Server) Start() (serverAddr net.Addr, err error)
- type ServerCodec
- type ServerError
- type TwoWayFunc
Constants ¶
This section is empty.
Variables ¶
var ErrDone = fmt.Errorf("done channel closed")
var ErrHandshakeQUIC = fmt.Errorf("quic handshake failure")
var ErrNetConnectionNotFound = fmt.Errorf("error: net.Conn not found")
var ErrNetRpcShutdown = errors.New("connection is shut down")
ErrNetRpcShutdown is from net/rpc, and still distinct from ErrShutdown to help locate when and where the error was generated. It indicates the system, or at least the network connection or stream, is closed or shutting down.
var ErrNotFound = fmt.Errorf("known_tls_hosts file not found")
var ErrShutdown = fmt.Errorf("shutting down")
var ErrTooLong = fmt.Errorf("message message too long: over 2GB; encrypted client vs an un-encrypted server?")
Functions ¶
func SelfyNewKey ¶ added in v1.0.3
SelfyNewKey will generate a self-signed certificate authority, a new ed25519 key pair, sign the public key to create a cert, and write these four new files to disk. The directories odir/my-keep-private-dir and odir/certs will be created, based on the odir argument. For a given createKeyPairNamed name, we will create odir/certs/name.crt and odir/certs/name.key files. The odir/certs/name.key and my-keep-private-dir/ca.key files contain private keys and should be kept confidential. The `selfy` command in this package can be used to produce the same keys but with password protection, which is recommended.
Types ¶
type Call ¶ added in v1.0.42
type Call struct { ServiceMethod string // The name of the service and method to call. Args any // The argument to the function (*struct). Reply any // The reply from the function (*struct). Error error // After completion, the error status. Done chan *Call // Receives *Call when Go is complete. }
Call represents an active net/rpc RPC.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
A Client starts requests, and (might) wait for responses.
func NewClient ¶
NewClient attemps to connect to config.ClientDialToHostPort; err will come back with any problems encountered. The name setting allows users to track multiple instances of Clients, and the Client.Name() method will retreive it.
func (*Client) Call ¶ added in v1.0.42
Call implements the net/rpc Client.Call() API; its docs:
Call invokes the named function, waits for it to complete, and returns its error status.
func (*Client) GetOneRead ¶
GetOneRead responds on ch with the first incoming message whose Seqno matches seqno, then auto unregisters itself after that single send on ch.
func (*Client) GetReadIncomingCh ¶
GetReadIncomingCh creates and returns a buffered channel that reads incoming messages that are server-pushed (not associated with a round-trip rpc call request/response pair).
func (*Client) GetReads ¶
GetReads registers to get any received messages on ch. It is similar to GetReadIncomingCh but for when ch already exists and you do not want a new one.
func (*Client) Go ¶ added in v1.0.42
Go implements the net/rpc Client.Go() API; its docs:
Go invokes the function asynchronously. It returns the Call structure representing the invocation. The done channel will signal when the call is complete by returning the same Call object. If done is nil, Go will allocate a new channel. If non-nil, done must be buffered or Go will deliberately crash.
func (*Client) OneWaySend ¶
OneWaySend sends a message without expecting or waiting for a response. The doneCh is optional, and can be nil.
func (*Client) SendAndGetReply ¶
SendAndGetReply starts a round-trip RPC call. We will wait for a response before retuning. The doneCh is optional; it can be nil. A context.Done() like channel can be supplied there to stop waiting before a reply comes back.
func (*Client) SendAndGetReplyWithTimeout ¶
func (c *Client) SendAndGetReplyWithTimeout(timeout time.Duration, req *Message) (reply *Message, err error)
SendAndGetReplyWithTimeout expires the call after timeout.
func (*Client) UngetReads ¶
UngetReads reverses what GetReads does: un-register and have ch be deaf from now on. Idempotent: if ch is already gone, no foul is reported.
type ClientCodec ¶ added in v1.0.42
type ClientCodec interface { WriteRequest(*Request, any) error ReadResponseHeader(*Response) error ReadResponseBody(any) error Close() error }
ClientCodec is part of the net/rpc API. Its docs:
A ClientCodec implements writing of RPC requests and reading of RPC responses for the client side of an RPC session. The client calls [ClientCodec.WriteRequest] to write a request to the connection and calls [ClientCodec.ReadResponseHeader] and [ClientCodec.ReadResponseBody] in pairs to read responses. The client calls [ClientCodec.Close] when finished with the connection. ReadResponseBody may be called with a nil argument to force the body of the response to be read and then discarded. See NewClient's comment for information about concurrent access.
type Config ¶
type Config struct { // ServerAddr host:port where the server should listen. ServerAddr string // optional. Can be used to suggest that the // client use a specific host:port. NB: For QUIC, by default, the client and // server will share the same port if they are in the same process. // In that case this setting will definitely be ignored. ClientHostPort string // Who the client should contact ClientDialToHostPort string // TCP false means TLS-1.3 secured. true here means do TCP only; with no encryption. TCPonly_no_TLS bool // UseQUIC cannot be true if TCPonly_no_TLS is true. UseQUIC bool // path to certs/ like certificate // directory on the live filesystem. If left // empty then the embedded certs/ from build-time, those // copied from the on-disk certs/ directory and baked // into the executable as a virtual file system with // the go:embed directive are used. CertPath string // SkipVerifyKeys true allows any incoming // key to be signed by // any CA; it does not have to be ours. Obviously // this discards almost all access control; it // should rarely be used unless communication // with the any random agent/hacker/public person // is desired. SkipVerifyKeys bool ClientKeyPairName string // default "client" means use certs/client.crt and certs/client.key ServerKeyPairName string // default "node" means use certs/node.crt and certs/node.key // hex written in hex that must be 32 bytes (or more) long // (so 64 hex characters). Only the first 32 bytes will // be used to create a symmetric 2nd encryption layer. PreSharedKeyPath string // These are timeouts for connection and transport tuning. // The defaults of 0 mean wait forever. ConnectTimeout time.Duration ReadTimeout time.Duration WriteTimeout time.Duration // contains filtered or unexported fields }
Config is the same struct type for both NewClient and NewServer setup.
Config says who to contact (for a client), or where to listen (for a server and/or client); and sets how strong a security posture we adopt.
Copying a Config is fine, but it should be a simple shallow copy to preserve the shared *sharedTransport struct. See/use the Config.Clone() method if in doubt.
nitty gritty details/dev note: the `shared` pointer here is the basis of port (and file handle) reuse where a single process can maintain a server and multiple clients in a "star" pattern. This only works with QUIC of course, and is one of the main reasons to use QUIC.
The shared pointer is reference counted and the underlying net.UDPConn is only closed when the last instance in use is Close()-ed.
type HDR ¶ added in v1.0.42
type HDR struct { Nc net.Conn `msg:"-"` // registered func can query caller details. Created string `zid:"0"` // HDR creation time stamp. From string `zid:"1"` // originator host:port address. To string `zid:"2"` // destination host:port address. Subject string `zid:"3"` // in net/rpc, the "Service.Method" ServiceName IsRPC bool `zid:"4"` // in rpc25519 Message API, is this a TwoWayFunc call? IsLeg2 bool `zid:"5"` // in rpc25519 Message API, is TwoWayFunc reply? Serial int64 `zid:"6"` // serially incremented tracking number CallID string `zid:"7"` // 40-byte crypto/rand base-58 coded string (same on response). PID int64 `zid:"8"` // Process ID of originator. Seqno uint64 `zid:"9"` // client set sequence number for each call (same on response). IsNetRPC bool `zid:"10"` // is net/rpc API in use for this request/response? }
HDR provides header information and details about the transport. It is the first thing in every Message. It is public so that clients can understand the context of their calls. Traditional `net/rpc` API users can use the `ctx context.Context` first argument form of callback methods and get an *HDR with ctx.Value("HDR") as in the README.md introduction. Reproduced here:
func (s *Service) GetsContext(ctx context.Context, args *Args, reply *Reply) error { if hdr := ctx.Value("HDR"); hdr != nil { h, ok := hdr.(*rpc25519.HDR) if ok { fmt.Printf("GetsContext called with HDR = '%v'; "+ "HDR.Nc.RemoteAddr() gives '%v'; HDR.Nc.LocalAddr() gives '%v'\n", h.String(), h.Nc.RemoteAddr(), h.Nc.LocalAddr()) } } else { fmt.Println("HDR not found") } }
func HDRFromBytes ¶ added in v1.0.42
func HDRFromGreenpack ¶ added in v1.0.42
HDRFromGreenpack will unmarshal the header into the returned struct. The [greenpack format](https://github.com/glycerine/greenpack) is expected.
func HDRFromOpaqueURLFriendly ¶ added in v1.0.42
func (*HDR) AsGreenpack ¶ added in v1.0.42
AsGreenpack will marshall hdr into the o output bytes. The scratch bytes can be nil or reused and returned to avoid allocation. The [greenpack format](https://github.com/glycerine/greenpack) is used.
func (*HDR) DecodeMsg ¶ added in v1.0.42
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (*HDR) Equal ¶ added in v1.0.42
Equal compares two *HDR structs field by field for structural equality
func (*HDR) MarshalMsg ¶ added in v1.0.42
MarshalMsg implements msgp.Marshaler
func (*HDR) Msgsize ¶ added in v1.0.42
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*HDR) OpaqueURLFriendly ¶ added in v1.0.42
func (*HDR) UnmarshalMsg ¶ added in v1.0.42
UnmarshalMsg implements msgp.Unmarshaler
func (*HDR) UnmarshalMsgWithCfg ¶ added in v1.0.42
type Message ¶
type Message struct { // HDR contains header information. HDR HDR `zid:"0"` // JobSerz is the "body" of the message. // The user provides and interprets this. JobSerz []byte `zid:"1"` // JobErrs returns error information from the server-registered // user-defined callback functions. JobErrs string `zid:"2"` // Err is not serialized on the wire by the server. // It communicates only local (client side) information. Callback // functions should convey errors in JobErrs or in-band within // JobSerz. Err error `msg:"-"` // DoneCh will receive this Message itself when the call completes. // It must be buffered, with at least capacity 1. // NewMessage() automatically allocates DoneCh correctly and // so should be the preferred for creating Message(s). DoneCh chan *Message `msg:"-"` }
Message transports JobSerz []byte slices for the user, who can de-serialize them they wish. The HDR header field provides transport details.
func MessageFromGreenpack ¶ added in v1.0.28
MessageFromGreenpack unmarshals the by slice into a Message and returns it. The [greenpack format](https://github.com/glycerine/greenpack) is expected.
func NewMessage ¶
func NewMessage() *Message
NewMessage allocates a new Message with a DoneCh properly created (buffered 1).
func NewMessageFromBytes ¶
NewMessageFromBytes calls NewMessage() and sets by as the JobSerz field.
func (*Message) AsGreenpack ¶ added in v1.0.29
AsGreenpack marshalls m into o. The scrach workspace can be nil or reused to avoid allocation. The [greenpack format](https://github.com/glycerine/greenpack) is used.
func (*Message) DecodeMsg ¶ added in v1.0.26
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (*Message) MarshalMsg ¶ added in v1.0.26
MarshalMsg implements msgp.Marshaler
func (*Message) Msgsize ¶ added in v1.0.26
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Message) UnmarshalMsg ¶ added in v1.0.26
UnmarshalMsg implements msgp.Unmarshaler
func (*Message) UnmarshalMsgWithCfg ¶ added in v1.0.26
type NetConnWrapper ¶ added in v1.0.5
type NetConnWrapper struct { quic.Stream quic.Connection }
NetConnWrapper is exported so that clients like `goq` and others that want to inspect that context of their calls can do so.
type OneWayFunc ¶ added in v1.0.39
type OneWayFunc func(req *Message)
OneWayFunc is the simpler sibling to the above. A OneWayFunc will not return anything to the sender.
As above req.JobSerz [] byte contains the job payload.
type Request ¶ added in v1.0.42
type Request struct { ServiceMethod string // format: "Service.Method" Seq uint64 // sequence number chosen by client // contains filtered or unexported fields }
Request is part of the net/rpc API. Its docs:
Request is a header written before every RPC call. It is used internally but documented here as an aid to debugging, such as when analyzing network traffic.
type Response ¶ added in v1.0.42
type Response struct { ServiceMethod string // echoes that of the Request Seq uint64 // echoes that of the request Error string // error, if any. // contains filtered or unexported fields }
Response is part of the net/rpc API. Its docs:
Response is a header written before every RPC return. It is used internally but documented here as an aid to debugging, such as when analyzing network traffic.
type Server ¶
type Server struct { // RemoteConnectedCh sends the remote host:port address // when the server gets a new client, // See srv_test.go Test004_server_push for example, // where it is used to avoid a race/panic. RemoteConnectedCh chan string // contains filtered or unexported fields }
Servers read and respond to requests. Two APIs are available.
Using the rpc25519.Message based API:
Register1Func() and Register2Func() register callbacks.
Using the net/rpc API:
Server.Register() registers structs with callback methods on them.
The net/rpc API is implemented as a layer on top of the rpc25519.Message based API. Both can be used concurrently if desired.
func NewServer ¶
NewServer will keep its own copy of config. If config is nil, the server will make its own upon Start().
func (*Server) Register ¶ added in v1.0.42
Register implements the net/rpc Server.Register() API. Its docs:
Register publishes in the server the set of methods of the receiver value that satisfy the following conditions:
- exported method of exported type
- two arguments, both of exported type
- the second argument is a pointer
- one return value, of type error
It returns an error if the receiver is not an exported type or has no suitable methods. It also logs the error using package log. The client accesses each method using a string of the form "Type.Method", where Type is the receiver's concrete type.
rpc25519 addendum:
Callback methods in the `net/rpc` style traditionally look like this first `NoContext` example below. We now allow a context.Context as an additional first parameter. The ctx will have an "HDR" value set on it giving a pointer to the `rpc25519.HDR` header from the incoming Message.
func (s *Service) NoContext(args *Args, reply *Reply) error
* new:
func (s *Service) GetsContext(ctx context.Context, args *Args, reply *Reply) error { if hdr := ctx.Value("HDR"); hdr != nil { h, ok := hdr.(*rpc25519.HDR) if ok { fmt.Printf("GetsContext called with HDR = '%v'; "+ "HDR.Nc.RemoteAddr() gives '%v'; HDR.Nc.LocalAddr() gives '%v'\n", h.String(), h.Nc.RemoteAddr(), h.Nc.LocalAddr()) } } else { fmt.Println("HDR not found") } }
func (*Server) Register1Func ¶ added in v1.0.39
func (s *Server) Register1Func(callme1 OneWayFunc)
Register1Func tells the server about a func or method that will not reply. See the OneWayFunc definition.
func (*Server) Register2Func ¶ added in v1.0.39
func (s *Server) Register2Func(callme2 TwoWayFunc)
Register2Func tells the server about a func or method that will have a returned Message value. See the TwoWayFunc definition.
func (*Server) RegisterName ¶ added in v1.0.42
RegisterName is like [Register] but uses the provided name for the type instead of the receiver's concrete type.
func (*Server) SendMessage ¶
SendMessage can be used on the server to push data to one of the connected clients; that found at destAdddr.
A NewMessage() Message will be created and JobSerz will contain the data. The HDR fields Subject, CallID, and Seqno will also be set from the arguments.
If the destAddr is not already connected to the server, the ErrNetConnectionNotFound error will be returned.
type ServerCodec ¶ added in v1.0.42
type ServerCodec interface { ReadRequestHeader(*Request) error ReadRequestBody(any) error WriteResponse(*Response, any) error // Close can be called multiple times and must be idempotent. Close() error }
ServerCodec is part of the net/rpc API. Its docs:
A ServerCodec implements reading of RPC requests and writing of RPC responses for the server side of an RPC session. The server calls [ServerCodec.ReadRequestHeader] and [ServerCodec.ReadRequestBody] in pairs to read requests from the connection, and it calls [ServerCodec.WriteResponse] to write a response back. The server calls [ServerCodec.Close] when finished with the connection. ReadRequestBody may be called with a nil argument to force the body of the request to be read and discarded. See NewClient's comment for information about concurrent access.
type ServerError ¶ added in v1.0.42
type ServerError string
ServerError represents an error that has been returned from the remote side of the RPC connection.
func (ServerError) Error ¶ added in v1.0.42
func (e ServerError) Error() string
type TwoWayFunc ¶ added in v1.0.39
TwoWayFunc is the user's own function that they register with the server for remote procedure calls.
The user's Func may not want to return anything. In that case they should register a OneWayFunc instead.
req.JobSerz []byte contains the job payload.
Implementers of TwoWayFunc should assign their return []byte to reply.JobSerz. reply.Jobserz can also be left nil, of course.
Any errors can be returned on reply.JobErrs; this is optional. Note that JobErrs is a string value rather than an error.
The system will overwrite the reply.HDR field when sending the reply, so the user should not bother trying to alter it.