README
¶
petrel
Petrel is a non-HTTP toolkit for adding network capabilities to programs. With it you can define APIs/RPCs of arbitrary complexity, using any data format you like. Here are some key features:
-
Optimized for programmer ease-of-use, but has been proven decently performant in real-world datacenter use.
-
Supports command-line style requests (automatic tokenization, like ARGV), or blob style request handling (raw payload passed through to your code).
-
Works over Unix domain sockets or TCP.
-
Security-conscious design:
-
TLS support for link security and/or client authentication.
-
HMAC support for message verification.
-
Message length limits to protect against memory exhaustion, accidental or purposeful
-
-
Petrel has no external dependencies, and passes
golint,go vet, andgo test -racecleanly.
News
- 2020-05-14: v0.31.0: Transition to Go module
- 2017-09-30: v0.30.1: Code run through
gofmt -s - 2016-11-29: v0.30.0: Internal changes to accomodate petreljs
- 2016-11-20: v0.29.0: HMAC is now base64 encoded
- 2016-11-01: v0.28.0: HMAC improvements; added protocol version
See the Release notes for all updates.
Documentation
-
Install:
go get github.com/firepear/petrel
See the demo server and client for worked examples of Petrel usage.
To see them in action, in one terminal, do 'go run demo/server.go' to start the example
server.
In another terminal, try a few runs of the client, like::
go run demo/client.go date go run demo/client.go echo whatever you feel like typing here go run demo/client.go go run demo/client.go foobar
When you're done, kill the server with C-c in its terminal.
Documentation
¶
Index ¶
Constants ¶
const ( All = iota Conn Error Fatal )
Message levels control which messages will be sent to h.Msgr
const ( // Proto is the version of the wire protocol implemented by // this library Proto = uint8(0) )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// transmission sequence id
Seq uint32
// contains filtered or unexported fields
}
Client is a Petrel client instance.
func TCPClient ¶
func TCPClient(c *ClientConfig) (*Client, error)
TCPClient returns a Client which uses TCP.
func TLSClient ¶
func TLSClient(c *ClientConfig, t *tls.Config) (*Client, error)
TLSClient returns a Client which uses TLS + TCP.
func UnixClient ¶
func UnixClient(c *ClientConfig) (*Client, error)
UnixClient returns a Client which uses Unix domain sockets.
func (*Client) DispatchRaw ¶
DispatchRaw sends a pre-encoded transmission and returns the response.
type ClientConfig ¶
type ClientConfig struct {
// For Unix clients, Addr takes the form "/path/to/socket". For
// TCP clients, it is either an IPv4 or IPv6 address followed by
// the desired port number ("127.0.0.1:9090", "[::1]:9090").
Addr string
// Timeout is the number of milliseconds the client will wait
// before timing out due to on a Dispatch() or Read()
// call. Default (zero) is no timeout.
Timeout int64
//HMACKey is the secret key used to generate MACs for signing
//and verifying messages. Default (nil) means MACs will not be
//generated for messages sent, or expected for messages
//received.
HMACKey []byte
}
ClientConfig holds values to be passed to the client constructor.
type Msg ¶
type Msg struct {
// Conn is the connection ID that the Msg is coming from.
Conn uint32
// Req is the request number that resulted in the Msg.
Req uint32
// Code is the numeric status indicator.
Code int
// Txt is the content/description.
Txt string
// Err is the error (if any) passed upward as part of the Msg.
Err error
}
Msg is the format which Petrel uses to communicate informational messages and errors to its host program via the s.Msgr channel.
type Perr ¶
Perr is a Petrel error -- though perhaps a better name would have been Pstatus. The data which is used to generate internal and external informational and error messages are stored as Perrs.
type Responder ¶
Responder is the type which functions passed to Server.Register must match: taking a slice of slices of bytes as an argument and returning a slice of bytes and an error.
type Server ¶
type Server struct {
// Msgr is the channel which receives notifications from
// connections.
Msgr chan *Msg
// contains filtered or unexported fields
}
Server is a Petrel server instance.
func TCPServer ¶
func TCPServer(c *ServerConfig) (*Server, error)
TCPServer returns a Server which uses TCP networking.
func TLSServer ¶
func TLSServer(c *ServerConfig, t *tls.Config) (*Server, error)
TLSServer returns a Server which uses TCP networking, secured with TLS.
func UnixServer ¶
func UnixServer(c *ServerConfig, p uint32) (*Server, error)
UnixServer returns a Server which uses Unix domain sockets. Argument `p` is the Unix permissions to set on the socket (e.g. 770)
func (*Server) Quit ¶
func (s *Server) Quit()
Quit handles shutdown and cleanup, including waiting for any connections to terminate. When it returns, all connections are fully shut down and no more work will be done.
func (*Server) Register ¶
Register adds a Responder function to a Server.
'name' is the command you wish this function do be the responder for.
'mode' has two legal values: 'argv' and 'blob'. To pass JSON or other data to Responders unaltered, use 'blob'. To have the portion of the request following the command split and passed to the Responder as an ARGV style list, use 'argv'. 'argv', as might be expected, has a higher overhead than 'blob'.
'r' is the name of the Responder function which will be called on dispatch.
type ServerConfig ¶
type ServerConfig struct {
// Sockname is the location/IP+port of the socket. For Unix
// sockets, it takes the form "/path/to/socket". For TCP, it is an
// IPv4 or IPv6 address followed by the desired port number
// ("127.0.0.1:9090", "[::1]:9090").
Sockname string
// Timeout is the number of milliseconds the Server will wait
// when performing network ops before timing out. Default
// (zero) is no timeout. Each connection to the server is
// handled in a separate goroutine, however, so one blocked
// connection does not affect any others (unless you run out of
// file descriptors for new conns).
Timeout int64
// Reqlen is the maximum number of bytes in a single read from
// the network. If a request exceeds this limit, the
// connection will be dropped. Use this to prevent memory
// exhaustion by arbitrarily long network reads. The default
// (0) is unlimited.
Reqlen uint32
// Buffer sets how many instances of Msg may be queued in
// Server.Msgr. Non-Fatal Msgs which arrive while the buffer
// is full are dropped on the floor to prevent the Server from
// blocking. Defaults to 32.
Buffer int
// Msglvl determines which messages will be sent to the
// Server's message channel. Valid values are All, Conn,
// Error, and Fatal.
Msglvl int
// LogIP determines if the IP of clients is logged on
// connect. Enabling IP logging creates a bit of overhead on
// each connect. If this isn't needed, or if the client can be
// identified at the application layer, leaving this off will
// somewhat improve performance in high-usage scenarios.
LogIP bool
//HMACKey is the secret key used to generate MACs for signing
//and verifying messages. Default (nil) means MACs will not be
//generated for messages sent, or expected for messages
//received. Enabling message authentication adds significant
//overhead for each message sent and received, so use this
//when security outweighs performance.
HMACKey []byte
}
ServerConfig holds values to be passed to server constuctors.
Source Files
Directories