airrecord 0.2.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1224190a9be6b7349af9ab26640516b13961d88bc3b42d188c5879777e90fe04
-  data.tar.gz: 119beef65efdc6d110cc4e5c1865e92308c3e2a043b0e2e853484480488307d2
+  metadata.gz: 52a1efc847fab74c1bd0ff89814a274b1eb789359efda52a71675b6e7602f362
+  data.tar.gz: cb766b78e31e88ed253c2f7d7f2f7a1166fb5fec61bdbf46602b20b76a43cf9c
 SHA512:
-  metadata.gz: 577ae326c6cb761f7557c9b75a6a3e1fc46373aba67b6300430d9d0efac54e21eea30885237d40c233ef1c33f2d4bd3766984f0697211ebbff8bd6d7af160bcf
-  data.tar.gz: 11c1ce89e39a1f0e66f8c3b34cbf53eb21f69a2e91f98ae5460af85f1df2b62e37a1c01940263da8dba7c0499e822f8a3280ef55345cc93f76401c2d36579252
+  metadata.gz: ee40920b905e08644f8de12241b3bd842bac654b396c71e68677d8eec53b6f67f2fec17841754c9841e61542ac9f5de83c420141efc198cc2309d7d4fbbf0629
+  data.tar.gz: 64de96b6d7b81a8b9e147aa6adbf81402a5a6c1c5e23b681807df3cd408e420dfe065beb15135ad63706bf5899539cd979792afac9c8971aa21281fb55cce9d5

data/CHANGELOG.md

@@ -1,6 +1,22 @@
-# 1.0.0 (unreleased)
-
-* 1.0.0 will introduce breaking changes, including removing support for symbols. To update, change snake-case symbols to their correct column names (for example, `record["First Name"]` instead of `record[:first_name]`)
+# 1.0.0
+
+* 1.0.0 introduces breaking changes, including removing support for symbols and
+  implementing associations as instance methods. To upgrade:
+  1. Change snake-case symbols to their correct column names:
+    `record["First Name"]` instead of `record[:first_name]`)
+  2. Change your association calls to use instance methods instead of `[]`:
+      ```ruby
+      class Tea < Airrecord::Table
+        has_many :brews, class: "Brew", column: "Brews"
+      end
+      tea[:brews] #=> Error, no longer supported
+      tea.brews #=> [<Brew>, <Brew>] returns associated Brew instances
+      tea["Brews"] #=> ["rec456", "rec789"] returns a raw Airtable field
+      ```
+  3. Dates that are formed `\d{4}-\d{2}-\d{2}` are no longer auto-parsed. Define a helper instead.
+* Automatically throttle client calls to Airtable's API limit of 5 requests per second.
+* Fix sorting by multiple fields
+* Report `User-Agent` as `Airrecord`.
 
 # 0.2.5
 

data/README.md

@@ -20,7 +20,7 @@ class Tea < Airrecord::Table
   self.base_key = "app1"
   self.table_name = "Teas"
 
-  has_many "Brews", class: 'Brew', column: "Brews"
+  has_many :brews, class: "Brew", column: "Brews"
 
   def self.chinese
     all(filter: '{Country} = "China"')
@@ -43,14 +43,14 @@ class Brew < Airrecord::Table
   self.base_key = "app1"
   self.table_name = "Brews"
 
-  belongs_to "Tea", class: 'Tea', column: 'Tea'
+  belongs_to :tea, class: "Tea", column: "Tea"
 
   def self.hot
     all(filter: "{Temperature} > 90")
   end
 
   def done_brewing?
-    self["Created At"] + self["Duration"] > Time.now
+    Time.parse(self["Created At"]) + self["Duration"] > Time.now
   end
 end
 
@@ -58,7 +58,7 @@ teas = Tea.all
 tea = teas.first
 tea["Country"] # access atribute
 tea.location # instance methods
-tea["Brews"] # associated brews
+tea.brews # associated brews
 ```
 
 A short-hand API for definitions and more ad-hoc querying is also available:
@@ -115,10 +115,17 @@ end
 This gives us a class that maps to records in a table. Class methods are
 available to fetch records on the table.
 
+### Reading a Single Record
+
+Retrieve a single record via `#find`:
+```ruby
+tea = Tea.find("someid")
+```
+
 ### Listing Records
 
-Retrieval of multiple records is done through `#all`. To get all records in a
-table:
+Retrieval of multiple records is usually done through `#all`. To get all records
+in a table:
 
 ```ruby
 Tea.all # array of Tea instances
@@ -183,17 +190,33 @@ Tea.all(paginate: false)
 Tea.all(sort: { "Created At" => "desc" }, paginate: false)
 ```
 
