petrel

package module
v0.36.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 18, 2022 License: MIT Imports: 12 Imported by: 2

README

Petrel

This module is pre-v1; breaking changes will be flagged in release notes

SQLite embeds serverless relational databases into programs. Petrel lets you do the same with networking and RPC.

  • 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
  • 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 external dependencies (Go stdlib only)
  • Proven mostly reliable and decently performant in real-world use!

See the Release notes for updates.

GoReportCard link (client)

API documentation

Over the wire

The Petrel wire protocol has a fixed 10-byte header, two run-length encoded data segments, and an optional 44-byte HMAC segment.

Seqence number    uint32 (4 bytes)
Protocol version  uint8  (1 byte)
Request length    uint8  (1 byte)
Payload length    uint32 (4 bytes)
------------------------------------
Request text      Per request length
Payload text      Per payload length
------------------------------------
HMAC              44 bytes, optional

There is no need for wire messages to specify whether HMAC is included or not, as that is negotiated between the client and server at connection time.

Documentation

Index

Constants

View Source
const (
	Debug = iota
	Conn
	Error
	Fatal
)

Message levels control which messages will be sent to h.Msgr

View Source
const (
	// Proto is the version of the wire protocol implemented by
	// this library
	Proto = uint8(0)
)

Variables

View Source
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}
)
View Source
var (
	Sigchan chan os.Signal
)

Functions

func ConnRead added in v0.33.0

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

ConnRead reads a message from a connection.

func ConnReadRaw added in v0.33.0

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

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

func ConnWrite added in v0.33.0

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

ConnWrite writes a message to a connection.

func ConnWriteRaw added in v0.33.0

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.

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL