airtable_client 0.1.0

data/lib/airtable_client/record.rb

@@ -0,0 +1,110 @@
+class AirtableClient
+
+  # A single Airtable record: a set of fields plus (once persisted) an id.
+  #
+  # Attributes are readable by original column name, underscored symbol, or
+  # generated accessor method:
+  #
+  #   record = AirtableClient::Record.new('Full Name' => 'Sarah Jaine')
+  #   record['Full Name']  # => "Sarah Jaine"
+  #   record[:full_name]   # => "Sarah Jaine"
+  #   record.full_name     # => "Sarah Jaine"
+  #
+  # Writing back to the API uses {#fields}, which preserves the original
+  # column-name capitalisation.
+  class Record
+    # @param attrs [Hash] field name => value; include +id+ for an
+    #   already-persisted record
+    def initialize(attrs={})
+      override_attributes!(attrs)
+    end
+
+    # @return [String, nil] the record id, nil until persisted
+    def id; @attrs[:id]; end
+
+    # @param val [String] the record id
+    def id=(val); @attrs[:id] = val; end
+
+    # Reads an attribute by column name or underscored symbol.
+    #
+    # @param name [String, Symbol]
+    # @return [Object] the value, or +""+ when the attribute is absent
+    def [](name)
+      @attrs.has_key?(to_key(name)) ? @attrs[to_key(name)] : ""
+    end
+
+    # Sets an attribute, defining an accessor method for it when possible.
+    #
+    # @param name [String, Symbol]
+    # @param value [Object]
+    def []=(name, value)
+      @column_keys << name
+      @attrs[to_key(name)] = value
+      define_accessor(name) unless respond_to?(name)
+    end
+
+    def inspect
+      "#<AirtableClient::Record #{attributes.map { |a, v| ":#{a}=>#{v.inspect}" }.join(", ")}>"
+    end
+
+    # @return [Hash{Symbol => Object}] attributes keyed by underscored symbol
+    def attributes; @attrs; end
+
+    # Replaces all attributes. Called by {Table#create} and {Table#update}
+    # with the API response.
+    #
+    # @param attrs [Hash] field name => value
+    def override_attributes!(attrs={})
+      @column_keys = attrs.keys
+      @attrs = attrs.to_h { |k, v| [to_key(k), v] }
+      @attrs.each_key { |k| define_accessor(k) }
+    end
+
+    # @return [Hash] attributes keyed by the original column names, as sent
+    #   in API request bodies
+    def fields
+      @column_keys.to_h { |k| [k, @attrs[to_key(k)]] }
+    end
+
+    # {#fields} without the id in any spelling — Airtable rejects an +id+
+    # inside a request body.
+    #
+    # @return [Hash] attributes safe to send in an update request
+    def fields_for_update
+      fields.reject { |k, _| to_key(k) == :id }
+    end
+
+    def method_missing(name, *args, &blk)
+      # Accessor for attributes
+      if args.empty? && blk.nil? && @attrs.has_key?(name)
+        @attrs[name]
+      else
+        super
+      end
+    end
+
+    def respond_to?(name, include_private = false)
+      @attrs.has_key?(name) || super
+    end
+
+    protected
+
+    def to_key(string)
+      string.is_a?(Symbol) ? string : underscore(string).to_sym
+    end
+
+    def underscore(string)
+      string.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        gsub(/\s/, '_').tr("-", "_").downcase
+    end
+
+    def define_accessor(name)
+      return if self.class.method_defined?(name)
+
+      self.class.send(:define_method, name) { @attrs[name] }
+    end
+
+  end # Record
+end # Airtable

data/lib/airtable_client/record_set.rb

@@ -0,0 +1,34 @@
+class AirtableClient
+
+  # One page of query results: the records plus the pagination offset for
+  # the next page. Delegates array behaviour to {#records}, so it can be
+  # iterated and indexed directly.
+  #
+  # @example
+  #   page = table.records(limit: 50)
+  #   page.each { |record| ... }
+  #   next_page = table.records(offset: page.offset) if page.offset
+  class RecordSet < SimpleDelegator
+
+    # @return [Array<Record>] the records in this page
+    attr_reader :records
+
+    # @return [String, nil] pass to the next query's +offset:+ option to
+    #   fetch the following page; nil on the last page
+    attr_reader :offset
+
+    # @param results [Hash] a parsed list-records response,
+    #   e.g. +{ "records" => [...], "offset" => "itr..." }+
+    def initialize(results)
+      # Parse records
+      @records = results && results["records"] ?
+        results["records"].map { |r| Record.new(r["fields"].merge("id" => r["id"])) } : []
+      # Store offset
+      @offset = results["offset"] if results
+      # Assign delegation object
+      __setobj__(@records)
+    end
+
+  end # Record
+
+end # Airtable

data/lib/airtable_client/resource.rb