+When you know the IDs of the records you want, and you want them in an ad-hoc
+order, use `#find_many` instead of `#all`:
+
+```ruby
+teas = Tea.find_many(["someid", "anotherid", "yetanotherid"])
+#=> [<Tea @id="someid">,<Tea @id="anotherid">, <Tea @id="yetanotherid">]
+```
+
 ### Creating
 
-Creating a new record is done through `#create`.
+Creating a new record is done through `Table.create`.
 
 ```ruby
-tea = Tea.new("Name" => "Feng Gang", "Type" => "Green", "Country" => "China")
-tea.create # creates the record
+tea = Tea.create("Name" => "Feng Gang", "Type" => "Green", "Country" => "China")
 tea.id # id of the new record
 tea["Name"] # "Feng Gang"
 ```
 
+If you need to manipulate a record before saving it, you can use `Table.new`
+instead of `create`, then call `#save` when you're ready.
+
+```ruby
+tea = Tea.new("Type" => "Green", "Country" => "China")
+tea["Name"] = "Feng Gang"
+tea.save
+```
+
 Note that column names need to match the exact column names in Airtable,
 otherwise Airrecord will throw an error that no column matches it.
 
@@ -268,14 +291,22 @@ class Tea < Airrecord::Table
   self.base_key = "app1"
   self.table_name = "Teas"
 
-  has_many "Brews", class: 'Brew', column: "Brews"
+  has_many :brews, class: "Brew", column: "Brews"
+  has_one :teapot, class: "Teapot", column: "Teapot"
 end
 
 class Brew < Airrecord::Table
   self.base_key = "app1"
   self.table_name = "Brews"
 
-  belongs_to "Tea", class: 'Tea', column: 'Tea'
+  belongs_to :tea, class: "Tea", column: "Tea"
+end
+
+class Teapot < Airrecord::Table
+  self.base_key = "app1"
+  self.table_name = "Teapot"
+
+  belongs_to :tea, class: "Tea", column: "Tea"
 end
 ```
 
@@ -289,15 +320,23 @@ _not_ support associations across Bases.
 To retrieve records from associations to a record:
 
 ```ruby
-tea = Tea.find('rec84')
-tea["Brews"] # brews associated with tea
+tea = Tea.find("rec123")
+
+# record.association returns Airrecord instances
+tea.brews #=> [<Brew @id="rec456">, <Brew @id="rec789">]
+tea.teapot #=> <Teapot @id="rec012">
+
+# record["Associated Column"] returns the raw Airtable field, an array of IDs
+tea["Brews"] #=> ["rec789", "rec456"]
+tea["Teapot"] #=> ["rec012"]
 ```
 
 This in turn works the other way too:
 
 ```ruby
-brew = Brew.find('rec849')
-brew["Tea"] # the associated tea instance
+brew = Brew.find("rec456")
+brew.tea #=> <Tea @id="rec123"> the associated tea instance
+brew["Tea"] #=> the raw Airtable field, a single-item array ["rec123"]
 ```
 
 ### Creating associated records
@@ -305,9 +344,18 @@ brew["Tea"] # the associated tea instance
 You can easily associate records with each other:
 
 ```ruby
-tea = Tea.find('rec849829')
+tea = Tea.find("rec123")
 # This will create a brew associated with the specific tea
-brew = Brew.new("Tea" => tea, "Temperature" => "80", "Time" => "4m", "Rating" => "5")
+brew = Brew.new("Temperature" => "80", "Time" => "4m", "Rating" => "5")
+brew.tea = tea
+brew.create
+```
+
+Alternatively, you can specify association ids directly:
+
+```ruby
+tea = Tea.find("rec123")
+brew = Brew.new("Tea" => [tea.id], "Temperature" => "80", "Time" => "4m", "Rating" => "5")
 brew.create
 ```
 
@@ -328,6 +376,15 @@ end
 Tea.find("rec3838")
 ```
 
+### Throttling
+
+Airtable's API enforces a 5 requests per second limit per client. In most cases,
+you won't reach this limit in a single thread but it's possible for some fast
+calls. Airrecord automatically enforces this limit. It doesn't use a naive
+throttling algorithm that does a `sleep(0.2)` between each call, but rather
+keeps a sliding window of when each call was made and will sleep at the end of
+the window if requires. This means that bursting is supported.
+
 ### Production Middlewares
 
 For production use-cases, it's worth considering adding retries and circuit

data/lib/airrecord.rb

