ree_lib 1.3.8 → 1.3.10

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

@@ -17,7 +17,8 @@ class Roda
 
       module ClassMethods
         def ree_routes(routes, swagger_title: "", swagger_description: "",
-                        swagger_version: "", swagger_url: "", api_url: "")
+                        swagger_version: "", swagger_url: "", api_url: "",
+                        swagger_include_internal: nil)
           @ree_routes ||= []
           @ree_routes += routes
 
@@ -27,12 +28,17 @@ class Roda
           opts[:ree_routes_swagger_url] = swagger_url
           opts[:ree_routes_api_url] = api_url
 
+          # nil keeps the global default (Ree.hide_internal_swagger_endpoints);
+          # pass true/false to force one app to differ from it.
+          swagger_opts = swagger_include_internal.nil? ? {} : { include_internal: swagger_include_internal }
+
           opts[:ree_routes_swagger] = ReeRoda::BuildSwaggerFromRoutes.new.call(
             @ree_routes,
             opts[:ree_routes_swagger_title],
             opts[:ree_routes_swagger_description],
             opts[:ree_routes_swagger_version],
-            opts[:ree_routes_api_url]
+            opts[:ree_routes_api_url],
+            **swagger_opts
           )
 
           build_routes_proc

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

@@ -7,8 +7,19 @@ class ReeRoda::BuildSwaggerFromRoutes
     link "ree_swagger/dto/endpoint_dto", -> { EndpointDto }
   end
 
-  contract(ArrayOf[ReeRoutes::Route], String, String, String, String => Hash)
-  def call(routes, title, description, version, api_url)
+  contract(
+    ArrayOf[ReeRoutes::Route], String, String, String, String,
+    Ksplat[include_internal?: Bool] => Hash
+  )
+  def call(routes, title, description, version, api_url, **opts)
+    # Defaults to the global switch (see Ree.hide_internal_swagger_endpoints),
+    # so one codebase can serve a public and an internal document.
+    include_internal = opts.fetch(:include_internal) {
+      !Ree.hide_internal_swagger_endpoints?
+    }
+
+    routes = routes.select(&:public?) if !include_internal
+
     endpoints = routes.map do |route|
       method_decorator = Ree::Contracts.get_method_decorator(
         route.action.klass, :call, scope: :instance

data/lib/ree_lib/packages/ree_routes/package/ree_routes/dsl.rb

@@ -24,6 +24,8 @@ module ReeRoutes
       include Ree::Contracts::Core
       include Ree::Contracts::ArgContracts
 
+      ADMIN_PATH_SEGMENT = "admin"
+
       def routes(name, &proc)
         raise ArgumentError.new("block is required") if !block_given?
 
@@ -87,6 +89,14 @@ module ReeRoutes
           raise ArgumentError.new("action, summary and auth scope should be provided for #{builder.get_route.inspect}")
         end
 
+        if builder.get_route.visibility.nil? && admin_path?(path)
+          raise ArgumentError.new(
+            "admin route #{path} must declare visibility explicitly: " \
+            "`visibility :internal` to keep it out of generated swagger, " \
+            "or `visibility :public` if it is intentionally documented"
+          )
+        end
+
         route = builder.get_route
 
         @dsl.link(route.action.name, from: route.action.package_name)
@@ -98,6 +108,13 @@ module ReeRoutes
         @routes << route
         route
       end
+
+      # Forgetting `visibility` on an admin route is invisible in review and
+      # silently publishes it, so make it a boot-time failure instead.
+      contract String => Bool
+      def admin_path?(path)
+        path.split("/").include?(ADMIN_PATH_SEGMENT)
+      end
     end
   end
 end

data/lib/ree_lib/packages/ree_routes/package/ree_routes/route.rb

@@ -2,7 +2,17 @@
 
 class ReeRoutes::Route
   attr_accessor :summary, :request_method, :serializer, :respond_to,
-                :sections, :action, :route, :warden_scopes, :path, :override
+                :sections, :action, :route, :warden_scopes, :path, :override,
+                :visibility
+
+  # Routing always includes every route; visibility only affects generated docs.
+  def public?
+    visibility.nil? || visibility == :public
+  end
+
+  def internal?
+    !public?
+  end
 
   def valid?
     !action.nil? && !summary.nil? && !warden_scopes.nil? && !warden_scopes.empty?

data/lib/ree_lib/packages/ree_routes/package/ree_routes/route_builder.rb

@@ -5,6 +5,8 @@ require_relative "route"
 class ReeRoutes::RouteBuilder
   Redirect = Struct.new(:path, :code)
 
+  VISIBILITIES = [:public, :internal].freeze
+
   def initialize
     @route = ReeRoutes::Route.new
     @route.respond_to = :json
@@ -42,6 +44,17 @@ class ReeRoutes::RouteBuilder
     @route.summary = str
   end
 
+  contract Symbol => Symbol
+  def visibility(value)
+    if !VISIBILITIES.include?(value)
+      raise ArgumentError.new(
+        "visibility should be one of #{VISIBILITIES.inspect}, got #{value.inspect}"
+      )
+    end
+
+    @route.visibility = value
+  end
+
   contract Symbol, Symbol => nil
   def serializer(name, from:)
     object = Ree.container.packages_facade.get_object(from, name)

data/lib/ree_lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReeLib
-  VERSION = "1.3.8"
+  VERSION = "1.3.10"
 end