avro-gen-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba3c25a3781ca50da7273e62f05126ffe641538096cae34178161cae558a20ff
+  data.tar.gz: b8c25703ca1cda292d6fb50e2158a75a6b3b7a7dbe7109908fb55db129ab7545
+SHA512:
+  metadata.gz: bee416615047e91d012ceb396a9249990fb748b8e951f13d7d5296a7b4d5ba36f2ff1a748974171fc0351b3df3ae8500e4bbb5551a0c334abfebe7300beaf741
+  data.tar.gz: c4c97a2939069802696506c370b4e72582dffa5d6b97f9cc8ba2d08e2c4840fe7d572ad7ed0790b9256c8c92d071b1f3e49907ed580bf4a8ec96461564425edd

data/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  linting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby 3.3
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.3
+          bundler-cache: true
+      - name: Rubocop
+        run: bundle exec rubocop --format progress
+
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ '3.2', '3.3', '3.4', '4.0' ]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Test
+        run: bundle exec rspec

data/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release Gem
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*.*.*' # Matches semantic versioning tags like v1.0.0
+  workflow_dispatch: # Allows manual triggering of the workflow
+
+jobs:
+  push:
+    name: Push gem to RubyGems.org
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+      contents: write # IMPORTANT: this permission is required for `rake release` to push the release tag
+
+    steps:
+      # Set up
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ruby
+
+      # Release
+      - uses: rubygems/release-gem@v1

data/.gitignore

@@ -0,0 +1,6 @@
+/.bundle/
+/Gemfile.lock
+/pkg/
+/tmp/
+/spec/app/
+*.gem

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper --format documentation

data/.rubocop.yml

