acfs 1.3.3 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0acb19bd6d18e4b93032f4524ca80005cc7d8b6c4beff1bc48c7bd4cc3f96f9e
-  data.tar.gz: f62b3bb0715a4df057784c44475cd273a64b1d2ddef61d50d9d04189b70c1d05
+  metadata.gz: 46dc13b234cd5b704b67a731292b06ad8b32ee3fafb0a7a0af2a1003824e6df8
+  data.tar.gz: a35249f8e2a7a6cc49351b62c75b3fe641b26691132f4fb70b0a183ab041a380
 SHA512:
-  metadata.gz: 1ca766572e15eb68818f22f0ef02d3cb3c4ad7177f2eb8b7a0da01b12052adfc118054308790fb0826ebd417022f59e6a64baee1a484f446bc74a1340cb2dca3
-  data.tar.gz: d3df90c063afa8ad98672c10beacf350e24bf34c725cc83e0c15fd931080e27fcd0e7726d815aad059ad5de29f5b041f6ccf14733f2a5e4c7ca2c7934a9c1373
+  metadata.gz: 07132ad9797084fccd7fdeb31cc9f51572ddda1eb9dc88aaf875cd244000d15823223d3c6c503f0af7ac4cc1f59cb0b748eea75d8592323b807001e82c93d781
+  data.tar.gz: 6d6d15b6841820ae2ee672eec742b417113523ce613f1a7c7d493eeed50232b0915d7edcbf3df1b7060c5ced484bb82f59904e34fe6e17f70babe3b5ddf0a4e7

data/CHANGELOG.md

