sea_shanty 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49c70b677534f10db5b3f98e4e49cc7a5259ac816db7f63cdf65d4768bbe207e
+  data.tar.gz: fdbe5b1e9588650f4772648973043e35144fdaf5f0c90b035b687901b4dfd05d
+SHA512:
+  metadata.gz: 9b7a690390d6a80adb76b8c91a2ac789a07238c460661f77079751993b72321172ddf7175d7b40880815b834d1b59781ec57801f92c91c996b4c6c0a900ef765
+  data.tar.gz: 856de8a10bf572640facea7ada229122f2b751f71230152cd4f9a4c44e9b2c1483bb78f1a34a4236c6d1d6cace2e5a7eddb1f91fe33690443599725034d3759e

data/.standard.yml

@@ -0,0 +1,2 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-01-04
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at rasmus@nerdd.dk. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in sea_shanty.gemspec
+gemspec
+
+gem "rake"
+
+gem "minitest"
+
+gem "standard"
+
+gem "faraday"

data/Gemfile.lock

@@ -0,0 +1,59 @@
+PATH
+  remote: .
+  specs:
+    sea_shanty (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    faraday (2.7.2)
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.2)
+    json (2.6.3)
+    language_server-protocol (3.17.0.2)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.3.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.1)
+    rexml (3.2.5)
+    rubocop (1.40.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.24.0)
+      parser (>= 3.1.1.0)
+    rubocop-performance (1.15.1)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    ruby-progressbar (1.11.0)
+    ruby2_keywords (0.0.5)
+    standard (1.20.0)
+      language_server-protocol (~> 3.17.0.2)
+      rubocop (= 1.40.0)
+      rubocop-performance (= 1.15.1)
+    unicode-display_width (2.3.0)
+
+PLATFORMS
+  x86_64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  faraday
+  minitest
+  rake
+  sea_shanty!
+  standard
+
+BUNDLED WITH
+   2.3.3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Rasmus Bang Grouleff
+
+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,178 @@
+# SeaShanty
+
+SeaShanty is a tiny library that records HTTP interactions and replays responses for requests it has seen before.
+
+The primary purpose is to speed up your test suite regardless of which test framework used by not relying on the network.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sea_shanty'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install sea_shanty
+
+## Usage
+
+The following is a minimal example of how to use SeaShanty.
+
+```ruby
+require "rubygems"
+require "minitest"
+require "faraday"
+require "sea_shanty"
+require "sea_shanty/faraday"
+
+SeaShanty.configure do |config|
+  config.storage_dir = "fixtures/sea_shanty"
+end
+SeaShanty.intercept(:faraday)
+
+class TestSeaShanty < Minitest::Test
+  def test_fetch
+    response = Faraday.get("https://example.com")
+    assert_equal(200, response.status)
+  end
+end
+```
+
+The first time the test above is run, the request is sent as normal, because SeaShanty hasn't seen it before, and the request and response is stored, before the response is returned. On subsequent runs of the test, no requests will be sent over the network. Instead the response is loaded from the storage directory and returned.
+
+**CAUTION!**
+
+To prevent storing sensitive information like `Authorization` headers or credentials in the request body, use the `Configuration#request_body_filter` and `Configuration#request_headers_filter` described in the [Configuration](#configuration) section.
+
+### Interccept requests in an HTTP library
+
+The following call intercepts requests made with Faraday.
+
+```ruby
+SeaShanty.intercept :faraday
+```
+
+Any HTTP requests made before the call to `SeaShanty.intercept` will not be handled by SeaShanty.
+
+### Configuration
+
+* `storage_dir`
+  * The storage directory for the requests and responses.
+  * A string that can either be an absolute path or a path relative to `Dir.pwd`
+* `bypass`
+  * Tells if SeaShanty should be bypassed
+  * A boolean. If it is true, SeaShanty will not look up or store responses, but just pass the request to the HTTP library
+  * This can be overwritten by setting the environment variable `SEA_SHANTY_BYPASS`
+* `readonly`
+  * Tells if SeaShanty should allow the HTTP library to send the request over the network
+  * A boolean. If it is true, no requests are sent over the network. Instead SeaShanty will raise a `SeaShanty::UnknownRequest` error, if the request has not been seen before
+  * This can be overwritten by setting the environment variable `SEA_SHANTY_READONLY`
+* `generic_responses`
+  * Tells SeaShanty to return generic responses whenever the request url matches one of the keys
+  * A hash where the keys are `Regexp`s and the values are strings with the path to a file with a stored response relative to the `storage_dir`
+  * The request url is matched against the `Regexp`s, and the first match will make SeaShanty return the response stored in the file with the path in the hash value
+* `request_body_filter`
+  * Is applied to the request body before figuring out if the request has been seen before, and before the request and response is saved
+  * A callable object with an arity of 1.
+  * Is called with the raw request body
+  * Must return the filtered body
+* `request_headers_filter`
+  * Is applied to the request headers before the request and response is saved
+  * A callable object with an arity of 2
+  * Is called once with each header name and value
+  * Must return the filtered value
+
+### Creating your own interceptor
+
+Any object responding to `intercept!` and `remove` can be registered as interceptors in SeaShanty by calling `SeaShanty.register_interceptor(:identifier, interceptor)`.
+
+The `intercept!` method must be able to take an instance of a `SeaShanty::RequestStore` as its sole argument.
+
+#### Using the RequestStore
+
+When intercepting a request from the HTTP library, a `SeaShanty::Request` should be instantiated like so:
+
+```ruby
+request = SeaShanty::Request.new(method: "GET", url: "https://example.com", headers: {}, body: "")
+```
+
+The `method` should be a String or symbol, `url` should be a String or an `URI`, `headers` should be a hash, and `body` a String or `nil`.
+
+This `Request` objejct is then passed to `RequestStore#fetch` together with a block that takes no parameters and returns a `SeaShanty::Response`.
+
+If the response is not loaded from the request store, the block is instead called.
+
+To build a `Response` object use the initializer:
+
+```ruby
+SeaShanty::Response.new(status: 200, message: "OK", headers: {}, body: "", original_response: response_from_library)
+```
+
+The `status` should be an Integer, `message` a String or `nil`, `headers` should be a hash, `body` a String or `nil`. `original_response` is optional provided as a convenience.
+
+When `RequestStore#fetch` returns the response, it is the interceptor's responsibility to convert the `Response` object into a format the library understands. If the block to `fetch` was called, and `original_response` is set, `Response#was_stored?` is `true`, and the response from the HTTP library is available in `Response#original_response`. Otherwise the interceptor can retrieve the data from the `Response` object using attributes similarly named as the named parameters in the initializer.
+
+#### Registering an interceptor
+
+The Faraday interceptor is registered like so in `lib/sea_shanty/faraday.rb`:
+
+```ruby
+require "sea_shanty/faraday/interceptor"
+
+SeaShanty.register_interceptor :faraday, SeaShanty::Faraday::Interceptor.new
+```
+
+### Supported HTTP libraries
+
+In the current version [Faraday](https://lostisland.github.io/faraday/) is the only library SeaShanty supports.
+
+## Alternatives
+
+* [VCR](https://github.com/vcr/vcr)
+* [Ephemeral Response](https://github.com/sandro/ephemeral_response)
+* [Net::HTTP Spy](https://github.com/martinbtt/net-http-spy)
+* [NetRecorder](https://github.com/chrisyoung/netrecorder)
+* [Puffing Billy](https://github.com/oesmith/puffing-billy)
+* [REST-assured](https://github.com/artemave/REST-assured)
+* [Stale Fish](https://github.com/jsmestad/stale_fish)
+* [WebFixtures](https://github.com/trydionel/web_fixtures)
+
+## Future development
+
+- [ ] Add interceptors for more HTTP libraries
+- [ ] Add optional response body compression to reduce storage requirements
+- [ ] Make it possible to overwrite stored requests and responses
+- [ ] Document `Request`, `Response` and `RequestStore`
+- [ ] More? Create an issue or send a pull request, if you think something is missing 🎉
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+Before creating a pull request, please make sure `rake test` passes, and `rake standard` has no suggestions.
+
+## Releasing a new version
+
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+The SeaShanty versioning scheme follows [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rbgrouleff/sea_shanty. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/rbgrouleff/sea_shanty/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the SeaShanty project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rbgrouleff/sea_shanty/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[test standard]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "sea_shanty"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/sea_shanty/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "sea_shanty/errors"
+
+module SeaShanty
+  class Configuration
+    attr_accessor :bypass, :readonly, :storage_dir
+    alias_method :bypass?, :bypass
+    alias_method :readonly?, :readonly
+
+    def generic_responses=(responses)
+      unless Hash === responses
+        raise(
+          ConfigurationError,
+          "Generic responses must be a hash that maps a Regexp or something else that responds to `match?` to a relative path to a file with a recorded response."
+        )
+      end
+
+      raise ConfigurationError, "keys in the generic responses hash must respond to `match?`." unless responses.keys.all? { |key| key.respond_to?(:match?) }
+
+      @generic_responses = responses
+    end
+
+    def generic_responses
+      @generic_responses ||= {}
+    end
+
+    def request_body_filter=(filter)
+      raise ConfigurationError, "Filter must have a call method" unless filter.respond_to?(:call)
+      raise ConfigurationError, "Filter must have an arity of exactly 1" unless filter.arity == 1
+      @request_body_filter = filter
+    end
+
+    def request_body_filter
+      @request_body_filter ||= lambda { |body| body }
+    end
+
+    def request_headers_filter
+      @request_headers_filter ||= lambda { |key, value| value }
+    end
+
+    def request_headers_filter=(filter)
+      raise ConfigurationError, "Filter must have a call method" unless filter.respond_to?(:call)
+      raise ConfigurationError, "Filter must have an arity of exactly 2" unless filter.arity == 2
+      @request_headers_filter = filter
+    end
+  end
+end

data/lib/sea_shanty/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SeaShanty
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class UnknownRequest < Error
+  end
+
+  class UnknownInterceptor < Error
+  end
+end

data/lib/sea_shanty/faraday/interceptor.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "sea_shanty/faraday/middleware"
+require "sea_shanty/faraday/rack_builder"
+
+module SeaShanty
+  module Faraday
+    class Interceptor
+      BUILDER_CLASS_ATTR_NAME = :builder_class
+
+      def intercept!(request_store)
+        Middleware.request_store = request_store
+        ::Faraday::ConnectionOptions.memoized(BUILDER_CLASS_ATTR_NAME) { RackBuilder }
+      end
+
+      def remove
+        ::Faraday::ConnectionOptions.memoized(BUILDER_CLASS_ATTR_NAME) { ::Faraday::RackBuilder }
+      end
+    end
+  end
+end

data/lib/sea_shanty/faraday/middleware.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+require "sea_shanty/request"
+require "sea_shanty/response"
+
+module SeaShanty
+  module Faraday
+    class Middleware
+      class << self
+        attr_accessor :request_store
+      end
+
+      attr_reader :request_store
+
+      def initialize(app, request_store: self.class.request_store)
+        @app = app
+        @request_store = request_store
+      end
+
+      def call(env)
+        response = request_store.fetch(build_request(env)) do
+          faraday_response = @app.call(env).on_complete do |response_env|
+            response_env
+          end
+
+          build_response(faraday_response.env)
+        end
+
+        build_faraday_response(response, env)
+      end
+
+      def close
+        @app.close if @app.respond_to?(:close)
+      end
+
+      private
+
+      def build_request(env)
+        Request.new(method: env.method, url: env.url, headers: env.request_headers.to_h, body: env.request_body)
+      end
+
+      def build_response(response_env)
+        Response.new(
+          status: response_env.status,
+          message: response_env.reason_phrase,
+          headers: response_env.response_headers.to_h,
+          body: response_env.response_body,
+          original_response: response_env.response
+        )
+      end
+
+      def build_faraday_response(response, env)
+        if response.was_stored?
+          response.original_response
+        else
+          env.response = ::Faraday::Response.new
+          env.status = response.status
+          env.reason_phrase = response.message
+          env.response_headers = ::Faraday::Utils::Headers.from(response.headers)
+          env.response_body = response.body
+          env.response.finish(env)
+        end
+      end
+    end
+  end
+end

data/lib/sea_shanty/faraday/rack_builder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "sea_shanty/faraday/middleware"
+
+module SeaShanty
+  module Faraday
+    class RackBuilder < ::Faraday::RackBuilder
+      def lock!
+        insert_middleware
+        super
+      end
+
+      private
+
+      def insert_middleware
+        return if handlers.any? { |h| ::SeaShanty::Faraday::Middleware == h.klass }
+        insert_before(handlers.size, ::SeaShanty::Faraday::Middleware)
+      end
+    end
+  end
+end

data/lib/sea_shanty/faraday.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "sea_shanty/faraday/interceptor"
+
+SeaShanty.register_interceptor(:faraday, SeaShanty::Faraday::Interceptor.new)

data/lib/sea_shanty/request.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module SeaShanty
+  class Request
+    attr_reader :method, :url, :headers, :body
+
+    def initialize(method:, url:, headers:, body:)
+      @method = method
+      @url = case url
+      when String
+        URI.parse(url)
+      when URI
+        url
+      else
+        raise ArgumentError, "url should be a String or an URI"
+      end
+      @headers = headers
+      @body = body
+    end
+
+    def to_h
+      {
+        method: method.to_s,
+        url: url.to_s,
+        headers: headers,
+        body: {
+          string: body.to_s,
+          encoding: body.nil? ? "" : body.encoding.name
+        }
+      }
+    end
+  end
+end

data/lib/sea_shanty/request_serializer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+require "pathname"
+
+module SeaShanty
+  class RequestSerializer
+    def initialize(headers_filter: lambda { |_name, value| value }, body_filter: lambda { |body| body })
+      @headers_filter = headers_filter
+      @body_filter = body_filter
+    end
+
+    def digest(request)
+      Digest::SHA1.hexdigest(request.method.to_s + request.url.to_s + body_filter.call(request.body.to_s))
+    end
+
+    def filename(request)
+      "#{digest(request)}.yml"
+    end
+
+    def file_path(request)
+      # Don't assume system directory separator is /
+      url_path = request.url.path.delete_prefix("/").split("/").join(File::SEPARATOR)
+      Pathname.new(request.url.hostname).join(url_path, request.method.to_s, filename(request))
+    end
+
+    def serialize(request)
+      hash = request.to_h
+      hash[:headers] = hash.fetch(:headers).map { |name, value| [name, headers_filter.call(name, value)] }.to_h
+      hash[:body] = body_filter.call(hash.fetch(:body))
+      hash
+    end
+
+    private
+
+    attr_reader :headers_filter, :body_filter
+  end
+end

data/lib/sea_shanty/request_store.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "date"
+require "pathname"
+require "yaml"
+require "sea_shanty/request_serializer"
+
+module SeaShanty
+  class RequestStore
+    def initialize(configuration, generic_responses: configuration.generic_responses, storage_dir: configuration.storage_dir)
+      @configuration = configuration
+      @generic_responses = generic_responses
+      @storage_dir = Pathname.new(storage_dir)
+      @request_serializer = RequestSerializer.new(headers_filter: configuration.request_headers_filter, body_filter: configuration.request_body_filter)
+    end
+
+    def fetch(request, &block)
+      if configuration.bypass?
+        raise ConfigurationError, "Bypass and readonly are both true - please set only one of them." if configuration.readonly?
+        yield
+      elsif configuration.readonly?
+        load_response(request)
+      elsif has_response_for?(request)
+        load_response(request)
+      else
+        response = yield
+        store(request, response) unless configuration.bypass?
+        response
+      end
+    end
+
+    def has_response_for?(request)
+      request_file_path(request).exist?
+    end
+
+    def load_response(request)
+      raise UnknownRequest, "SeaShanty: Unknown request #{request.method.to_s.upcase} to #{request.url}" unless has_response_for?(request)
+      contents = YAML.safe_load(request_file_path(request).read, permitted_classes: [Symbol])
+      Response.from_h(contents.fetch(:response))
+    end
+
+    def store(request, response)
+      file_path = request_file_path(request)
+      file_path.dirname.mkpath
+      file_path.open("w+") do |file|
+        file.write(YAML.dump(serialize(request, response)))
+      end
+    end
+
+    private
+
+    attr_reader :configuration, :generic_responses, :storage_dir, :request_serializer
+
+    def request_file_path(request)
+      _, generic_file_path = generic_responses.find { |matcher, path| matcher.match?(request.url.to_s) }
+      file_path = if generic_file_path.nil?
+        request_serializer.file_path(request)
+      else
+        Pathname.new(generic_file_path.to_s)
+      end
+
+      storage_dir.join(file_path)
+    end
+
+    def serialize(request, response)
+      {
+        request: request_serializer.serialize(request),
+        response: response.to_h,
+        stored_at: DateTime.now.to_s
+      }
+    end
+  end
+end

data/lib/sea_shanty/response.rb

@@ -0,0 +1,60 @@
+# frozen_literal_string: true
+
+module SeaShanty
+  class Response
+    attr_reader :body, :headers, :message, :status, :original_response
+
+    class << self
+      def from_h(hash)
+        new(
+          status: hash.fetch(:status).fetch(:code),
+          message: hash.fetch(:status).fetch(:message),
+          headers: hash.fetch(:headers),
+          body: hash.fetch(:body).fetch(:encoding).empty? ? nil : hash.fetch(:body).fetch(:string)
+        )
+      end
+    end
+
+    def initialize(status:, message:, headers:, body:, original_response: ORIGINAL_RESPONSE_NOT_PRESENT)
+      @status = Integer(status, status.is_a?(String) ? 10 : 0)
+      @message = message
+      @headers = headers
+      @body = body
+      @original_response = original_response
+    end
+
+    def to_h
+      {
+        status: {
+          code: status,
+          message: message
+        },
+        headers: headers,
+        body: {
+          string: body.to_s,
+          encoding: body.nil? ? "" : body.encoding.name
+        }
+      }
+    end
+
+    def was_stored?
+      ORIGINAL_RESPONSE_NOT_PRESENT != original_response
+    end
+
+    def ==(other)
+      self.class === other &&
+        status == other.status && message == other.message && headers == other.headers &&
+        body == other.body
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      [self.class, status, message, headers, body].hash
+    end
+
+    private
+
+    ORIGINAL_RESPONSE_NOT_PRESENT = :original_response_not_present
+  end
+end

data/lib/sea_shanty/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SeaShanty
+  VERSION = "0.1.0"
+end

data/lib/sea_shanty.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "sea_shanty/errors"
+require "sea_shanty/configuration"
+require "sea_shanty/request_store"
+require "sea_shanty/version"
+
+module SeaShanty
+  TRUE_VALUES = %w[1 yes y true]
+
+  module_function
+
+  def configuration
+    @configuration ||= Configuration.new
+  end
+
+  def configure(&block)
+    yield configuration
+
+    configuration.bypass = configuration_overwrite(ENV["SEA_SHANTY_BYPASS"], configuration.bypass)
+    configuration.readonly = configuration_overwrite(ENV["SEA_SHANTY_READONLY"], configuration.readonly)
+  end
+
+  def intercept(identifier)
+    return if intercepting.include?(identifier)
+    interceptors.fetch(identifier).intercept!(request_store)
+    intercepting << identifier
+  rescue KeyError
+    raise(
+      UnknownInterceptor,
+      "Cannot find an interceptor for #{identifier}. Available interceptors are: [#{interceptors.keys.join(", ")}]"
+    )
+  end
+
+  def intercepting
+    @intercepting ||= []
+  end
+
+  def interceptors
+    @interceptors ||= {}
+  end
+
+  def register_interceptor(identifier, interceptor)
+    interceptors[identifier] = interceptor
+  end
+
+  def remove(identifier)
+    return unless intercepting.include?(identifier)
+    interceptors.fetch(identifier).remove
+    intercepting.delete(identifier)
+  rescue KeyError
+    raise(
+      UnknownInterceptor,
+      "Cannot find an interceptor for #{identifier}. Available interceptors are: [#{interceptors.keys.join(", ")}]"
+    )
+  end
+
+  def request_store
+    @request_store ||= RequestStore.new(configuration)
+  end
+
+  def configuration_overwrite(env_var, value)
+    if env_var.nil? || env_var.empty?
+      value
+    else
+      TRUE_VALUES.include?(env_var.downcase)
+    end
+  end
+end

data/sea_shanty.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/sea_shanty/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "sea_shanty"
+  spec.version = SeaShanty::VERSION
+  spec.authors = ["Rasmus Bang Grouleff"]
+  spec.email = ["rasmus@nerdd.dk"]
+
+  spec.summary = "SeaShanty records HTTP requests and responses and returns saved responses for requests it has seen before."
+  spec.description = "SeaShanty is a minimalistic library for recording HTTP requests and responses and replaying responses for already seen requests in an unobtrusive and test framework agnostic way."
+  spec.homepage = "https://github.com/rbgrouleff/sea_shanty"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = [spec.homepage, "CHANGELOG.md"].join("/")
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/sig/sea_shanty.rbs

@@ -0,0 +1,4 @@
+module SeaShanty
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: sea_shanty
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rasmus Bang Grouleff
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-01-04 00:00:00.000000000 Z
+dependencies: []
+description: SeaShanty is a minimalistic library for recording HTTP requests and responses
+  and replaying responses for already seen requests in an unobtrusive and test framework
+  agnostic way.
+email:
+- rasmus@nerdd.dk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/sea_shanty.rb
+- lib/sea_shanty/configuration.rb
+- lib/sea_shanty/errors.rb
+- lib/sea_shanty/faraday.rb
+- lib/sea_shanty/faraday/interceptor.rb
+- lib/sea_shanty/faraday/middleware.rb
+- lib/sea_shanty/faraday/rack_builder.rb
+- lib/sea_shanty/request.rb
+- lib/sea_shanty/request_serializer.rb
+- lib/sea_shanty/request_store.rb
+- lib/sea_shanty/response.rb
+- lib/sea_shanty/version.rb
+- sea_shanty.gemspec
+- sig/sea_shanty.rbs
+homepage: https://github.com/rbgrouleff/sea_shanty
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rbgrouleff/sea_shanty
+  source_code_uri: https://github.com/rbgrouleff/sea_shanty
+  changelog_uri: https://github.com/rbgrouleff/sea_shanty/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: SeaShanty records HTTP requests and responses and returns saved responses
+  for requests it has seen before.
+test_files: []