fmrest 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 368ed06195288490b1388c451b00bb33f5c19e526348422a3760a14902459d76
-  data.tar.gz: a445ef1bd8ef708b6aea2c5f8c2362f77e8c1afbd80bb6ef1d354c669ef8c9f6
+  metadata.gz: 61e4602ba4797de70a866ea14197056bd0d09ca0bab4d09e44ddade7719395ac
+  data.tar.gz: 77982322ac28bef17e648888dc67753a56fb02c3b31e616d7d4129c6031ba676
 SHA512:
-  metadata.gz: 1d2e8cb78c9a232f8ec13dde7ad3407f5dbfc14c49c0e5aadeb7a940c1fe07f14e919832b53841e4ac054f81c74a64fb7721614218c342835a2274c3b187aa96
-  data.tar.gz: 9695ef91a8eef005420c0003e62eb1712eda8f11667e87f345c311b008c712113b4ff52be31e1fc207237efc7e7279d5952b2d0b2ed3b4a26a2a8aa55ad38638
+  metadata.gz: c872d1d1b37710720d0cd5398f985c1abc6d59105fe117905518d86f2617f82e539e743b8d57693bde34558381a500d32f1d942f240705db21d5415ca2c86f14
+  data.tar.gz: e71b4ca034162ed34b847b66d7ae0063f3fa654be1a73ddf12c9f995ca62956a186737ca15ba06939d5982a3b62bab30c2ad7d125498b07024276a7b0518d00c

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## Changelog
 
