webvalve 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 75f876084825a8cc70b8977e26afa6133f0191a0
+  data.tar.gz: acb351fdfc895185361b55e0e756d3488e2a2ea0
+SHA512:
+  metadata.gz: 8ed9a0819c09b29f2bfe2fccf03d3234acaf1dec62ef29eeb5387894c2ab20bfa7b6daeeee684ef8b2e044096136fa85cfd7558bba17bcd0ad82ae5434f3b1fa
+  data.tar.gz: cf953ff845781e4320197f6a62c76f49b422514cdc73066ebded9fd2d07716865bb4183f346548b3a12ffa855e989d0435f51134f3e67f9c5a18820c8e822243

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Betterment
+
+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,195 @@
+WebValve
+========
+
+[![Build Status](https://travis-ci.com/Betterment/webvalve.svg?token=6b6DErRMUHX47kEoBZ3t&branch=master)](https://travis-ci.com/Betterment/webvalve)
+
+WebValve is a tool for defining and registering fake implementations of
+HTTP services and toggling between the real services and the fake ones
+in non-production environments.
+
+This library is made possible by the incredible gems
+[WebMock](https://github.com/bblimke/webmock) and
+[Sinatra](https://github.com/sinatra/sinatra).
+
+## Getting Started
+
+### Network connections disabled by default
+
+The default mode in development and test is to disallow all HTTP network
+connections. This provides a clean foundation for consuming new
+services. If you add a new service integration, the first thing that you
+will be presented with when you attempt to hit it in development or test
+is a warning that the requested URL was not mocked. This behavior comes
+straight outta WebMock.
+
+```ruby
+irb(main):007:0> Net::HTTP.get(URI('http://bank.dev'))
+
+WebMock::NetConnectNotAllowedError: Real HTTP connections are disabled. Unregistered request: GET http://bank.dev/ with headers {'Accept'=>'*/*', 'User-Agent'=>'Ruby'}
+
+You can stub this request with the following snippet:
+
+stub_request(:get, "http://bank.dev/").
+  with(:headers => {'Accept'=>'*/*', 'User-Agent'=>'Ruby'}).
+  to_return(:status => 200, :body => "", :headers => {})
+
+============================================================
+```
+
+### Creating a config file
+
+The first thing to do is run the install generator.
+
+```
+$ rails generate webvalve:install
+```
+
+This will drop a new file in your config directory.
+
+```ruby
+# config/webvalve.rb
+
+# # register services
+#
+# WebValve.register FakeBank
+# WebValve.register FakeExample, url: 'https://api.example.org'
+#
+# # whitelist urls
+#
+# WebValve.whitelist_url 'https://example.com'
+```
+
+### Registering a service
+
+Next, you will want create a `FakeService` and register
+it with the framework.
+
+This can be accomplished by running the fake service generator:
+
+```
+$ rails generate webvalve:fake_service Bank
+```
+
+This will generate a file `fake_bank.rb` in the top-level folder
+`webvalve`. This file will be autoloaded by Rails, so you can
+tweak it as you go without having to restart your application.
+
+```ruby
+# webvalve/fake_bank.rb
+
+class FakeBank < WebValve::FakeService
+  # # define your routes here
+  #
+  # get '/widgets' do
+  #   json result: 'it works!'
+  # end
+  #
+  # # toggle this service on via ENV
+  #
+  # export BANK_ENABLED=true
+end
+```
+
+And it will automatically register it in `config/webvalve.rb`
+
+```ruby
+# config/webvalve.rb
+WebValve.register FakeBank
+```
+
+You'll also want to define an environment variable for the base url of
+your service.
+
+```bash
+export BANK_API_URL='http://bank.dev'
+```
+
+That's it. Now when you hit your service again, it will route your
+request into the `FakeBank` instance.
+
+If you want to connect to the _actual_ service, all you have to do is
+set another environment variable.
+
+```bash
+export BANK_ENABLED=true
+```
+
+You will have to restart your application after making this change
+because service faking is an initialization time concern and not a
+runtime concern.
+
+## Configuring fakes in tests
+
+In order to get WebValve fake servies working properly in tests, you
+have to configure WebValve at the beginning of each test. For RSpec, there
+is a configuration provided. 
+
+```ruby
+# spec/rails_helper.rb
+require 'webvalve/rspec'
+```
+
+For any other test framework, you will just want to set up a hook before
+each test that will run `WebValve.setup`.
+
+## Setting deterministic fake results in tests
+
+Given a scenario where we want to mock a specific behavior for an
+endpoint in a test, we can just use WebMock™.
+
+```ruby
+# in an rspec test...
+
+it 'handles 404s by returning nil' do
+  fake_req = stub_request('http://bank.dev/some/url/1234')
+    .to_return(status: 404, body: nil)
+
+  response = Faraday.get 'http://bank.dev/some/url/1234'
+  expect(response.body).to be_nil
+  expect(fake_req).to have_been_requested
+end
+```
+
+In other scenarios where we don't care about the specific response from
+the endpoint, you can just lean into the behavior you've configured for
+that route in your fake service.
+
+## Overriding conventional defaults
+
+Sometimes a service integration may want to use an unconventional name
+for its environment variables. In that case, you can register the fake
+service using the optional `url:` argument.
+
+```ruby
+# config/webvalve.rb
+
+# using an ENV variable
+WebValve.register FakeBank, url: ENV.fetch("SOME_CUSTOM_API_URL")
+
+# or with a constant value
+WebValve.register FakeBank, url: "https://some-service.com"
+```
+
+## What's in a `FakeService`?
+
+The definition of `FakeService` is really simple. It's just a
+`Sinatra::Base` class. It is wired up to support returning JSON 
+responses and it will raise when a route is requested but it is 
+not registered.
+
+## How to Contribute
+
+We would love for you to contribute! Anything that benefits the majority
+of `webvalve` users—from a documentation fix to an entirely new
+feature—is encouraged.
+
+Before diving in, [check our issue
+tracker](//github.com/Betterment/webvalve/issues) and consider
+creating a new issue to get early feedback on your proposed change.
+
+### Suggested Workflow
+
+* Fork the project and create a new branch for your contribution.
+* Write your contribution (and any applicable test coverage).
+* Make sure all tests pass (`bundle exec rake`).
+* Submit a pull request.

data/Rakefile

@@ -0,0 +1,22 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+if Rails.env.development? || Rails.env.test?
+  if defined? Dummy
+    require 'rspec/core'
+    require 'rspec/core/rake_task'
+    RSpec::Core::RakeTask.new(:spec)
+    task default: :spec
+  end
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/generators/webvalve/fake_service_generator.rb

@@ -0,0 +1,70 @@
+require 'rails/generators/base'
+
+module Webvalve
+  module Generators
+    class FakeServiceGenerator < Rails::Generators::Base
+      desc "Creates a WebValve fake service"
+
+      argument :service_name, required: true
+
+      def create_webvalve_fake_service_file
+        require_config!
+        create_fake_service_file
+        register_fake_in_config
+      end
+
+      private
+
+      def create_fake_service_file
+        create_file full_file_path, <<-FILE.strip_heredoc
+          class #{fake_service_class_name} < WebValve::FakeService
+            # # define your routes here
+            #
+            # get '/widgets' do
+            #   json result: 'it works!'
+            # end
+            #
+            # # set the base url for this API via ENV
+            #
+            # export #{parsed_service_name.upcase}_API_URL='http://whatever.dev'
+            #
+            # # toggle this service on via ENV
+            #
+            # export #{parsed_service_name.upcase}_ENABLED=true
+          end
+        FILE
+      end
+
+      def register_fake_in_config
+        append_to_file config_file_path do <<~RUBY
+          WebValve.register #{fake_service_class_name}
+        RUBY
+        end
+      end
+
+      def require_config!
+        raise 'No WebValve configuration file found. Please run `rails generate webvalve:install` first' unless File.exists?(config_file_path)
+      end
+
+      def config_file_path
+        "config/webvalve.rb"
+      end
+
+      def full_file_path
+        "webvalve/#{fake_service_filename}.rb"
+      end
+
+      def fake_service_class_name
+        fake_service_filename.camelize
+      end
+
+      def fake_service_filename
+        "fake_#{parsed_service_name.underscore}"
+      end
+
+      def parsed_service_name
+        service_name.sub(/fake/i, '')
+      end
+    end
+  end
+end

data/lib/generators/webvalve/install_generator.rb

@@ -0,0 +1,33 @@
+require 'rails/generators/base'
+
+module Webvalve
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Install WebValve"
+
+      def create_webvalve_config_file
+        create_config_file
+        create_file "webvalve/.keep", ""
+      end
+
+      private
+
+      def create_config_file
+        create_file full_file_path, <<-FILE.strip_heredoc
+          # # register services
+          #
+          # WebValve.register FakeThing
+          # WebValve.register FakeExample, url: 'https://api.example.org'
+          #
+          # # whitelist urls
+          #
+          # WebValve.whitelist_url 'https://example.com'
+        FILE
+      end
+
+      def full_file_path
+        "config/webvalve.rb"
+      end
+    end
+  end
+end

data/lib/webvalve.rb

@@ -0,0 +1,40 @@
+require 'set'
+
+module WebValve
+  extend ActiveSupport::Autoload
+  autoload :FakeService, 'webvalve/fake_service'
+  autoload :FakeServiceWrapper, 'webvalve/fake_service_wrapper'
+  autoload :FakeServiceConfig, 'webvalve/fake_service_config'
+  autoload :Manager, 'webvalve/manager'
+
+  ENABLED_ENVS = %w(development test).freeze
+
+  class << self
+    # @!method setup
+    #   @see WebValve::Manager#setup
+    # @!method register
+    #   @see WebValve::Manager#register
+    # @!method whitelist_url
+    #   @see WebValve::Manager#whitelist_url
+    # @!method reset
+    #   @see WebValve::Manager#reset
+    delegate :setup, :register, :whitelist_url, :reset, to: :manager
+
+    def enabled?
+      Rails.env.in?(ENABLED_ENVS)
+    end
+
+    def config_paths
+      @config_paths ||= Set.new
+    end
+
+    private
+
+    def manager
+      WebValve::Manager.instance
+    end
+  end
+end
+
+require 'webvalve/instrumentation'
+require 'webvalve/engine'

data/lib/webvalve/engine.rb

@@ -0,0 +1,26 @@
+module WebValve
+  class Engine < ::Rails::Engine
+    isolate_namespace WebValve
+
+    if WebValve.enabled?
+      initializer "webvalve.set_autoload_paths", before: :set_autoload_paths do |app|
+        WebValve.config_paths << app.root
+
+        WebValve.config_paths.each do |root|
+          app.config.eager_load_paths << root.join('webvalve').to_s
+        end
+      end
+
+      initializer "webvalve.setup" do
+        WebValve.config_paths.each do |root|
+          path = root.join('config', 'webvalve.rb').to_s
+          load path if File.exist?(path)
+        end
+
+        config.after_initialize do
+          WebValve.setup
+        end
+      end
+    end
+  end
+end

data/lib/webvalve/fake_service.rb

@@ -0,0 +1,22 @@
+require 'sinatra/base'
+require 'sinatra/json'
+require 'webvalve/instrumentation/middleware'
+
+module WebValve
+  class FakeService < Sinatra::Base
+
+    set :dump_errors, false
+    set :show_exceptions, false
+    set :raise_errors, true
+
+    configure do
+      use Instrumentation::Middleware
+    end
+
+    private
+
+    def route_missing
+      raise "route not defined for #{request.request_method} #{uri} in #{self.class.name}."
+    end
+  end
+end