faraday-hot_mock 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f1312baf1b9659238322e8f0700f7dffcc1eb5854e6c827d35ad86d9d2f7652
+  data.tar.gz: 8bb84381f365ac2bbc02b2fbfabec03824a092f61dfe9f14985e678d9be3254c
+SHA512:
+  metadata.gz: 2e7e4946d1afee93a8732a00fd667c58d091faf3d2b3b83e7814f446fc03e44a53212996174f762e70d31d7d176e353055565e9ee31095654745a50e4f324008
+  data.tar.gz: 84ebe958dfe19c87eb636edf000f6dc2533528a7cfd304eb762c5d1198cf8820fc5397c55ef545413f5118be522b216aea849737b1bb2eec984c9811573d1327

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Sean Hogge
+
+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,111 @@
+# Faraday::HotMock
+
+When using Faraday with Rails to develop an API integration, it can be challenging to simulate errors from the API if they don't provide a mechanism for doing so.
+
+This adapter attempts to make that simpler by parsing YAML files at runtime. If a match exists in any YAML file in the proper location, that response is returned. If no match exists, a real call is made.
+
+_**This adapter is meant for Faraday usage in Rails, not for Faraday that's used in other frameworks or situations.**_
+
+
+## Usage
+
+Create YAML files in `lib/faraday/mocks/#{Rails.env}` - the name of the files doesn't matter, and you can nest them in subdirectories.
+
+This means that if you have a Staging environment, or a UAT environment along with a Demo and Development environment, you can mock each separately.
+
+You can organize your per-environment mocks as you see fit - all in one file, or split between descriptive directories and file names.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "faraday-hot_mock", git: "https://github.com/seanhogge/faraday-hot_mock"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Then, use this adapter in your middleware pipeline, making sure that it's last:
+
+```ruby
+@conn = Faraday.new(url: "https://dog.ceo/api/") do |faraday|
+  faraday.request :json
+  faraday.response :json
+  faraday.adapter :hot_mock
+end
+```
+
+Optionally, specify a fallback adapter (`Faraday.default_adapter` is the default) - this is what will be used if a matching mock can't be found. It's unlikely you will ever need to specify the fallback.
+
+```ruby
+@conn = Faraday.new(url: "https://dog.ceo/api/") do |faraday|
+  faraday.request :json
+  faraday.response :json
+  faraday.adapter :hot_mock, fallback: :cool_community_adapter
+end
+```
+
+Then add the switch: `tmp/mocking-#{Rails.env}.txt`. Just like Rails' own `tmp/caching-dev.txt` file, this will toggle HotMock on when present, and off when not present.
+
+> ⚠️ REMEMBER: For caching, it's `tmp/caching-dev.txt`, but for mocking it's `tmp/mocking-development.txt`
+
+Now, create the directory `lib/faraday/mocks/` and a subdirectory for each environment you want to hot mock. Within that directory, create whatever files and subdirectories you like.
+
+> ⚠️ REMEMBER: it's `lib/faraday/mocks`, not `app/lib/faraday/mocks`
+
+Consider adding these directories to .gitignore unless you want mocks to be shared.
+
+```yaml
+# lib/faraday/mocks/development/vendor_name_mocks.yml
+- url_pattern: vendorname.com.*/endpoint
+  method: POST
+  status: 418
+  headers:
+    Content-Type: application/json
+  body:
+    error: I'm a teapot
+```
+
+Now, any POST request made to `vendorname.com/api/v1/endpoint` will return a mock 418 response with a JSON body. A GET to the same endpoint will make the actual call.
+
+If you edit the file to be:
+
+```yaml
+# lib/faraday/mocks/development/vendor_name_mocks.yml
+- url_pattern: vendorname.com.*/endpoint
+  method: POST
+  status: 503
+  headers:
+    Content-Type: application/json
+  body:
+    error: Service Unavailable
+```
+
+then the next request made to `vendorname.com/api/v1/endpoint` will return a mock 503 response with a JSON body. No need to reload anything.
+
+This lets you quickly simulate any type of response you need.
+
+If you want to disable mocks, you can:
+
+- Comment out individual entries
+- Comment out entire files
+- Rename the directory from "development" to "development-disabled" or anything that isn't a Rails environment name
+- Delete the entry
+- Delete the file(s)
+- Delete the directory
+
+If you'd rather keep the file(s) around, just delete `tmp/mocking-development.txt`. That will globally disable any mocked responses.
+
+
+## Contributing
+
+Fork, work, PR while following the [Code of Conduct](https://github.com/seanhogge/faraday-hot_mock/CODE_OF_CONDUCT.md)
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/faraday/hot_mock/adapter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+require "faraday"
+
+module Faraday
+  module HotMock
+    class Adapter < Faraday::Adapter
+      def initialize(app, options = {})
+        super(app)
+        @mock_dir = options[:mock_dir] || default_mock_dir
+        @enabled_file = options[:enabled_file] || "tmp/mocking-#{Rails.env}.txt"
+        fallback = options[:fallback] || Faraday.default_adapter
+        @fallback_adapter = Faraday::Adapter.lookup_middleware(fallback)
+        @mocks = load_mocks
+      end
+
+      def call(env)
+        super
+        if mocking_enabled? && @mocks && (mock = find_mock(env.method, env.url))
+          save_response(env, mock["status"] || 200, mock["body"] || "", mock["headers"] || {})
+        else
+          @fallback_adapter.new(@app, @options).call(env)
+        end
+      end
+
+      private
+
+      def load_mocks
+        return [] unless Dir.exist?(Rails.root.join @mock_dir)
+
+        mocks = []
+
+        yaml_files.each do |file|
+          file_mocks = YAML.load_file(file)
+          mocks.concat(file_mocks) if file_mocks.is_a?(Array)
+        end
+
+        mocks
+      end
+
+      def mocking_enabled?
+        File.exist?(Rails.root.join @enabled_file)
+      end
+
+      def default_mock_dir
+        rails_env = defined?(Rails) ? Rails.env : ENV["RAILS_ENV"] || "development"
+        "lib/faraday/mocks/#{rails_env}"
+      end
+
+      def find_mock(method, url)
+        return nil unless @mocks.any?
+
+        @mocks.find do |mock|
+          url_matches = Regexp.new(mock["url_pattern"]).match?(url)
+          method_matches = mock["method"].nil? || mock["method"].to_s.upcase == method.to_s.upcase
+
+          url_matches && method_matches
+        end
+      end
+
+      def yaml_files
+        Dir.glob(File.join(Rails.root.join(@mock_dir), "**", "*.{yml,yaml}"))
+      end
+    end
+  end
+end

data/lib/faraday/hot_mock/railtie.rb

@@ -0,0 +1,6 @@
+module Faraday
+  module HotMock
+    class Railtie < ::Rails::Railtie
+    end
+  end
+end

data/lib/faraday/hot_mock/version.rb

@@ -0,0 +1,5 @@
+module Faraday
+  module HotMock
+    VERSION = "0.1.0"
+  end
+end

data/lib/faraday/hot_mock.rb

@@ -0,0 +1,11 @@
+require "faraday/hot_mock/version"
+require "faraday/hot_mock/railtie"
+require "faraday/hot_mock/adapter"
+require "faraday"
+
+module Faraday
+  module HotMock
+  end
+end
+
+Faraday::Adapter.register_middleware hot_mock: Faraday::HotMock::Adapter

data/lib/tasks/faraday/hot_mock_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :faraday_hot_mock do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: faraday-hot_mock
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sean Hogge
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Faraday middleware for simple mocking of Faraday requests per environment
+  by means of YAML files read at runtime.
+email:
+- sean@seanhogge.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/faraday/hot_mock.rb
+- lib/faraday/hot_mock/adapter.rb
+- lib/faraday/hot_mock/railtie.rb
+- lib/faraday/hot_mock/version.rb
+- lib/tasks/faraday/hot_mock_tasks.rake
+homepage: https://github.com/seanhogge/faraday-hot_mock
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/seanhogge/faraday-hot_mock
+  source_code_uri: https://github.com/seanhogge/faraday-hot_mock
+  changelog_uri: https://github.com/seanhogge/faraday-hot_mock/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Faraday middleware for simple mocking of Faraday requests per environment.
+test_files: []