@@ -9,4 +9,10 @@ module Airrecord
   extend self
   Error = Class.new(StandardError)
   attr_accessor :api_key
+  attr_accessor :throttle
+
+  def throttle?
+    return true if @throttle.nil?
+    @throttle
+  end
 end

data/lib/airrecord/client.rb

@@ -1,25 +1,39 @@
 require 'uri'
+require_relative 'query_string'
+require_relative 'faraday_rate_limiter'
 
 module Airrecord
   class Client
     attr_reader :api_key
     attr_writer :connection
 
+    # Per Airtable's documentation you will get throttled for 30 seconds if you
+    # issue more than 5 requests per second. Airrecord is a good citizen.
+    AIRTABLE_RPS_LIMIT = 5
+
     def initialize(api_key)
       @api_key = api_key
     end
 
     def connection
-      @connection ||= Faraday.new(url: "https://api.airtable.com", headers: {
-        "Authorization" => "Bearer #{api_key}",
-        "X-API-VERSION" => "0.1.0",
-      }) { |conn|
+      @connection ||= Faraday.new(
+        url: "https://api.airtable.com",
+        headers: {
+          "Authorization" => "Bearer #{api_key}",
+          "User-Agent"    => "Airrecord/#{Airrecord::VERSION}",
+          "X-API-VERSION" => "0.1.0",
+        },
+        request: { params_encoder: Airrecord::QueryString },
+      ) { |conn|
+        if Airrecord.throttle?
+          conn.request :airrecord_rate_limiter, requests_per_second: AIRTABLE_RPS_LIMIT
+        end
         conn.adapter :net_http_persistent
       }
     end
 
     def escape(*args)
-      URI.escape(*args)
+      QueryString.escape(*args)
     end
 
     def parse(body)

data/lib/airrecord/faraday_rate_limiter.rb

@@ -0,0 +1,60 @@
+require 'thread'
+
+module Airrecord
+  class FaradayRateLimiter < Faraday::Middleware
+    class << self
+      attr_accessor :requests
+    end
+
+    def initialize(app, requests_per_second: nil, sleeper: nil)
+      super(app)
+      @rps = requests_per_second
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @mutex = Mutex.new
+      clear
+    end
+
+    def call(env)
+      @mutex.synchronize do
+        wait if too_many_requests_in_last_second?
+        @app.call(env).on_complete do |_response_env|
+          requests << Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          requests.shift if requests.size > @rps
+        end
+      end
+    end
+
+    def clear
+      self.class.requests = []
+    end
+
+    private
+
+    def requests
+      self.class.requests
+    end
+
+    def too_many_requests_in_last_second?
+      return false unless @rps
+      return false unless requests.size >= @rps
+      window_span < 1.0
+    end
+
+    def wait
+      # Time to wait until making the next request to stay within limits.
+      # [1.1, 1.2, 1.3, 1.4, 1.5] => 1 - 0.4 => 0.6
+      wait_time = 1.0 - window_span
+      @sleeper.call(wait_time)
+    end
+
+    # [1.1, 1.2, 1.3, 1.4, 1.5] => 1.5 - 1.1 => 0.4
+    def window_span
+      requests.last - requests.first
+    end
+  end
+end
+
+Faraday::Request.register_middleware(
+  # Avoid polluting the global middleware namespace with a prefix.
+  :airrecord_rate_limiter => Airrecord::FaradayRateLimiter
+)

data/lib/airrecord/query_string.rb

@@ -0,0 +1,47 @@
+require 'erb'
+
+module Airrecord
+  # Airtable expects that arrays in query strings be encoded with indices.
+  # Faraday follows Rack conventions and encodes arrays _without_ indices.
+  #
+  # Airrecord::QueryString is a Faraday-compliant params_encoder that follows
+  # the Airtable spec.
+  module QueryString
+    def self.encode(params)
+      params.map { |key, val| Encodings[val].call(key, val) }.join('&')
+    end
+
+    def self.decode(query)
+      Faraday::NestedParamsEncoder.decode(query)
+    end
+
+    def self.escape(*query)
+      query.map { |qs| ERB::Util.url_encode(qs) }.join('')
+    end
+
+    module Encodings
+      using QueryString
+
+      def self.[](value)
+        TYPES.fetch(value.class, DEFAULT)
+      end
+
+      TYPES = {
+        Array => lambda { |prefix, array|
+          array.each_with_index.map do |value, index|
+            self[value].call("#{prefix}[#{index}]", value)
+          end
+        },
+        Hash => lambda { |prefix, hash|
+          hash.map do |key, value|
+            self[value].call("#{prefix}[#{key}]", value)
+          end
+        },
+      }.freeze
+
+      DEFAULT = lambda do |key, value|
+        "#{QueryString.escape(key)}=#{QueryString.escape(value)}"
+      end
+    end
+  end
+end

data/lib/airrecord/table.rb

@@ -1,47 +1,33 @@
 module Airrecord
-  # TODO: This would be much simplified if we had a schema instead. Hopefully
-  # one day Airtable will add this, but to simplify and crush the majority of
-  # the bugs that hide in here (which would be related to the dynamic schema) we
-  # may just query the first page and infer a schema from there that can be
-  # overridden on the specific classes.
-  #
-  # Right now I bet there's a bunch of bugs around similar named column keys (in
-  # terms of capitalization), it's inconsistent and non-obvious that `create`
-  # doesn't use the same column keys as everything else.
-  #
-  # 2018-11-01
-  # deprecate_symbols: long-term plan is to force everyone to use raw strings,
-  # to match the Airtable behavior. For now we'll just warn when using symbols
-  # with a deprecation notice.
-
   class Table
-    def deprecate_symbols
-      self.class.deprecate_symbols
-    end
-
     class << self
       attr_accessor :base_key, :table_name, :api_key, :associations
 
-      def deprecate_symbols
-        warn Kernel.caller.first + ": warning: Using symbols with airrecord is deprecated."
-      end
-      
       def client
         @@clients ||= {}
         @@clients[api_key] ||= Client.new(api_key)
       end
 
-      def has_many(name, options)
-        @associations ||= []
-        @associations << {
-          field: name.to_sym, # todo: deprecate_symbols
-        }.merge(options)
+      def has_many(method_name, options)
+        define_method(method_name.to_sym) do
+          # Get association ids in reverse order, because Airtable’s UI and API
+          # sort associations in opposite directions. We want to match the UI.
+          ids = (self[options.fetch(:column)] || []).reverse
+          table = Kernel.const_get(options.fetch(:class))
+          options[:single] ? table.find(ids.first) : table.find_many(ids)
+        end
+
+        define_method("#{method_name}=".to_sym) do |value|
+          self[options.fetch(:column)] = Array(value).map(&:id).reverse
+        end
       end
 
-      def belongs_to(name, options)
-        has_many(name, options.merge(single: true))
+      def belongs_to(method_name, options)
+        has_many(method_name, options.merge(single: true))
       end
 
+      alias has_one belongs_to
+
       def api_key
         @api_key || Airrecord.api_key
       end
@@ -57,13 +43,22 @@ module Airrecord
         end
       end
 
+      def find_many(ids)
+        or_args = ids.map { |id| "RECORD_ID() = '#{id}'"}.join(',')
+        formula = "OR(#{or_args})"
+        records(filter: formula).sort_by { |record| or_args.index(record.id) }
+      end
+
+      def create(fields)
+        new(fields).tap { |record| record.save }
+      end
+
       def records(filter: nil, sort: nil, view: nil, offset: nil, paginate: true, fields: nil, max_records: nil, page_size: nil)
         options = {}
         options[:filterByFormula] = filter if filter
 
         if sort
           options[:sort] = sort.map { |field, direction|
-            deprecate_symbols if field.is_a? Symbol
             { field: field.to_s, direction: direction }
           }
         end
@@ -105,7 +100,7 @@ module Airrecord
       alias_method :all, :records
     end
 
-    attr_reader :fields, :column_mappings, :id, :created_at, :updated_keys
+    attr_reader :fields, :id, :created_at, :updated_keys
 
     def initialize(fields, id: nil, created_at: nil)
       @id = id
@@ -118,51 +113,22 @@ module Airrecord
     end
 
     def [](key)
-      value = nil
-
-      if fields[key]
-        deprecate_symbols if key.is_a? Symbol
-        value = fields[key]
-      elsif column_mappings[key]
-        deprecate_symbols if key.is_a? Symbol
-        value = fields[column_mappings[key]]
-      end
-
-      if association = self.association(key)
-        klass = Kernel.const_get(association[:class])
-        associations = value.map { |id_or_obj|
-          id_or_obj = id_or_obj.respond_to?(:id) ? id_or_obj.id : id_or_obj
-          klass.find(id_or_obj)
-        }
-        return associations.first if association[:single]
-        associations
-      else
-        type_cast(value)
-      end
+      validate_key(key)
+      fields[key]
     end
 
     def []=(key, value)
-      deprecate_symbols if key.is_a? Symbol
-      if fields[key]
-        return if fields[key] == value # no-op
-        @updated_keys << key
-        fields[key] = value
-      elsif column_mappings[key]
-        deprecate_symbols
-        return if fields[column_mappings[key]] == value # no-op
-        @updated_keys << column_mappings[key]
-        fields[column_mappings[key]] = value
-      else
-        @updated_keys << key
-        fields[key] = value
-      end
+      validate_key(key)
+      return if fields[key] == value # no-op
+      @updated_keys << key
+      fields[key] = value
     end
 
     def create
       raise Error, "Record already exists (record has an id)" unless new_record?
 
       body = { fields: serializable_fields }.to_json
-      response = client.connection.post("/v0/#{self.class.base_key}/#{client.escape(self.class.table_name)}", body, { 'Content-Type': 'application/json' })
+      response = client.connection.post("/v0/#{self.class.base_key}/#{client.escape(self.class.table_name)}", body, { 'Content-Type' => 'application/json' })
       parsed_response = client.parse(response.body)
 
       if response.success?
@@ -175,7 +141,7 @@ module Airrecord
     end
 
     def save
-      raise Error, "Unable to save a new record" if new_record?
+      return create if new_record?
 
       return true if @updated_keys.empty?
 
@@ -186,11 +152,11 @@ module Airrecord
         }]
       }.to_json
 
