Skip to content

Protobuf

field_struct-protobuf gives a struct a Protocol Buffers form without a protoc run. It prints .proto source for other teams, registers a message class with google-protobuf, and converts instances to messages, to binary and back.

gem 'field_struct-protobuf'
require 'field_struct/protobuf'

You choose the field numbers. Each field carries proto: {number: n} and the gem never guesses one. require 'field_struct/protobuf' registers proto: as a field option (with FieldStruct.register_option), so require it before those classes; until then the option raises and says which file to require. An unknown key inside proto: raises when the schema or message is built, with a did-you-mean: proto: has no key numbr: (did you mean number:?). If it numbered by declaration order, moving two lines around in a class would quietly change the wire format.

FieldStruct::Protobuf.proto prints the file for a single class. It prints from the descriptor that gets registered, so the text and the registered message can’t drift apart.

require 'field_struct/protobuf'
module Fleet
class Depot < FieldStruct::Base
required :name, :string, proto: { number: 1 }
end
class Trip < FieldStruct::Base
required :route, :string, proto: { number: 1 }
optional :meters, :integer, proto: { number: 2 }
optional :origin, Depot, proto: { number: 3 }
optional :waypoints, :array, of: :string, proto: { number: 4 }
optional :battery, :big_decimal, proto: { number: 5 }
optional :departed, :time, zone: 'America/Denver', proto: { number: 6 }
end
end
text = FieldStruct::Protobuf.proto(Fleet::Trip)
text.lines.grep(/\A(message| )/).map(&:strip)
# => ["message Trip {", "optional string route = 1;", "optional int64 meters = 2;", ".fleet.Depot origin = 3;", "repeated string waypoints = 4;", "optional string battery = 5;", ".google.protobuf.Timestamp departed = 6;"]
FieldStruct::Protobuf.file_name(Fleet::Trip) # => "field_struct/fleet/trip.proto"
FieldStruct::Protobuf.full_name(Fleet::Trip) # => ".fleet.Trip"

Here is the whole file for Fleet::Trip:

// field_struct/fleet/trip.proto: generated by field_struct-protobuf from Fleet::Trip.
// Field numbers come from each field's proto: {number:} option.
syntax = "proto3";
package fleet;
import "field_struct/fleet/depot.proto";
import "google/protobuf/timestamp.proto";
message Trip {
optional string route = 1;
optional int64 meters = 2;
.fleet.Depot origin = 3;
repeated string waypoints = 4;
optional string battery = 5;
.google.protobuf.Timestamp departed = 6;
}

The module Fleet turns into the package. Each class gets its own file with one message in it. A file imports the files of whatever structs it refers to. A struct can refer to itself, but two structs can’t point at each other.

FieldStruct type Protobuf
:binary bytes
:string, :immutable_string, :uuid, :email, :url, :symbol string
:big_decimal, :decimal string, so 19.9 stays exact
:date string, as 2026-11-01
:boolean bool
:integer int64
:float double
:time, :datetime .google.protobuf.Timestamp; the zone: offset is restored on decode
:value .google.protobuf.Value; numbers come back as Floats
a struct class its message
:array, of: X repeated X
:hash, of: X map<string, X>

Singular scalars are all optional, so presence is explicit: a field nobody set reads back as nil, not 0 or an empty string. Arrays and maps differ. Empty and unset look the same on the wire, so an unset array reads back as [] and an unset map as {}.

A map’s keys are Strings, as field_struct keeps them. proto3 has no repeated or map values, so a :hash of arrays or maps is refused, and since a map entry can’t hold null either, encoding a nil value raises "<key>: protobuf map values can't be nil".

