flexirest 1.6.5 → 1.6.6

data/docs/using-callbacks.md

@@ -0,0 +1,114 @@
+# *Flexirest:* Using callbacks
+
+You can use callbacks to alter get/post parameters, the URL or set the post body (doing so overrides normal parameter insertion in to the body) before a request or to adjust the response after a request. This can either be a block or a named method (like ActionController's `before_callback`/`before_action` methods).
+
+The callback is passed the name of the method (e.g. `:save`) and an object (a request object for `before_request` and a response object for `after_request`). The request object has four public attributes `post_params` (a Hash of the POST parameters), `get_params` (a Hash of the GET parameters), `headers` and `url` (a `String` containing the full URL without GET parameters appended).
+
+```ruby
+require 'secure_random'
+
+class Person < Flexirest::Base
+  before_request do |name, request|
+    if request.post? || name == :save
+      id = request.post_params.delete(:id)
+      request.get_params[:id] = id
+    end
+  end
+
+  before_request :replace_token_in_url
+
+  before_request :add_authentication_details
+
+  before_request :replace_body
+
+  before_request :override_default_content_type
+
+  private
+
+  def replace_token_in_url(name, request)
+    request.url.gsub!("#token", SecureRandom.hex)
+  end
+
+  def add_authentication_details(name, request)
+    request.headers["X-Custom-Authentication-Token"] = ENV["AUTH_TOKEN"]
+  end
+
+  def replace_body(name, request)
+    if name == :create
+      request.body = request.post_params.to_json
+    end
+  end
+
+  def override_default_content_type(name, request)
+    if name == :save
+      request.headers["Content-Type"] = "application/json"
+    end
+  end
+end
+```
+
+If you need to, you can create a custom parent class with a `before_request` callback and all children will inherit this callback.
+
+```ruby
+class MyProject::Base < Flexirest::Base
+  before_request do |name, request|
+    request.get_params[:api_key] = "1234567890-1234567890"
+  end
+end
+
+class Person < MyProject::Base
+  # No need to declare a before_request for :api_key, already defined by the parent
+end
+```
+
+After callbacks work in exactly the same way:
+
+```ruby
+class Person < Flexirest::Base
+  get :all, "/people"
+
+  after_request :fix_empty_content
+  after_request :cache_all_people
+
+  private
+
+  def fix_empty_content(name, response)
+    if response.status == 204 && response.body.blank?
+      response.body = '{"empty": true}'
+    end
+  end
+
+  def cache_all_people(name, response)
+    if name == :all
+      response.response_headers["Expires"] = 1.hour.from_now.iso8601
+    end
+  end
+end
+```
+
+**Note:** since v1.3.21 the empty response trick above isn't necessary, empty responses for 204 are accepted normally (the method returns `true`), but this is here to show an example of an `after_request` callback adjusting the body. The `cache_all_people` example shows how to cache a response even if the server doesn't send the correct headers.
+
+If you want to trap an error in an `after_request` callback and retry the request, this can be done - but retries will only happen once for each request (so we'd recommend checking all conditions in a single `after_request` and then retrying after fixing them all). You achieve this by returning `:retry` from the callback.
+
+```ruby
+class Person < Flexirest::Base
+  get :all, "/people"
+
+  after_request :fix_invalid_request
+
+  private
+
+  def fix_invalid_request(name, response)
+    if response.status == 401
+      # Do something to fix the state of caches/variables used in the 
+      # before_request, etc
+      return :retry
+    end
+  end
+end
+```
+
+
+-----
+
+[< Caching](caching.md) | [Lazy loading >](lazy-loading.md)

data/docs/validation.md

@@ -0,0 +1,89 @@
+# *Flexirest:* Validation
+
+You can create validations on your objects just like Rails' built in ActiveModel validations. For example:
+
+```ruby
+class Person < Flexirest::Base
+  validates :first_name, presence: true #ensures that the value is present and not blank
+  validates :last_name, existence: true #ensures that the value is non-nil only
+  validates :password, length: {within:6..12}, message: "Invalid password length, must be 6-12 characters"
+  validates :post_code, length: {minimum:6, maximum:8}
+  validates :salary, numericality: true, minimum: 20_000, maximum: 50_000
+  validates :age, numericality: { minumum: 18, maximum: 65 }
+  validates :suffix, inclusion: { in: %w{Dr. Mr. Mrs. Ms.}}
+
+  validates :first_name do |object, name, value|
+    object._errors[name] << "must be over 4 chars long" if value.length <= 4
+  end
+
+  get :index, '/'
+end
+```
+
+Note: the block based validation is responsible for adding errors to `object._errors[name]` (and this will automatically be ready for `<<` inserting into).
+
+Validations are run when calling `valid?` or when calling any API on an instance (and then only if it is `valid?` will the API go on to be called).
+
+`full_error_messages` returns an array of attributes with their associated error messages, i.e. `["age must be at least 18"]`. Custom messages can be specified by passing a `:message` option to `validates`. This differs slightly from ActiveRecord in that it's an option to `validates` itself, not a part of a final hash of other options. This is because the author doesn't like the ActiveRecord format (but will accept pull requests that make both syntaxes valid). To make this clearer, an example may help:
+
+```ruby
+# ActiveRecord
+validates :name, presence: { message: "must be given please" }
+
+# Flexirest
+validates :name, :presence, message: "must be given please"
+```
+
+## Permitting nil values
+
+The default behavior for `:length`, `:numericality` and `:inclusion` validators is to fail when a `nil` value is encountered. You can prevent `nil` attribute values from triggering validation errors for attributes that may permit `nil` by adding the `:allow_nil => true` option. Adding this option with a `true` value to `:length`, `:numericality` and `:inclusion` validators will permit `nil` values and not trigger errors. Some examples are:
+
+```ruby
+class Person < Flexirest::Base
+  validates :first_name, presence: true
+  validates :middle_name, length: { minimum: 2, maximum: 30 }, allow_nil: true
+  validates :last_name, existence: true
+  validates :nick_name, length: { minimum: 2, maximum: 30 }
+  validates :alias, length: { minimum: 2, maximum: 30 }, allow_nil: false
+  validates :password, length: { within: 6..12 }
+  validates :post_code, length: { minimum: 6, maximum: 8 }
+  validates :salary, numericality: true, minimum: 20_000, maximum: 50_000
+  validates :age, numericality: { minimum: 18, maximum: 65 }
+  validates :suffix, inclusion: { in: %w{Dr. Mr. Mrs. Ms.}}
+  validates :golf_score, numericality: true, allow_nil: true
+  validates :retirement_age, numericality: { minimum: 65 }, allow_nil: true
+  validates :cars_owned, numericality: true
+  validates :houses_owned, numericality: true, allow_nil: false
+  validates :favorite_authors, inclusion: { in: ["George S. Klason", "Robert T. Kiyosaki", "Lee Child"] }, allow_nil: true
+  validates :favorite_artists, inclusion: { in: ["Claude Monet", "Vincent Van Gogh", "Andy Warhol"] }
+  validates :favorite_composers, inclusion: { in: ["Mozart", "Bach", "Pachelbel", "Beethoven"] }, allow_nil: false
+end
+```
+
+In the example above, the following results would occur when calling `valid?` on an instance where all attributes have `nil` values:
+
+- `:first_name` must be present
+- `:last_name` must be not be nil
+- `:nick_name` must be not be nil
+- `:alias` must not be nil
+- `:password` must not be nil
+- `:post_code` must not be nil
+- `:salary` must not be nil
+- `:age` must not be nil
+- `:suffix` must not be nil
+- `:cars_owned` must not be nil
+- `:houses_owned` must not be nil
+- `:favorite_artists` must not be nil
+- `:favorite_composers` must not be nil
+
+The following attributes will pass validation since they explicitly `allow_nil`:
+
+- `:middle_name`
+- `:golf_score`
+- `:retirement_age`
+- `:favorite_authors`
+
+
+-----
+
+[< HTTP/parse error handling](httpparse-error-handling.md) | [Filtering result lists >](filtering-result-lists.md)

data/docs/xml-responses.md

@@ -0,0 +1,58 @@
+# *Flexirest:* XML Responses
+
+Flexirest uses `Crack` to allow parsing of XML responses. For example, given an XML response of (with a content type of `application/xml` or `text/xml`):
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+
+  <title>Example Feed</title>
+  <link href="http://example.org/"/>
+  <updated>2003-12-13T18:30:02Z</updated>
+  <author>
+    <name>John Doe</name>
+  </author>
+  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
+
+  <entry>
+    <title>Atom-Powered Robots Run Amok</title>
+    <link href="http://example.org/2003/12/13/atom03"/>
+    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
+    <updated>2003-12-13T18:30:02Z</updated>
+    <summary>Some text.</summary>
+  </entry>
+
+  <entry>
+    <title>Something else cool happened</title>
+    <link href="http://example.org/2015/08/11/andyjeffries"/>
+    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6b</id>
+    <updated>2015-08-11T18:30:02Z</updated>
+    <summary>Some other text.</summary>
+  </entry>
+
+</feed>
+```
+
+You can use:
+
+```ruby
+class Feed < Flexirest::Base
+  base_url "http://www.example.com/v1/"
+  get :atom, "/atom"
+end
+
+@atom = Feed.atom
+
+puts @atom.feed.title
+puts @atom.feed.link.href
+@atom.feed.entry.each do |entry|
+  puts "#{entry.title} -> #{entry.link.href}"
+end
+```
+
+For testing purposes, if you are using a `fake` content response when defining your endpoint, you should also provide `fake_content_type: "application/xml"` so that the parser knows to use XML parsing.
+
+
+-----
+
+[< Debugging](debugging.md)

data/lib/flexirest/configuration.rb

@@ -45,22 +45,30 @@ module Flexirest
         @@base_url = value
       end
 
-      def username(value = nil)
+      def username(value = nil, &block)
         @username ||= nil
         @@username ||= nil
         if value.nil?
-          value = if @username.nil?
-            @@username
+          if block_given?
+            @username = block
           else
-            @username
-          end
-          if value.nil? && superclass.respond_to?(:username)
-            value = superclass.username
+            value = if @username.nil?
+              @@username
+            else
+              @username
+            end
+            if value.nil? && superclass.respond_to?(:username)
+              value = superclass.username
+            end
+            value
           end
-          value
         else
-          value = CGI::escape(value) if value.present? && !value.include?("%")
-          @username = value
+          if value.respond_to?(:call)
+            @username = value
+          else
+            value = CGI::escape(value) if value.present? && !value.include?("%")
+            @username = value
+          end
         end
       end
 
@@ -70,20 +78,28 @@ module Flexirest
         @@username = value
       end
 
-      def password(value = nil)
+      def password(value = nil, &block)
         if value.nil?
-          value = if @password.nil?
-            @@password
+          if block_given?
+            @password = block
           else
-            @password
-          end
-          if value.nil? && superclass.respond_to?(:password)
-            value = superclass.password
+            value = if @password.nil?
+              @@password
+            else
+              @password
+            end
+            if value.nil? && superclass.respond_to?(:password)
+              value = superclass.password
+            end
+            value
           end
-          value
         else
-          value = CGI::escape(value) if value.present? && !value.include?("%")
-          @password = value
+          if value.respond_to?(:call)
+            @password = value
+          else
+            value = CGI::escape(value) if value.present? && !value.include?("%")
+            @password = value
+          end
         end
       end
 

data/lib/flexirest/request.rb

@@ -93,19 +93,27 @@ module Flexirest
     end
 
     def username
+      ret = nil
       if object_is_class?
-        @object.username
+        ret = @object.username
+        ret = ret.call if ret.respond_to?(:call)
       else
-        @object.class.username
+        ret = @object.class.username
+        ret = ret.call(@object) if ret.respond_to?(:call)
       end
+      ret
     end
 
     def password
+      ret = nil
       if object_is_class?
-        @object.password
+        ret = @object.password
+        ret = ret.call if ret.respond_to?(:call)
       else
-        @object.class.password
+       ret = @object.class.password
+       ret = ret.call(@object) if ret.respond_to?(:call)
       end
+      ret
     end
 
     def request_body_type

data/lib/flexirest/version.rb

@@ -1,3 +1,3 @@
 module Flexirest
-  VERSION = "1.6.5"
+  VERSION = "1.6.6"
 end

data/spec/lib/request_spec.rb

@@ -62,6 +62,19 @@ describe Flexirest::Request do
       get :all, "/"
     end
 
+    class AuthenticatedProcExampleClient < Flexirest::Base
+      base_url "http://www.example.com"
+      username Proc.new { |obj| obj ? "bill-#{obj.id}" : "bill" }
+      password do |obj|
+        if obj
+          "jones-#{obj.id}"
+        else
+          "jones"
+        end
+      end
+      get :all, "/"
+    end
+
     class ProcDefaultExampleClient < Flexirest::Base
       base_url "http://www.example.com"
       get :all, "/", defaults: (Proc.new do |params|
@@ -167,6 +180,21 @@ describe Flexirest::Request do
     AuthenticatedExampleClient.all
   end
 
+  it "should get an HTTP connection with authentication using procs when called in a class context" do
+    connection = double(Flexirest::Connection).as_null_object
+    expect(Flexirest::ConnectionManager).to receive(:get_connection).with("http://bill:jones@www.example.com").and_return(connection)
+    expect(connection).to receive(:get).with("/", an_instance_of(Hash)).and_return(::FaradayResponseMock.new(OpenStruct.new(body:'{"result":true}', response_headers:{})))
+    AuthenticatedProcExampleClient.all
+  end
+
+  it "should get an HTTP connection with authentication using procs when called in an object context" do
+    connection = double(Flexirest::Connection).as_null_object
+    expect(Flexirest::ConnectionManager).to receive(:get_connection).with("http://bill-1:jones-1@www.example.com").and_return(connection)
+    expect(connection).to receive(:get).with("/?id=1", an_instance_of(Hash)).and_return(::FaradayResponseMock.new(OpenStruct.new(body:'{"result":true}', response_headers:{})))
+    obj = AuthenticatedProcExampleClient.new(id: 1)
+    obj.all
+  end
+
   it "should get an HTTP connection when called and call get on it" do
     expect_any_instance_of(Flexirest::Connection).to receive(:get).with("/", an_instance_of(Hash)).and_return(::FaradayResponseMock.new(OpenStruct.new(body:'{"result":true}', response_headers:{})))
     ExampleClient.all

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flexirest
 version: !ruby/object:Gem::Version
-  version: 1.6.5
+  version: 1.6.6
 platform: ruby
 authors:
 - Andy Jeffries
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-19 00:00:00.000000000 Z
+date: 2018-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -218,19 +218,47 @@ files:
 - ".simplecov"
 - ".travis.yml"
 - CHANGELOG.md
-- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
-- Migrating-from-ActiveRestClient.md
 - README.md
 - Rakefile
-- Ruby-on-Rails-Integration.md
 - docs/FLEXIREST.svg
 - docs/FLEXIREST@2x.png
-- docs/Flexirest Internals.graffle
 - docs/Flexirest Internals.png
-- docs/Flexirest Logo.sketch
+- docs/associations.md
+- docs/authentication.md
+- docs/automatic-conversion-of-fields-to-datedatetime.md
+- docs/basic-usage.md
+- docs/body-types.md
+- docs/caching.md
+- docs/combined-example.md
+- docs/debugging.md
+- docs/default-parameters.md
+- docs/faking-calls.md
+- docs/faraday-configuration.md
+- docs/filtering-result-lists.md
+- docs/httpparse-error-handling.md
+- docs/internals.md
 - docs/issue_template.md
+- docs/json-api.md
+- docs/lazy-loading.md
+- docs/migrating-from-activerestclient.md
+- docs/parallel-requests.md
+- docs/per-request-parameter-encoding.md
+- docs/per-request-timeouts.md
+- docs/plain-requests.md
+- docs/proxying-apis.md
+- docs/raw-requests.md
+- docs/required-parameters.md
+- docs/root-elements.md
+- docs/ruby-on-rails-integration.md
+- docs/source/Flexirest Internals.graffle
+- docs/source/Flexirest Logo.sketch
+- docs/translating-apis.md
+- docs/updating-only-changed-dirty-attributes.md
+- docs/using-callbacks.md
+- docs/validation.md
+- docs/xml-responses.md
 - flexirest.gemspec
 - lib/flexirest.rb
 - lib/flexirest/associations.rb