airtable-orm 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22ca62058d684f1b34fbf154b50afb7c8a5c37659b5235fef23614f97642d6c1
-  data.tar.gz: 554987924ef0c43b3692adc311cdf72dd367d927e9396f92af7dc4ba1a2f12d5
+  metadata.gz: dc3056cbf98026ea8a89b01d99c632ad01da304d85841544552b44565f897793
+  data.tar.gz: cf839f12c5812c4834604dc46c716fdb671c47110d94829fa863d82f5d56e489
 SHA512:
-  metadata.gz: 52e3f9c34c7f34d6ffa17e2f85ebc97a072917611bac555ee300852c6b20799dd22c448485e69e07ab3d14cf85b88984fb6d52c054893b2a0f24e980293e2bfb
-  data.tar.gz: bc2d2694f67595eac95ba645056ff3d2e9778d38dcf072737fd8312a2677eb046dbddbf9414238994f0f9c7f0a9d10c7f343a7f1fb7f97c32279e131b03818bd
+  metadata.gz: dfcd829b2a0df28d151770f30c0f51e98680bc6ab0c6f8fd5f0ff9fd2fd6ffefdef4f3c30fbe7dbcb3f3afa08689d6dffb6fc234d28a4403c3ec56f004f0abfa
+  data.tar.gz: 6c31d239c24e6c86e6303cc5eb7fdd34a5916c914c27999625c6b0c945178f9d7def6386855ba77cc13493054d14dc8abf1f087ca27474b8ff6a21f1e34f2e57

data/CHANGELOG.md

@@ -1,5 +1,60 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-07-15
+
+### Fixed
+
+- The schema cache stores the full base schema instead of only the tables configured at fetch
+  time — a table added to `config.tables` after the cache warmed up (24 h expiry, shared store
+  in Rails hosts) now resolves immediately instead of raising `ConfigurationError` until expiry.
+
+### Changed
+
+- Record payloads are parsed by string keys directly instead of deep-converting every record
+  with `with_indifferent_access` — one avoided deep copy per record on `where`/`all`/`find`,
+  two per record on batch updates. The (undocumented) `instantiate_from_api_response` and
+  `apply_response_fields` now expect string-keyed parsed payloads; `createdTime` parsing lives
+  in the single `Persistence.parse_created_time` helper.
+
+## [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
 
@@ -102,21 +111,28 @@ module Airtable
           record
         end
 
-        # Instantiate a record from API response
+        # Instantiate a record from a parsed API payload. Expects string keys (the shape the
+        # JSON middleware produces) — this runs once per record on every where/all/find, so no
+        # per-record deep conversion here.
         def instantiate_from_api_response(response)
-          data = response.with_indifferent_access
-          symbol_attrs = fields_to_symbol_attributes(data[:fields])
-
-          record = new(**symbol_attrs)
+          record = new(**fields_to_symbol_attributes(response["fields"]))
           record.send(:assign_persistence_state,
-                      id: data[:id],
-                      created_at: data[:createdTime] ? Time.iso8601(data[:createdTime].to_s) : nil,
+                      id: response["id"],
+                      created_at: parse_created_time(response),
                       persisted: true)
           record.clear_changes_information
 
           record
         end
 
+        # @api private — createdTime is ISO-8601 UTC, parsed with Time.iso8601 (Time.zone
+        # doesn't exist outside Rails); nil-guarded. The single parse site for both
+        # instantiate_from_api_response and #apply_response_fields.
+        def parse_created_time(data)
+          created_time = data["createdTime"]
+          created_time ? Time.iso8601(created_time.to_s) : nil
+        end
+
         # Convert API field IDs to symbol attributes.
         # field_mapping already contains only declared attributes.
         def fields_to_symbol_attributes(fields)
@@ -139,9 +155,8 @@ module Airtable
           parsed = response.body
 
           if response.success?
-            parsed = parsed.with_indifferent_access if parsed.is_a?(Hash)
-            response_records = parsed[:records] || []
-            response_by_id = response_records.index_by { |r| r[:id] }
+            response_records = (parsed.is_a?(Hash) && parsed["records"]) || []
+            response_by_id = response_records.index_by { |r| r["id"] }
 
             batch.each do |record|
               record_data = response_by_id[record.id]
@@ -154,7 +169,7 @@ module Airtable
             end
           else
             batch.each { |record| result.failed << record }
-            error_message = parsed.is_a?(Hash) ? parsed.with_indifferent_access.dig(:error, :message) : parsed
+            error_message = parsed.is_a?(Hash) ? parsed.dig("error", "message") : parsed
             ORM.config.logger.error(
               "Airtable batch update failed: HTTP #{response.status}: #{error_message.to_s.truncate(200)}"
             )
@@ -165,11 +180,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
@@ -304,13 +318,12 @@ module Airtable
       def apply_response_fields(data)
         @previously_new_record = new_record?
 
-        data = data.with_indifferent_access
-        symbol_attrs = self.class.fields_to_symbol_attributes(data[:fields])
+        symbol_attrs = self.class.fields_to_symbol_attributes(data["fields"])
         symbol_attrs.each { |key, value| write_raw_attribute(key, value) }
 
         assign_persistence_state(
-          id: data[:id],
-          created_at: data[:createdTime] ? Time.iso8601(data[:createdTime].to_s) : nil,
+          id: data["id"],
+          created_at: self.class.parse_created_time(data),
           persisted: true
         )
         changes_applied

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/schema.rb

@@ -19,10 +19,6 @@ module Airtable
 
         private
 
-        def required_table_ids
-          ORM.config.table_ids
-        end
-
         def fetch_from_api(base_id)
           response = client.connection.get("/v0/meta/bases/#{base_id}/tables")
           parsed_response = response.body
@@ -34,12 +30,13 @@ module Airtable
           end
         end
 
+        # Index the FULL base schema — no filtering by the tables configured at fetch time.
+        # The cached payload outlives the config (24h, shared store in Rails hosts), so a
+        # fetch-time filter would hide tables added to config after the cache warmed up.
+        # Reads are keyed lookups (fetch(base_id)[table_id]), so no read-time filter is needed.
         def indexed_schema(parsed_response)
           tables = parsed_response.deep_symbolize_keys[:tables]
 
-          # Filter only required tables
-          tables.select! { |table| required_table_ids.include?(table[:id]) }
-
           # Transform fields into hash indexed by field id
           tables.each do |table|
             table[:fields] = table[:fields].index_by { |field| field[:id] }

data/lib/airtable/orm/version.rb

@@ -2,6 +2,6 @@
 
 module Airtable
   module ORM
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   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.1
 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: []