+### 0.5.0
+
+* Much improved script execution support
+  ([#20](https://github.com/beezwax/fmrest-ruby/issues/20))
+* Fixed bug when setting `default_limi` and trying to find a record
+  ([35](https://github.com/beezwax/fmrest-ruby/issues/35))
+
 ### 0.4.1
 
 * Prevent raising an exception when a /\_find request yields no results

data/README.md

@@ -587,6 +587,16 @@ Honeybee.query(name: "Hutch", omit: true)
 # JSON -> {"query": [{"Bee Name": "Hutch", "omit": "true"}]}
 ```
 
+#### .script
+
+`.script` enables the execution of scripts during query requests.
+
+```ruby
+Honeybee.script("My script").find_some # Fetch records and execute a script
+```
+
+See section on [script execution](#script-execution) below for more info.
+
 #### Other notes on querying
 
 You can chain all query methods together:
@@ -625,14 +635,18 @@ force `.limit(1)`):
 Honeybee.query(name: "Hutch").find_one # => <Honeybee...>
 ```
 
-NOTE: If you know the id of the record you should use `.find(id)` instead of
-`.query(id: id).find_one` (so that the request is sent as `GET ../:layout/records/:id`
-instead of `POST ../:layout/_find`).
+If you know the id of the record you should use `.find(id)` instead of
+`.query(id: id).find_one` (so that the sent request is
+`GET ../:layout/records/:id` instead of `POST ../:layout/_find`).
 
 ```ruby
 Honeybee.find(89) # => <Honeybee...>
 ```
 
+Note also that if you use `.find(id)` your `.query()` parameters (as well as
+limit, offset and sort parameters) will be discarded as they're not supported
+by the single record endpoint.
+
 ### Container fields
 
 You can define container fields on your model class with `container`:
@@ -670,6 +684,118 @@ bee.photo.upload(filename_or_io) # Upload a file to the container
 * `:content_type` - The MIME content type to use (defaults to
   `application/octet-stream`)
 
+### Script execution
+
+The Data API allows running scripts as part of many types of requests.
+
+#### Model.execute_script
+As of FM18 you can execute scripts directly. To do that for a specific model
+use `Model.execute_script`:
+
+```ruby
+result = Honeybee.execute_script("My Script", param: "optional parameter")
+```
+
+This will return a `Spyke::Result` object containing among other things the
+result of the script execution:
+
+```ruby
+result.metadata[:script][:after]
+# => { result: "oh hi", error: "0" }
+```
+
+#### Script options object format
+
+All other script-capable requests take one or more of three possible script
+execution options: `script.prerequest`, `script.presort` and plain `script`
+(which fmrest-ruby dubs `after` for convenience).
+
+Because of that fmrest-ruby uses a common object format for specifying script options
+across multiple methods. That object format is as follows:
+
+```ruby
+# Just a string means to execute that `after' script without a parameter
+"My Script"
+
+# A 2-elemnent array means [script name, script parameter]
+["My Script", "parameter"]
+
+# A hash with keys :prerequest, :presort and/or :after sets those scripts for
+{
+  prerequest: "My Prerequest Script",
+  presort: "My Presort Script",
+  after: "My Script"
+}
+
+# Using 2-element arrays as objects in the hash allows specifying parameters
+{
+  prerequest: ["My Prerequest Script", "parameter"],
+  presort: ["My Presort Script", "parameter"],
+  after: ["My Script", "parameter"]
+}
+```
+
+#### Script execution on record save, destroy and reload
+
+A record instance's `.save` and `.destroy` methods both accept a `script:`
+option to which you can pass a script options object with
+[the above format](#script-options-object-format):
+
+```ruby
+# Save the record and execute an `after' script called "My Script"
+bee.save(script: "My Script")
+
+# Same as above but with an added parameter
+bee.save(script: ["My Script", "parameter"])
+
+# Save the record and execute a presort script and an `after' script
+bee.save(script: { presort: "My Presort Script", after: "My Script" })
+
+# Destroy the record and execute a prerequest script with a parameter
+bee.destroy(script: { prerequest: ["My Prerequest Script", "parameter"] })
+
+# Reload the record and execute a prerequest script with a parameter
+bee.reload(script: { prerequest: ["My Prerequest Script", "parameter"] })
+```
+
+#### Retrieving script execution results
+
+Every time a request is ran on a model or record instance of a model, a
+thread-local `Model.last_request_metadata` attribute is set on that model,
+which is a hash containing the results of script executions, if any were
+performed, among other metadata.
+
+The results for `:after`, `:prerequest` and `:presort` scripts are stored
+separately, under their matching key.
+
+```ruby
+bee.save(script: { presort: "My Presort Script", after: "My Script" })
+
+Honeybee.last_request_metadata[:script]
+# => { after: { result: "oh hi", error: "0" }, presort: { result: "lo", error: "0" } }
+```
+
+#### Executing scripts through query requests
+
+As mentioned under the [Query API](#query-api) section, you can use the
+`.script` query method to specify that you want scripts executed when a query
+is performed on that scope.
+
+`.script` takes the same options object specified [above](#script-options-object-format):
+
+```ruby
+# Find one Honeybee record executing a presort and after script
+Honeybee.script(presort: ["My Presort Script", "parameter"], after: "My Script").find_one
+```
+
+The model class' `.last_request_metadata` will be set in case you need to get the result.
+
+In the case of retrieving multiple results (i.e. via `.find_some`) the
+resulting collection will have a `.metadata` attribute method containing the
+same metadata hash with script execution results. Note that this does not apply
+to retrieving single records, in that case you'll have to use
+`.last_request_metadata`.
+
 ## Logging
 
 If using fmrest-ruby + Spyke in a Rails app pretty log output will be set up

data/fmrest.gemspec

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

data/lib/fmrest/spyke/json_parser.rb

@@ -11,6 +11,7 @@ module FmRest
       MULTIPLE_RECORDS_RE = %r(/records\z).freeze
       CONTAINER_RE = %r(/records/\d+/containers/[^/]+/\d+\z).freeze
       FIND_RECORDS_RE = %r(/_find\b).freeze
+      SCRIPT_REQUEST_RE = %r(/script/[^/]+\z).freeze
 
       VALIDATION_ERROR_RANGE = 500..599
 
@@ -32,6 +33,11 @@ module FmRest
           env.body = prepare_collection(json)
         when create_request?(env), update_request?(env), delete_request?(env), container_upload_request?(env)
           env.body = prepare_save_response(json)
+        when execute_script_request?(env)
+          env.body = build_base_hash(json)
+        else
+          # Attempt to parse unknown requests too
+          env.body = build_base_hash(json)
         end
       end
 
@@ -72,11 +78,35 @@ module FmRest
       # @return [Hash] the skeleton structure for a Spyke-formatted response
       def build_base_hash(json, include_errors = false)
         {
-          metadata: { messages: json[:messages] },
+          metadata: { messages: json[:messages] }.merge(script: prepare_script_results(json).presence),
           errors:   include_errors ? prepare_errors(json) : {}
         }
       end
 
+      # @param json [Hash]
+      # @return [Hash] the script(s) execution results for Spyke metadata format
+      def prepare_script_results(json)
+        results = {}
+
+        [:prerequest, :presort].each do |s|
+          if json[:response][:"scriptError.#{s}"]
+            results[s] = {
+              result: json[:response][:"scriptResult.#{s}"],
+              error:  json[:response][:"scriptError.#{s}"]
+            }
+          end
+        end
+
+        if json[:response][:scriptError]
+          results[:after] = {
+            result: json[:response][:scriptResult],
+            error:  json[:response][:scriptError]
+          }
+        end
+
+        results
+      end
+
       # @param json [Hash]
       # @return [Hash] the errors hash in Spyke format
       def prepare_errors(json)
@@ -196,6 +226,10 @@ module FmRest
         env.method == :delete && env.url.path.match(SINGLE_RECORD_RE)
       end
 
+      def execute_script_request?(env)
+        env.method == :get && env.url.path.match(SCRIPT_REQUEST_RE)
+      end
+
       # @param source [String] a JSON string
       # @return [Hash] the parsed JSON
       def parse_json(source)

data/lib/fmrest/spyke/model.rb

@@ -7,6 +7,7 @@ require "fmrest/spyke/model/serialization"
 require "fmrest/spyke/model/associations"
 require "fmrest/spyke/model/orm"
 require "fmrest/spyke/model/container_fields"
+require "fmrest/spyke/model/http"
 
 module FmRest
   module Spyke
@@ -20,6 +21,7 @@ module FmRest
       include Associations
       include Orm
       include ContainerFields
+      include Http
 
       included do
         # @return [Integer] the record's modId

data/lib/fmrest/spyke/model/associations.rb

@@ -64,7 +64,7 @@ module FmRest
           end
         end
 
-        def reload
+        def reload(*_)
           super.tap { @loaded_portals = nil }
         end
 

data/lib/fmrest/spyke/model/http.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "fmrest/spyke/relation"
+
+module FmRest
+  module Spyke
+    module Model
+      module Http
+        extend ::ActiveSupport::Concern
+
+        class_methods do
+
+          # Override Spyke's request method to keep a thread-local copy of the
+          # last request's metadata, so that we can access things like script
+          # execution results after a save, etc.
+
+
+          def request(*args)
+            super.tap do |r|
+              Thread.current[last_request_metadata_key] = r.metadata
+            end
+          end
+
+          def last_request_metadata(key: last_request_metadata_key)
+            Thread.current[key]
+          end
+
+          private
+
+          def last_request_metadata_key
+            "#{to_s}.last_request_metadata"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fmrest/spyke/model/orm.rb

@@ -23,10 +23,10 @@ module FmRest
           # Methods delegated to FmRest::Spyke::Relation
           delegate :limit, :offset, :sort, :order, :query, :omit, :portal,
                    :portals, :includes, :with_all_portals, :without_portals,
-                   to: :all
+                   :script, to: :all
 
           def all
-            # Use FmRest's Relation insdead of Spyke's vanilla one
+            # Use FmRest's Relation instead of Spyke's vanilla one
             current_scope || Relation.new(self, uri: uri)
           end
 
@@ -66,6 +66,12 @@ module FmRest
             new(attributes).tap(&:save!)
           end
 
+          def execute_script(script_name, param: nil)
+            params = {}
+            params = {"script.param" => param} unless param.nil?
+            request(:get, FmRest::V1::script_path(layout, script_name), params)
+          end
+
           private
 
           def extend_scope_with_fm_params(scope, prefixed: false)
@@ -92,11 +98,15 @@ module FmRest
               end
             end
 
+            if scope.script_params.present?
+              where_options.merge!(scope.script_params)
+            end
+
             scope.where(where_options)
           end
         end
 
-        # Completely override Spyke's save to provide a number of features:
+        # Overwrite Spyke's save to provide a number of features:
         #
         # * Validations
         # * Data API scripts execution
@@ -115,15 +125,32 @@ module FmRest
           save(options.merge(raise_validation_errors: true))
         end
 
+        # Overwrite Spyke's destroy to provide Data API script execution
+        #
+        def destroy(options = {})
+          # For whatever reason the Data API wants the script params as query
+          # string params for DELETE requests, making this more complicated
+          # than it should be
+          script_query_string = if options.has_key?(:script)
+                                  "?" + Faraday::Utils.build_query(FmRest::V1.convert_script_params(options[:script]))
+                                else
+                                  ""
+                                end
+
+          self.attributes = delete(uri.to_s + script_query_string)
+        end
+
         # API-error-raising version of #update
         #
-        def update!(new_attributes)
+        def update!(new_attributes, options = {})
           self.attributes = new_attributes
-          save!
+          save!(options)
         end
 
-        def reload
-          reloaded = self.class.find(id)
+        def reload(options = {})
+          scope = self.class
+          scope = scope.script(options[:script]) if options.has_key?(:script)
+          reloaded = scope.find(id)
           self.attributes = reloaded.attributes
           self.mod_id = reloaded.mod_id
         end

data/lib/fmrest/spyke/relation.rb

@@ -12,7 +12,7 @@ module FmRest
 
 
       attr_accessor :limit_value, :offset_value, :sort_params, :query_params,
-                    :included_portals, :portal_params
+                    :included_portals, :portal_params, :script_params
 
       def initialize(*_args)
         super
@@ -27,6 +27,42 @@ module FmRest
 
         @included_portals = nil
         @portal_params = {}
+        @script_params = {}
+      end
+
+      # @param options [String, Array, Hash, nil, false] sets script params to
+      #   execute in the next get or find request
+      #
+      # @example
+      #   # Find records and run the script named "My script"
+      #   Person.script("My script").find_some
+      #
+      #   # Find records and run the script named "My script" with param "the param"
+      #   Person.script(["My script", "the param"]).find_some
+      #
+      #   # Find records and run a prerequest, presort and after (normal) script
+      #   Person.script(after: "Script", prerequest: "Prereq script", presort: "Presort script").find_some
+      #
+      #   # Same as above, but passing parameters too
+      #   Person.script(
+      #     after:      ["After script", "the param"],
+      #     prerequest: ["Prereq script", "the param"],
+      #     presort: o  ["Presort script", "the param"]
+      #   ).find_some
+      #
+      #   Person.script(nil).find_some # Disable script execution
+      #   Person.script(false).find_some # Disable script execution
+      #
+      # @return [FmRest::Spyke::Relation] a new relation with the script
+      #   options applied
+      def script(options)
+        with_clone do |r|
+          if options.eql?(false) || options.eql?(nil)
+            r.script_params = {}
+          else
+            r.script_params = script_params.merge(FmRest::V1.convert_script_params(options))
+          end
+        end
       end
 
       # @param value_or_hash [Integer, Hash] the limit value for this layout,
@@ -140,12 +176,17 @@ module FmRest
         query_params.present?
       end
 
-      # Finds a single instance of the model by forcing limit = 1
+      # Finds a single instance of the model by forcing limit = 1, or simply
+      # fetching the record by id if the primary key was set
       #
       # @return [FmRest::Spyke::Base]
       def find_one
-        return super if params[klass.primary_key].present?
-        @find_one ||= klass.new_collection_from_result(limit(1).fetch).first
+        @find_one ||=
+          if primary_key_set?
+            without_collection_params { super }
+          else
+            klass.new_collection_from_result(limit(1).fetch).first
+          end
       rescue ::Spyke::ConnectionError => error
         fallback_or_reraise(error, default: nil)
       end
@@ -223,6 +264,18 @@ module FmRest
         end
       end
 
+      def primary_key_set?
+        params[klass.primary_key].present?
+      end
+
+      def without_collection_params
+        orig_values = limit_value, offset_value, sort_params, query_params
+        self.limit_value = self.offset_value = self.sort_params = self.query_params = nil
+        yield
+      ensure
+        self.limit_value, self.offset_value, self.sort_params, self.query_params = orig_values
+      end
+
       def with_clone
         clone.tap do |relation|
           yield relation

data/lib/fmrest/v1/paths.rb

@@ -26,6 +26,10 @@ module FmRest
         "layouts/#{url_encode(layout)}/_find"
       end
 
+      def script_path(layout, script)
+        "layouts/#{url_encode(layout)}/script/#{url_encode(script)}"
+      end
+
       def globals_path
         "globals"
       end

data/lib/fmrest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FmRest
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmrest
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-28 00:00:00.000000000 Z
+date: 2020-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -152,16 +152,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.6
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.6
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mock_redis
   requirement: !ruby/object:Gem::Requirement
@@ -220,6 +220,7 @@ files:
 - lib/fmrest/spyke/model/attributes.rb
 - lib/fmrest/spyke/model/connection.rb
 - lib/fmrest/spyke/model/container_fields.rb
+- lib/fmrest/spyke/model/http.rb
 - lib/fmrest/spyke/model/orm.rb
 - lib/fmrest/spyke/model/serialization.rb
 - lib/fmrest/spyke/model/uri.rb
@@ -260,8 +261,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.8
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: FileMaker Data API client using Faraday