airtable-orm 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22ca62058d684f1b34fbf154b50afb7c8a5c37659b5235fef23614f97642d6c1
-  data.tar.gz: 554987924ef0c43b3692adc311cdf72dd367d927e9396f92af7dc4ba1a2f12d5
+  metadata.gz: 970cedc7b68168b8add9fa80225982de0e902758bfb0dbfb7b3d04184c292871
+  data.tar.gz: 9e45c6326f0daa9b07eee7f6aa81601217437f40022ca05a34c85d0fd17714f1
 SHA512:
-  metadata.gz: 52e3f9c34c7f34d6ffa17e2f85ebc97a072917611bac555ee300852c6b20799dd22c448485e69e07ab3d14cf85b88984fb6d52c054893b2a0f24e980293e2bfb
-  data.tar.gz: bc2d2694f67595eac95ba645056ff3d2e9778d38dcf072737fd8312a2677eb046dbddbf9414238994f0f9c7f0a9d10c7f343a7f1fb7f97c32279e131b03818bd
+  metadata.gz: 3812676e76a07ae378a285030f30c8175fc9bb23670d626d2103e44611894785f962554d3cd9737c9c88f2ba6aaf9b8d80c8d5ee6e9401ca0a5da6b413ba7dcd
+  data.tar.gz: 0bc1ea55739db84a90a92b8389d3df1c37121e496838388ec863621e3e8fb13adc6cbb54ee19e9f09f2c0eeebf8b20dd70521a6e827b6b6d384dca4230f9f35d

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-14
+
+Hardening release from a deep code review of the whole gem. Minor (not patch) because a few
+observable contracts changed — see Changed below.
+
+### Fixed
+
+- `find_by` validates field references before formula interpolation — a string key containing
+  braces raises `ArgumentError` instead of injecting formula clauses.
+- `find` rejects IDs that don't match Airtable's record-ID format with `RecordNotFound` —
+  `find(nil)` no longer falls through to the list endpoint and returns a phantom record, and
+  IDs are no longer interpolated unvalidated into the URL path.
+- `format_formula_value` normalizes `DateTime` values to UTC (they previously matched the
+  `Date` branch and kept their local offset) and no longer mutates the caller's `Time` object
+  (`getutc` instead of `utc`).
+- Formula escaping keeps control characters intact — Airtable formula string literals have no
+  escape sequences, so values containing newlines or tabs now actually match.
+- The rate limiter prunes its sliding window against the current time (no more spurious ~1 s
+  pause on the first request after an idle period) and sleeps outside its mutex, so a throttled
+  thread no longer serializes every other thread's request.
+- A 2xx response without a records array (e.g. an HTML body from a proxy) raises `ApiError`
+  instead of `NoMethodError` deep inside `where`/`count`.
+- `preload` and `has_many` readers slice linked-ID lists to the `find_many` per-request cap
+  (500), so associations with more links load instead of raising `ArgumentError`.
+- `Airtable::ORM.configure` invalidates the memoized HTTP client, so reconfiguring after the
+  first request (e.g. rotating the API key or changing timeouts) takes effect instead of being
+  silently ignored.
+
+### Changed
+
+- Invalid `sort:` arguments (anything but a Hash or Array) raise `ArgumentError` instead of
+  being silently discarded — `last(sort: :field)` previously ran unsorted and returned an
+  arbitrary record.
+- A configured table missing from the fetched base schema raises the new
+  `Airtable::ORM::ConfigurationError` with a diagnostic message instead of `NoMethodError`
+  on `nil`.
+- A stale `belongs_to` link to a deleted record reads as `nil` (matching the preloaded path)
+  instead of raising `RecordNotFound`.
+
 ## [0.1.0] - 2026-07-10
 
 Initial release — the generic Airtable client/ORM extracted from the EUCS Mono application:

data/lib/airtable/orm/associations.rb

@@ -5,6 +5,14 @@ module Airtable
     module Associations
       extend ActiveSupport::Concern
 
+      # Fetch linked records via find_many, slicing to its per-request ID cap so an
+      # association (or preload union) with more links than the cap still loads.
+      def self.fetch_linked_records(klass, ids)
+        records = ids.each_slice(Airtable::ORM::Persistence::MAX_FIND_MANY_IDS)
+                     .flat_map { |slice| klass.find_many(slice).to_a }
+        Airtable::ORM::Collection.new(records, model_class: klass)
+      end
+
       # Requires Attributes concern. Uses read_raw_attribute/write_raw_attribute to
       # bypass accessors and avoid infinite recursion when association names match attributes.
 
@@ -57,7 +65,11 @@ module Airtable
             memoize_association(association_name) do
               ids = read_linked_ids(foreign_key)
               klass = class_name.constantize
-              ids.empty? ? Airtable::ORM::Collection.new([], model_class: klass) : klass.find_many(ids)
+              if ids.empty?
+                Airtable::ORM::Collection.new([], model_class: klass)
+              else
+                Airtable::ORM::Associations.fetch_linked_records(klass, ids)
+              end
             end
           end
 
