ree_lib 1.3.9 → 1.3.11

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/wrappers/abstract_wrapper.rb

@@ -6,6 +6,11 @@ class ReeMapper::AbstractWrapper
     @subject = field
   end
 
+  # See ReeMapper::AbstractType#db_load_trusted_check. Wrappers always cast.
+  def db_load_trusted_check(var)
+    nil
+  end
+
   private
 
   def truncate(str, limit = 180)

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper.rb

@@ -47,12 +47,18 @@ module ReeMapper
 
   require_relative 'ree_mapper/mapper_strategy'
   require_relative 'ree_mapper/mapper'
+  require_relative 'ree_mapper/db_load_compiler'
   require_relative 'ree_mapper/mapper_factory_proxy'
   require_relative 'ree_mapper/mapper_factory'
 
   require_relative 'ree_mapper/default_factory'
   require_relative 'ree_mapper/dsl'
 
+  # Defensive read: an older ree gem without the flag means the mode is off
+  def self.db_load_performance_mode?
+    Ree.respond_to?(:db_load_performance_mode?) && Ree.db_load_performance_mode?
+  end
+
   def self.get_mapper_factory(mod)
     if !mod.is_a?(Module)
       raise Ree::Error.new("module should be provided", :invalid_dsl_usage)

data/lib/ree_lib/packages/ree_mapper/spec/ree_mapper/benchmarks/db_load_benchmark_spec.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+require 'benchmark'
+
+package_require "ree_mapper"
+package_require "ree_dto/entity_dsl"
+
+# Run with:
+#   REE_BENCHMARK=1 bundle exec rspec ... db_load_benchmark_spec.rb
+# Contracts state is fixed at method definition time, so measure both setups
+# in separate processes: a plain run (contracts on) and NO_CONTRACTS=1.
+RSpec.public_send(ENV["REE_BENCHMARK"] ? :describe : :xdescribe, 'db_load performance mode benchmark') do
+  link :build_mapper_factory, from: :ree_mapper
+  link :build_mapper_strategy, from: :ree_mapper
+
+  after { Ree.disable_db_load_performance_mode }
+
+  ROWS_COUNT = 10_000
+  REPS = 10
+
+  class DbLoadBenchDto
+    include ReeDto::DSL
+
+    build_dto do
+      field :id, Integer
+      field :num2, Integer
+      field :num3, Integer
+      field :num4, Integer
+      field :num5, Integer
+      field :name, String
+      field :s2, String
+      field :s3, String
+      field :s4, String
+      field :s5, String
+      field :active, Bool
+      field :flag2, Bool
+      field :score, Float
+      field :score2, Float
+      field :born_on, Date
+      field :born2, Date
+      field :seen_at, Time
+      field :seen2, Time
+      field :registered_at, DateTime
+      field :payload, Any
+    end
+  end
+
+  class DbLoadBenchEntity
+    include ReeDto::EntityDSL
+
+    properties(
+      id: Nilor[Integer], num2: Nilor[Integer], num3: Nilor[Integer],
+      num4: Nilor[Integer], num5: Nilor[Integer],
+      name: Nilor[String], s2: Nilor[String], s3: Nilor[String],
+      s4: Nilor[String], s5: Nilor[String],
+      active: Nilor[Bool], flag2: Nilor[Bool],
+      score: Nilor[Float], score2: Nilor[Float],
+      born_on: Nilor[Date], born2: Nilor[Date],
+      seen_at: Nilor[Time], seen2: Nilor[Time],
+      registered_at: Nilor[DateTime], payload: Any,
+    )
+  end
+
+  wide_blk = Proc.new do
+    integer :id
+    integer :num2
+    integer :num3
+    integer :num4
+    integer :num5
+    string :name
+    string :s2
+    string :s3
+    string :s4
+    string :s5
+    bool :active
+    bool :flag2
+    float :score
+    float :score2
+    date :born_on
+    date :born2
+    time :seen_at
+    time :seen2
+    date_time :registered_at
+    any :payload
+  end
+
+  mixed_blk = Proc.new do
+    integer :id
+    string :name
+    bool :active
+    date :born_on
+    hash :meta, null: true do
+      date :day
+      integer :num
+    end
+    array :nums, integer, null: true
+  end
+
+  def build_mapper_with_mode(mode_on, dto, blk)
+    mode_on ? Ree.enable_db_load_performance_mode : Ree.disable_db_load_performance_mode
+
+    build_mapper_factory(
+      strategies: [
+        build_mapper_strategy(method: :db_load, dto: dto, always_optional: true)
+      ]
+    ).call.use(:db_load, dto: dto, &blk)
+  ensure
+    Ree.disable_db_load_performance_mode
+  end
+
+  def wide_rows
+    Array.new(ROWS_COUNT) do |i|
+      {
+        id: i, num2: i, num3: i, num4: i, num5: i,
+        name: "name-#{i}", s2: "a", s3: "b", s4: "c", s5: "d",
+        active: true, flag2: false,
+        score: 1.5, score2: 2.5,
+        born_on: Date.new(2020, 1, 1), born2: Date.new(2021, 2, 2),
+        seen_at: Time.at(i).utc, seen2: Time.at(i * 2).utc,
+        registered_at: DateTime.new(2020, 1, 1, 12, 0, 0),
+        payload: { x: i },
+      }
+    end
+  end
+
+  def mixed_rows
+    Array.new(ROWS_COUNT) do |i|
+      {
+        id: i, name: "name-#{i}", active: true, born_on: Date.new(2020, 1, 1),
+        meta: { day: "2020-01-01", num: i }, # string date: the JSONB guard-fallback path
+        nums: [1, 2, 3],
+      }
+    end
+  end
+
+  def report_alloc(label, rows, mapper)
+    GC.start
+    allocated_before = GC.stat(:total_allocated_objects)
+    gc_before = GC.count
+    rows.each { mapper.db_load(_1) }
+    allocated = GC.stat(:total_allocated_objects) - allocated_before
+    gc_runs = GC.count - gc_before
+    puts format("%-28s %10d objects, %3d GC runs per %d rows", label, allocated, gc_runs, rows.size)
+  end
+
+  it 'wide primitive row: generic vs compiled' do
+    rows = wide_rows
+
+    pairs = {
+      "hash dto" => [
+        build_mapper_with_mode(false, Hash, wide_blk),
+        build_mapper_with_mode(true, Hash, wide_blk),
+      ],
+      "ree_dto" => [
+        build_mapper_with_mode(false, DbLoadBenchDto, wide_blk),
+        build_mapper_with_mode(true, DbLoadBenchDto, wide_blk),
+      ],
+      "entity_dsl" => [
+        build_mapper_with_mode(false, DbLoadBenchEntity, wide_blk),
+        build_mapper_with_mode(true, DbLoadBenchEntity, wide_blk),
+      ],
+    }
+
+    puts "\ncontracts: #{Ree::Contracts.no_contracts? ? 'OFF (NO_CONTRACTS)' : 'ON'}"
+
+    Benchmark.bmbm do |x|
+      pairs.each do |name, (generic, compiled)|
+        x.report("generic  #{name}") { REPS.times { rows.each { generic.db_load(_1) } } }
+        x.report("compiled #{name}") { REPS.times { rows.each { compiled.db_load(_1) } } }
+      end
+    end
+
+    puts "\nallocations:"
+    pairs.each do |name, (generic, compiled)|
+      report_alloc("generic  #{name}", rows, generic)
+      report_alloc("compiled #{name}", rows, compiled)
+    end
+  end
+
+  it 'mixed row with nested hash and array: generic vs compiled' do
+    rows = mixed_rows
+    generic = build_mapper_with_mode(false, DbLoadBenchDto, mixed_blk)
+    compiled = build_mapper_with_mode(true, DbLoadBenchDto, mixed_blk)
+
+    Benchmark.bmbm do |x|
+      x.report("generic  mixed") { REPS.times { rows.each { generic.db_load(_1) } } }
+      x.report("compiled mixed") { REPS.times { rows.each { compiled.db_load(_1) } } }
+    end
+
+    puts "\nallocations:"
+    report_alloc("generic  mixed", rows, generic)
+    report_alloc("compiled mixed", rows, compiled)
+  end
+end
+
+# Results (2026-08-16, Ruby 4.0.1, 10_000 rows x 10 reps, real seconds):
+#
+# contracts: ON
+#                            generic    compiled   speedup
+#   wide (20 fields) hash      60.53s      0.41s     ~149x
+#   wide ree_dto               74.76s      0.43s     ~174x
+#   wide entity_dsl            63.78s      0.36s     ~175x
+#   mixed (jsonb-like)         37.23s      5.43s     ~6.9x
+#
+#   allocations per 10_000 rows:
+#   wide hash        15_820_000 -> 10_000      wide ree_dto  18_350_000 -> 20_000
+#   wide entity_dsl  15_820_000 -> 10_000      mixed          8_930_000 -> 1_190_000
+#   GC runs: 40-46 -> 0 (wide), 72 -> 9 (mixed)
+#
+# contracts: OFF (NO_CONTRACTS=1)
+#                            generic    compiled   speedup
+#   wide (20 fields) hash       2.54s      0.42s     ~6.0x
+#   wide ree_dto                2.77s      0.43s     ~6.4x
+#   wide entity_dsl             2.43s      0.39s     ~6.2x
+#   mixed (jsonb-like)          2.52s      1.21s     ~2.1x
+#
+#   allocations per 10_000 rows:
+#   wide hash        220_000 -> 10_000          wide ree_dto  260_000 -> 20_000
+#   wide entity_dsl  220_000 -> 10_000          mixed         360_000 -> 200_000

