protobufable 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f133f23141bc2f8aef5ad8d1d0dd0f88dd58a51843d468d3b242cf0ec7a6d83
-  data.tar.gz: f030966b166069c87390a9d962904fe363ab36a5a9b9531c66deb4e77c3a67cb
+  metadata.gz: e47657701ef1c828034181cc1bbc82a53445dec597c256ece0d574a088a59949
+  data.tar.gz: 80279d482e808aff6d938f5e791b8a20f56f97f4615019c55f938b9aedb43fce
 SHA512:
-  metadata.gz: 6b3ea92d4a634aa17b4a67b2f612e6d5172c1de26184fb0f5462222f07553ed97091aaa21994f7f8e3c55ec49149aaf74597068e732b97e9f29c2d9af99180b1
-  data.tar.gz: 4895b5014905f7e2e353f31fca6f8b76000560cf474602b0c2f8e3bafcc3efaedb74d15b5e39aa661c6bd6148f628093c6aa96a1469a9d70378dc8e96c5c222a
+  metadata.gz: f2b3025271f7476e546207c56fdd4e0c194436577a4b43cce6f14e64fb3d9805d79570035106f0c87be46455746a5c8f8b9c78b7871e8057468cfde66f7b309d
+  data.tar.gz: ef41c4a81f5b34389ba4b57c99941dff8755dec28f649501a1296a25d01510a0bcb8f133b3951746c0f6aff0c9b602022de89fb80a42b9280d476a0ffde1d6dd

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.0 - 2026-11-05
+
+- `Protobufable::JsonCoder` and `Protobufable::BinaryCoder` are `serialize` coders keeping a
+  message in a `text` column as ProtoJSON or in a `binary` column as wire format. A `json` or
+  `jsonb` column still takes `Protobufable::JsonType`; `JsonCoder` raises `Protobufable::Error`
+  on a row such a column hands back parsed.
+- The Railtie registers the Alba `:timestamp` type on boot when Alba is loaded, unless the
+  application already registered a type by that name. Calling
+  `Protobufable::AlbaBinding.register_timestamp_type!` from an initializer is no longer needed.
+- `Protobufable::AlbaBinding` extends the resource with `with_protobuf` and `message_class`
+  rather than installing them as an Alba helper. On Alba 4 they no longer reach resource
+  instances, where `message_class` shadowed an includer's own, and a resource's own
+  `helper do ... end` no longer adds methods to every bound resource.
+
 ## 0.1.0 - 2026-10-13
 
 Initial release.

data/DESIGN.md

@@ -73,6 +73,10 @@ tracking would compare encoded text. `changed_in_place?` compares decoded messag
 `jsonb` column hands back a canonicalized document whose key order need not match what
 `encode_json` produced, which would otherwise read as a change on every load.
 
+`JsonCoder` and `BinaryCoder` exist for columns the database does not treat as JSON: `text`, and
+`binary` holding bytes such as a ciphertext. They are no answer for a `json` column, because
+`serialize` runs the column's own JSON type around the coder.
+
 ## The problem catalogue
 
 `Problem::Detailable` documents an extension contract for exactly this: prepend a module to the

data/README.md

