Protozoa 🦠

A Protocol Buffers library for Gleam, providing encoding and decoding of protobuf messages.

Features

✅ Complete proto3 support - Messages, enums, nested types, oneofs, maps, and repeated fields
✅ Type-safe encoding/decoding - Compile-time guarantees for message structure
✅ All field types - Full support for all scalar types, including fixed32/fixed64
✅ Wire format compliance - Correct Protocol Buffers binary format
✅ Performance optimized - Efficient encoding and decoding operations

Installation

Add to your gleam.toml:

[dependencies]
protozoa = ">= 2.0.3 and < 3.0.0"

Usage

Basic Encoding and Decoding

import protozoa/encode
import protozoa/decode

// Define your message type
pub type User {
  User(name: String, age: Int, active: Bool)
}

// Encode a message
pub fn encode_user(user: User) -> BitArray {
  encode.message([
    encode.string_field(1, user.name),
    encode.int32_field(2, user.age),
    encode.bool_field(3, user.active),
  ])
}

// Create a decoder
fn user_decoder() -> decode.Decoder(User) {
  use name <- decode.then(decode.string_with_default(1, ""))
  use age <- decode.then(decode.int32_with_default(2, 0))
  use active <- decode.then(decode.bool_with_default(3, False))
  decode.success(User(name: name, age: age, active: active))
}

// Decode a message
pub fn decode_user(data: BitArray) -> Result(User, List(decode.DecodeError)) {
  decode.run(data, user_decoder())
}

Supported Features

Protocol Buffer Features

| Feature | Support | Description | |---------|---------|-------------| | Messages | ✅ Complete | Message definitions with all field types | | Enums | ✅ Complete | Enum definitions with proper value handling | | Services | ✅ Complete | gRPC service definitions with streaming support | | Nested Types | ✅ Complete | Messages and enums nested within messages | | Oneofs | ✅ Complete | Union types with proper variant handling | | Maps | ✅ Complete | Map fields with Dict support | | Repeated Fields | ✅ Complete | List/array fields with proper encoding | | Import System | ✅ Complete | Cross-file dependencies and path resolution | | Well-Known Types | ✅ Complete | Google's standard types auto-imported | | Field Options | ✅ Complete | deprecated, json_name, packed options |

RPC/Service Features

| Streaming Type | Syntax | Support | Generated Code | |---------------|--------|---------|----------------| | Unary | rpc Method(Request) returns (Response) | ✅ | Client/server stubs | | Server Streaming | rpc Method(Request) returns (stream Response) | ✅ | Streaming support | | Client Streaming | rpc Method(stream Request) returns (Response) | ✅ | Streaming support | | Bidirectional | rpc Method(stream Request) returns (stream Response) | ✅ | Bidirectional streaming |

Field Types

| Proto Type | Gleam Type | Wire Type | Support | |------------|------------|-----------|---------| | bool | Bool | Varint | ✅ | | int32, sint32 | Int | Varint | ✅ | | int64, sint64 | Int | Varint | ✅ | | uint32, uint64 | Int | Varint | ✅ | | fixed32, sfixed32 | Int | Fixed32 | ✅ | | fixed64, sfixed64 | Int | Fixed64 | ✅ | | float | Float | Fixed32 | ✅ | | double | Float | Fixed64 | ✅ | | string | String | Length-delimited | ✅ | | bytes | BitArray | Length-delimited | ✅ | | Message types | Custom types | Length-delimited | ✅ | | Enum types | Custom types | Varint | ✅ |

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

License

This project is licensed under the MIT License.