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.

Contents

• Server
• Client
• Wire protocol

Server

• Server

Signal handling

Embedding a Petrel server in your code gets you handlers for SIGINT and SIGTERM, for free. At the moment, Petrel does not handle pidfiles.

Client

• Client
• Examples

Wire protocol

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 messages to specify whether HMAC is included or not, as that is set between the client and server at connection time.