@@ -91,7 +103,13 @@ module Airtable
           define_method(association_name) do
             memoize_association(association_name) do
               id = read_linked_ids(foreign_key).first
-              id ? class_name.constantize.find(id) : nil
+              begin
+                id ? class_name.constantize.find(id) : nil
+              rescue Airtable::ORM::RecordNotFound
+                # A stale link to a deleted record reads as nil, matching the preloaded
+                # path (find_many simply omits missing records).
+                nil
+              end
             end
           end
 
@@ -135,7 +153,12 @@ module Airtable
                       records.filter_map { |r| r.send(:read_linked_ids, foreign_key).first }.uniq
                     end
 
-          fetched_by_id = all_ids.empty? ? {} : klass.find_many(all_ids).index_by(&:id)
+          fetched_by_id =
+            if all_ids.empty?
+              {}
+            else
+              Airtable::ORM::Associations.fetch_linked_records(klass, all_ids).index_by(&:id)
+            end
 
           records.each do |record|
             ids = record.send(:read_linked_ids, foreign_key)

data/lib/airtable/orm/attributes.rb

@@ -47,7 +47,11 @@ module Airtable
         def schema
           return {} unless table_name
 
-          @schema ||= Airtable::ORM::Schema.fetch(base_id)[table_id]
+          @schema ||= Airtable::ORM::Schema.fetch(base_id)[table_id] || raise(
+            Airtable::ORM::ConfigurationError,
+            "No table #{table_id.inspect} (#{table_name.inspect}) in the fetched schema for base " \
+            "#{base_id.inspect} — check config.tables against the Airtable base"
+          )
         end
 
         # Clear the memoized schema cache

data/lib/airtable/orm/errors.rb

@@ -14,6 +14,10 @@ module Airtable
     # Raised when an invalid attribute is provided
     class InvalidAttributeError < Error; end
 
+    # Raised when the host configuration doesn't match the Airtable base
+    # (e.g. a configured table ID absent from the fetched schema)
+    class ConfigurationError < Error; end
+
     # Raised when a record fails validation.
     # Use the #record method to retrieve the record which did not validate.
     class RecordInvalid < Error

data/lib/airtable/orm/http/rate_limiter.rb

@@ -13,11 +13,7 @@ module Airtable
         end
 
         def call(env)
-          @mutex.synchronize do
-            wait if too_many_requests_in_last_second?
-            @requests << Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            @requests.shift if @rps && @requests.size > @rps
-          end
+          throttle if @rps
           @app.call(env)
         end
 
@@ -27,20 +23,33 @@ module Airtable
 
         private
 
-        def too_many_requests_in_last_second?
-          return false unless @rps
-          return false unless @requests.size >= @rps
+        # Compute the wait under the lock but sleep outside it, so a throttled thread
+        # doesn't serialize every other thread's request behind its sleep.
+        def throttle
+          wait_time = @mutex.synchronize do
+            now = monotonic_now
+            prune(now)
+            1.0 - (now - @requests.first) if @requests.size >= @rps
+          end
+
+          @sleeper.call(wait_time) if wait_time&.positive?
 
-          window_span < 1.0
+          @mutex.synchronize do
+            now = monotonic_now
+            prune(now)
+            @requests << now
+            @requests.shift while @requests.size > @rps
+          end
         end
 
-        def wait
-          wait_time = 1.0 - window_span
-          @sleeper.call(wait_time)
+        # Drop timestamps that fell out of the 1-second sliding window — without this,
+        # a full window recorded before an idle period would throttle the next request.
+        def prune(now)
+          @requests.shift while @requests.any? && now - @requests.first >= 1.0
         end
 
-        def window_span
-          @requests.last - @requests.first
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
         end
       end
     end

data/lib/airtable/orm/persistence.rb

@@ -17,6 +17,10 @@ module Airtable
       BATCH_SIZE = 10
       MAX_FIND_MANY_IDS = 500
 
+      # Airtable record IDs: rec + alphanumeric characters. Validated before any ID reaches
+      # a URL path or formula interpolation (injection guard).
+      RECORD_ID_FORMAT = /\Arec[a-zA-Z0-9_-]+\z/
+
       class_methods do
         # Batch update records (up to 10 per API request).
         # Triages locally: new/invalid → failed, unchanged → skipped, changed → sent.
@@ -54,8 +58,13 @@ module Airtable
           "#{full_path}?returnFieldsByFieldId=true"
         end
 
-        # Find a record by ID
+        # Find a record by ID. Rejects malformed IDs up front — an ID that can never exist
+        # must not reach the URL path (nil would hit the LIST endpoint, "recX/.." another one).
         def find(id)
+          unless id.to_s.match?(RECORD_ID_FORMAT)
+            raise Airtable::ORM::RecordNotFound, "Couldn't find record with id=#{id.inspect}"
+          end
+
           response = client.connection.get(api_path(id))
           parsed_response = response.body
 