-      response = client.connection.patch("/v0/#{self.class.base_key}/#{client.escape(self.class.table_name)}/#{self.id}", body, { 'Content-Type': 'application/json' })
+      response = client.connection.patch("/v0/#{self.class.base_key}/#{client.escape(self.class.table_name)}/#{self.id}", body, { 'Content-Type' => 'application/json' })
       parsed_response = client.parse(response.body)
 
       if response.success?
-        self.fields = parsed_response
+        self.fields = parsed_response["fields"]
       else
         client.handle_error(response.status, parsed_response)
       end
@@ -209,18 +175,8 @@ module Airrecord
       end
     end
 
-    def serializable_fields(fields = self.fields)
-      Hash[fields.map { |(key, value)|
-        if association(key)
-          value = [ value ] unless value.is_a?(Enumerable)
-          assocs = value.map { |assoc|
-            assoc.respond_to?(:id) ? assoc.id : assoc
-          }
-          [key, assocs]
-        else
-          [key, value]
-        end
-        }]
+    def serializable_fields
+      fields
     end
 
     def ==(other)
@@ -236,28 +192,11 @@ module Airrecord
 
     protected
 
-    def association(key)
-      if self.class.associations
-        self.class.associations.find { |association|
-          association[:column].to_s == column_mappings[key].to_s || association[:column].to_s == key.to_s
-        }
-      end
-    end
-
     def fields=(fields)
       @updated_keys = []