@@ -0,0 +1,187 @@
+class AirtableClient
+  # Base class for authorised resources sending network requests.
+  #
+  # Each Table instance holds its own persistent connection to the Airtable
+  # API. Table instances must not be shared across threads.
+  class Resource
+    BASE_URI = 'https://api.airtable.com'
+    BASE_PATH = '/v0'
+    DEFAULT_TIMEOUT = 52
+
+    attr_reader :api_key, :app_token, :worksheet_name
+
+    def initialize(api_key, app_token, worksheet_name, timeout: DEFAULT_TIMEOUT)
+      @api_key = api_key
+      @app_token = app_token
+      @worksheet_name = worksheet_name
+      @timeout = timeout
+    end
+
+    private
+
+    def connection
+      if @connection.nil? || !connection_active?
+        @connection = build_connection
+      end
+      @connection
+    end
+
+    def build_connection
+      reused = !@connection.nil?
+      uri = URI(BASE_URI)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout
+      http.keep_alive_timeout = 30
+      http.start
+      log_connection(reused ? :reconnected : :opened)
+      http
+    end
+
+    def connection_active?
+      @connection&.started?
+    rescue IOError
+      false
+    end
+
+    def close_connection
+      @connection&.finish if connection_active?
+      log_connection(:closed)
+    rescue IOError
+      # already closed
+    ensure
+      @connection = nil
+    end
+
+    MAX_API_RETRIES = 3
+    RETRYABLE_STATUSES = [429, 503].freeze
+
+    def perform_request(request)
+      api_attempts = 0
+
+      loop do
+        AirtableClient::RateLimiter.instance.wait!(app_token)
+
+        response = perform_request_with_connection_retry(request)
+        api_attempts += 1
+        status = response.code.to_i
+
+        if RETRYABLE_STATUSES.include?(status) && api_attempts < MAX_API_RETRIES
+          delay = backoff_delay(api_attempts)
+          log_api_retry(request, status, api_attempts, delay)
+          sleep_for_retry(delay)
+          next
+        end
+
+        return response
+      end
+    end
+
+    def perform_request_with_connection_retry(request)
+      retries = 0
+      begin
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = connection.request(request)
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+        @last_request_duration_ms = duration_ms
+        @last_request_body_size = request.body&.bytesize || 0
+        @last_response_body_size = response.body&.bytesize || 0
+        response
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE, OpenSSL::SSL::SSLError => e
+        close_connection
+        retries += 1
+        if retries <= 1
+          log_retry(request, e)
+          retry
+        end
+        raise e
+      end
+    end
+
+    def sleep_for_retry(delay)
+      Kernel.sleep(delay)
+    end
+
+    def backoff_delay(attempt)
+      base = 2**(attempt - 1)   # attempt 1 => 1s, attempt 2 => 2s
+      base + (rand * base)      # full jitter: [base, 2*base)
+    end
+
+    def log_api_retry(request, status, attempt, delay)
+      emit_log(:warn, "[Airtable] HTTP #{status} on #{request.method} #{worksheet_name}, " \
+                      "retry #{attempt}/#{MAX_API_RETRIES - 1} in #{'%.2f' % delay}s")
+    end
+
+    def log_retry(request, error)
+      emit_log(:warn, "[Airtable] Connection reset (#{error.class}: #{error.message}), retrying #{request.method} #{worksheet_name}")
+    end
+
+    def log_connection(event)
+      AirtableClient.configuration.logger&.debug("[Airtable] Connection #{event} for #{worksheet_name}")
+    end
+
+    # Routes a message to the configured logger. Without a logger, info/warn
+    # fall back to $stderr and debug is suppressed.
+    def emit_log(severity, message)
+      logger = AirtableClient.configuration.logger
+      if logger
+        logger.public_send(severity, message)
+      else
+        $stderr.puts(message)
+      end
+    end
+
+    def default_headers
+      {
+        'Authorization' => "Bearer #{@api_key}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def build_get_request(path, query: nil)
+      full_path = query ? "#{path}?#{encode_query(query)}" : path
+      request = Net::HTTP::Get.new(full_path)
+      default_headers.each { |key, value| request[key] = value }
+      request
+    end
+
+    def build_post_request(path, body:)
+      request = Net::HTTP::Post.new(path)
+      default_headers.each { |key, value| request[key] = value }
+      request.body = body.to_json
+      request
+    end
+
+    def build_put_request(path, body:)
+      request = Net::HTTP::Put.new(path)
+      default_headers.each { |key, value| request[key] = value }
+      request.body = body.to_json
+      request
+    end
+
+    def build_patch_request(path, body:)
+      request = Net::HTTP::Patch.new(path)
+      default_headers.each { |key, value| request[key] = value }
+      request.body = body.to_json
+      request
+    end
+
+    def build_delete_request(path)
+      request = Net::HTTP::Delete.new(path)
+      default_headers.each { |key, value| request[key] = value }
+      request
+    end
+
+    def encode_query(params)
+      params.flat_map do |key, value|
+        if value.is_a?(Array)
+          value.map { |v| "#{URI.encode_www_form_component(key.to_s)}=#{URI.encode_www_form_component(v.to_s)}" }
+        else
+          "#{URI.encode_www_form_component(key.to_s)}=#{URI.encode_www_form_component(value.to_s)}"
+        end
+      end.join('&')
+    end
+  end
+end