/go-capnproto2

Cap'n Proto library and code generator for Go

Primary LanguageGoOtherNOASSERTION

Cap'n Proto bindings for Go

License CodeQuality Go GoDoc Matrix

Cap’n Proto is an insanely fast data interchange format similar to Protocol Buffers, but much faster.

It also includes a sophisticated RPC system based on Object Capabilities, ideal for secure, low-latency applications.

This package provides:

  • Go code-generation for Cap'n Proto
  • Runtime support for the Go language
  • Level 1 support for the Cap'n Proto RPC protocol

Support for Level 3 RPC is planned.

Installation

To interact with pre-compiled schemas

Ensure that Go modules are enabled, then run the following command:

$ go get capnproto.org/go/capnp/v3

To compile Cap'n Proto schema files to Go

Two additional steps are needed to compile .capnp files to Go:

  1. Install the Cap'n Proto tools.
  2. Install the Go language bindings by running:
go install capnproto.org/go/capnp/v3/capnpc-go@latest  # install go compiler plugin
GO111MODULE=off go get -u capnproto.org/go/capnp/v3/  # install go-capnproto to $GOPATH

To learn how to compile a simple schema, click here.

This package has been tested with version 0.8.0 of the capnp tool.

Documentation

Getting Started

Read the "Getting Started" guide for a high-level introduction to the package API and workflow. A minimal working RPC example can be found here.

Browse rest of the Wiki for in depth explanations of concepts, migration guides, and tutorials.

Help and Support

You can find us on Matrix: Go Cap'n Proto

API Reference

Available on GoDoc.

API Compatibility

Until the official Cap'n Proto spec is finalized, this repository should be considered beta software.

We use semantic versioning to track compatibility and signal breaking changes. In the spirit of the Go 1 compatibility guarantee, we will make every effort to avoid making breaking API changes within major version numbers, but nevertheless reserve the right to introduce breaking changes for reasons related to:

  • Security.
  • Changes in the Cap'n Proto specification.
  • Bugs.

An exception to this rule is currently in place for the pogs package, which is relatively new and may change over time. However, its functionality has been well-tested, and breaking changes are relatively unlikely.

Note also we may merge breaking changes to the main branch without notice. Users are encouraged to pin their dependencies to a major version, e.g. using the semver-aware features of go get.

License

MIT - see LICENSE file