capnp

Cap'n Proto for Haskell https://github.com/zenhack/haskell-capnp

Latest on Hackage:0.4.0.0

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.

MIT licensed by Ian Denhardt
Maintained by ian@zenhack.net

build status hackage

A Haskell library for the Cap’N Proto Cerialization and RPC protocol.

Getting Started

There is a module Capnp.Tutorial which contains an introduction to the library; users are strongly encouraged to read this first, as the reference documentation can be bewildering without that context.

Status

Serialization support works, with some limitations:

  • Generated schema currently ignore type parameters (#29).
  • We do not support define custom default values for fields of pointer type; see (#28).
  • We currently do not correctly handle decoding lists of structs from non-composite lists (#27). This means that, contrary to the protocol evolution rules, it is not safe to change a field from type List(T) (where T is any non-struct type) to a list of a struct type.

Level 1 RPC support is implemented and usable, though there are a couple gaps in the API. It should be considered alpha quality for now. Specific things to be aware of:

  • The implementation is not robust against resource exhaustion attacks; for now users are strongly discouraged from using it to do RPC with untrusted peers.
  • While most of the machinery for it is in place, the API does not currently expose a way to do field projection on remote promises. As a consequence, actually pipelining method calls is not currently possible, so the library is currently best suited to environments which are already low-latency.

The API is considered unstable. It will likely see changes, for the sake of polish, consistency, etc. as well as to improve performance and accommodate more features as we add them.

Changes

0.4.0.0

  • RPC support! This should be considered alpha quality for now. The API will likely change substantially.
  • Many bug fixes; users are strongly encouraged to upgrade.
  • Reorganization of the module hierarchy:
    • Generated code is now placed under Capnp.Gen, rather than Capnp.
    • The Data prefix has been removed from the Data.Capnp hierarchy.
  • The included generated modules for the core schema have been updated to those shipped with version 0.7 of the reference implementation.
  • Other miscellaneous API Changes:
    • createPure can now be used with any instance of MonadThrow, not just Either SomeException.
    • LimitT m is now an instance of MonadIO, provided that m is an instance.
    • More type class instances from elsewhere in the library are re-exported via the Capnp module.
    • The IsPtr type class has been split into FromPtr and ToPtr. Most user code should not care about this.
    • Generated high-level types no longer have Read instances; interfaces make this problematic.
    • Getters for anonymous unions are now get_Foo' instead of get_Foo'union'.
    • newMessage now accepts an optional size hint.
    • Instances of Cerialize now exist/are generated for (Vector (Vector (Vector ...))) up to a reasonable depth.
  • Other improvements not directly reflected in the API:
    • The allocation strategy has changed to reduce unnecessary copying.
    • It is now possible to create messages with a size > 2GiB. Note that individual segments are still limited.

0.3.0.0

  • Instances of some type classes are no longer generated for “second class” types (i.e. types which cannot appear as stand-alone definitions in schema files – groups and unions).
  • has_* functions are now only generated for pointer fields.
  • Various non-functional changes in the output of the code generator.
  • We now generate constants for (most) pointer types; previously constants defined in a schema would not result in any generated code (#41).
  • The set_* functions now check if the arguments are in the same message, and copy if need be (#34).
  • MutMsg is now an instance of Eq.
  • The HasMessage class from Data.Capnp.Untyped is now a type family, rather than a multi-parameter type class. This improves inference and removes some superfluous generalization.
  • The module Data.Capnp.Pure has been folded into Data.Capnp. If you were previously using the Text and Data type aliases it exported, you should instead use Text from Data.Text and ByteString from Data.ByteString; the Text and Data exported by Data.Capnp are types from the low-level API.

0.2.0.0

  • Redesign the ‘Mutable’ type class’s API.
  • Provide helpers for doing zero-copy message creation in pure code.
  • General improvements to the documentation.

0.1.0.0

  • First release; basic read & write support, serialization only.
comments powered byDisqus