@@ -0,0 +1,372 @@
+# Changelog
+
+
+
+## Unreleased
+---
+
+### New
+
+### Changes
+
+### Fixes
+
+### Breaks
+
+
+## 1.6.0 - (2021-01-07)
+---
+
+### New
+* Support Ruby 3.0
+* Use keyword arguments in parameters and when calling methods
+
+
+## 1.5.1 - (2020-12-30)
+---
+
+### Changes
+* Revert back to using `::MultiJson`
+
+
+## 1.5.0 - (2020-06-19)
+---
+
+### New
+* Error classes for more HTTP error responses: `400`, `401`, `403`, `500`, `502`, `503`, `504`.
+
+### Changes
+* Replace deprecated MultiJson with core JSON module
+
+
+## 1.4.0 - (2020-06-12)
+---
+
+### New
+* Use strict TCP keepalive probing by default (5s/5s)
+* Adapter accepts curl request opts
+
+
+## 1.3.4 - (2020-03-22)
+---
+
+### Fixes
+* Empty package build for Gem release 1.3.3
+
+
+## 1.3.3 - (2020-03-22)
+---
+
+### Changes
+* Improved handling of low-level connection errors and timeouts
+
+
+## 1.3.2 - (2019-09-24)
+
+
+### Fixes
+* Fix Acfs.on callbacks for empty find_by results (#42)
+
+
+---
+
+## 1.3.1 - (2019-07-02)
+
+### Fixes
+* Improve URL argument encoding when building resource requests
+
+## 1.3.0
+
+* Change default error messages to a more compact representation to ease integration with error reporting services.
+
+## 1.2.1
+
+* Fix issues with resources errors if response payload differs from the expected `field => [messages]`, such as `field => message` or `[messages]`.
+
+## 1.2.0
+
+* Add Rails 5.2 compatibility
+
+## 1.1.1
+
+* `each_item`: Pass collection to provided block (#40)
+
+## 1.1.0
+
+* Add support for Rails 5.1
+
+## 1.0.1
+
+* Fix deprecation warnings when using ::Mime
+
+## 1.0.0
+
+* Switch to first non-development major as it's long time used in production.
+* Fix NewRelic RPM inference with middleware stack inherited from `ActionDispatch::MiddlewareStack`.
+
+## 0.48.0
+
+* Remove #attribute_types broke since f7e4109 (Sep 2013, v0.23)
+* Fix attribute inheritance on subclassing broken since commit 7cf1d11 (Apr 2014, v0.43)
+
+## 0.47.0
+
+* Change blank value handling of dict and list type (0a12ef1)
+
+## 0.46.0
+
+* Rework types system (#39)
+
+## 0.45.0
+
+* Fetching multiple records (`find(ary)`) is stable now, but untested (#38)
+* Middleware stack is build on ActionDispatch::MiddlewareStack now
+* Deprecate legacy middleware names (xyEncoder, xyDecoder)
+
+## 0.44.0
+
+* Add option to configure adapter creation and pass option to typhoeus adapter e.g.
+  limiting concurrency.
+
+## 0.43.2
+
+* add `total_count` for paginated collections
+
+## 0.43.1
+
+* Fix `:with` condition matching on stubs
+
+## 0.43.0
+
+* Remove `Acfs::Model` (inherit from `Acfs::Resource`)
+* Stub does only a partial match of `:with` attributes now
+* Allow blocks as stub `:return`s
+
+## 0.42.0
+
+* Add simple dict attribute type
+
+## 0.40.0
+
+* Change `Resource#persisted?` to return true if it is not new
+
+## 0.39.1
+
+* Fix automatic path parameter handling for #destroy
+
+## 0.39.0
+
+* Add new event acfs.operation.before_process
+
+## 0.38.0
+
+* Allow middlewares to abort request processing
+* Allow middlewares to receive the request operation object (via the request)
+
+## 0.37.0
+
+* Add Acfs.on
+
+## 0.36.0
+
+* Add #each_page and #each_item query methods
+
+## 0.35.0
+
+* Add instrumentation support
+
+## 0.34.1
+
+* Fix leaking failed requests in request queues
+
+## 0.34.0
+
+* Add support for will_paginate view helper used with `Acfs::Collection`s
+* Add support for pagination header added by [paginate-responder](https://github.com/jgraichen/paginate-responder)
+* Improve `Resource#new?` detection by using `loaded?` instead of presence of `:id` attribute
+
+## 0.33.0
+
+* Do not raise errors on unknown attributes by default, add :unknown option.
+* Add support to store unknown attributes
+
+## 0.32.1
+
+* Fix multiple callbacks on `QueryMethods#all`
+
+## 0.32.0
+
+* Add new attribute type `UUID`
+
+## 0.31.0
+
+* Add experimental support for multiple and chained paths with placeholders
+
+## 0.30.0
+
+* Add experimental support for multiple operation callbacks (Acfs.add_callback)
+
+## 0.29.1
+
+* Fix: rescue NameError and NoMethodError on invalid type
+
+## 0.29.0
+
+* Add find_by!
+
+## 0.28.0
+
+* Add find_by
+
+## 0.27.0
+
+* Reset method to clear stubs, request queues, internal state
+* Add RSpec helper to enable stubs and clear state after each spec
+
+## 0.26.0
+
+* Add support for singleton resources
+
+## 0.25.0
+
+* Add option to allow blank attribute values (Johannes Jasper)
+* Internal changes
+
+## 0.24.0
+
+* Fix issues with stubs using type inheritance
+* Allow '1' as true value for bool attributes (Tino Junge)
+
+## 0.23.2
+
+* Fix regression in delegator usage by #find due to resource type inheritance.
+
+## 0.23.1
+
+* Fix error class name typo
+
+## 0.23.0
+
+* Add Resource Type Inheritance
+
+## 0.22.2
+
+* Preserve errors received from service on revalidation (2f1fc178)
+* Fix parameter ordering bug on stubs (1dc78dc8)
+
+## 0.22.1
+
+* Fix hash modification on iteration bug on ActiveModel::Errors due to string keys in error hash
+
+## 0.22.0
+
+* Fill local resource errors hash also on 422 responses when saving resources
+
+## 0.21.1
+
+* Fix wrong validation context
+
+## 0.21.0
+
+* Add update_attributes
+* Add validation check to `save` method
+* Inherit attributes to subclasses
+
+## 0.20.0
+
+* Remove messaging
+* Introduce `Acfs::Resource`
+
+## 0.19.0
+
+* Add support for DateTime and Float attribute types
+* Add experimental list attribute type
+* Allow block usage in stub `with` option
+* Allow to test if operation stubs were called and how often
+* Fix bug on operation stubs
+
+## 0.18.0
+
+* Basic DELETE operations
+
+## 0.17.0
+
+* Basic messaging
+* Extensible YARD documentation
+
+## 0.16.0
+
+* Add YAML configuration
+* Add external configuration for services
+* Add Rubinius support
+
+## 0.15.0
+
+* Add stubbing capabilities for resources
+
+## 0.14.0 & 0.13.0
+
+* Fix response attributes
+
+## 0.12.0
+
+* Add JRuby support
+* Improve handling of error respones (422)
+
+## 0.11.0
+
+* Add Logger Middleware
+* Add handling of error responses
+
+## 0.10.0
+
+* Return hash with indifferent access for resource attributes
+
+## 0.9.0
+
+* Add create operation
+
+## 0.8.0
+
+* Add save operation (PUT and POST)
+* Add JSON and MessagePack encoder middlewares for encoding request data
+* ActiveModel::Dirty
+* Add persistant state methods
+
+## 0.7.0
+
+* Per-service middleware stack
+
+## 0.6.0
+
+* Add support for multiple ids for .find
+* Add MessagePack support
+
+## 0.5.1
+
+* Fix mime type parsing for mime types with aditional parameters (ActionPack < 4.0)
+
+## 0.5.0
+
+* Add mime type support for respones
+
+## 0.4.0
+
+* Improve JSON response detection
+* Add bool attribute type
+
+## 0.3.0
+
+* Add tracking for loading state (if resource is loaded or queued)
+* Add JSON middleware to decode respones
+* Add middleware support
+* Add method to fetch single resources or list of resources
+* Use typhoeus as http library for parallel request processing
+
+## 0.2.0
+
+* Allow to define resources and attributes
+
+## 0.1.0
+
+* Project start

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jan Graichen
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,321 @@
+# Acfs - *API client for services*
+
+[![Gem Version](https://img.shields.io/gem/v/acfs?logo=ruby)](https://rubygems.org/gems/acfs)
+[![Build Status](https://img.shields.io/travis/jgraichen/acfs/master?logo=travis)](https://travis-ci.org/jgraichen/acfs)
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/jgraichen/acfs/Test/master?logo=github)](https://github.com/jgraichen/acfs/actions?query=branch%3Amaster)
+[![Coverage Status](http://img.shields.io/coveralls/jgraichen/acfs/master.svg)](https://coveralls.io/r/jgraichen/acfs)
+[![RubyDoc Documentation](http://img.shields.io/badge/rubydoc-here-blue.svg)](http://rubydoc.info/github/jgraichen/acfs/master/frames)
+
+Acfs is a library to develop API client libraries for single services within a larger service oriented application.
+
+Acfs covers model and service abstraction, convenient query and filter methods, full middleware stack for pre-processing requests and responses on a per service level and automatic request queuing and parallel processing. See Usage for more.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'acfs', '~> 1.3'
+
+And then execute:
+
+    > bundle
+
+Or install it yourself as:
+
+    > gem install acfs
+
+
+## Usage
+
+First you need to define your service(s):
+
+```ruby
+class UserService < Acfs::Service
+  self.base_url = 'http://users.myapp.org'
+
+  # You can configure middlewares you want to use for the service here.
+  # Each service has it own middleware stack.
+  #
+  use Acfs::Middleware::JsonDecoder
+  use Acfs::Middleware::MessagePackDecoder
+end
+```
+
+This specifies where the `UserService` is located. You can now create some models representing resources served by the `UserService`.
+
+```ruby
+class User < Acfs::Resource
+  service UserService # Associate `User` model with `UserService`.
+
+  # Define model attributes and types
+  # Types are needed to parse and generate request and response payload.
+
+  attribute :id, :uuid # Types can be classes or symbols.
+                       # Symbols will be used to load a class from `Acfs::Model::Attributes` namespace.
+                       # Eg. `:uuid` will load class `Acfs::Model::Attributes::Uuid`.
+
+  attribute :name, :string, default: 'Anonymous'
+  attribute :age, ::Acfs::Model::Attributes::Integer # Or use :integer
+
+end
+```
+
+The service and model classes can be shipped as a gem or git submodule to be included by the frontend application(s).
+
+You can use the model there:
+
+```ruby
+@user = User.find 14
+
+@user.loaded? #=> false
+
+Acfs.run # This will run all queued request as parallel as possible.
+         # For @user the following URL will be requested:
+         # `http://users.myapp.org/users/14`
+
+@model.name # => "..."
+
+@users = User.all
+@users.loaded? #=> false
+
+Acfs.run # Will request `http://users.myapp.org/users`
+
+@users #=> [<User>, ...]
+```
+
+If you need multiple resources or dependent resources first define a "plan" how they can be loaded:
+
+```ruby
+@user = User.find(5) do |user|
+  # Block will be executed right after user with id 5 is loaded
+
+  # You can load additional resources also from other services
+  # Eg. fetch comments from `CommentSerivce`. The line below will
+  # load comments from `http://comments.myapp.org/comments?user=5`
+  @comments = Comment.where user: user.id
+
+  # You can load multiple resources in parallel if you have multiple
+  # ids.
+  @friends  = User.find 1, 4, 10 do |friends|
+    # This block will be executed when all friends are loaded.
+    # [ ... ]
+  end
+end
+
+Acfs.run # This call will fire all request as parallel as possible.
+         # The sequence above would look similar to:
+         #
+         # Start                Fin
+         #   |===================|       `Acfs.run`
+         #   |====|                      /users/5
+         #   |    |==============|       /comments?user=5
+         #   |    |======|               /users/1
+         #   |    |=======|              /users/4
+         #   |    |======|               /users/10
+
+# Now we can access all resources:
+
+@user.name       # => "John
+@comments.size   # => 25
+@friends[0].name # => "Miraculix"
+```
+
+Use `.find_by` to get first element only. `.find_by` will call the `index`-Action and return the first resource. Optionally passed params will be sent as `GET` parameters and can be used for filtering in the service's controller.
+```ruby
+@user = User.find_by age: 24
+
+Acfs.run # Will request `http://users.myapp.org/users?age=24`
+
+@user # Contains the first user object returned by the index action
+```
+If no object can be found, `.find_by` will return `nil`. The optional callback will then be called with `nil` as parameter. Use `.find_by!` to raise an `Acfs::ResourceNotFound` exception if no object can be found. `.find_by!` will only invoke the optional callback if an object was successfully loaded.
+
+Acfs has basic update support using `PUT` requests:
+
+```ruby
+@user = User.find 5
+@user.name = "Bob"
+
+@user.changed? # => true
+@user.persisted? # => false
+
+@user.save # Or .save!
+           # Will PUT new resource to service synchronously.
+
+@user.changed? # => false
+@user.persisted? # => true
+```
+
+
+## Singleton resources
+
+Singletons can be used in Acfs by creating a new resource which inherits from `SingletonResource`:
+
+```ruby
+class Single < Acfs::SingletonResource
+  service UserService # Associate `Single` model with `UserService`.
+
+  # Define model attributes and types as with regular resources
+
+  attribute :name, :string, default: 'Anonymous'
+  attribute :age, :integer
+
+end
+```
+
+The following code explains the routing for singleton resource requests:
+
+```ruby
+my_single = Single.new
+mysingle.save # sends POST request to /single
+
+my_single = Single.find
+Acfs.run # sends GET request to /single
+
+my_single.age = 28
+my_single.save # sends PUT request to /single
+
+my_single.delete # sends DELETE request to /single
+```
+
+You also can pass parameters to the find call, these will sent as GET params to the index action:
+
+```ruby
+my_single = Single.find name: 'Max'
+Acfs.run # sends GET request with param to /single?name=Max
+```
+
+
+## Resource Inheritance
+
+Acfs provides a resource inheritance similar to ActiveRecord Single Table Inheritance. If a
+`type` attribute exists and is a valid subclass of your resource they will be converted
+to you subclassed resources:
+
+```ruby
+class Computer < Acfs::Resource
+  ...
+end
+
+class Pc < Computer end
+class Mac < Computer end
+```
+
+With the following response on `GET /computers` the collection will contain the appropriate
+subclass resources:
+
+```json
+[
+    { "id": 5, "type": "Computer"},
+    { "id": 6, "type": "Mac"},
+    { "id": 8, "type": "Pc"}
+]
+```
+
+```ruby
+@computers = Computer.all
+
+Acfs.run
+
+@computer[0].class # => Computer
+@computer[1].class # => Mac
+@computer[2].class # => Pc
+```
+
+
+## Stubbing
+
+You can stub resources in applications using an Acfs service client:
+
+```ruby
+# spec_helper.rb
+
+# This will enable stabs before each spec and clear internal state
+# after each spec.
+require 'acfs/rspec'
+```
+
+```ruby
+before do
+  @stub = Acfs::Stub.resource MyUser, :read, with: { id: 1 }, return: { id: 1, name: 'John Smith', age: 32 }
+  Acfs::Stub.resource MyUser, :read, with: { id: 2 }, raise: :not_found
+  Acfs::Stub.resource Session, :create, with: { ident: 'john@exmaple.org', password: 's3cr3t' }, return: { id: 'longhash', user: 1 }
+  Acfs::Stub.resource MyUser, :update, with: lambda { |op| op.data.include? :my_var }, raise: 400
+end
+
+it 'should find user number one' do
+  user = MyUser.find 1
+  Acfs.run
+
+  expect(user.id).to be == 1
+  expect(user.name).to be == 'John Smith'
+  expect(user.age).to be == 32
+
+  expect(@stub).to be_called
+  expect(@stub).to_not be_called 5.times
+end
+
+it 'should not find user number two' do
+  MyUser.find 3
+
+  expect { Acfs.run }.to raise_error(Acfs::ResourceNotFound)
+end
+
+it 'should allow stub resource creation' do
+  session = Session.create! ident: 'john@exmaple.org', password: 's3cr3t'
+
+  expect(session.id).to be == 'longhash'
+  expect(session.user).to be == 1
+end
+```
+
+By default Acfs raises an error when a non stubbed resource should be requested. You can switch of the behavior:
+
+```ruby
+before do
+  Acfs::Stub.allow_requests = true
+end
+
+it 'should find user number one' do
+  user = MyUser.find 1
+  Acfs.run             # Would have raised Acfs::RealRequestNotAllowedError
+                       # Will run real request to user service instead.
+end
+```
+
+
+## Instrumentation
+
+Acfs supports [instrumentation via active support][1].
+
+Acfs expose to following events
+
+* `acfs.operation.complete(operation, response)`: Acfs operation completed
+* `acfs.runner.sync_run(operation)`: Run operation right now skipping queue.
+* `acfs.runner.enqueue(operation)`: Enqueue operation to be run later.
+* `acfs.before_run`: directly before `acfs.run`
+* `acfs.run`: Run all queued operations.
+
+Read [official guide][2] to see to to subscribe.
+
+[1]: http://guides.rubyonrails.org/active_support_instrumentation.html
+[2]: http://guides.rubyonrails.org/active_support_instrumentation.html#subscribing-to-an-event
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+4. Add specs for your feature
+5. Implement your feature
+6. Commit your changes (`git commit -am 'Add some feature'`)
+7. Push to the branch (`git push origin my-new-feature`)
+8. Create new Pull Request
+
+
+## License
+
+MIT License
+
+Copyright (c) 2013-2020 Jan Graichen. MIT license, see LICENSE for more details.