@@ -76,8 +76,9 @@ render proto_json: Api::GetWidgetResponse.new(widget: WidgetResource.new(widget)
 ### Messages in a column
 
 `Protobufable::JsonType` keeps a message in a `json` or `jsonb` column, declared per attribute.
-It is an `ActiveModel` type, not a `serialize` coder, so dirty tracking and casting behave. See
-[docs/columns.md](docs/columns.md).
+It is an `ActiveModel` type, not a `serialize` coder, so dirty tracking and casting behave. For a
+`text` or `binary` column, `Protobufable::JsonCoder` and `Protobufable::BinaryCoder` are coders
+for `serialize`. See [docs/columns.md](docs/columns.md).
 
 ```ruby
 class Widget < ApplicationRecord

data/docs/columns.md

@@ -32,3 +32,26 @@ in SQL from telling absent from default.
 
 To run `buf.validate` rules over the column before save, see
 [Value validation](validation.md#stored-columns).
+
+## `text` and `binary` columns
+
+A column that is not JSON to the database takes a `serialize` coder instead.
+
+```ruby
+class Credential < ApplicationRecord
+  serialize :secret, coder: Protobufable::BinaryCoder.new(Internal::CredentialSecret)
+  serialize :settings, coder: Protobufable::JsonCoder.new(Internal::WidgetSettings)
+end
+```
+
+`BinaryCoder` stores the wire format, for a `binary` or `bytea` column or anything that holds
+opaque bytes, such as a value encrypted before it is written. `JsonCoder` stores ProtoJSON in a
+`text` column, reading and writing it as `JsonType` does, and takes the same
+`preserve_proto_fieldnames:`. Neither casts from a Hash, and dirty tracking compares encoded
+values. `ColumnValidatable` checks only `JsonType` columns.
+
+`JsonCoder` does not work on a `json` or `jsonb` column. `serialize` layers a coder over the
+column's own type, so the String the coder dumps is JSON-encoded a second time and stored as a
+string literal, and a stored object reaches the coder already parsed into a Hash. `JsonCoder`
+raises `Protobufable::Error` on the latter. Rails refuses only `coder: JSON` on such a column, so
+nothing stops the declaration at boot.

data/docs/responses.md

@@ -32,11 +32,49 @@ declare, and a field no attribute produces, each raise there rather than at resp
 every attribute inside the block — the check runs when `with_protobuf` does, so anything
 declared after it is never compared.
 
-`attributes created_at: :timestamp` needs the converter, because a `google.protobuf.Timestamp`
-field refuses the `ActiveSupport::TimeWithZone` an ActiveRecord column hands back:
+### Nested messages
+
+A message field is an ordinary Alba association: `one` for a singular sub-message, `many` for a
+repeated one, each with a resource bound to that sub-message.
+
+```ruby
+class OwnerResource < ApplicationResource
+  include Protobufable::AlbaBinding
+
+  with_protobuf Api::Owner do
+    attributes :id, :name
+  end
+end
+
+class WidgetResource < ApplicationResource
+  include Protobufable::AlbaBinding
+
+  with_protobuf Api::Widget do
+    attributes :id
+    one :owner, resource: OwnerResource   # Api::Owner owner = 2;
+    many :tags, resource: TagResource     # repeated Api::Tag tags = 3;
+  end
+end
+```
+
+A `nil` association leaves the field unset. Each resource is checked against its own message
+only: `WidgetResource` counts `owner` as one attribute and never looks inside it. Bind the
+associated resource too. With an unbound resource or an inline `one :owner do ... end` block, a
+stray attribute fails only at response time and a missing one comes back empty.
+
+Keys must stay proto field names at every level, so a `transform_keys` or `root_key` on the
+resource breaks the binding.
+
+### Timestamps
+
+`attributes created_at: :timestamp` converts to `Time`, because a `google.protobuf.Timestamp`
+field refuses the `ActiveSupport::TimeWithZone` an ActiveRecord column hands back.
+
+The Railtie registers the `:timestamp` type on boot when Alba is loaded, unless the application
+has already registered a type by that name. Alba's type registry is global, so outside Rails, or
+after `Alba.reset!` in a test suite, register it yourself:
 
 ```ruby
-# config/initializers/protobufable.rb
 Protobufable::AlbaBinding.register_timestamp_type!
 ```
 

data/lib/protobufable/alba_binding.rb

@@ -35,13 +35,11 @@ module Protobufable
     # @return [void]
     #: (untyped base) -> void
     def self.included(base)
-      base.helper(HelperMethods)
+      # Alba's `helper` would also put the DSL on instances (since Alba 4) and adopt this module
+      # as the resource's helper, which a later `helper do ... end` then writes into.
+      base.extend(HelperMethods)
     end
 
-    # Each of these reaches the binding through `self.class`: Alba installs HelperMethods on
-    # instances too, so a bare `message_class` here would resolve to the class-level reader with
-    # `self` being the instance, whose ivar is never set.
-    #
     # @return [Object] the bound message, built from the serialized attributes
     #: () -> untyped
     def as_protobuf = self.class.message_class.new(as_json)
@@ -60,7 +58,7 @@ module Protobufable
         .encode_json(as_protobuf, preserve_proto_fieldnames: true, emit_defaults: false)
     end
 
-    # Class-level DSL, installed through Alba's own helper mechanism.
+    # Class-level DSL.
     #
     # @rbs module-self _AlbaBindingClass
     module HelperMethods
@@ -114,12 +112,10 @@ module Protobufable
     # ActiveSupport::TimeWithZone, which is what an ActiveRecord timestamp column hands back,
     # so a resource serializing one needs the conversion.
     #
-    #   Protobufable::AlbaBinding.register_timestamp_type!
-    #
     #   attribute :created_at, :timestamp
     #
-    # Opt-in rather than done on require: Alba's type registry is global, and a gem should not
-    # add to it behind a host's back.
+    # The Railtie calls this on boot unless `:timestamp` is already registered. Outside Rails, or
+    # after `Alba.reset!`, call it directly.
     #
     # @return [void]
     #: () -> void

data/lib/protobufable/binary_coder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "protobufable"
+
+module Protobufable
+  # A `serialize` coder storing a protobuf message as its binary wire format, for a `binary` or
+  # `bytea` column.
+  #
+  # @example
+  #   class Credential < ApplicationRecord
+  #     serialize :secret, coder: Protobufable::BinaryCoder.new(Internal::CredentialSecret)
+  #   end
+  class BinaryCoder
+    # @return [Class] the generated message class this column holds
+    attr_reader :message_class #: Google::Protobuf::_MessageClass
+
+    # @param message_class [Class] the generated message class this column holds
+    # @return [void]
+    #: (Google::Protobuf::_MessageClass message_class) -> void
+    def initialize(message_class)
+      @message_class = message_class
+    end
+
+    # @param bytes [String, nil] the stored bytes
+    # @return [Object, nil] the decoded message, or nil for a null column
+    #: (String? bytes) -> untyped
+    def load(bytes)
+      return if bytes.nil?
+
+      @message_class.decode(bytes)
+    end
+
+    # @param message [Object, nil] the message to store
+    # @return [String, nil] the encoded bytes, or nil
+    #: (untyped message) -> String?
+    def dump(message)
+      return if message.nil?
+
+      @message_class.encode(message)
+    end
+  end
+end

data/lib/protobufable/json_coder.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "protobufable"
+
+module Protobufable
+  # A `serialize` coder storing a protobuf message as ProtoJSON in a `text` column.
+  #
+  # It cannot serve a `json` or `jsonb` column. `serialize` layers the coder over the column's
+  # own type, which encodes the String {#dump} returns a second time, storing a JSON string
+  # literal, and parses a stored object into a Hash before {#load} sees it. Use {JsonType}.
+  #
+  # @example
+  #   class Widget < ApplicationRecord
+  #     serialize :settings, coder: Protobufable::JsonCoder.new(Internal::WidgetSettings)
+  #   end
+  class JsonCoder
+    # @return [Class] the generated message class this column holds
+    attr_reader :message_class #: Google::Protobuf::_MessageClass
+
+    # @param message_class [Class] the generated message class this column holds
+    # @param preserve_proto_fieldnames [Boolean] whether documents are written with the
+    #   `.proto` field names (`snake_case`) rather than their lowerCamelCase JSON names
+    # @return [void]
+    #: (Google::Protobuf::_MessageClass message_class, ?preserve_proto_fieldnames: bool) -> void
+    def initialize(message_class, preserve_proto_fieldnames: false)
+      @message_class = message_class
+      @preserve_proto_fieldnames = preserve_proto_fieldnames
+    end
+
+    # Decodes a stored document, tolerating unknown fields as {JsonType#deserialize} does.
+    #
+    # @param json [String, nil] the stored document
+    # @return [Object, nil] the decoded message, or nil for a null column
+    # @raise [Error] when handed an already parsed document, as a json column does
+    #: (untyped json) -> untyped
+    def load(json)
+      return if json.nil?
+
+      unless json.is_a?(::String)
+        raise Error,
+          "#{self.class} received a #{json.class} rather than a String; " \
+            "a json or jsonb column needs Protobufable::JsonType instead"
+      end
+
+      @message_class.decode_json(json, ignore_unknown_fields: true)
+    end
+
+    # Encodes a message, emitting defaults as {JsonType#serialize} does.
+    #
+    # @param message [Object, nil] the message to store
+    # @return [String, nil] the document to write, or nil
+    #: (untyped message) -> String?
+    def dump(message)
+      return if message.nil?
+
+      @message_class.encode_json(
+        message,
+        emit_defaults: true,
+        preserve_proto_fieldnames: @preserve_proto_fieldnames,
+      )
+    end
+  end
+end

data/lib/protobufable/railtie.rb

@@ -10,8 +10,8 @@ require "action_dispatch/railtie"
 require "protobufable"
 
 module Protobufable
-  # Installs the renderers and the request body parser on boot, and classifies a broken
-  # `buf.validate` rule as a 400.
+  # Installs the renderers and the request body parser on boot, classifies a broken
+  # `buf.validate` rule as a 400, and registers the Alba `:timestamp` type when Alba is loaded.
   class Railtie < ::Rails::Railtie
     # A string, so protovalidate stays unloaded for an application that does not use it.
     # `config.action_dispatch` is answered by method_missing, which RBS cannot describe.
@@ -22,5 +22,15 @@ module Protobufable
     initializer "protobufable.install" do
       Protobufable.install!
     end
+
+    # Leaves a `:timestamp` type the application registered itself in place.
+    initializer "protobufable.alba" do
+      next unless defined?(::Alba)
+
+      ::Alba.find_type(:timestamp)
+    rescue ::Alba::UnsupportedType
+      require "protobufable/alba_binding"
+      Protobufable::AlbaBinding.register_timestamp_type!
+    end
   end
 end

data/lib/protobufable/version.rb

@@ -6,5 +6,5 @@
 
 module Protobufable
   # The gem's version.
-  VERSION = "0.1.0" #: String
+  VERSION = "0.2.0" #: String
 end

data/lib/protobufable.rb

@@ -9,6 +9,8 @@ require "google/protobuf/well_known_types"
 
 require "protobufable/version"
 require "protobufable/json_type"
+require "protobufable/json_coder"
+require "protobufable/binary_coder"
 require "protobufable/request_parseable"
 require "protobufable/renderers"
 

data/sig/generated/protobufable/alba_binding.rbs

@@ -28,10 +28,6 @@ module Protobufable
     # : (untyped base) -> void
     def self.included: (untyped base) -> void
 
-    # Each of these reaches the binding through `self.class`: Alba installs HelperMethods on
-    # instances too, so a bare `message_class` here would resolve to the class-level reader with
-    # `self` being the instance, whose ivar is never set.
-    #
     # @return [Object] the bound message, built from the serialized attributes
     # : () -> untyped
     def as_protobuf: () -> untyped
@@ -47,7 +43,7 @@ module Protobufable
     # : (*untyped) -> String
     def to_json: (*untyped) -> String
 
-    # Class-level DSL, installed through Alba's own helper mechanism.
+    # Class-level DSL.
     #
     # @rbs module-self _AlbaBindingClass
     module HelperMethods : _AlbaBindingClass
@@ -77,12 +73,10 @@ module Protobufable
     # ActiveSupport::TimeWithZone, which is what an ActiveRecord timestamp column hands back,
     # so a resource serializing one needs the conversion.
     #
-    #   Protobufable::AlbaBinding.register_timestamp_type!
-    #
     #   attribute :created_at, :timestamp
     #
-    # Opt-in rather than done on require: Alba's type registry is global, and a gem should not
-    # add to it behind a host's back.
+    # The Railtie calls this on boot unless `:timestamp` is already registered. Outside Rails, or
+    # after `Alba.reset!`, call it directly.
     #
     # @return [void]
     # : () -> void

data/sig/generated/protobufable/binary_coder.rbs

@@ -0,0 +1,30 @@
+# Generated from lib/protobufable/binary_coder.rb with RBS::Inline
+
+module Protobufable
+  # A `serialize` coder storing a protobuf message as its binary wire format, for a `binary` or
+  # `bytea` column.
+  #
+  # @example
+  #   class Credential < ApplicationRecord
+  #     serialize :secret, coder: Protobufable::BinaryCoder.new(Internal::CredentialSecret)
+  #   end
+  class BinaryCoder
+    # @return [Class] the generated message class this column holds
+    attr_reader message_class: Google::Protobuf::_MessageClass
+
+    # @param message_class [Class] the generated message class this column holds
+    # @return [void]
+    # : (Google::Protobuf::_MessageClass message_class) -> void
+    def initialize: (Google::Protobuf::_MessageClass message_class) -> void
+
+    # @param bytes [String, nil] the stored bytes
+    # @return [Object, nil] the decoded message, or nil for a null column
+    # : (String? bytes) -> untyped
+    def load: (String? bytes) -> untyped
+
+    # @param message [Object, nil] the message to store
+    # @return [String, nil] the encoded bytes, or nil
+    # : (untyped message) -> String?
+    def dump: (untyped message) -> String?
+  end
+end

data/sig/generated/protobufable/json_coder.rbs

@@ -0,0 +1,40 @@
+# Generated from lib/protobufable/json_coder.rb with RBS::Inline
+
+module Protobufable
+  # A `serialize` coder storing a protobuf message as ProtoJSON in a `text` column.
+  #
+  # It cannot serve a `json` or `jsonb` column. `serialize` layers the coder over the column's
+  # own type, which encodes the String {#dump} returns a second time, storing a JSON string
+  # literal, and parses a stored object into a Hash before {#load} sees it. Use {JsonType}.
+  #
+  # @example
+  #   class Widget < ApplicationRecord
+  #     serialize :settings, coder: Protobufable::JsonCoder.new(Internal::WidgetSettings)
+  #   end
+  class JsonCoder
+    # @return [Class] the generated message class this column holds
+    attr_reader message_class: Google::Protobuf::_MessageClass
+
+    # @param message_class [Class] the generated message class this column holds
+    # @param preserve_proto_fieldnames [Boolean] whether documents are written with the
+    #   `.proto` field names (`snake_case`) rather than their lowerCamelCase JSON names
+    # @return [void]
+    # : (Google::Protobuf::_MessageClass message_class, ?preserve_proto_fieldnames: bool) -> void
+    def initialize: (Google::Protobuf::_MessageClass message_class, ?preserve_proto_fieldnames: bool) -> void
+
+    # Decodes a stored document, tolerating unknown fields as {JsonType#deserialize} does.
+    #
+    # @param json [String, nil] the stored document
+    # @return [Object, nil] the decoded message, or nil for a null column
+    # @raise [Error] when handed an already parsed document, as a json column does
+    # : (untyped json) -> untyped
+    def load: (untyped json) -> untyped
+
+    # Encodes a message, emitting defaults as {JsonType#serialize} does.
+    #
+    # @param message [Object, nil] the message to store
+    # @return [String, nil] the document to write, or nil
+    # : (untyped message) -> String?
+    def dump: (untyped message) -> String?
+  end
+end

data/sig/generated/protobufable/railtie.rbs

@@ -1,8 +1,8 @@
 # Generated from lib/protobufable/railtie.rb with RBS::Inline
 
 module Protobufable
-  # Installs the renderers and the request body parser on boot, and classifies a broken
-  # `buf.validate` rule as a 400.
+  # Installs the renderers and the request body parser on boot, classifies a broken
+  # `buf.validate` rule as a 400, and registers the Alba `:timestamp` type when Alba is loaded.
   class Railtie < ::Rails::Railtie
   end
 end

data/sig/manual/alba_binding.rbs

@@ -2,6 +2,10 @@
 # is declared, and the resource DSL stays untyped: it is Alba's to describe, not ours.
 module Alba
   def self.register_type: (Symbol name, converter: untyped, ?auto_convert: bool) -> void
+  def self.find_type: (Symbol name) -> untyped
+
+  class UnsupportedType < StandardError
+  end
 
   module Resource
   end
@@ -21,7 +25,6 @@ module Protobufable
       def message_class: () -> Google::Protobuf::_MessageClass
       def name: () -> String?
       def module_eval: () { () -> void } -> untyped
-      def helper: (Module) -> void
       def instance_variable_get: (Symbol) -> untyped
       def class_eval: () { () -> void } -> untyped
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protobufable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sorah Fukumori
@@ -241,10 +241,12 @@ files:
 - lib/protobufable.rb
 - lib/protobufable/alba_binding.rb
 - lib/protobufable/bad_request.rb
+- lib/protobufable/binary_coder.rb
 - lib/protobufable/column_validatable.rb
 - lib/protobufable/connect.rb
 - lib/protobufable/connect/problem_rescuable.rb
 - lib/protobufable/field_path.rb
+- lib/protobufable/json_coder.rb
 - lib/protobufable/json_type.rb
 - lib/protobufable/problem.rb
 - lib/protobufable/problem/information.rb
@@ -264,10 +266,12 @@ files:
 - sig/generated/protobufable.rbs
 - sig/generated/protobufable/alba_binding.rbs
 - sig/generated/protobufable/bad_request.rbs
+- sig/generated/protobufable/binary_coder.rbs
 - sig/generated/protobufable/column_validatable.rbs
 - sig/generated/protobufable/connect.rbs
 - sig/generated/protobufable/connect/problem_rescuable.rbs
 - sig/generated/protobufable/field_path.rbs
+- sig/generated/protobufable/json_coder.rbs
 - sig/generated/protobufable/json_type.rbs
 - sig/generated/protobufable/problem.rbs
 - sig/generated/protobufable/problem/information.rbs