fmrest 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3fd72c8d862e6225e0997c1b5a3f68597304dccba912d4230f92495536bf528
-  data.tar.gz: 528e8673d20825ed9d1dacacad8b59493099a8b18f8f530baaac34038ba3e8ce
+  metadata.gz: d9ac0ed8884efb3c03f32de33e934f5ba7298ff17fd6f2531bc31c09fff53654
+  data.tar.gz: c1b29afaf072953515843db4c95e9e7426662a64bc8df3aa88ec99dc7c3715f6
 SHA512:
-  metadata.gz: 38fed0930933ce59b32054459f41a9aeb7b7d1b4c7ae6e5ead53e331452c2180cab4e1a08b582f5729df745e94db85ae4b5fdf448aacebce9dd772e9073f5d53
-  data.tar.gz: 00ab8ffd3e3dd0ac1ab8a91eccc8e60f0edd9844e77c32bf2775ac03fbd610e969315e6398d499ca8cf919c78c9dc7baa45b38109ee1f328241b46bca01769a5
+  metadata.gz: 685dbf33e5fb4fd929e7fd5dba1a35ba6791f81590dd34e3abef16ea129b1603403e1c5fb09ea82b536e501ff7ab072a62e24b85223a53ab85602f757e825831
+  data.tar.gz: 25fd66ec79dfb9356c7939641e97ef65e6ba49decfc289fd4cdfc373de9656392b4889d143f91bf5df5a5c9e020913c068e1bfcdfe9573a16063a598cf86b8b9

data/.gitignore

@@ -20,6 +20,7 @@ tmp
 *.o
 *.a
 mkmf.log