data/lib/ree_lib/packages/ree_mapper/spec/ree_mapper/db_load_performance_mode_spec.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+package_require "ree_mapper"
+package_require "ree_dto/entity_dsl"
+
+RSpec.describe "db_load performance mode" do
+  link :build_mapper_factory, from: :ree_mapper
+  link :build_mapper_strategy, from: :ree_mapper
+
+  after do
+    Ree.disable_db_load_performance_mode
+  end
+
+  class PerfModeDto
+    include ReeDto::DSL
+
+    build_dto do
+      field :id, Integer
+      field :name, String
+    end
+  end
+
+  class PerfModeEntity
+    include ReeDto::EntityDSL
+
+    properties(
+      id: Nilor[Integer],
+      name: Nilor[String],
+    )
+  end
+
+  def build_factory(dto:, always_optional: true)
+    build_mapper_factory(
+      strategies: [
+        build_mapper_strategy(method: :db_load, dto: dto, always_optional: always_optional)
+      ]
+    )
+  end
+
+  # builds the same mapper twice: with the mode off (generic path) and on
+  # (compiled path), so examples can assert identical behavior
+  def build_pair(dto: Hash, always_optional: true, register_as: nil, &blk)
+    Ree.disable_db_load_performance_mode
+    generic = build_factory(dto: dto, always_optional: always_optional)
+      .call(register_as: register_as).use(:db_load, dto: dto, &blk)
+
+    Ree.enable_db_load_performance_mode
+    compiled = build_factory(dto: dto, always_optional: always_optional)
+      .call(register_as: register_as).use(:db_load, dto: dto, &blk)
+    Ree.disable_db_load_performance_mode
+
+    [generic, compiled]
+  end
+
+  def expect_same_result(generic, compiled, input, **opts)
+    generic_result = begin; generic.db_load(input, **opts); rescue => e; e; end
+    compiled_result = begin; compiled.db_load(input, **opts); rescue => e; e; end
+
+    if generic_result.is_a?(Exception)
+      expect(compiled_result.class).to eq(generic_result.class)
+      expect(compiled_result.message).to eq(generic_result.message)
+    else
+      expect(compiled_result).to eq(generic_result)
+    end
+
+    compiled_result
+  end
+
+  wide_blk = Proc.new do
+    integer :id
+    string :name
+    bool :active
+    float :score, null: true
+    date :born_on, null: true
+    time :seen_at, null: true
+    date_time :registered_at, null: true
+    rational :ratio, null: true
+    any :payload, null: true
+    integer :renamed, from: :src
+    string? :note, default: "-"
+    integer? :maybe
+    integer :admin_count, role: :admin
+    hash :meta, null: true do
+      date :day
+      integer :num
+    end
+    array :nums, integer, null: true
+  end
+
+  def wide_row
+    {
+      id: 1,
+      name: "n",
+      active: true,
+      score: 1.5,
+      born_on: Date.new(2020, 1, 1),
+      seen_at: Time.at(0).utc,
+      registered_at: DateTime.new(2020, 1, 1, 12, 0, 0),
+      ratio: Rational(1, 2),
+      payload: { x: 1 },
+      src: 5,
+      note: "hi",
+      maybe: 2,
+      meta: { day: "2020-01-01", num: 3 },
+      nums: [1, 2],
+    }
+  end
+
+  it "compiles db_load when the mode is on and keeps the generic fallback" do
+    _generic, compiled = build_pair(&wide_blk)
+
+    expect(compiled.class.method_defined?(:__generic_db_load, false)).to be true
+    expect(compiled.class.const_defined?(:DB_LOAD_FIELDS, false)).to be true
+  end
+
+  it "does not compile when the mode is off" do
+    generic, _compiled = build_pair(&wide_blk)
+
+    expect(generic.class.method_defined?(:__generic_db_load, false)).to be false
+  end
+
+  context "parity with the generic path" do
+    it "loads a full row identically" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, wide_row)
+
+      expect(result[:id]).to eq(1)
+      expect(result[:renamed]).to eq(5)
+      expect(result[:meta][:day]).to eq(Date.new(2020, 1, 1)) # JSONB-style string is still cast
+      expect(result[:nums]).to eq([1, 2])
+      expect(result.key?(:admin_count)).to be false
+    end
+
+    it "still coerces values that fail the type guard" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, wide_row.merge(id: "5", score: 2))
+
+      expect(result[:id]).to eq(5)
+      expect(result[:score]).to eq(2.0)
+      expect(result[:score]).to be_a(Float)
+    end
+
+    it "raises the same error for nil in a null: false field" do
+      generic, compiled = build_pair(&wide_blk)
+      error = expect_same_result(generic, compiled, wide_row.merge(name: nil))
+
+      expect(error).to be_a(ReeMapper::TypeError)
+      expect(error.message).to include("`name`")
+    end
+
+    it "raises the same error for garbage that fails coercion" do
+      generic, compiled = build_pair(&wide_blk)
+      error = expect_same_result(generic, compiled, wide_row.merge(id: "abc"))
+
+      expect(error).to be_a(ReeMapper::CoercionError)
+      expect(error.message).to include("`id`")
+    end
+
+    it "raises the same error from a nested mapper with the field path" do
+      generic, compiled = build_pair(&wide_blk)
+      error = expect_same_result(generic, compiled, wide_row.merge(meta: { day: "not a date", num: 1 }))
+
+      expect(error).to be_a(ReeMapper::CoercionError)
+      expect(error.message).to include("`meta[day]`")
+    end
+
+    it "assigns nil without casting for null: true fields" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(
+        generic, compiled,
+        wide_row.merge(score: nil, born_on: nil, meta: nil, nums: nil, payload: nil)
+      )
+
+      expect(result[:score]).to be_nil
+      expect(result[:meta]).to be_nil
+    end
+
+    it "applies defaults and skips missing optional fields" do
+      generic, compiled = build_pair(&wide_blk)
+      row = wide_row
+      row.delete(:note)
+      row.delete(:maybe)
+      result = expect_same_result(generic, compiled, row)
+
+      expect(result[:note]).to eq("-")
+      expect(result.key?(:maybe)).to be false
+    end
+
+    it "skips missing fields when the strategy is always_optional" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, { id: 1 })
+
+      expect(result).to eq({ id: 1, note: "-" })
+    end
+
+    it "raises for missing required fields when the strategy is not always_optional" do
+      generic, compiled = build_pair(always_optional: false) do
+        integer :id
+        string? :name
+      end
+      error = expect_same_result(generic, compiled, { name: "n" })
+
+      expect(error).to be_a(ReeMapper::TypeError)
+      expect(error.message).to include("`id` is missing (required field)")
+    end
+
+    it "supports string-keyed input" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, { "id" => 1, "name" => "n" })
+
+      expect(result[:id]).to eq(1)
+    end
+
+    it "falls back to the generic path for non-Hash input" do
+      generic, compiled = build_pair(&wide_blk)
+      input = OpenStruct.new(id: 1, name: "n")
+      result = expect_same_result(generic, compiled, input)
+
+      expect(result[:id]).to eq(1)
+    end
+
+    it "falls back to the generic path for role calls" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, wide_row.merge(admin_count: 7), role: :admin)
+
+      expect(result[:admin_count]).to eq(7)
+    end
+
+    it "falls back to the generic path for only/except calls" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, wide_row, only: [:id, :name])
+
+      expect(result.keys).to contain_exactly(:id, :name)
+    end
+
+    it "respects field-level only filters on nested mappers" do
+      generic, compiled = build_pair do
+        integer :id
+        hash :meta, null: true, only: [:num] do
+          date :day, null: true
+          integer :num
+        end
+      end
+      result = expect_same_result(generic, compiled, { id: 1, meta: { day: "2020-01-01", num: 3 } })
+
+      expect(result[:meta]).to eq({ num: 3 })
+    end
+  end
+
+  context "dto outputs" do
+    it "builds ree_dto entities" do
+      generic, compiled = build_pair(dto: PerfModeDto) do
+        integer :id
+        string :name
+      end
+
+      generic_dto = generic.db_load({ id: 1, name: "n" })
+      compiled_dto = compiled.db_load({ id: 1, name: "n" })
+
+      expect(compiled_dto).to be_a(PerfModeDto)
+      expect(compiled_dto.id).to eq(generic_dto.id)
+      expect(compiled_dto.name).to eq(generic_dto.name)
+      expect(compiled_dto.attrs).to eq(generic_dto.attrs)
+    end
+
+    it "builds entity_dsl objects via instance variables" do
+      generic, compiled = build_pair(dto: PerfModeEntity) do
+        integer :id
+        string :name
+      end
+
+      generic_entity = generic.db_load({ id: 1, name: "n" })
+      compiled_entity = compiled.db_load({ id: 1, name: "n" })
+
+      expect(compiled_entity).to be_a(PerfModeEntity)
+      expect(compiled_entity.id).to eq(generic_entity.id)
+      expect(compiled_entity.name).to eq(generic_entity.name)
+    end
+
+    it "keeps the generic path for struct dto" do
+      Ree.enable_db_load_performance_mode
+      mapper = build_factory(dto: Struct).call.use(:db_load, dto: Struct) do
+        integer :id
+      end
+      Ree.disable_db_load_performance_mode
+
+      expect(mapper.class.method_defined?(:__generic_db_load, false)).to be false
+      expect(mapper.db_load({ id: 1 }).id).to eq(1)
+    end
+  end
+
+  context "registered (frozen) mappers" do
+    it "compiles mappers registered via register_as" do
+      generic, compiled = build_pair(register_as: :perf_mode_frozen, &wide_blk)
+
+      expect(compiled.frozen?).to be true
+      expect(compiled.class.method_defined?(:__generic_db_load, false)).to be true
+      expect_same_result(generic, compiled, wide_row)
+    end
+  end
+
+  describe "guard/cast identity invariant" do
+    {
+      ReeMapper::Integer => [1, -5, 10**20],
+      ReeMapper::String => ["s", ""],
+      ReeMapper::Bool => [true, false],
+      ReeMapper::Float => [1.5, -0.0],
+      ReeMapper::Date => [Date.new(2020, 1, 1)],
+      ReeMapper::Time => [Time.at(0).utc],
+      ReeMapper::DateTime => [DateTime.new(2020, 1, 1)],
+      ReeMapper::Rational => [Rational(1, 2)],
+      ReeMapper::Any => [1, "s", nil, [1], { a: 1 }],
+    }.each do |type_class, values|
+      it "#{type_class}: guard implies db_load is identity" do
+        type = type_class.new
+        check = type.db_load_trusted_check("v")
+
+        values.each do |v|
+          expect(eval(check)).to be(true), "guard rejected #{v.inspect} for #{type_class}"
+          expect(type.db_load(v)).to equal(v)
+        end
+      end
+    end
+
+    it "guards reject values that db_load would convert" do
+      {
+        ReeMapper::Integer.new => "5",
+        ReeMapper::Float.new => 2,
+        ReeMapper::Date.new => DateTime.new(2020, 1, 1),
+        ReeMapper::Time.new => DateTime.new(2020, 1, 1),
+        ReeMapper::DateTime.new => Time.at(0).utc,
+        ReeMapper::Rational.new => "1/2",
+        ReeMapper::Bool.new => 1,
+      }.each do |type, v|
+        check = type.db_load_trusted_check("v")
+        expect(eval(check)).to be(false), "guard accepted #{v.inspect} for #{type.class}"
+      end
+    end
+  end
+end

