petrel

README

petrel

Analagous to SQLite's embedding of serverless relational database capablities within programs, Petrel lets you easily add RPC capabilities into your programs with no external message broker.

• Optimized for programmer time
• A program can embed multiple Petrel servers and/or clients
• Petrel servers support arbitrarily many concurrent connections
  • But individual connections are synchronous
• Supports multiple request styles
  • Command-line, with automatic tokenization
  • Blob/JSON, with raw payload pass-thru
• 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
• No third-party dependencies
• Proven reliable and decently performant in real-world use

N.B. Petrel is pre-v1.0.0 so assume that there will be breaking changes

News

• 2022-05-07: v0.34.0: Msglvl All renamed to Debug; server config now specifies Msglvl as a string for easier app configuration
• 2022-04-23: v0.33.0: Client and server are separate packages
• 2021-01-09: v0.32.0: More module updates
• 2020-05-14: v0.31.0: Transition to Go module
• 2017-09-30: v0.30.1: Code run through gofmt -s

See the Release notes for all updates.

Documentation

• Client
• Server
• 

Example

See the demo server and client for worked examples of Petrel usage.

To see them in action, in the basic example directory, do go run example-server.go to start the example server. Then in another terminal, try a few runs of the client:

go run demo/example-client.go time
go run demo/example-client.go echo whatever you feel like typing here
go run demo/example-client.go
go run demo/example-client.go foobar

Check out the results of the client, and the messages printed in the server's terminal. When you're done, kill the server with C-c.

Documentation

Overview

Package petrel contains common code, data, and types that are shared between petrel/server and petrel/client.

Users should not import it directly.

Index

• Constants
• Variables
• func ConnRead(c net.Conn, timeout time.Duration, plimit uint32, key []byte, seq *uint32) ([]byte, string, string, error)
• func ConnReadRaw(c net.Conn, timeout time.Duration) ([]byte, string, string, error)
• func ConnWrite(c net.Conn, payload, key []byte, timeout time.Duration, seq uint32) (string, error)
• func ConnWriteRaw(c net.Conn, timeout time.Duration, xmission []byte) (string, error)
• type Perr
  • func (p Perr) Error() string

Constants

const (
	Debug = 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

var (
	// Errs is the map of Perr instances. It is used by Msg
	// handling code throughout the Petrel packages.
	Errs = map[string]*Perr{
		"connect": {
			100,
			Conn,
			"client connected",
			nil},
		"dispatch": {
			101,
			Debug,
			"dispatching",
			nil},
		"netreaderr": {
			196,
			Conn,
			"network read error",
			nil},
		"netwriteerr": {
			197,
			Conn,
			"network write error",
			nil},
		"disconnect": {
			198,
			Conn,
			"client disconnected",
			nil},
		"quit": {
			199,
			Debug,
			"Quit called: closing listener socket",
			nil},
		"success": {
			200,
			Debug,
			"reply sent",
			nil},
		"badreq": {
			400,
			Debug,
			"bad command",
			[]byte("PERRPERR400")},
		"nilreq": {
			401,
			Debug,
			"nil request",
			[]byte("PERRPERR401")},
		"plenex": {
			402,
			Error,
			"payload size limit exceeded; closing conn",
			[]byte("PERRPERR402")},
		"reqerr": {
			500,
			Error,
			"request failed",
			[]byte("PERRPERR500")},
		"internalerr": {
			501,
			Error,
			"internal error",
			nil},
		"badmac": {
			502,
			Error,
			"HMAC verification failed; closing conn",
			[]byte("PERRPERR502")},
		"listenerfail": {
			599,
			Fatal,
			"read from listener socket failed",
			nil},
	}

	// Errmap lets you go the other way, from a numeric status to
	// the name of a Perr
	Errmap = map[int]string{
		100: "connect",
		101: "dispatch",
		196: "netreaderr",
		197: "netwriteerr",
		198: "disconnect",
		199: "quit",
		200: "success",
		400: "badreq",
		401: "nilreq",
		402: "plenex",
		403: "badmac",
		500: "reqerr",
		501: "internalerr",
		599: "listenerfail"}

	// Loglvl maps string logging levels (from configurations) to
	// their int equivalents (actually used in code)
	Loglvl = map[string]int{
		"debug": Debug,
		"conn":  Conn,
		"error": Error,
		"fatal": Fatal}
)

Functions

func ConnRead

func ConnRead(c net.Conn, timeout time.Duration, plimit uint32, key []byte, seq *uint32) ([]byte, string, string, error)

ConnRead reads a message from a connection

func ConnReadRaw

func ConnReadRaw(c net.Conn, timeout time.Duration) ([]byte, string, string, error)

ConnReadRaw is only used by the Client, via DispatchRaw. As such it has no payload length checking.

func ConnWrite

func ConnWrite(c net.Conn, payload, key []byte, timeout time.Duration, seq uint32) (string, error)

ConnWrite writes a message to a connection.

func ConnWriteRaw

func ConnWriteRaw(c net.Conn, timeout time.Duration, xmission []byte) (string, error)

ConnWriteRaw is a lower-level function that handles network writes for ConnWrite and the client.

Types

type Perr

type Perr struct {
	Code int
	Lvl  int
	Txt  string
	Xmit []byte
}

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.

func (Perr) Error

func (p Perr) Error() string

Error implements the error interface for Perr.