proto-convert

proto-convert is a CLI tool to convert protobuf messages from binary to JSON and vice versa.

Tested on Ubuntu, macOS and Windows runners. For details, see CI workflow.

Installation

Make sure that the Protocol Buffers Compiler protoc is installed. Follow these instructions to install it.

Install proto-convert with RubyGems:

gem install proto-convert

Depending on your installed Ruby version, the latest google-protobuf may not install due to compatibility issues. You need to install the older version yourself or you may choose to upgrade to a later Ruby version.

It has also been observed that the installed protoc and google-protobuf gem may be incompatible and may result into compilation failure of the input file on runtime.

• For Ruby 2.6, protoc v3.17.3 and google-protobuf v3.12 work fine.
• For Ruby 2.7 and later, the latest versions of both should work fine.

Usage

Run proto-convert -h for usage help.

$ proto-convert -h
Usage: bin/proto-convert -m [mode] -p [proto] -t [msgtype] -i [input] -o [output]

OPTIONS:

    -m, --mode [MODE]                conversion mode ["binary2json", "b2j", "json2binary", "j2b"]
    -p, --proto [FILENAME]           protobuf schema (.proto)
    -t, --msgtype [TYPE]             fully-qualified message type
    -i, --input [FILENAME]           source file (JSON/binary)
    -o, --output [FILENAME]          destination file (binary/JSON)
    -v, --verbose                    print verbose information
    -h, --help                       print help

NOTE: Use -v / --verbose flag to print detailed intermediate steps.

Test Run

Consider this simple .proto file (test.proto):

syntax = "proto3";

package test;

message Message {
    int32 id = 1;
    string body = 2;
}

See test directory for test files.

JSON to Binary Conversion

$ proto-convert -m j2b -p test.proto -t test.Message -i test.json -o test.bin
>> [J] test.json (24 bytes)
<< [B] test.bin (8 bytes)

Binary to JSON Conversion

$ proto-convert -m b2j -p test.proto -t test.Message -i test.bin -o test.json
>> [B] test.bin (8 bytes)
<< [J] test.json (24 bytes)

Output:

$ cat test.json
{"id":123,"body":"test"}

Contribute

• Fork the project.
• Check out the latest main branch.
• Create a feature or bugfix branch from main.
• Commit and push your changes.
• Make sure to add tests. See CI.
• Run Rubocop and fix the lint errors.
• Submit the PR.

License

MIT