ProtocolBuffers::PP

A pure Perl implementation of Google Protocol Buffers with full proto2/proto3 support, canonical JSON mapping, a protoc code generator plugin, and a gRPC client.

Passes all 2737 required tests in the official protobuf conformance suite and all 211 tests in the ConnectRPC gRPC conformance suite.

Features

• Binary wire format encoding and decoding (varint, zigzag, fixed-width, length-delimited, groups)
• Canonical JSON mapping (ProtoJSON) with proper lowerCamelCase field names, int64-as-string, bytes-as-base64, enum-as-name
• Well-Known Types with special JSON representations: Timestamp, Duration, FieldMask, Any, Struct/Value/ListValue, Wrappers
• gRPC client over HTTP/2 with unary, client-streaming, server-streaming, and bidirectional streaming support
• protoc-gen-perl plugin generates Perl packages from .proto files
• No XS or compiled extensions required

Requirements

• Perl 5.20+ (64-bit integer support required)
• protoc compiler (for code generation)
• Core modules: JSON::PP, MIME::Base64, Math::BigInt, POSIX

Installation

# Install dependencies
cpanm --installdeps .

# Or manually:
cpanm JSON::PP MIME::Base64 Math::BigInt

Usage

Code Generation

Generate Perl packages from .proto files using protoc:

protoc --perl_out=lib/ --plugin=protoc-gen-perl=script/protoc-gen-perl \
    -I /path/to/proto/includes your_message.proto

This produces Perl packages under lib/ mirroring the proto package structure.

Encoding and Decoding

use ProtocolBuffers::PP::Encode qw(encode_message);
use ProtocolBuffers::PP::Decode qw(decode_message);

# Load your generated message class
use Your::Proto::Message;

my $desc = Your::Proto::Message->__DESCRIPTOR__;

# Encode
my $msg = { name => "example", id => 42 };
my $bytes = encode_message($msg, $desc);

# Decode
my $decoded = decode_message($desc, $bytes, $desc);

JSON Serialization

use ProtocolBuffers::PP::JSON::Print;
use ProtocolBuffers::PP::JSON::Parse;

# Message -> JSON string
my $json = ProtocolBuffers::PP::JSON::Print::print_message($msg, $desc);

# JSON string -> Message
my $parsed = ProtocolBuffers::PP::JSON::Parse::parse_message($json, $desc);

gRPC Client

The gRPC client supports unary, client-streaming, server-streaming, and bidirectional RPCs over HTTP/2 with optional TLS.

The code generator produces typed service client stubs from proto service definitions:

use ProtocolBuffers::PP::GRPC::Client;
use Your::Proto::Service;  # generated from your .proto

my $channel = ProtocolBuffers::PP::GRPC::Client->new(
    host     => 'router.example.com',
    port     => 57777,
    tls      => 1,
    timeout  => 10000,
    metadata => [
        ['username', ['admin']],
        ['password', ['secret']],
    ],
);

my $client = Your::Proto::Service::Client->new(channel => $channel);

# Unary RPC
my $response = $client->SomeMethod({ field => 'value' });

# Server streaming (synchronous - returns all messages)
my $messages = $client->ServerStream($request);

# Server streaming (async - callback per message)
$client->ServerStream($request,
    on_message => sub { my ($msg) = @_; ... },
    on_close   => sub { my (%result) = @_; ... },
);

Channel-level metadata is sent with every RPC. Per-call metadata can be passed via the headers option on individual calls.

See example/gnmi/ for a working gNMI client that queries network device capabilities and operational state.

Project Layout

Directory	Contents
lib/ProtocolBuffers/PP/	Runtime: encoding, decoding, JSON mapping, gRPC client, wire format, WKT helpers
lib/ProtocolBuffers/Generated/	Base classes for generated message/enum code
script/	protoc-gen-perl plugin, conformance harnesses, and test wrapper scripts
example/	Working examples: gNMI client, gRPC echo client
conformance/	Conformance config and known-failing lists
docs/	Feature documentation
t/unit/	Unit tests

Testing

# Run unit tests
prove -r t/unit/

# Run the official protobuf conformance suite
script/protobuf-conformance-test --protobuf-root /path/to/protobuf

# Run the gRPC conformance suite
script/grpc-conformance-test --connectrpc-root /path/to/connectrpc-conformance

The conformance wrapper scripts generate types into a temp directory via protoc and locate the test runner binary automatically. See docs/protobuf-conformance.md and docs/grpc-conformance.md for details.

Conformance Status

Suite	Result
Protobuf required tests	2737/2737 passing
Protobuf recommended tests	33 warnings (non-blocking)
gRPC conformance tests	211/211 passing

License

Same terms as Perl itself.