#buffer #toolkit #reserved #field #prototcol

prototk

prototk provides a toolkit for prototcol buffers

12 releases (breaking)

0.10.0 Oct 8, 2024
0.8.0 Aug 19, 2024
0.6.0 Feb 19, 2024
0.5.0 Dec 27, 2023
0.2.1 Jul 9, 2023

#302 in Encoding

Download history 75/week @ 2024-07-21 92/week @ 2024-07-28 66/week @ 2024-08-04 67/week @ 2024-08-11 389/week @ 2024-08-18 106/week @ 2024-08-25 103/week @ 2024-09-01 51/week @ 2024-09-08 284/week @ 2024-09-15 110/week @ 2024-09-22 75/week @ 2024-09-29 249/week @ 2024-10-06 57/week @ 2024-10-13 37/week @ 2024-10-20 97/week @ 2024-10-27 75/week @ 2024-11-03

278 downloads per month
Used in 26 crates (22 directly)

Apache-2.0

155KB
3.5K SLoC

prototk

prototk provides a toolkit for prototcol buffers.

Status

Maintenance track. The library is considered stable and will be put into maintenance mode if unchanged for one year. The clock was last reset 2023-09-19.

Scope

This library is about serialization and deserialization of messages. It strives to distil protocol buffers to this:

#[derive(Debug, Default, Message)]
pub enum Error {
    #[prototk(278528, message)]
    #[default]
    Success {
        #[prototk(1, message)]
        core: ErrorCore,
    },
    #[prototk(278529, message)]
    SerializationError {
        #[prototk(1, message)]
        core: ErrorCore,
        #[prototk(2, message)]
        err: prototk::Error,
        #[prototk(3, string)]
        context: String,
    },
    #[prototk(278530, message)]
    UnknownServerName {
        #[prototk(1, message)]
        core: ErrorCore,
        #[prototk(2, string)]
        name: String,
    },
    #[prototk(278531, message)]
    UnknownMethodName {
        #[prototk(1, message)]
        core: ErrorCore,
        #[prototk(2, string)]
        name: String,
    },
    #[prototk(278532, message)]
    RequestTooLarge {
        #[prototk(1, message)]
        core: ErrorCore,
        #[prototk(2, uint64)]
        size: u64,
    },
}

// serialize
let err = Error::UnknownServerName {
    core: ErrorCore::new("robert@rescrv.net", "unknown server name", &UNKOWN_SERVER_NAME_COUNTER),
    name: "FooRpcServer",
};
let buf = stack_pack(err).to_vec()

// deserialize
let up = Unpacker::new(&buf);
let err: Error = up.unpack()?;

Warts

  • The derive macro's errors are not the most easy to understand.

Reserved Field Ranges

The error types in my libraries all have diffrent field numbers. Here is where I track them.

  • 262144..262400 prototk::Error
  • 278528..278784 rpc_pb::Error
  • 294912..295168 macarunes::Error
  • 311296..311552 tuple_key::Error
  • 376832..377088 mani::Error
  • 442368..442624 sst::Error
  • 507904..508160 protoql::Error
  • 573440..573696 paxos_pb::Error

Maps

Maps are not supported by prototk natively because the typing is too complicated. Make a MapEntry type that has field number 1 for the key and 2 for the value. Put it in a Vec tagged as a message.

Documentation

The latest documentation is always available at docs.rs.

Dependencies

~1.5MB
~36K SLoC