@@ -0,0 +1,100 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - vendor/**/*
+    - spec/app/**/*
+    - spec/schemas/**/*
+    - spec/snapshots/**/*
+
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: gemspec
+
+Layout/AccessModifierIndentation:
+  EnforcedStyle: outdent
+
+Layout/DotPosition:
+  EnforcedStyle: trailing
+
+Layout/LineLength:
+  Max: 120
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: no_space
+
+Lint/UnusedBlockArgument:
+  AllowUnusedKeywordArguments: true
+
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Lint/MissingSuper:
+  Enabled: false
+
+Metrics:
+  Enabled: false
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    '%i': '()'
+    '%I': '()'
+    '%w': '()'
+    '%W': '()'
+
+Style/RedundantSelf:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/SymbolArray:
+  EnforcedStyle: percent
+
+RSpec/ExampleWording:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/HookArgument:
+  EnforcedStyle: each
+
+RSpec/LeakyConstantDeclaration:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flipp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,61 @@
+# avro-gen-ruby
+
+Generate Ruby schema classes / models from Avro schemas.
+
+`avro-gen-ruby` (namespace `AvroGen`) takes a directory of Avro `.avsc` schema files
+and generates plain-Ruby classes for each record and enum, giving you typed,
+IDE-friendly objects to work with instead of raw hashes. It was extracted from
+[deimos-ruby](https://github.com/flipp-oss/deimos), which now depends on it.
+
+## Installation
+
+```ruby
+gem 'avro-gen-ruby'
+```
+
+## Configuration
+
+```ruby
+AvroGen.configure do |config|
+  config.schema_path = 'avro/schemas'
+  config.generated_class_path = 'app/lib/schema_classes'
+  config.nest_child_schemas = true
+  config.use_full_namespace = false
+  config.schema_namespace_map = {}
+  config.root_module = 'Schemas'
+end
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `schema_path` | `nil` | Local path to the directory containing your Avro `.avsc` schema files. Required for generation. |
+| `generated_class_path` | `app/lib/schema_classes` | Local path that generated schema classes are written to. |
+| `nest_child_schemas` | `true` | When `true`, subschemas (nested records/enums) are nested inside the generated class for the parent schema. When `false`, each subschema is generated as its own file. |
+| `use_full_namespace` | `false` | When `true`, generate nested folders/modules matching the full Avro namespace (e.g. `com.my-org.Foo` → `Schemas::Com::MyOrg::Foo`). When `false`, all classes are generated directly under the root module. |
+| `schema_namespace_map` | `{}` | A map of namespace prefixes to base module name(s), used to reduce nesting when `use_full_namespace` is `true`. Example: `{ 'com.mycompany.suborg' => ['SchemaClasses'] }` generates classes under `SchemaClasses::` instead of `Schemas::Com::Mycompany::Suborg::`. Has no effect unless `use_full_namespace` is `true`. |
+| `root_module` | `'Schemas'` | The top-level module that generated classes are nested under. |
+
+## Usage
+
+Generate classes for every schema in `schema_path`:
+
+```bash
+rake avro:generate
+```
+
+Generated classes inherit from `AvroGen::SchemaClass::Record` / `AvroGen::SchemaClass::Enum`
+and are namespaced under the configured `root_module` (default `Schemas`).
+
+### Migrating from Deimos
+
+If you previously generated classes with Deimos, they reference `Deimos::SchemaClass::*`.
+Those still load (Deimos maps them to the AvroGen equivalents with a deprecation warning),
+but you can rewrite them in place:
+
+```bash
+rake avro:upgrade
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+  task(default: :spec)
+rescue LoadError
+  # no rspec available
+end

data/avro-gen-ruby.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'avro_gen/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'avro-gen-ruby'
+  spec.version       = AvroGen::VERSION
+  spec.authors       = ['Daniel Orner']
+  spec.email         = ['daniel.orner@flipp.com']
+  spec.summary       = 'Generate Ruby schema classes from Avro schemas.'
+  spec.homepage      = 'https://github.com/flipp-oss/avro-gen-ruby'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.add_dependency('activesupport', '>= 6.0')
+  spec.add_dependency('avro', '~> 1.9')
+  spec.add_dependency('railties', '>= 6.0')
+  spec.add_dependency('schema_registry_client')
+
+  spec.add_development_dependency('rake', '~> 13')
+  spec.add_development_dependency('rspec', '~> 3')
+  spec.add_development_dependency('rspec-snapshot', '~> 2.0')
+  spec.add_development_dependency('rubocop', '~> 1.0')
+  spec.add_development_dependency('rubocop-rspec', '~> 3.0')
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/avro_gen/avro_parser.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'avro'
+require 'active_support/core_ext/string'
+
+module AvroGen
+  # Helper methods for interpreting Avro schema objects when generating classes.
+  module AvroParser
+    class << self
+      # @param schema [Avro::Schema::NamedSchema] A named schema
+      # @return [String]
+      def schema_classname(schema)
+        schema.name.underscore.camelize.singularize
+      end
+
+      # Converts Avro::Schema::NamedSchema's to String form for generated YARD docs.
+      # Recursively handles the typing for Arrays, Maps and Unions.
+      # @param avro_schema [Avro::Schema::NamedSchema]
+      # @return [String] A string representation of the Type of this SchemaField
+      def field_type(avro_schema)
+        case avro_schema.type_sym
+        when :string, :boolean
+          avro_schema.type_sym.to_s.titleize
+        when :int, :long
+          'Integer'
+        when :float, :double
+          'Float'
+        when :record, :enum
+          schema_classname(avro_schema)
+        when :array
+          arr_t = field_type(AvroGen::SchemaField.new('n/a', avro_schema.items).type)
+          "Array<#{arr_t}>"
+        when :map
+          map_t = field_type(AvroGen::SchemaField.new('n/a', avro_schema.values).type)
+          "Hash<String, #{map_t}>"
+        when :union
+          types = avro_schema.schemas.map do |t|
+            field_type(AvroGen::SchemaField.new('n/a', t).type)
+          end
+          types.join(', ')
+        when :null
+          'nil'
+        end
+      end
+
+      # Returns the base type of this schema. Decodes Arrays, Maps and Unions
+      # @param schema [Avro::Schema::NamedSchema]
+      # @return [Avro::Schema::NamedSchema]
+      def schema_base_class(schema)
+        case schema.type_sym
+        when :array
+          schema_base_class(schema.items)
+        when :map
+          schema_base_class(schema.values)
+        when :union
+          schema.schemas.map(&method(:schema_base_class)).
+            reject { |s| s.type_sym == :null }.first
+        else
+          schema
+        end
+      end
+    end
+  end
+end

data/lib/avro_gen/configuration.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module AvroGen
+  # Configuration for schema class generation.
+  class Configuration
+    # Local path to look for Avro schemas (.avsc files) in.
+    # @return [String]
+    attr_accessor :schema_path
+
+    # Local path for schema classes to be generated in.
+    # @return [String]
+    attr_accessor :generated_class_path
+
+    # Set to false to generate child schemas as their own files.
+    # @return [Boolean]
+    attr_accessor :nest_child_schemas
+
+    # Set to true to generate folders matching the last part of the schema namespace.
+    # @return [Boolean]
+    attr_accessor :use_full_namespace
+
+    # Use this option to reduce nesting when using use_full_namespace.
+    # For example: { 'com.mycompany.suborg' => 'SchemaClasses' }
+    # would replace a prefix matching the given key with the module name SchemaClasses.
+    # @return [Hash]
+    attr_accessor :schema_namespace_map
+
+    # The top-level module that generated classes are nested under.
+    # @return [String]
+    attr_accessor :root_module
+
+    def initialize
+      reset!
+    end
+
+    # Restore all settings to their defaults.
+    # @return [void]
+    def reset!
+      @schema_path = nil
+      @generated_class_path = 'app/lib/schema_classes'
+      @nest_child_schemas = true
+      @use_full_namespace = false
+      @schema_namespace_map = {}
+      @root_module = 'Schemas'
+    end
+  end
+
+  class << self
+    # @return [AvroGen::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yieldparam [AvroGen::Configuration]
+    # @return [void]
+    def configure
+      yield config if block_given?
+    end
+  end
+end

data/lib/avro_gen/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AvroGen
+  # Raised when a subclass fails to implement a required method.
+  class MissingImplementationError < StandardError; end
+end

data/lib/avro_gen/generator/templates/schema_class.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# This file is autogenerated by AvroGen, Do NOT modify
+<%= @modules.map { |m| "module #{m}"}.join('; ') %>
+  ### Primary Schema Class ###
+  <%=- @main_class_definition -%>
+
+<%= @modules.map { "end" }.join('; ') %>

data/lib/avro_gen/generator/templates/schema_enum.rb.tt

@@ -0,0 +1,13 @@
+  # Autogenerated Schema for Enum at <%= @current_schema.namespace %>.<%= @current_schema.name %>
+  class <%= AvroGen::AvroParser.schema_classname(@current_schema) %> < AvroGen::SchemaClass::Enum
+    # @override
+    def symbols
+      %w(<%= @current_schema.symbols.join(' ') %>)
+    end
+
+    <% @current_schema.symbols.each do |symbol| %>
+    def <%= symbol.underscore %>?
+      @value == '<%= symbol %>'
+    end
+    <% end %>
+  end

data/lib/avro_gen/generator/templates/schema_record.rb.tt

@@ -0,0 +1,102 @@
+  # Autogenerated Schema for Record at <%= @current_schema.namespace %>.<%= @current_schema.name %>
+  class <%= AvroGen::AvroParser.schema_classname(@current_schema) %> < AvroGen::SchemaClass::Record
+<% if @sub_schema_templates.present? -%>
+
+    ### Secondary Schema Classes ###
+  <%- @sub_schema_templates.each do |schema_template| -%>
+  <%=- schema_template.gsub(/^/, "  ") %>
+
+  <%- end -%>
+<% end -%>
+
+  <%- if @field_assignments.select{ |h| h[:is_schema_class] }.any? -%>
+    ### Attribute Readers ###
+  <%- @field_assignments.select{ |h| h[:is_schema_class] }.each do |method_definition| -%>
+    # @return [<%= method_definition[:deimos_type] %>]
+    attr_reader :<%= method_definition[:field].name %>
+  <%- end -%>
+
+<% end -%>
+<%- if @field_assignments.select{ |h| !h[:is_schema_class] }.any? -%>
+    ### Attribute Accessors ###
+  <%- @field_assignments.select{ |h| !h[:is_schema_class] }.each do |method_definition| -%>
+    # @return [<%= method_definition[:deimos_type] %>]
+    attr_accessor :<%= method_definition[:field].name %>
+  <%- end -%>
+
+<% end -%>
+<%- if @field_assignments.select{ |h| h[:is_schema_class] }.any? -%>
+    ### Attribute Writers ###
+  <%- @field_assignments.select{ |h| h[:is_schema_class] }.each do |method_definition| -%>
+    # @return [<%= method_definition[:deimos_type] %>]
+    def <%= method_definition[:field].name %>=(<%= method_definition[:method_argument] %>)
+    <%- if method_definition[:field_type] == :array -%>
+      @<%= method_definition[:field].name %> = values&.map do |value|
+        <%= method_definition[:field_initialization] %>
+      end
+    <%- elsif method_definition[:field_type] == :map -%>
+      @<%= method_definition[:field].name %> = values&.transform_values do |value|
+        <%= method_definition[:field_initialization] %>
+      end
+    <%- else -%>
+      @<%= method_definition[:field].name %> = <%= method_definition[:field_initialization] %>
+    <%- end -%>
+    end
+
+  <%- end -%>
+<% end -%>
+<%- if @field_assignments.select{ |h| h[:is_complex_union] }.any? -%>
+    <%- @field_assignments.select{ |h| h[:is_complex_union] }.each do |method_definition| -%>
+    # Helper method to determine which schema type to use for <%= method_definition[:field].name %>
+    # @param value [Hash, nil]
+    # @param from_message [Boolean] whether this was initialized from a real Avro message
+    # @return [Object, nil]
+    def initialize_<%= method_definition[:field].name %>_type(value, from_message: false)
+      return nil if value.nil?
+
+      klass = [<%= method_definition[:field].type.schemas.reject { |s| s.type_sym == :null }.select { |s| s.type_sym == :record }.map { |s| AvroGen::AvroParser.schema_classname(s) }.join(', ') %>].find do |candidate|
+        fields = candidate.new.as_json.keys
+        (value.keys - fields).empty?
+      end
+
+      klass.initialize_from_value(value, from_message: self._from_message)
+    end
+
+    <%- end -%>
+<% end -%>
+    # @override
+    <%= @initialization_definition %>
+      @_from_message = _from_message
+      super
+<%- @fields.each do |field| -%>
+      self.<%= field.name %> = <%= field.name %>
+<% end -%>
+    end
+
+    # @override
+    def schema
+      '<%= @current_schema.name %>'
+    end
+
+    # @override
+    def namespace
+      '<%= @current_schema.namespace %>'
+    end
+<%- if @tombstone_assignment %>
+    def self.tombstone(key)
+      record = self.allocate
+<%- if @tombstone_assignment.present? -%>
+      <%= @tombstone_assignment %>
+<%- end -%>
+      record
+    end
+<%- end %>
+    # @override
+    def as_json(_opts={})
+      {
+<%- @fields.each do |field| -%>
+        <%= field_as_json(field) %>
+<% end -%>
+      }
+    end
+  end