-      @column_mappings = Hash[fields.keys.map { |key| [underscore(key), key] }] # TODO remove (deprecate_symbols)
       @fields = fields
     end
 
-    def self.underscore(key) # TODO remove (deprecate_symbols)
-      key.to_s.strip.gsub(/\W+/, "_").downcase.to_sym
-    end
-
-    def underscore(key) # TODO remove (deprecate_symbols)
-      self.class.underscore(key)
-    end
-
     def created_at=(created_at)
       return unless created_at
       @created_at = Time.parse(created_at)
@@ -267,14 +206,14 @@ module Airrecord
       self.class.client
     end
 
-    def type_cast(value)
-      if value =~ /\d{4}-\d{2}-\d{2}/
-        Time.parse(value + " UTC")
-      else
-        value
-      end
+    def validate_key(key)
+      return true unless key.is_a?(Symbol)
+      raise Error, <<~MSG
+        Airrecord 1.0 dropped support for Symbols as field names.
+        Please use the full column name, a String, instead.
+        You might try: record['#{key.to_s.gsub('_', ' ')}']
+      MSG
     end
-
   end
 
   def self.table(api_key, base_key, table_name)

data/lib/airrecord/version.rb

@@ -1,3 +1,3 @@
 module Airrecord
-  VERSION = "0.2.5"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: airrecord
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 1.0.0
 platform: ruby
 authors:
 - Simon Eskildsen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-05 00:00:00.000000000 Z
+date: 2018-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -113,6 +113,8 @@ files:
 - bin/setup
 - lib/airrecord.rb
 - lib/airrecord/client.rb
+- lib/airrecord/faraday_rate_limiter.rb
+- lib/airrecord/query_string.rb
 - lib/airrecord/table.rb
 - lib/airrecord/version.rb
 homepage: https://github.com/sirupsen/airrecord