README
¶
rpc25519: ed25519 based RPC for Go/golang
Motivation: I needed a small, simple, and compact RPC system
with modern, strong cryptography
for goq.
To that end, rpc25519 uses only
ed25519 keys for its public-key cryptography. A
pre-shared-key layer can also be configured
for post-quantum security.
Excitedly, I am delighted to report this package also supports QUIC as a transport. QUIC is very fast even though it is always encrypted. This is due to its 0-RTT design and the mature quic-go implementation of the protocol. QUIC allows a local client and server in the same process to share a UDP port. This feature can be useful for conserving ports and connecting across networks.
After tuning and hardening, the UDP/QUIC versus TCP/TLS decision is not really difficult if the client is new every time. In our measurements, TLS (over TCP) has both better connection latency and better throughput than QUIC (over UDP). QUIC does not get to take advantage of its optimization for 0-RTT re-connection under these circumstances (when the client is new). If you have clients that frequently re-connect after loosing network connectivity, then measure QUIC versus TLS/TCP in your application. Otherwise, for performance, prefer TLS over TCP. The latency of TLS is better and, moreover, the throughput of TLS can be much better (4-5x greater). If client port re-use and conservation is a needed, then QUIC may be your only choice.
The rpc25519 package docs are here.
Benchmarks versus other rpc systems are here: https://github.com/glycerine/rpcx-benchmark
# to install/get started:
# *warning: ~/go/bin/{srv,cli,selfy,greenpack} are written
#
git clone https://github.com/glycerine/greenpack ## pre-req
cd greenpack; make; cd ..
git clone https://github.com/glycerine/rpc25519
cd rpc25519; make
# make test keys and CA: saved to certs/ and my-keep-private-dir/
./selfy -k client -nopass; ./selfy -k node -nopass
./selfy -gensym psk.binary ## saved to my-keep-private-dir/psk.binary
make run && make runq ## verify TLS over TCP and QUIC
For getting started, see the small example programs here: https://github.com/glycerine/rpc25519/tree/master/cmd . These illustrate client (cli), server (srv), and QUIC port sharing
by a client and a server (samesame). The tests in srv_test.go and
cli_test.go also make great starting points.
overview
rpc25519 is a Remote Procedure Call (RPC) system with two APIs.
We offer both a traditional net/rpc
style API, and a generic []byte oriented API for carrying
user typed or self describing []byte payloads (in Message.JobSerz).
As of v1.1.0, the net/rpc API has been updated to use
greenpack encoding
rather than gob encoding, to provide a self-describing,
evolvable serialization format. Greenpack allows fields to be added
or deprecated over time and is multi-language compatible.
We re-used net/rpc's client-facing API layer, and
wired it into/on top of our native []byte slice Message transport infrastructure.
(The LICENSE file reflects this code re-use.) Instead
of taking any struct, arguments and responses must now have greenpack
generated methods. Typically this means adding
//go:generate greenpack to the files that define the
structs that will go over the wire, and running go generate.
rpc25519 was built originally for the distributed job management
use-case, and so uses TLS/QUIC directly. It does not use http,
except perhaps in the very first contact:
like net/rpc, there is limited support for
http CONNECT based hijacking; see the
cfg.HTTPConnectRequired flag. Nonetheless, this protocol remains
distinct from http. In particular, note that the connection hijacking does
not work with (https/http2/http3) encrypted protocols.
The generic byte-slice API is designed to work smoothly with our greenpack serialization format that requires no extra IDL file. See the https://github.com/glycerine/rpc25519/blob/master/hdr.go#L18 file herein, for example.
Using the rpc25519.Message based API:
Server.Register1Func()registers one-way (no reply) callbacks on the server. They look like this:
func ExampleOneWayFunc(req *Message) { ... }
Server.Register2Func()registers traditional two-way callbacks. They look like this:
func ExampleTwoWayFunc(req *Message, reply *Message) error { ... }
The central Message struct itself is simple.
type Message struct {
// HDR contains header information. See hdr.go.
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
// user-defined callback functions. If a
// TwoWayFunc returns a non-nil error, its
// err.Error() will be set here.
JobErrs string `zid:"2"`
// LocalErr is not serialized on the wire.
// It communicates only local (client/server side)
// API information. For example, Server.SendMessage() or
// Client.SendAndGetReply() can read it after
// DoneCh has been received on.
//
// Callback functions should convey
// errors in JobErrs (by returning an error);
// or in-band within JobSerz.
LocalErr 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
// should always be used when creating a new Message.
DoneCh chan *Message `msg:"-"`
}
Using the net/rpc API:
Server.Register()registers structs with callback methods on them. For a struct calledService, this method would be identified and registered:
func (s *Service) NoContext(args *Args, reply *Reply) error { ... }
See the net/rpc docs for full guidance on using that API.
- Extended method types:
Callback methods in the net/rpc
style traditionally look like the NoContext method above.
We also allow a ctx context.Context as an additional first
parameter. This is an extension to what net/rpc provides.
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) 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")
}
...
return nil
}
TODO/deferred: The client does not transmit context to server at the moment. Although the context package clearly describes this is an intended use, I don't have a use case myself for it, and so I'm not sure how the implementation should work. How are cancellation requests coordinated across a network? Do they initiate their own messages?
The net/rpc API is implemented as a layer on top of the rpc25519.Message based API. Both can be used concurrently if desired.
In the Message API, server push is available. Use Client.GetReadIncomingCh or Client.GetReads on the client side to receive server initiated messages. To push from the server (in a callback func), see Server.SendMessage. An live application example of server push is here, in the ServerCallbackMgr.pushToClient() method.
See the full source for my distributed job-queuing server goq
as an example application that uses most all features of this, the rpc25519 package.
In the following we'll look at choice of transport, why
public-key certs are preferred, and how to use the included selfy
tool to easily generate self-signed certificates.
TLS-v1.3 over TCP
Three transports are available: TLS-v1.3 over TCP, plain TCP, and QUIC which uses TLS-v1.3 over UDP.
QUIC is so much faster than even plain TCP, it should probably be your default choice.
How to KYC or Know Your Clients
How do we identify our clients in an RPC situation?
We have clients and servers in RPC. For that matter, how do we authenticate the server too?
The identity of an both client and server, either end of a connection, is established with a private-key/public-key pair in which the remote party proves posession of a private-key and we can confirm that the associated public-key has been signed by our certificate authority. Public keys signed in this way are more commonly called certificates or "certs".
An email address for convenience in identifying jobs can be listed in the certificate.
This is a much saner approach than tying a work-load identity to a specific machine, domain name, or machine port. Access to the private key corresponding to our cert should convey identity during a TLS handshake. The later part of the handshake verifies that the key was signed by our CA. This suffices. We may also want to reject based on IP address to block off clearly irrelevant traffic; both to for DDos mitigation and to keep our CPU cycles low, but these are second order optimizations. The crytographic proof is the central identifying factor.
Such a requirement maintains the strongest security but still allows elastic clouds to grow and shrink and migrate the workloads of both clients and servers. It allows for sane development and deployment on any hardware a developer can access with ssh, without compromising on encryption on either end.
TOFU or not
By creating (touch will do) a known_client_keys file on the server directory where the server is running, you activate the key tracking system on the server.
Similarly, by touching the known_server_keys file in the directory where the client is running, you tell the client to record the server certificates it has seen.
Without these files, no history of seen certs is recorded. While certs are still checked (assuming you have left SkipVerifyKeys at the default false value in the config), they are not remembered.
In a typical use case, touch the file to record the certs in use, then make the known keys file read-only to block out any new certs.
This works because clients are accepted or rejected depending on the writability of the known_client_keys file, and the presence of their certificates in that file.
Trust on first use, or TOFU, is used if the known_client_keys file is writable. When the file is writable and a new client arrives, their public key and email (if available) are stored. This is similar to how the classic ~/.ssh/known_hosts file works, but with a twist.
The twist is that once the desired identities have been recorded, the file can be used to reject any new or unknown certs from new or unkown clients.
If the file has been made unwritable (say with chmod -w known_client_keys), then we are "locked down". In this case, TOFU is not allowed and only existing keys will be accepted. Any others whose public keys are not in the known_client_hosts file will be dropped during the TLS handshake.
These unknown clients are usually just attackers that should in fact be rejected soundly. In case of misconfiguration however, all clients should be prepared to timeout as, if they are not on the list, they will be shunned and shown no further attention or packets. Without a timeout, they may well hang indefinitely waiting for network activity.
encryption details
Modern Ed25519 keys are used with TLS-1.3. The TLS_CHACHA20_POLY1305_SHA256 cipher suite is the only one configured. This is similar to the crypto suite used in Wireguard (TailScale), the only difference being that Wireguard uses Blake2s as a hash function (apparently faster than SHA-256 when hardware support SHA-extensions/SHA-NI instructions are not available). The ChaCha20, Poly1305, and Curve25519 parts are the same.
Config.PreSharedKeyPath allows specifying a 32 byte pre-shared key
file for further security. An additional, independently keyed
layer of ChaCha20-Poly1305 stream cipher/AEAD will be applied
by mixing that key into the shared secret from an ephemeral
Elliptic Curve Diffie-Hellman handshake. The same pre-shared-key must be pre-installed
on both client and server.
The pre-shared-key traffic is "tunnelled" or runs inside the outer encryption layer. Thus a different symmetric encryption scheme could be wired in without much difficulty.
The pre-shared-key file format is just raw random binary bytes. See
the srv_test.go Test011_PreSharedKey_over_TCP test in
https://github.com/glycerine/rpc25519/blob/master/srv_test.go#L297
for an example of using NewChaCha20CryptoRandKey()
to generate a key programmatically. Or just use
selfy -gensym my_pre_shared_key.binary
on the command line. For safety, selfy -gensym will
not over-write an existing file. If you want
to change keys, mv the old key out of the way first.
security posture for both extremes
The strength of security is controlled by the Config options to NewServer() and NewClient(). This section was written before we added the second symmetric encryption by pre-shared key option. All comments below about lack of security (e.g. in TCPonly_no_TLS = true mode) should be read modulo the pre-shared-key stuff: assume there is no 2nd layer.
See the cli.go file and the Config struct there; also copied below.
By default security is very strong, requiring TLS-1.3 and valid signed client certs, but allowing TOFU for previously unseen clients who come bearing valid certs; those signed by our CA.
This allows one to test one's initial setup with a minimum of fuss.
Further hardening (into a virtual fortress) can then be
accomplished by making read-only the set of already
seen clients; with chmod -w known_client_keys.
With this done, only those clients who we have already seen will be permitted in; and these are clients bearing proper certs signed by our CA private key; this will be verified during the TLS handshake. Any others will be rejected.
On the other extreme, setting TCPonly_no_TLS to true means we will use only TCP, no TLS at all, and everything will be transmitted in clear text.
In the middle of the road, setting Config.SkipVerifyKeys to true means the server will act like an HTTPS web server: any client with any key will be allowed to talk to the server, but TLS-1.3 will encrypt the traffic. Whenever TLS is used, it is always TLS-1.3 and set to the tls.TLS_CHACHA20_POLY1305_SHA256 cipher suite. Thus this setting is of no use for authenticating clients; it should almost never be used since it opens up your server to the world. But for web servers, this may be desirable.
Note that both sides of the connection (client and server) must agree to -skip-verify (Config.SkipVerifyKeys = true); otherwise the signing authority (CA) must agree. Under the default, SkipVerifyKeys = false, by signing only your own keys, with your own CA, that you keep private from the world, you maintain very tight control over access to your server.
We only create and only accept Ed25519 keys (with SkipVerifyKeys off/false,
the default). (See selfy below, or the included gen.sh script
to create keys).
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.
// So 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.
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
// default "client" means use certs/client.crt and certs/client.key
ClientKeyPairName string
// default "node" means use certs/node.crt and certs/node.key
ServerKeyPairName string
// PreSharedKeyPath locates an optional pre-shared
// binary that must be 32 bytes long.
// If supplied, this key will be used in a symmetric
// encryption layer inside the outer TLS encryption.
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
...
// This is not a Config option, but creating
// the known_{server,client}_keys file on the client/server is
// typically the last security measure in hardening.
//
// If known_client_keys exists in the server's directory,
// then we will read from it.
// Likewise, if known_server_keys exists in
// the client's directory, then we will read from it.
//
// If the known keys file is read-only: Read-only
// means we are in lockdown mode and no unknown
// client certs will be accepted, even if they
// have been properly signed by our CA.
//
// If the known keys file is writable then we are
// Trust On First Use mode, and new remote parties
// are recorded in the file if their certs are valid (signed
// by us/our CA).
//
// Note if the known_client_keys is read-only, it
// had better not be empty or nobody will be
// able to contact us. The server will notice
// this and crash since why bother being up.
}
The selfy tool: create new keys quickly; view certificates
Certificates are great, but making them has traditionally
been a massive pain. That is why I wrote selfy.
The selfy command is an easy way to create private keys, certificates,
and self-signed certficate authories. It is vastly more usable than the
mountain of complexity that is openssl. It is more limited in scope.
In our opinion, this a good thing.
If you are in a hurry to get started, the most basic
use of selfy is to create a new ed25519 key-pair:
$ selfy -k name_of_your_identity -e your@email.here.org
With other tools you would need to already have a CA (Certificate Authority).
But we've got your back. If you lack a CA in the default directory (see -p below), then, for your convenience, a self-signed CA will be auto-generated for you. It will then be used to sign the new cert. Hence the above command is all that a typical developer needs to get started. Yay(!)
If you want to first create a CA manually, you can do that
with the -ca flag. The -p flag will let you put it somewhere
other than the default directory.
selfy -ca # make a new self-signed Certificate Authority
Your newly created cert can be viewed with the selfy -v flag, just give it the
path to your .crt file.
$ selfy -v certs/name_of_your_identity.crt
By default, the CA is stored in the ./my-keep-private-dir/ca.{crt,key},
while the -k named identifying cert is stored in certs/name.crt.
The corresponding private key is stored in certs/name.key.
Update: we have added pass-phrase protection to the private keys by default.
In order to forgo this protection and use the original behavior, supply the
selfy --nopass flag. A long salt and the Argon2id key-derivation-function are used to
provide time and memory-hard protection against ASIC brute-force cracking
attempts (see https://en.wikipedia.org/wiki/Argon2 https://datatracker.ietf.org/doc/html/rfc9106 ).
$ selfy -h
Usage of selfy:
-ca
create a new self-signed certificate authority (1st of 2
steps in making new certs). Written to the -p directory
(see selfy -p flag, where -p is for private).
The CA uses ed25519 keys too.
-e string
email to write into the certificate (who to contact
about this job) (strongly encouraged when making
new certs! defaults to name@host if not given)
-gensym string
generate a new 32-byte symmetric encryption
key with crypto/rand, and save it under
this filename in the -p directory.
-k string
2nd of 2 steps: -k {key_name} ; create a new ed25519
key pair (key and cert), and save it to this name.
The pair will be saved under the -o directory;
we strongly suggest you also use the
-e your_email@actually.org flag to
describe the job and/or provide the owner's email
to contact when needed. A CA will be auto-generated
if none is found in the -p directory, which has
a default name which warns the user to protect it.
-nopass
by default we request a password and use
it with Argon2id to encrypt private key files (CA & identity).
Setting -nopass means we generate an un-encrypted
private key; this is not recommended.
-o string
directory to save newly created certs into. (default "certs")
-p string
directory to find the CA in. If doing -ca, we will save
the newly created Certificate Authority (CA) private
key to this directory. If doing -k to create a new key,
we'll look for the CA here. (default "my-keep-private-dir")
-v string
path to cert to view. Similar output as the openssl
command: 'openssl x509 -in certs/client.crt -text -noout',
which you could use instead; just replace certs/client.crt
with the path to your cert.
-verify string
verify this path is a certificate signed by the private key
corresponding to the -p {my-keep-private-dir}/ca.crt public key
The openssl commands in the included gen.sh script do the same things as
selfy does, but it is more painful to incorporate an email because
you have to modify the openssl-san.cnf file to do so each time.
generating keys with emails inside
See the selfy -e flag above for details.
Delightfully, email addresses can be stored in certificates!
This provides a fantastically convenient way to identify the job and/or the owner of the job. Importantly, if you are supporting work loads from many people, this can be critical in telling who needs to know when something goes wrong with a job.
A localhost by any other name would not smell as sweet
The server name will always be 'localhost' on selfy
generated certificates, and this is critical to allowing
our processes to run on any machine. By doing so,
we leverage the SNI technology[1],
to break the troublesome adhesion of IP address
and certificate. SNI was
developed to let a single IP address host many
different web sites. We want multiple
IP addresses to run many different jobs, and
to be able to migrate jobs between hosts.
Brilliantly, SNI lets us move our clients and servers
between machines without having to re-issue
the certificates. The certs are always
issued to 'localhost' and clients always
request ServerName 'localhost' in their
tls.Config.ServerName field.
This is much more like the convenience and
usability ssh. To me ssh has
always been so much easier to deal with than
certificates. rpc25519 aims for
usability on par with ssh. Leveraging
SNI is one way we get there.
[1] https://en.wikipedia.org/wiki/Server_Name_Indication ,
Author: Jason E. Aten, Ph.D.
License: See the LICENSE file for the 3-clause BSD-style license; the same as Go.
Documentation
¶
Index ¶
- Constants
- Variables
- func GoroNumber() int
- func IsNil(face interface{}) bool
- func NewChaCha20CryptoRandKey() []byte
- func SelfyNewKey(createKeyPairNamed, odir string) error
- type Args
- func (z *Args) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Args) EncodeMsg(en *msgp.Writer) (err error)
- func (z Args) MarshalMsg(b []byte) (o []byte, err error)
- func (z Args) Msgsize() (s int)
- func (z *Args) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Args) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type Arith
- func (t *Arith) Add(args Args, reply *Reply) error
- func (z *Arith) DecodeMsg(dc *msgp.Reader) (err error)
- func (t *Arith) Div(args Args, reply *Reply) error
- func (z Arith) EncodeMsg(en *msgp.Writer) (err error)
- func (t *Arith) Error(args *Args, reply *Reply) error
- func (z Arith) MarshalMsg(b []byte) (o []byte, err error)
- func (z Arith) Msgsize() (s int)
- func (t *Arith) Mul(args *Args, reply *Reply) error
- func (t *Arith) Scan(args string, reply *Reply) (err error)
- func (t *Arith) SleepMilli(args *Args, reply *Reply) error
- func (t *Arith) String(args *Args, reply *string) error
- func (z *Arith) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Arith) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type BenchmarkMessage
- func (z *BenchmarkMessage) DecodeMsg(dc *msgp.Reader) (err error)
- func (z *BenchmarkMessage) EncodeMsg(en *msgp.Writer) (err error)
- func (z *BenchmarkMessage) MarshalMsg(b []byte) (o []byte, err error)
- func (z *BenchmarkMessage) Msgsize() (s int)
- func (z *BenchmarkMessage) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *BenchmarkMessage) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type BuiltinTypes
- func (BuiltinTypes) Array(args *Args, reply *[2]int) error
- func (z *BuiltinTypes) DecodeMsg(dc *msgp.Reader) (err error)
- func (z BuiltinTypes) EncodeMsg(en *msgp.Writer) (err error)
- func (BuiltinTypes) Map(args *Args, reply *map[int]int) error
- func (z BuiltinTypes) MarshalMsg(b []byte) (o []byte, err error)
- func (z BuiltinTypes) Msgsize() (s int)
- func (BuiltinTypes) Slice(args *Args, reply *[]int) error
- func (z *BuiltinTypes) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *BuiltinTypes) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- func (BuiltinTypes) WantsContext(ctx context.Context, args *Args, reply *[2]int) error
- type Call
- type CallType
- func (z *CallType) DecodeMsg(dc *msgp.Reader) (err error)
- func (z CallType) EncodeMsg(en *msgp.Writer) (err error)
- func (z CallType) MarshalMsg(b []byte) (o []byte, err error)
- func (z CallType) Msgsize() (s int)
- func (z *CallType) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *CallType) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type Client
- func (c *Client) Call(serviceMethod string, args, reply Green, octx context.Context) 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 Green, reply Green, done chan *Call, ...) *Call
- func (c *Client) IsDown() (down bool)
- func (c *Client) LocalAddr() string
- func (c *Client) Name() string
- func (c *Client) OneWaySend(msg *Message, cancelJobCh <-chan struct{}) (err error)
- func (c *Client) SendAndGetReply(req *Message, cancelJobCh <-chan struct{}) (reply *Message, err error)
- func (c *Client) SendAndGetReplyWithTimeout(timeout time.Duration, req *Message) (reply *Message, err error)
- func (c *Client) Start() error
- func (c *Client) UngetReads(ch chan *Message)
- type ClientCodec
- type Config
- type Embed
- func (z *Embed) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Embed) EncodeMsg(en *msgp.Writer) (err error)
- func (z Embed) MarshalMsg(b []byte) (o []byte, err error)
- func (z Embed) Msgsize() (s int)
- func (z *Embed) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Embed) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type Green
- 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) 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 Hello
- func (z *Hello) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Hello) EncodeMsg(en *msgp.Writer) (err error)
- func (z Hello) MarshalMsg(b []byte) (o []byte, err error)
- func (z Hello) Msgsize() (s int)
- func (z *Hello) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Hello) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type InvalidRequest
- func (z *InvalidRequest) DecodeMsg(dc *msgp.Reader) (err error)
- func (z InvalidRequest) EncodeMsg(en *msgp.Writer) (err error)
- func (z InvalidRequest) MarshalMsg(b []byte) (o []byte, err error)
- func (z InvalidRequest) Msgsize() (s int)
- func (z *InvalidRequest) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *InvalidRequest) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type Message
- func (m *Message) AsGreenpack(scratch []byte) (o []byte, err error)
- func (m *Message) AsJSON(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 Reply
- func (z *Reply) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Reply) EncodeMsg(en *msgp.Writer) (err error)
- func (z Reply) MarshalMsg(b []byte) (o []byte, err error)
- func (z Reply) Msgsize() (s int)
- func (z *Reply) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Reply) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type Request
- func (z *Request) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Request) EncodeMsg(en *msgp.Writer) (err error)
- func (z Request) MarshalMsg(b []byte) (o []byte, err error)
- func (z Request) Msgsize() (s int)
- func (z *Request) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Request) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type Response
- func (z *Response) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Response) EncodeMsg(en *msgp.Writer) (err error)
- func (z Response) MarshalMsg(b []byte) (o []byte, err error)
- func (z Response) Msgsize() (s int)
- func (z *Response) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Response) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type Server
- func (s *Server) Close() error
- func (s *Server) Register(rcvr msgp.Encodable) error
- func (s *Server) Register1Func(callme1 OneWayFunc)
- func (s *Server) Register2Func(callme2 TwoWayFunc)
- func (s *Server) RegisterName(name string, rcvr msgp.Encodable) error
- func (s *Server) SendMessage(callID, subject, destAddr string, data []byte, seqno uint64, ...) error
- func (server *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)
- func (s *Server) Start() (serverAddr net.Addr, err error)
- type ServerClient
- type ServerCodec
- type ServerError
- type Simple
- func (z *Simple) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Simple) EncodeMsg(en *msgp.Writer) (err error)
- func (t *Simple) Exported(args Args, reply *Reply) error
- func (z Simple) MarshalMsg(b []byte) (o []byte, err error)
- func (z Simple) Msgsize() (s int)
- func (z *Simple) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (z *Simple) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
- type TwoWayFunc
Constants ¶
const (
// Defaults used by HandleHTTP
DefaultRPCPath = "/_goRPC_"
)
Variables ¶
var ErrDone = fmt.Errorf("done channel closed")
var ErrDone2 = fmt.Errorf("done channel closed 2")
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 ErrTimeout = fmt.Errorf("time-out waiting for call to complete")
var ErrTooLong = fmt.Errorf("message message too long: over 2GB; encrypted client vs an un-encrypted server?")
Functions ¶
func GoroNumber ¶ added in v1.1.43
func GoroNumber() int
GoroNumber returns the calling goroutine's number.
func IsNil ¶ added in v1.1.32
func IsNil(face interface{}) bool
IsNil uses reflect to to return true iff the face contains a nil pointer, map, array, slice, or channel.
func NewChaCha20CryptoRandKey ¶ added in v1.0.114
func NewChaCha20CryptoRandKey() []byte
func SelfyNewKey ¶ added in v1.0.3
SelfyNewKey is only for testing, not production. It is used by the tests to check that certs are signed by the expected CA.
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 Args ¶ added in v1.1.0
func (*Args) DecodeMsg ¶ added in v1.1.0
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (Args) MarshalMsg ¶ added in v1.1.0
MarshalMsg implements msgp.Marshaler
func (Args) Msgsize ¶ added in v1.1.0
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Args) UnmarshalMsg ¶ added in v1.1.0
UnmarshalMsg implements msgp.Unmarshaler
func (*Args) UnmarshalMsgWithCfg ¶ added in v1.1.0
type Arith ¶ added in v1.1.0
type Arith int
func (*Arith) DecodeMsg ¶ added in v1.1.0
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (Arith) MarshalMsg ¶ added in v1.1.0
MarshalMsg implements msgp.Marshaler
func (Arith) Msgsize ¶ added in v1.1.0
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Arith) SleepMilli ¶ added in v1.1.0
func (*Arith) UnmarshalMsg ¶ added in v1.1.0
UnmarshalMsg implements msgp.Unmarshaler
func (*Arith) UnmarshalMsgWithCfg ¶ added in v1.1.0
type BenchmarkMessage ¶ added in v1.1.30
type BenchmarkMessage struct {
Field1 string `zid:"0"`
Field9 string `zid:"1"`
Field18 string `zid:"2"`
Field80 bool `zid:"3"`
Field81 bool `zid:"4"`
Field2 int32 `zid:"5"`
Field3 int32 `zid:"6"`
Field280 int32 `zid:"7"`
Field6 int32 `zid:"8"`
Field22 int64 `zid:"9"`
Field4 string `zid:"10"`
Field5 []uint64 `zid:"11"`
Field59 bool `zid:"12"`
Field7 string `zid:"13"`
Field16 int32 `zid:"14"`
Field130 int32 `zid:"15"`
Field12 bool `zid:"16"`
Field17 bool `zid:"17"`
Field13 bool `zid:"18"`
Field14 bool `zid:"19"`
Field104 int32 `zid:"20"`
Field100 int32 `zid:"21"`
Field101 int32 `zid:"22"`
Field102 string `zid:"23"`
Field103 string `zid:"24"`
Field29 int32 `zid:"25"`
Field30 bool `zid:"26"`
Field60 int32 `zid:"27"`
Field271 int32 `zid:"28"`
Field272 int32 `zid:"29"`
Field150 int32 `zid:"30"`
Field23 int32 `zid:"31"`
Field24 bool `zid:"32"`
Field25 int32 `zid:"33"`
Field78 bool `zid:"34"`
Field67 int32 `zid:"35"`
Field68 int32 `zid:"36"`
Field128 int32 `zid:"37"`
Field129 string `zid:"38"`
Field131 int32 `zid:"39"`
}
func (*BenchmarkMessage) DecodeMsg ¶ added in v1.1.30
func (z *BenchmarkMessage) DecodeMsg(dc *msgp.Reader) (err error)
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (*BenchmarkMessage) EncodeMsg ¶ added in v1.1.30
func (z *BenchmarkMessage) EncodeMsg(en *msgp.Writer) (err error)
EncodeMsg implements msgp.Encodable
func (*BenchmarkMessage) MarshalMsg ¶ added in v1.1.30
func (z *BenchmarkMessage) MarshalMsg(b []byte) (o []byte, err error)
MarshalMsg implements msgp.Marshaler
func (*BenchmarkMessage) Msgsize ¶ added in v1.1.30
func (z *BenchmarkMessage) Msgsize() (s int)
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*BenchmarkMessage) UnmarshalMsg ¶ added in v1.1.30
func (z *BenchmarkMessage) UnmarshalMsg(bts []byte) (o []byte, err error)
UnmarshalMsg implements msgp.Unmarshaler
func (*BenchmarkMessage) UnmarshalMsgWithCfg ¶ added in v1.1.30
func (z *BenchmarkMessage) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
type BuiltinTypes ¶ added in v1.1.0
type BuiltinTypes struct {
Placeholder int `zid:"0"` // greenpack refuses to serialize an empty struct.
}
func (BuiltinTypes) Array ¶ added in v1.1.0
func (BuiltinTypes) Array(args *Args, reply *[2]int) error
func (*BuiltinTypes) DecodeMsg ¶ added in v1.1.0
func (z *BuiltinTypes) DecodeMsg(dc *msgp.Reader) (err error)
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (BuiltinTypes) EncodeMsg ¶ added in v1.1.0
func (z BuiltinTypes) EncodeMsg(en *msgp.Writer) (err error)
EncodeMsg implements msgp.Encodable
func (BuiltinTypes) Map ¶ added in v1.1.0
func (BuiltinTypes) Map(args *Args, reply *map[int]int) error
func (BuiltinTypes) MarshalMsg ¶ added in v1.1.0
func (z BuiltinTypes) MarshalMsg(b []byte) (o []byte, err error)
MarshalMsg implements msgp.Marshaler
func (BuiltinTypes) Msgsize ¶ added in v1.1.0
func (z BuiltinTypes) Msgsize() (s int)
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (BuiltinTypes) Slice ¶ added in v1.1.0
func (BuiltinTypes) Slice(args *Args, reply *[]int) error
func (*BuiltinTypes) UnmarshalMsg ¶ added in v1.1.0
func (z *BuiltinTypes) UnmarshalMsg(bts []byte) (o []byte, err error)
UnmarshalMsg implements msgp.Unmarshaler
func (*BuiltinTypes) UnmarshalMsgWithCfg ¶ added in v1.1.0
func (z *BuiltinTypes) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
func (BuiltinTypes) WantsContext ¶ added in v1.1.0
mimic Array's reply
type Call ¶ added in v1.0.42
type Call struct {
ServiceMethod string // The name of the service and method to call.
Args Green // The argument to the function (*struct).
Reply Green // 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 CallType ¶ added in v1.1.29
type CallType int
func (*CallType) DecodeMsg ¶ added in v1.1.29
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (CallType) MarshalMsg ¶ added in v1.1.29
MarshalMsg implements msgp.Marshaler
func (CallType) Msgsize ¶ added in v1.1.29
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*CallType) UnmarshalMsg ¶ added in v1.1.29
UnmarshalMsg implements msgp.Unmarshaler
func (*CallType) UnmarshalMsgWithCfg ¶ added in v1.1.29
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
A Client starts requests, and (might) wait for responses.
func NewClient ¶
NewClient creates a new client. Call Start() to begin a connection. 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.
Added: octx is an optional context for cancelling the job. It can be nil.
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
func (c *Client) Go(serviceMethod string, args Green, reply Green, done chan *Call, octx context.Context) *Call
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.
octx is an optional context, for early cancelling of a job. It can be nil.
func (*Client) OneWaySend ¶
OneWaySend sends a message without expecting or waiting for a response. The cancelJobCh is optional, and can be nil.
func (*Client) SendAndGetReply ¶
func (c *Client) SendAndGetReply(req *Message, cancelJobCh <-chan struct{}) (reply *Message, err error)
SendAndGetReply starts a round-trip RPC call. We will wait for a response before retuning. The requestStopCh is optional; it can be nil. A context.Done() like channel can be supplied there to cancel the job before a reply comes back.
UPDATE: a DEFAULT timeout is in force now. Because server failure or blink (down then up) can leave us stalled forever, we put in a default timeout of 10 seconds, if not otherwise specified. If you expect your call to take more than a few seconds, you should set the timeout directly with SendAndGetReplyWithTimeout() or pass in a cancelJobCh here to manage it. Otherwise, to handle the common case when we expect very fast replies, if cancelJobCh is nil, we will cancel the job if it has not finished after 10 seconds.
func (*Client) SendAndGetReplyWithTimeout ¶
func (c *Client) SendAndGetReplyWithTimeout(timeout time.Duration, req *Message) (reply *Message, err error)
SendAndGetReplyWithTimeout expires the call after timeout.
func (*Client) Start ¶ added in v1.1.15
Start dials the server. That is, Start attemps to connect to config.ClientDialToHostPort. The err will come back with any problems encountered.
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, msgp.Encodable) error
ReadResponseHeader(*Response) error
ReadResponseBody(msgp.Decodable) 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
// If true, then we do not share same UDP port between a QUIC
// client and server (in the same process). Used
// for testing client shutdown paths too.
NoSharePortQUIC bool
// path to certs/ like certificate
// directory on the live filesystem.
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
// key. It must be 32 bytes (or more). Ideally
// it should be generated from crypto/rand.
// The `selfy -gensym outpath` command will
// write 32 randomly bytes to output.
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
ServerSendKeepAlive time.Duration
ClientSendKeepAlive time.Duration
// Intially speak HTTP and only
// accept CONNECT requests that
// we turn into our protocol.
// Only works with TCPonly_no_TLS true also,
// at the moment. Also adds on another
// round trip.
HTTPConnectRequired bool
// 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 Embed ¶ added in v1.1.0
type Embed struct {
Simple `zid:"0"`
}
func (*Embed) DecodeMsg ¶ added in v1.1.0
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (Embed) MarshalMsg ¶ added in v1.1.0
MarshalMsg implements msgp.Marshaler
func (Embed) Msgsize ¶ added in v1.1.0
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Embed) UnmarshalMsg ¶ added in v1.1.0
UnmarshalMsg implements msgp.Unmarshaler
func (*Embed) UnmarshalMsgWithCfg ¶ added in v1.1.0
type HDR ¶ added in v1.0.42
type HDR struct {
// Nc is supplied to reveal the LocalAddr() or RemoteAddr() end points.
// Do not read from, or write to, this connection;
// that will cause the RPC connection to fail.
Nc net.Conn `msg:"-"`
Created time.Time `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
Seqno uint64 `zid:"4"` // user (client) set sequence number for each call (same on response).
Typ CallType `zid:"5"` // see constants below.
CallID string `zid:"6"` // 20 bytes pseudo random base-64 coded string (same on response).
Serial int64 `zid:"7"` // system serial number
LocalRecvTm time.Time `zid:"8"`
}
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 (*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) UnmarshalMsg ¶ added in v1.0.42
UnmarshalMsg implements msgp.Unmarshaler
func (*HDR) UnmarshalMsgWithCfg ¶ added in v1.0.42
type Hello ¶ added in v1.1.30
type Hello struct {
Placeholder int `zid:"0"` // must have public field or greenpack will ignore it.
}
func (*Hello) DecodeMsg ¶ added in v1.1.30
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (Hello) MarshalMsg ¶ added in v1.1.30
MarshalMsg implements msgp.Marshaler
func (Hello) Msgsize ¶ added in v1.1.30
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Hello) UnmarshalMsg ¶ added in v1.1.30
UnmarshalMsg implements msgp.Unmarshaler
func (*Hello) UnmarshalMsgWithCfg ¶ added in v1.1.30
type InvalidRequest ¶ added in v1.1.0
type InvalidRequest struct {
Placeholder int `zid:"0"`
}
InvalidRequest used instead of struct{} since greenpack needs one member element.
func (*InvalidRequest) DecodeMsg ¶ added in v1.1.0
func (z *InvalidRequest) DecodeMsg(dc *msgp.Reader) (err error)
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (InvalidRequest) EncodeMsg ¶ added in v1.1.0
func (z InvalidRequest) EncodeMsg(en *msgp.Writer) (err error)
EncodeMsg implements msgp.Encodable
func (InvalidRequest) MarshalMsg ¶ added in v1.1.0
func (z InvalidRequest) MarshalMsg(b []byte) (o []byte, err error)
MarshalMsg implements msgp.Marshaler
func (InvalidRequest) Msgsize ¶ added in v1.1.0
func (z InvalidRequest) Msgsize() (s int)
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*InvalidRequest) UnmarshalMsg ¶ added in v1.1.0
func (z *InvalidRequest) UnmarshalMsg(bts []byte) (o []byte, err error)
UnmarshalMsg implements msgp.Unmarshaler
func (*InvalidRequest) UnmarshalMsgWithCfg ¶ added in v1.1.0
func (z *InvalidRequest) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)
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"`
// LocalErr is not serialized on the wire by the server.
// It communicates only local (client/server side) information.
//
// Callback functions convey
// errors in JobErrs (by returning an error);
// or in-band within JobSerz.
LocalErr 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
// should be used when creating a new Message.
DoneCh chan *Message `msg:"-"`
// contains filtered or unexported fields
}
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 scratch workspace can be nil or reused to avoid allocation. The [greenpack format](https://github.com/glycerine/greenpack) is used.
func (*Message) AsJSON ¶ added in v1.1.54
AsJSON returns JSON bytes via msgp.CopyToJSON() or msgp.UnmarshalAsJSON()
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.
func (*NetConnWrapper) Close ¶ added in v1.1.33
func (w *NetConnWrapper) Close() error
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 Reply ¶ added in v1.1.0
type Reply struct {
C int `zid:"0"`
}
func (*Reply) DecodeMsg ¶ added in v1.1.0
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (Reply) MarshalMsg ¶ added in v1.1.0
MarshalMsg implements msgp.Marshaler
func (Reply) Msgsize ¶ added in v1.1.0
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Reply) UnmarshalMsg ¶ added in v1.1.0
UnmarshalMsg implements msgp.Unmarshaler
func (*Reply) UnmarshalMsgWithCfg ¶ added in v1.1.0
type Request ¶ added in v1.0.42
type Request struct {
ServiceMethod string `zid:"0"` // format: "Service.Method"
Seq uint64 `zid:"1"` // 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.
func (*Request) DecodeMsg ¶ added in v1.0.42
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (Request) MarshalMsg ¶ added in v1.0.42
MarshalMsg implements msgp.Marshaler
func (Request) Msgsize ¶ added in v1.0.42
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Request) UnmarshalMsg ¶ added in v1.0.42
UnmarshalMsg implements msgp.Unmarshaler
func (*Request) UnmarshalMsgWithCfg ¶ added in v1.0.42
type Response ¶ added in v1.0.42
type Response struct {
ServiceMethod string `zid:"0"` // echoes that of the Request
Seq uint64 `zid:"1"` // echoes that of the request
Error string `zid:"2"` // 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.
func (*Response) DecodeMsg ¶ added in v1.0.42
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (Response) MarshalMsg ¶ added in v1.0.42
MarshalMsg implements msgp.Marshaler
func (Response) Msgsize ¶ added in v1.0.42
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Response) UnmarshalMsg ¶ added in v1.0.42
UnmarshalMsg implements msgp.Unmarshaler
func (*Response) UnmarshalMsgWithCfg ¶ added in v1.0.42
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 *ServerClient
// 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 ¶
func (s *Server) SendMessage(callID, subject, destAddr string, data []byte, seqno uint64, errWriteDur *time.Duration) error
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 callID argument is the empty string, we will use a crypto/rand randomly generated one.
If the destAddr is not already connected to the server, the ErrNetConnectionNotFound error will be returned.
errWriteDur is how long we pause waiting for the writing goroutine to send the message or give us a fast error reply. Early discovery of client disconnect can allow us to try other (worker) clients, rather than wait for pings or other slow error paths.
The errWriteDur can be set to a few seconds if this would save the caller a minute of two of waiting to discover the send is unlikely to suceed; or to time.Duration(0) if they want no pause after writing Message to the connection. The default is 30 msec. It is a guess and aims at balance: allowing enough time to get an error back from quic-go if we are going to discover "Application error 0x0 (remote)" right away, and not wanting to stall the caller too much.
func (*Server) ServeHTTP ¶ added in v1.1.33
func (server *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP implements an http.Handler that answers RPC requests.
type ServerClient ¶ added in v1.0.135
type ServerClient struct {
Remote string
GoneCh chan struct{}
}
type ServerCodec ¶ added in v1.0.42
type ServerCodec interface {
ReadRequestHeader(*Request) error
ReadRequestBody(msgp.Decodable) error
WriteResponse(*Response, msgp.Encodable) 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 Simple ¶ added in v1.1.0
type Simple int
func (*Simple) DecodeMsg ¶ added in v1.1.0
DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.
func (Simple) MarshalMsg ¶ added in v1.1.0
MarshalMsg implements msgp.Marshaler
func (Simple) Msgsize ¶ added in v1.1.0
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Simple) UnmarshalMsg ¶ added in v1.1.0
UnmarshalMsg implements msgp.Unmarshaler
func (*Simple) UnmarshalMsgWithCfg ¶ added in v1.1.0
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. The one exception to this rule is the reply.HDR.Subject string, which can be set by the user to return user-defined information. The reply will still be matched to the request on the HDR.Seqno, so a change of HDR.Subject will not change which goroutine receives the reply.
Source Files
Directories