class Locker < FieldStruct::Base
required :dock, :string, proto: { number: 1 }
optional :bikes_by_bay, :hash, of: :integer, proto: { number: 2 }
end
FieldStruct::Protobuf.proto(Locker).lines.map(&:strip).grep(/map/) # => ["map<string, int64> bikes_by_bay = 2;"]
bytes = FieldStruct::Protobuf.encode(Locker.new(dock: 'Quay', bikes_by_bay: {east: 4}))
FieldStruct::Protobuf.decode(Locker, bytes).bikes_by_bay # => {"east" => 4}

Take a trip that starts at the north depot and carries a battery reading.

trip = Fleet::Trip.new(route: 'Riverside loop', meters: '5400', origin: { name: 'North depot' },
waypoints: %w[dock-12 dock-31], battery: '87.5', departed: Time.utc(2026, 10, 27, 15, 30))
bytes = FieldStruct::Protobuf.encode(trip)
bytes.encoding # => #<Encoding:BINARY (ASCII-8BIT)>
back = FieldStruct::Protobuf.decode(Fleet::Trip, bytes)
back == trip # => true
back.battery == BigDecimal("87.5") # => true
back.departed.utc_offset # => -21600
back.origin.name # => "North depot"

Code that protoc generates from the printed .proto can read these bytes. The adapter’s own specs prove it by compiling the text with protoc, so this page relies on that claim and does not run it.

message_class builds the message for a class one time and registers it in google-protobuf’s generated pool. to_message and from_message convert a single instance.

depot = Fleet::Depot.new(name: 'Harbour depot')
message = FieldStruct::Protobuf.to_message(depot)
message.name # => "Harbour depot"
FieldStruct::Protobuf.message_class(Fleet::Depot).equal?(message.class) # => true
FieldStruct::Protobuf.from_message(Fleet::Depot, message) == depot # => true

Message field names are the serialize :protobuf names, as given. Pass serialization: when you want the names of another format.

sparse = Fleet::Trip.new(route: 'Riverside loop')
message = FieldStruct::Protobuf.to_message(sparse)
message.has_meters? # => false
FieldStruct::Protobuf.decode(Fleet::Trip, FieldStruct::Protobuf.encode(sparse)).meters # => nil
FieldStruct::Protobuf.decode(Fleet::Trip, FieldStruct::Protobuf.encode(sparse)).waypoints # => []

When there is no exact mapping, the call raises ArgumentError and names the class and field. Cases are a field with no number, a number used twice, a union, an array of arrays, a map of arrays or maps and a custom type.

class Unnumbered < FieldStruct::Base
required :dock, :string
end
class Twice < FieldStruct::Base
required :dock, :string, proto: { number: 2 }
required :slot, :string, proto: { number: 2 }
end
class Either < FieldStruct::Base
required :dock, :union, of: %i[integer string], proto: { number: 1 }
end
refusals = [Unnumbered, Twice, Either].map do |klass|
FieldStruct::Protobuf.proto(klass)
rescue ArgumentError => e
e.message
end
refusals
# => ["Unnumbered: give every field a protobuf field number, e.g. `proto: {number: 1}`; missing on dock", "Twice: field numbers 2 are used twice", "Either#dock is a union, which field_struct-protobuf can't map yet; split it into one field per member type, or declare it :value (a google.protobuf.Value)"]
Call Returns
proto(klass) the .proto text
file_name(klass), full_name(klass), package(klass), message_name(klass) the names given to the file and message
file_descriptor(klass) the registered descriptor
message_class(klass) the google-protobuf message class
to_message(struct), from_message(klass, message) one instance, to a message and back
encode(struct), decode(klass, bytes) binary
  • Output is proto3 only. There is no oneof, enum, service or option.
  • Registration lasts for the process and cannot be undone. If a class gains a field after its message was built, nothing notices, and the stale message rejects the new field. Reloading code means restarting.
  • Each class registers under one serialization:. Asking for a second one raises.
  • For malformed bytes, decode lets Google::Protobuf::ParseError pass through.
  • An integer past 64 bits raises RangeError.
  • format: and in: are not checked here. The struct does that.

FieldStruct, Actionable and their adapters are open source under the MIT license.