+spec/db/*
 
 # rspec failure tracking
 .rspec_status

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/README.md

@@ -1,5 +1,7 @@
 # fmrest-ruby
 
+<a href="https://rubygems.org/gems/fmrest"><img src="https://badge.fury.io/rb/fmrest.svg?style=flat" alt="Gem Version"></a>
+
 A Ruby client for
 [FileMaker 17's Data API](https://fmhelp.filemaker.com/docs/17/en/dataapi/)
 using
@@ -20,6 +22,9 @@ Add this line to your Gemfile:
 
 ```ruby
 gem 'fmrest'
+
+# Optional (for ORM features)
+gem 'spyke'
 ```
 
 ## Basic usage
@@ -63,23 +68,59 @@ By default fmrest-ruby will use a memory-based store for the session tokens.
 This is generally good enough for development, but not good enough for
 production, as in-memory tokens aren't shared across threads/processes.
 
-Besides the default memory token store an ActiveRecord-based token store is
-included with the gem (maybe more to come later).
+Besides the default token store the following token stores are bundled with fmrest-ruby:
+
+### ActiveRecord
 
 On Rails apps already using ActiveRecord setting up this token store should be
 dead simple:
 
 ```ruby
 # config/initializers/fmrest.rb
-require "fmrest/v1/token_store/active_record"
+require "fmrest/token_store/active_record"
 
-FmRest.token_store = FmRest::V1::TokenStore::ActiveRecord
+FmRest.token_store = FmRest::TokenStore::ActiveRecord
 ```
 
 No migrations are needed, the token store table will be created automatically
-when needed, defaulting to the table name "fmrest_session_tokens".
+when needed, defaulting to the table name "fmrest_session_tokens". If you want
+to change the table name you can do so by initializing the token store and
+passing it the `:table_name` option:
+
+```ruby
+FmRest.token_store = FmRest::TokenStore::ActiveRecord.new(table_name: "my_token_store")
+```
+
+### Redis
+
+To use the Redis token store do:
+
+```ruby
+require "fmrest/token_store/redis"
+
+FmRest.token_store = FmRest::TokenStore::Redis
+```
+
+You can also initialize it with the following options:
+
+* `:redis` - A `Redis` object to use as connection, if ommited a new `Redis` object will be created with remaining options
+* `:prefix` - The prefix to use for token keys, by default `"fmrest-token:"`
+* Any other options will be passed to `Redis.new` if `:redis` isn't provided
+
+Examples:
+
+```ruby
+# Passing a Redis connection explicitly
+FmRest.token_store = FmRest::TokenStore::Redis.new(redis: Redis.new, prefix: "my-fancy-prefix:")
 
-## Spyke support
+# Passing options for Redis.new
+FmRest.token_store = FmRest::TokenStore::Redis.new(prefix: "my-fancy-prefix:", host: "10.0.1.1", port: 6380, db: 15)
+```
+
+**NOTE:** redis-rb is not included as a gem dependency of fmrest-ruby, so you'll
+have to add it to your Gemfile.
+
+## Spyke support (ActiveRecord-like ORM)
 
 [Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
 building REST models. fmrest-ruby has Spyke support out of the box, although
@@ -348,18 +389,24 @@ class Kitty < Spyke::Base
 end
 ```
 
+#### .limit
+
 `.limit` sets the limit for get and find request:
 
 ```ruby
 Kitty.limit(10)
 ```
 
+#### .offset
+
 `.offset` sets the offset for get and find requests:
 
 ```ruby
 Kitty.offset(10)
 ```
 
+#### .sort
+
 `.sort` (or `.order`) sets sorting options for get and find requests:
 
 ```ruby
@@ -375,6 +422,8 @@ Kitty.sort(:name, :age!)
 Kitty.sort(:name, :age__desc)
 ```
 
+#### .portal
+
 `.portal` (or `.includes`) sets the portals to fetch for get and find requests
 (this recognizes portals defined with `has_portal`):
 
@@ -383,6 +432,8 @@ Kitty.portal(:toys)
 Kitty.includes(:toys) # alias method
 ```
 
+#### .query
+
 `.query` sets query conditions for a find request (and supports attributes as
 defined with `attributes`):
 
@@ -407,6 +458,8 @@ Kitty.query({ name: "Mr. Fluffers" }, { name: "Coronel Chai Latte" })
 # JSON -> {"query": [{"CatName": "Mr. Fluffers"}, {"CatName": "Coronel Chai Latte"}]}
 ```
 
+#### .omit
+
 `.omit` works like `.query` but excludes matches:
 
 ```ruby
@@ -421,6 +474,8 @@ Kitty.query(name: "Captain Whiskers", omit: true)
 # JSON -> {"query": [{"CatName": "Captain Whiskers", "omit": "true"}]}
 ```
 
+#### Other notes on querying
+
 You can chain all query methods together:
 
 ```ruby
@@ -463,6 +518,43 @@ instead of `POST ../:layout/_find`).
 Kitty.find(89) # => <Kitty...>
 ```
 
+### Container fields
+
+You can define container fields on your model class with `container`:
+
+```ruby
+class Kitty < FmRest::Spyke::Base
+  container :photo, field_name: "Vet Card Photo ID"
+end
+```
+
+`:field_name` specifies the original field in the FM layout and is optional, if
+not given it will default to the name of your attribute (just `:photo` in this
+example).
+
+(Note that you don't need to define container fields with `attributes` in
+addition to the `container` definition.)
+
+This will provide you with the following instance methods:
+
+```ruby
+kitty = Kitty.new
+
+kitty.photo.url # The URL of the container file on the FileMaker server
+
+kitty.photo.download # Download the contents of the container as an IO object
+
+kitty.photo.upload(filename_or_io) # Upload a file to the container
+```
+
+`upload` also accepts an options hash with the following options:
+
+* `:repetition` - Sets the field repetition
+* `:filename` - The filename to use when uploading (defaults to
+  `filename_or_io.original_filename` if available)
+* `:content_type` - The MIME content type to use (defaults to
+  `application/octet-stream`)
+
 ## Logging
 
 If using fmrest-ruby + Spyke in a Rails app pretty log output will be set up
@@ -510,11 +602,13 @@ end
 
 ## TODO
 
+- [ ] Support for FM18 features
 - [ ] Better/simpler-to-use core Ruby API
 - [ ] Better API documentation and README
 - [ ] Oauth support
 - [ ] Support for portal limit and offset
-- [ ] More options for token storage
+- [x] More options for token storage
+- [x] Support for container fields
 - [x] Optional logging
 - [x] FmRest::Spyke::Base class for single inheritance (as alternative for mixin)
 - [x] Specs

data/fmrest.gemspec

@@ -30,4 +30,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "webmock"
   spec.add_development_dependency "multi_json"
   spec.add_development_dependency "pry-byebug"
+  spec.add_development_dependency "activerecord"
+  spec.add_development_dependency "sqlite3", "~> 1.3.6"
+  spec.add_development_dependency "mock_redis"
 end

data/lib/fmrest.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "faraday"
 require "faraday_middleware"
 

data/lib/fmrest/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FmRest
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :code
+
+    def initialize(code, message = nil)
+      @code = code
+      super("FileMaker Data API responded with error #{code}: #{message}")
+    end
+  end
+
+  class APIError::UnknownError < APIError; end         # error code -1
+  class APIError::ResourceMissingError < APIError; end # error codes 100..199
+  class APIError::RecordMissingError < APIError::ResourceMissingError; end
+  class APIError::AccountError < APIError; end         # error codes 200..299
+  class APIError::LockError < APIError; end            # error codes 300..399
+  class APIError::ParameterError < APIError; end       # error codes 400..499
+  class APIError::ValidationError < APIError; end      # error codes 500..599
+  class APIError::SystemError < APIError; end          # error codes 800..899
+  class APIError::ScriptError < APIError; end          # error codes 1200..1299
+  class APIError::ODBCError < APIError; end            # error codes 1400..1499
+
+  class ContainerFieldError < Error; end
+end

data/lib/fmrest/spyke.rb

@@ -1,3 +1,12 @@
+# frozen_string_literal: true
+
+begin
+  require "spyke"
+rescue LoadError => e
+  e.message << " (Did you include Spyke in your Gemfile?)" unless e.message.frozen?
+  raise e
+end
+
 require "fmrest/spyke/json_parser"
 require "fmrest/spyke/model"
 require "fmrest/spyke/base"

data/lib/fmrest/spyke/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FmRest
   module Spyke
     class Base < ::Spyke::Base

data/lib/fmrest/spyke/container_field.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    class ContainerField
+
+      # @return [String] the name of the container field
+      attr_reader :name
+
+      # @param base [FmRest::Spyke::Base] the record this container belongs to
+      # @param name [Symbol] the name of the container field
+      def initialize(base, name)
+        @base = base
+        @name = name
+      end
+
+      # @return [String] the URL for the container
+      def url
+        @base.attributes[name]
+      end
+
+      # @return (see FmRest::V1::ContainerFields#fetch_container_data)
+      def download
+        FmRest::V1.fetch_container_data(url)
+      end
+
+      # @param filename_or_io [String, IO] a path to the file to upload or an
+      #   IO object
+      # @param options [Hash]
+      # @option options [Integer] :repetition (1) The repetition to pass to the
+      #   upload URL
+      # @option (see FmRest::V1::ContainerFields#upload_container_data)
+      def upload(filename_or_io, options = {})
+        raise ArgumentError, "Record needs to be saved before uploading to a container field" unless @base.persisted?
+
+        response =
+          FmRest::V1.upload_container_data(
+            @base.class.connection,
+            upload_path(options[:repetition] || 1),
+            filename_or_io,
+            options
+          )
+
+        # Update mod id on record
+        @base.mod_id = response.body[:data][:mod_id]
+
+        true
+      end
+
+      private
+
+      # @param repetition [Integer]
+      # @return [String] the path for uploading a file to the container
+      def upload_path(repetition)
+        FmRest::V1.container_field_path(@base.class.layout, @base.id, name, repetition)
+      end
+    end
+  end
+end

data/lib/fmrest/spyke/json_parser.rb

@@ -1,31 +1,41 @@
+# frozen_string_literal: true
+
 module FmRest
   module Spyke
+    # Response Faraday middleware for converting FM API's response JSON into
+    # Spyke's expected format
     class JsonParser < ::Faraday::Response::Middleware
       SINGLE_RECORD_RE = %r(/records/\d+\Z).freeze
+      MULTIPLE_RECORDS_RE = %r(/records\Z).freeze
       FIND_RECORDS_RE = %r(/_find\b).freeze
 
+      VALIDATION_ERROR_RANGE = 500..599
+
+      # @param app [#call]
+      # @param model [Class<FmRest::Spyke::Base>]
       def initialize(app, model)
         super(app)
         @model = model
       end
 
+      # @param env [Faraday::Env]
       def on_complete(env)
         json = parse_json(env.body)
 
-        env.body =
-          if env.method == :get || find_results?(env.url)
-            if single_record_url?(env.url)
-              prepare_single_record(json)
-            else
-              prepare_collection(json)
-            end
-          else
-            prepare_save_response(json)
-          end
+        case
+        when single_record_request?(env)
+          env.body = prepare_single_record(json)
+        when multiple_records_request?(env), find_request?(env)
+          env.body = prepare_collection(json)
+        when create_request?(env), update_request?(env), delete_request?(env)
+          env.body = prepare_save_response(json)
+        end
       end
 
       private
 
+      # @param json [Hash]
+      # @return [Hash] the response in Spyke format
       def prepare_save_response(json)
         response = json[:response]
 
@@ -33,33 +43,53 @@ module FmRest
         data[:mod_id] = response[:modId].to_i if response[:modId]
         data[:id]     = response[:recordId].to_i if response[:recordId]
 
-        base_hash(json).merge!(data: data)
+        build_base_hash(json, true).merge!(data: data)
       end
 
+      # (see #prepare_save_response)
       def prepare_single_record(json)
         data =
           json[:response][:data] &&
           prepare_record_data(json[:response][:data].first)
 
-        base_hash(json).merge!(data: data)
+        build_base_hash(json).merge!(data: data)
       end
 
+      # (see #prepare_save_response)
       def prepare_collection(json)
         data =
           json[:response][:data] &&
           json[:response][:data].map { |record_data| prepare_record_data(record_data) }
 
-        base_hash(json).merge!(data: data)
+        build_base_hash(json).merge!(data: data)
       end
 
-      def base_hash(json)
+      # @param json [Hash]
+      # @param include_errors [Boolean]
+      # @return [Hash] the skeleton structure for a Spyke-formatted response
+      def build_base_hash(json, include_errors = false)
         {
           metadata: { messages: json[:messages] },
-          errors:   {}
+          errors:   include_errors ? prepare_errors(json) : {}
         }
       end
 
-      # json_data is expected in this format:
+      # @param json [Hash]
+      # @return [Hash] the errors hash in Spyke format
+      def prepare_errors(json)
+        # Code 0 means "No Error"
+        # https://fmhelp.filemaker.com/help/17/fmp/en/index.html#page/FMP_Help/error-codes.html
+        return {} if json[:messages][0][:code].to_i == 0
+
+        json[:messages].each_with_object(base: []) do |message, hash|
+          # Only include validation errors
+          next unless VALIDATION_ERROR_RANGE.include?(message[:code].to_i)
+
+          hash[:base] << "#{message[:message]} (#{message[:code]})"
+        end
+      end
+
+      # `json_data` is expected in this format:
       #
       #     {
       #       "fieldData": {
@@ -83,6 +113,8 @@ module FmRest
       #       "recordId": <Unique_internal_ID_for_this_record>
       #     }
       #
+      # @param json_data [Hash]
+      # @return [Hash] the record data in Spyke format
       def prepare_record_data(json_data)
         out = { id: json_data[:recordId].to_i, mod_id: json_data[:modId].to_i }
         out.merge!(json_data[:fieldData])
@@ -90,17 +122,19 @@ module FmRest
         out
       end
 
-      # Extracts recordId and strips the PortalName:: field prefix for each
+      # Extracts `recordId` and strips the `"PortalName::"` field prefix for each
       # portal
       #
-      # Sample json_portal_data:
+      # Sample `json_portal_data`:
       #
       #     "portalData": {
       #       "Orders":[
-      #         { "Orders::DeliveryDate":"3/7/2017", "recordId":"23" }
+      #         { "Orders::DeliveryDate": "3/7/2017", "recordId": "23" }
       #       ]
       #     }
       #
+      # @param json_portal_data [Hash]
+      # @return [Hash] the portal data in Spyke format
       def prepare_portal_data(json_portal_data)
         json_portal_data.each_with_object({}) do |(portal_name, portal_records), out|
           portal_options = @model.portal_options[portal_name.to_s] || {}
@@ -115,7 +149,7 @@ module FmRest
 
               portal_fields.each do |k, v|
                 next if :recordId == k || :modId == k
-                attributes[k.to_s.gsub(prefix_matcher, "")] = v
+                attributes[k.to_s.gsub(prefix_matcher, "").to_sym] = v
               end
 
               attributes
@@ -123,14 +157,39 @@ module FmRest
         end
       end
 
-      def find_results?(url)
-        url.path.match(FIND_RECORDS_RE)
+      # @param env [Faraday::Env]
+      # @return [Boolean]
+      def single_record_request?(env)
+        env.method == :get && env.url.path.match(SINGLE_RECORD_RE)
+      end
+
+      # (see #single_record_request?)
+      def multiple_records_request?(env)
+        env.method == :get && env.url.path.match(MULTIPLE_RECORDS_RE)
+      end
+
+      # (see #single_record_request?)
+      def find_request?(env)
+        env.method == :post && env.url.path.match(FIND_RECORDS_RE)
+      end
+
+      # (see #single_record_request?)
+      def update_request?(env)
+        env.method == :patch && env.url.path.match(SINGLE_RECORD_RE)
+      end
+
+      # (see #single_record_request?)
+      def create_request?(env)
+        env.method == :post && env.url.path.match(MULTIPLE_RECORDS_RE)
       end
 
-      def single_record_url?(url)
-        url.path.match(SINGLE_RECORD_RE)
+      # (see #single_record_request?)
+      def delete_request?(env)
+        env.method == :delete && env.url.path.match(SINGLE_RECORD_RE)
       end
 
+      # @param source [String] a JSON string
+      # @return [Hash] the parsed JSON
       def parse_json(source)
         if defined?(::MultiJson)
           ::MultiJson.load(source, symbolize_keys: true)