@@ -165,11 +174,10 @@ module Airtable
         end
 
         # Validate that record IDs match Airtable's format to prevent formula injection
-        # Airtable record IDs follow the pattern: rec + alphanumeric characters
         def validate_record_ids(ids)
           ids.map do |id|
             id_str = id.to_s
-            unless id_str.match?(/\Arec[a-zA-Z0-9_-]+\z/)
+            unless id_str.match?(RECORD_ID_FORMAT)
               raise ArgumentError,
                     "Invalid Airtable record ID: #{id_str.inspect}"
             end

data/lib/airtable/orm/querying.rb

@@ -38,8 +38,7 @@ module Airtable
           raise ArgumentError, "find_by requires at least one condition" if conditions.empty?
 
           clauses = conditions.map do |field, value|
-            field_id = resolve_field_id(field)
-            "{#{field_id}} = #{format_formula_value(value)}"
+            "{#{formula_field_reference(field)}} = #{format_formula_value(value)}"
           end
           formula = clauses.size == 1 ? clauses.first : "AND(#{clauses.join(", ")})"
           first(formula: formula)
@@ -65,21 +64,20 @@ module Airtable
           when TrueClass then "TRUE()"
           when FalseClass then "FALSE()"
           when Integer, Float then value.to_s
+          # Time/DateTime before Date: DateTime is a Date subclass and must be UTC-normalized.
+          when Time, DateTime then "'#{value.getutc.iso8601}'"
           when Date then "'#{value.iso8601}'"
-          when Time, DateTime then "'#{value.utc.iso8601}'"
           else "'#{escape_formula_value(value)}'"
           end
         end
 
         # Escape a value for use in an Airtable formula string literal.
-        # Handles backslashes, single quotes, and control characters.
+        # Only backslashes and single quotes — Airtable formula string literals have no
+        # escape sequences for control characters, so a newline stays a real newline.
         def escape_formula_value(value)
           value.to_s
                .gsub("\\", "\\\\\\\\")  # backslashes first
                .gsub("'", "\\\\'")      # single quotes
-               .gsub("\n", "\\n")       # newlines
-               .gsub("\r", "\\r")       # carriage returns
-               .gsub("\t", "\\t")       # tabs
         end
 
         private
@@ -116,7 +114,15 @@ module Airtable
 
             Airtable::ORM::Http::Client.raise_api_error(response.status, parsed_response) unless response.success?
 
-            yield parsed_response["records"]
+            records = parsed_response.is_a?(Hash) ? parsed_response["records"] : nil
+            unless records.is_a?(Array)
+              raise Airtable::ORM::ApiError.new(
+                "Malformed Airtable response: expected a records array (HTTP #{response.status})",
+                status: response.status, response: parsed_response
+              )
+            end
+
+            yield records
 
             break unless paginate && parsed_response["offset"]
 
@@ -142,7 +148,7 @@ module Airtable
         # Accepts: { field: :asc } or [[:field1, :desc], [:field2, :asc]]
         # Converts symbol attributes to their Airtable field IDs
         def normalize_sort_options(sort)
-          return [] unless sort.respond_to?(:map)
+          raise_invalid_sort(sort) unless sort.is_a?(Hash) || sort.is_a?(Array)
 
           sort.map { |field, direction| { field: resolve_field_id(field), direction: direction.to_s } }
         end
@@ -166,6 +172,15 @@ module Airtable
           fields.map { |field| resolve_field_id(field) }
         end
 
+        # Resolve a field for interpolation inside {} in a formula. Braces would terminate
+        # the reference and let a user-supplied field name inject arbitrary formula clauses.
+        def formula_field_reference(field)
+          field_id = resolve_field_id(field)
+          raise ArgumentError, "Invalid field reference for formula: #{field_id.inspect}" if field_id.match?(/[{}]/)
+
+          field_id
+        end
+
         # Reverse sort order for last() method
         def reverse_sort_order(sort)
           return nil unless sort
@@ -175,8 +190,14 @@ module Airtable
           case sort
           when Hash then sort.transform_values(&flip)
           when Array then sort.map { |field, dir| [field, flip.call(dir)] }
+          else raise_invalid_sort(sort)
           end
         end
+
+        def raise_invalid_sort(sort)
+          raise ArgumentError,
+                "sort must be a Hash or Array of [field, direction] pairs, got #{sort.inspect}"
+        end
       end
     end
   end

data/lib/airtable/orm/version.rb

@@ -2,6 +2,6 @@
 
 module Airtable
   module ORM
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/airtable/orm.rb

@@ -29,6 +29,10 @@ module Airtable
 
       def configure
         yield config
+      ensure
+        # The client memoizes api_key/timeouts/rate_limit at first request — without this
+        # reset a later configure (e.g. rotating the API key) would be silently ignored.
+        Http::Client.reset!
       end
 
       # True when an API key is configured — hosts gate network-touching hooks on this.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: airtable-orm
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Roman Sklenar
@@ -125,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.16
 specification_version: 4
 summary: ActiveModel-style ORM for the Airtable API
 test_files: []