Cameleer

Protobuf data format

The protobuf data format encodes the message body as Protocol Buffers bytes (or proto3 JSON) using a .proto file, and decodes protobuf data back into a structured body.

Name: protobuf · Crate: cameleer-grpc · Cargo feature: grpc · Apache Camel: Protobuf

When to use it

  • Exchange protobuf messages over Kafka, MQTT or HTTP with services generated by protoc.
  • Decode device telemetry sent as protobuf from edge hardware.
  • Convert between protobuf and JSON at an API gateway.

For gRPC calls, the grpc component uses the same .proto support.

Marshal and unmarshal

directionbody inbody out
marshal, contentTypeFormat: native (default)an object, JSON text, or bytes that are already encodedprotobuf bytes. Sets Content-Type: application/octet-stream.
marshal, contentTypeFormat: jsonan object, JSON text or protobuf bytesproto3 JSON text (lowerCamelCase names). Sets Content-Type: application/json.
unmarshal, nativeprotobuf bytesan object keyed by field name
unmarshal, jsonproto3 JSON textan object

The .proto file is parsed at runtime: proto3 and basic proto2, imports from the same directory, nested types, enums, repeated (packed), map, oneof and the well-known types.

Difference from Apache Camel: no generated Java classes. instanceClass names the protobuf message (edge.Reading; a Java name such as org.acme.Outer$Reading is reduced to Reading), and protoFile points at the .proto file.

Example

The message type used by the examples:

text
syntax = "proto3";
package edge;

message Reading {
  string id = 1;
  double temp = 2;
  bool ok = 3;
}

Encode a JSON reading as protobuf and show the 16 bytes:

yaml example: protobuf-encode
- route:
    id: protobuf-encode
    from:
      uri: direct:protobuf-encode
      steps:
        - marshal:
            protobuf:
              instanceClass: edge.Reading
              protoFile: reading.proto
        - marshal:
            hex: {}
json
{"id":"s-1","temp":21.5,"ok":true}
text
0a03732d311100000000008035401801

Decode protobuf bytes and read a field:

yaml example: protobuf-decode
- route:
    id: protobuf-decode
    from:
      uri: direct:protobuf-decode
      steps:
        - unmarshal:
            hex: {}
        - unmarshal:
            protobuf:
              instanceClass: edge.Reading
              protoFile: reading.proto
        - setBody:
            simple: "${body.id} reports ${body.temp}"
text
0a03732d311100000000008035401801
text
s-1 reports 21.5

Rust DSL

rust
b.from("direct:protobuf-rust")
    .marshal(
        DataFormatDefinition::new("protobuf")
            .option("instanceClass", "edge.Reading")
            .option("protoFile", "reading.proto"),
    );

cameleer_grpc::protobuf("reading.proto", "edge.Reading")? builds the same definition and fails early if the file does not parse.

Options

optiondefaultdescription
instanceClass(none)The protobuf message name, e.g. edge.Reading. Required with protoFile.
protoFile(none)Path of the .proto file.
contentTypeFormatnativenative (binary) or json (proto3 JSON).
contentTypeHeadertrueSet the Content-Type header on marshal.

Without instanceClass and protoFile, the format is configured per message by the headers CamelProtobufInstanceClass, CamelProtobufProtoFile and CamelProtobufContentTypeFormat, or the properties camel.dataformat.protobuf.instanceClass, .protoFile and .contentTypeFormat.

Common questions

Do I need to run protoc?

No. The .proto file is read at runtime; there is no code generation step.

How do I convert protobuf to JSON?

unmarshal with the native format, then marshal: {json: {}}; or marshal with contentTypeFormat: json, which writes proto3 JSON (lowerCamelCase names, enums as names).

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.

Edit this page on GitHub