data/lib/ree_lib/packages/ree_roda/package/ree_roda/plugins/ree_routes.rb

@@ -7,12 +7,16 @@ class Roda
         package_require("ree_json/functions/to_json")
         package_require("ree_hash/functions/transform_values")
         package_require("ree_object/functions/not_blank")
+        package_require("ree_audit/beans/audit")
+        package_require("ree_audit/event")
 
         app.plugin :all_verbs
       end
 
       def self.configure(app, opts = {})
         app.opts[:ree_routes_before] = opts[:before] if opts[:before]
+        # An application that passes no `audit:` behaves exactly as before.
+        app.opts[:ree_routes_audit] = opts[:audit] if opts[:audit]
       end
 
       module ClassMethods
@@ -126,7 +130,31 @@ class Roda
                   end
 
                   accessor = authenticated_user
-                  action_result = get_cached_action(route).call(accessor, filtered_params)
+                  audit = context.opts[:ree_routes_audit]
+
+                  action_result = if audit && route.audited?
+                    # The event carries the params exactly as the action
+                    # received them. IP, user agent and session come from the
+                    # accessor rather than from the request, so that the audit
+                    # package stays free of any Roda dependency.
+                    audit_event = ReeAudit::Event.build(
+                      action_name: route.action.name,
+                      package_name: route.action.package_name,
+                      summary: route.summary,
+                      sections: route.sections,
+                      request_method: route.request_method,
+                      path: route.path,
+                      request_path: r.path,
+                      params: filtered_params,
+                      accessor: accessor
+                    )
+
+                    audit.around(audit_event) do
+                      get_cached_action(route).call(accessor, filtered_params)
+                    end
+                  else
+                    get_cached_action(route).call(accessor, filtered_params)
+                  end
 
                   if route.serializer
                     serialized_result = get_cached_serializer(route).serialize(action_result)

data/lib/ree_lib/packages/ree_roda/package/ree_roda.rb

@@ -11,6 +11,7 @@ module ReeRoda
     depends_on :ree_object
     depends_on :ree_swagger
     depends_on :ree_errors
+    depends_on :ree_audit
   end
 end