rack-service_api_versioning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cd275478211642acf09b98289aeedc3ce4a2b646
+  data.tar.gz: 4677eda8a6576e3a9446b67ac9433d54cdcb95dd
+SHA512:
+  metadata.gz: a71438c1f5917dcbb8667365510454d3b6957652ba3cc08206737965e7a37dbac015b7a5aab0454b42a6db4227993d60cb12c95bbb39c800b4a3f90b6e0c2275
+  data.tar.gz: 303b94ad05bc34ab76f085fcaf3e3806c4871977db7dfab1f3b1549094a05bf894b534d7423d6eb668a06f0a404b2bd2e7549fc06d78b85532888ebe8601408a

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.rbenv-gemsets
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/pkg/
+/spec/reports/
+/tmp/
+/o-rdoc/
+/bin/
+!/bin/setup
+.ruby-version

data/.rubocop.yml

@@ -0,0 +1,14 @@
+
+AllCops:
+  TargetRubyVersion: 2.3
+  Exclude:
+    - 'gemsets/**/*'
+    - 'bin/**/*'
+    - '*.gemspec'
+    - 'Rakefile'
+    - 'Guardfile'
+
+Metrics/BlockLength:
+  Max: 800
+  Include:
+    - 'test/**/*_test.rb'

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.3
+before_install: gem install bundler -v 1.14.4

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rack-service_api_versioning.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Jeff Dickey
+
+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,105 @@
+<h1>Rack::ServiceApiVersioning</h1>
+
+[![Join the chat at https://gitter.im/rack-service_api_versioning/Lobby](https://badges.gitter.im/rack-service_api_versioning/Lobby.svg)](https://gitter.im/rack-service_api_versioning/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+This Gem implements three Rack middleware components that, together, enable possibly multiple API Versions of one or more Component Services to be active at the same time. Incoming requests for a service specify their version requirements, if any, with an `Accept` HTTP header.
+
+----
+
+## Contents
+
+- [A Note on Terminology](#a-note-on-terminology)
+  * [Ubiquitous Language](#ubiquitous-language)
+  * [Requirement-Level Keywords](#requirement-level-keywords)
+- [Installation](#installation)
+- [Usage](#usage)
+  * [An Overview of the Protocol](#an-overview-of-the-protocol)
+  * [API Documentation](#api-documentation)
+- [Development](#development)
+  * [Prerequisites](#prerequisites)
+  * [Running Tests](#running-tests)
+- [Contributing](#contributing)
+- [License](#license)
+
+## A Note on Terminology
+
+### Ubiquitous Language
+
+This Gem was developed to support a larger project involving a collection of separately packaged, independent Component Services communicating via HTTP, with any data transfer objects encoded as JSON. As such, these middleware components use a subset of that project's [Ubiquitous Langauge](https://martinfowler.com/bliki/UbiquitousLanguage.html), which is documented in the file [`UBIQUITOUS_LANGUAGE.md`](https://github.com/jdickey/rack-service_api_versioning/blob/master/UBIQUITOUS_LANGUAGE.md) in the `/doc` directory.
+
+These terms, when used in this or other documents, can be identified as probable Ubiquitous Language terms by their use of initial capital letters, as demonstrated *by* the usage of *Ubiquitous Language* itself.
+
+### Requirement-Level Keywords
+
+Additionally, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). These keywords **must** be styled in a **strong** ("bold") font face when used in this or other related documents; rendering them in grammatically-appropriate case rather than in ALL CAPS is a **recommended** variance from the RFC *unless* the author is certain that the audience will be viewing the content only as raw text, in which case the ALL CAPS styling is strongly **recommended.**
+
+## Installation
+
+The middleware components in this Gem are intended for use in an API Version-independent Delivery Application, or AVIDA. They will not normally be used by API Version implementations or by other applications not developed using this protocol for API Version disambiguation. Therefore, this Gem will ordinarily be added to the Gemfile of such an AVIDA, rather than installed in the system Gem repository.
+
+Add this line to the Gemfile for an API Version-independent Delivery Application:
+
+```ruby
+gem 'rack-service_api_versioning'
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+### An Overview of the Protocol
+
+An application platform may be constructed of a number of separately-maintained components, including [use case or use story](https://martinfowler.com/bliki/UseCasesAndStories.html) implementations running as separate Primary Delivery Applications, or *PDAs.* Each of these is invoked by and interacts with other Component Services via HTTP, with data objects encoded using JSON. Each of these also is ordinarily versioned independently of others, which presents challenges when a Component Service and its PDA (collectively, a *Target Service*) are updated:
+
+* How do its collaborators, which may be implemented and maintained by different teams, ensure that they collaborate only with a known-good version of the Target Service when the possibility exists that new versions may introduce breaking changes?
+* How do new API Versions of the Target Service evolve and implement functionality, or even simple API changes, that introduce breaking changes without being hobbled by fealty to backwards compatibility?
+* Given the above, how can multiple API Versions of a given Target Service be deployed *in the same system* to meet the needs of different clients which have not all updated to the latest version due to API changes?
+* From an operational perspective, how can the system maintain adequate resilience if a newly-deployed API Version's PDA of a Service proves unreliable, yet all clients will happily work with previous API Versions if the new one is unavailable?
+* How can network- and server-related issues such as failover or migration be dealt with while maintaining continuous availability of the larger system?
+
+One solution is to define a single Service Base URL for each Component Service, with the AVIDA application accessible via that URL existing solely to generate HTTP redirects to the Service Base URL for the Primary Delivery Application of a given API Version. The AVIDA **must not** implement code to serve Service Endpoints itself, as they will never be accessed when using the middleware correctly. The middleware components get information about the currently-available API Versions by querying a [Repository](#the-repository); maintaining the correctness and currency of that data is outside the scope of this document (or this Gem).
+
+In the accompanying [API Documentation](https://github.com/jdickey/rack-service_api_versioning/doc/API-DOCUMENTATION.md), we discuss the three artefacts directly involved with the use of the Rack middleware components in this Gem: the AVIDA (API Version-Independent Primary Delivery Application); the Repository containing information about currently available API Versions; and the API Implementation Primary Delivery Application (PDA).
+
+### API Documentation
+
+As noted above, the [API Documentation](https://github.com/jdickey/rack-service_api_versioning/doc/API-DOCUMENTATION.md) for the Rack middleware components implemented in this Gem, including overview and usage, is in a separate document.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies (which as of now must already be in­stalled on your local system). Then, run `bin/rake test` to run the tests, or `bin/rake` to run tests and, if tests are successful, further static-analysis tools ([RuboCop](https://github.com/bbatsov/rubocop), [Flay](https://github.com/seattlerb/flay), [Flog](https://github.com/seattlerb/flog), and [RubyCritic](https://github.com/whitesmith/rubycritic)).
+
+To install *your build* of this Gem onto your local machine, run `bin/rake install`. We recom­mend that you uninstall any previously-installed "official" Gem to increase your confi­dence that your tests are running against *your* build. You should then be able to either run tests or test the middleware components from within your set of applications (AVIDA and PDA).
+
+### Prerequisites
+
+The development setup as automated by `bin/setup` assumes that
+
+1. you're using [`rbenv`](https://github.com/rbenv/rbenv) for Ruby version management;
+2. you have the [`rbenv-gemset`](https://github.com/jf/rbenv-gemset) plugin installed (see [here](https://gist.github.com/MicahElliott/2407918) for a quick setup HOWTO).
+
+Gemsets make life easier, both by maintaining a pristine system Gem repository and by guaranteeing that a program can be rebuilt with the *exact same versions* of Gems as was used to build a specific commit. Our use of Gemsets, as shown in the [`gemsets/setup_and_bundle.sh`](https://github.com/jdickey/rack-service_api_versioning/tree/master/gemsets/setup_and_bundle.sh) file and the [gemspec](https://github.com/jdickey/rack-service_api_versioning/tree/master/rack-service_api_versioning.gemspec), can be seen as "imposing a burden" on maintainence by requiring that Gem version updates be made consistently in both files, but it more than compensates for that by ensuring that each Gem directly used by *our* Gem doesn't have any "stealth updates" applied against it that risk changing functionality.
+
+### Running Tests
+
+Running tests works just as you would expect for individual MiniTest::Spec test scripts; you can run a command line such as `ruby test/rack/service_api_versioning/service_component_describer_test.rb` to run a single test-spec file. Also, running `rake` and `rake test` works just as you'd expect for running the complete set of tests.
+
+## Contributing
+
+1. [Fork it](https://github.com/jdickey/rack-service_api_versioning/fork);
+1. *Please* open an issue on this repo so we can discuss your feature. Features which reflect a consensus reached are much more likely to be merged quickly;
+1. Create your feature branch (`git checkout -b NNN-my-new-feature`) where `NNN` is the issue number for the aforementioned discussion;
+1. Ensure that your changes are completely covered by *passing* specs, and comply with the [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide) as enforced by [RuboCop](https://github.com/bbatsov/rubocop). To verify this, run `bundle exec rake`, noting and repairing any lapses in coverage or style violations;
+1. Commit your changes (`git add .; git commit`). Please *do not* use a single-line commit message (`git commit -am "some message"`). A good commit message notes what was changed and why in sufficient detail that a relative newcomer to the code can understand your reasoning and your code. We **recommend** (but do not yet enforce) commit messages conforming to [these conventions](http://karma-runner.github.io/1.0/dev/git-commit-msg.html);
+1. Push to the branch (`git push origin NNN-my-new-feature`). Remember that the first time pushing a branch to a remote requires an "unconditional" push (`git push -u origin NNN-my-new-feature`);
+1. Create a new Pull Request. In the initial message, reference the open issue where your feature has been discussed; if no such issue exists (why?), then describe at some length the rationale for your new feature; your implementation strategy at a higher level than each individual commit message; anything future maintainers should be aware of; and so on. Modifications to existing code *must* have been discussed in an issue for PRs containing them to be accepted and merged;
+1. Don't be discouraged if the PR generates further discussion leading to further refinement of your PR through additional commits. These should *generally* be discussed in comments on the relevant issue; discussion in the Gitter room (see below) may also be useful;
+1. If you've comments, questions, or just want to talk through your ideas, come hang out in the project's [room on Gitter](https://gitter.im/rack-service_api_versioning). Ask away!
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+Copyright &copy; 2017, Jeff Dickey and Prolog Systems (Singapore) Private Limited.

data/Rakefile

@@ -0,0 +1,60 @@
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+require 'rake/tasklib'
+require 'flay'
+require 'flay_task'
+require 'tasks/flog_task_patch'
+require 'reek/rake/task'
+require 'rubocop/rake_task'
+# require 'rubycritic/rake_task'
+
+Rake::TestTask.new(:test) do |t|
+  # t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+  # NOTE: Silences "loading in progress, circular require considered harmful"
+  #       (and any other warnings -- not spec failures -- from MiniTest). Try
+  #       removing/uncommenting this after a minitest update from 5.10.1.
+  t.warning = false
+end
+
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.patterns = [
+    'lib/**/*.rb',
+    'test/**/*.rb'
+  ]
+  task.formatters = ['simple', 'd']
+  task.fail_on_error = true
+  # task.options << '--rails'
+  task.options << '--display-cop-names'
+end
+
+Reek::Rake::Task.new do |t|
+  t.config_file = 'config.reek'
+  t.source_files = 'lib/**/*.rb'
+  t.reek_opts = '--sort-by smelliness --no-progress  -s'
+end
+
+FlayTask.new do |t|
+  t.verbose = true
+  t.dirs = %w(lib)
+end
+
+FlogTask.new do |t|
+  t.verbose = true
+  t.threshold = 300 # default is 200
+  t.methods_only = true
+  t.dirs = %w(lib) # Look, Ma; no tests! Run the tool manually every so often for those.
+end
+
+# # NOTE: We still want to keep the `config.reek` file, since RubyCritic uses Reek.
+# #       Also note that tests give craptastic scores, hence now skipped. :grimacing:
+# RubyCritic::RakeTask.new do |t|
+#   t.options = '-f console'
+#   t.paths = %w(lib)
+# end
+
+task(:default).clear
+task default: [:test, :rubocop, :flay, :flog, :reek]

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rack/service_api_versioning"
+
+# 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,12 @@
+#!/usr/bin/env zsh
+set -euo pipefail
+IFS=$'\n\t'
+# set -vx
+
+rm -f Gemfile.lock
+
+# bundle install
+source tmp/gemsets/setup-and-bundle.sh
+
+bundle binstub --force flay flog guard pry rake reek rubocop rubycritic
+echo "Setup completed."

data/config.reek

@@ -0,0 +1,21 @@
+
+# NOTE: Even if we're using RubyCritic "instead of" directly invoking Reek, be
+#       aware that RubyCritic *invokes* Reek. Hence, this file should remain
+#       where it is.
+
+# This tells Reek not to complain about module names such as `FooCsV42`, which
+# our conventions say implements the Foo Component Service, API Version 42.
+UncommunicativeModuleName:
+  accept:
+    - !ruby/regexp /CsV\d+?$/
+    - !ruby/regexp /UcV\d+?$/
+
+# Usual suspects copied from previous projects. Commented out until needed.
+
+# LongParameterList:
+#   max_params: 4  # If it's good enough for Sandi, it's good enough for us.
+
+# NestedIterators:
+#   max_allowed_nesting: 2
+#   ignore_iterators:
+#     - lambda

data/doc/API-DOCUMENTATION.md

@@ -0,0 +1,166 @@
+<h1>Contents</h1>
+
+# Contents
+
+- [Before We Get Started](#before-we-get-started)
+  * [A Note on Terminology](#a-note-on-terminology)
+  * [FAQ for This Document](#faq-for-this-document)
+- [Setup in the AVIDA](#setup-in-the-avida)
+- [The `ServiceComponentDescriber` Middleware Component](#the-servicecomponentdescriber-middleware-component)
+  * [The Repository](#the-repository)
+    + [Repository Value Schemata](#repository-value-schemata)
+  * [Error Reporting](#error-reporting)
+- [The `AcceptContentTypeSelector` Middleware Component](#the-acceptcontenttypeselector-middleware-component)
+  * [Inputs from Rack Environment](#inputs-from-rack-environment)
+  * [Error Reporting](#error-reporting-1)
+- [The `ApiVersionRedirector` Middleware Component](#the-apiversionredirector-middleware-component)
+  * [Error Reporting](#error-reporting-2)
+- [Feasible Future Features](#feasible-future-features)
+  * [Other Ideas?](#other-ideas)
+
+# Before We Get Started
+
+## A Note on Terminology
+
+The section [*A Note on Terminology*](https://github.com/jdickey/rack-service_api_versioning/README.md#a-note-on-terminology), including description of this project's [Ubiquitous Langauge](https://github.com/jdickey/rack-service_api_versioning/doc/UBIQUITOUS-LANGUAGE.md) and [Requirement-Level Keywords](https://github.com/jdickey/rack-service_api_versioning/README.md#requirement-level-keywords), is incorporated herein by reference.
+
+## FAQ for This Document
+
+<dl>
+<dt>Why the Funky Header for "Contents"?</dt>
+<dd>We use the [`markdown-toc`](https://github.com/nok/markdown-toc) Node (and Atom) package to generate the table of contents. That package understands Markdown syntax for headers; it does not fully comprehend that Markdown is a proper superset of HTML, and so HTML headers are valid, too. Since we don't want the "Contents" header itself to appear in the TOC, using the HTML markup gives the desired result. 
+</dd>
+</dl>
+
+# Setup in the AVIDA
+
+A typical AVIDA might read something like the following:
+
+```ruby
+
+require 'awesome_print'
+
+require_relative './repository'
+
+# Code for Acme Apidemo Service Component, API Version `v1`, namespaced in this module.
+module AcmeApiDemoV1
+  # Roda/Rack app to serve as API Demo Component Service delivery mechanism.
+  # Remember that Roda's convention is to set `response.status` to 200 by
+  # default, which is just fine for most cases.
+  # Reek complains about a :reek:UncommunicativeVariableName. Ah, convention.
+  class ServiceApp < Roda
+    use Rack::Session::Cookie, secret: ENV['ACME_APIDEMO_SESSION_COOKIE_SECRET']
+    plugin :default_headers, 'Content-Type' => 'application/json'
+    use ServiceComponentDescriber, repository: DummyRepository.new,
+                                   service_name: 'apidemo'
+    use AcceptContentTypeSelector
+    use ApiVersionRedirector
+
+    route do |r|
+      r.post 'register' do
+        'Hello from #register. I MUST NOT be shown. params: ' + r.params.ai
+      end
+    end # route
+  end # class ServiceCatalogueUcV1::ServiceApp
+end
+```
+
+Note that, although the demo code above uses (the underappreciated, awesome) [Roda](http://roda.jeremyevans.net) framework, the middleware works with any framework built on [Rack](http://rack.github.io); this includes Rails, Sinatra, [Brooklyn](https://github.com/luislavena/brooklyn), or [anything else](http://codecondo.com/12-small-ruby-frameworks/) that runs on top of Rack.
+
+What's important is the use of the three middleware components `ServiceComponentDescriber`, `AcceptContentTypeSelector`, and `ApiVersionRedirector`; their ordering in the main application module *prior to* any routing or other application logic; and the parameters (for `ServiceComponentDescriber`). Each will be discussed in turn below.
+
+# The `ServiceComponentDescriber` Middleware Component
+
+The `ServiceComponentDescriber` middleware component is the first of our three middleware components to be used in an AVIDA for a Component Service. It **must** be invoked with parameters for `repository` and `service_name`. These parameters **may** be in either order.
+
+The component retrieves information concerning the implementation(s) of a specific named Component Service from a Repository whose data has been provided by an external service, formats that data into a JSON string which it uses to set a value in the Rack environment (using the key `'COMPONENT_DESCRIPTION'`), and then passes that environment on to the next link in the Rack call chain (which in practice **should** be the next middleware component).
+
+## The Repository
+
+The Repository is an object which returns an array of zero or more entities describing Component Services and their API Versions asserted to be presently available for use by external clients via HTTP.
+
+The Repository is queried via its `#find` method. The method takes as its parameter a Hash of entity attribute/value pairs, the only one of which that is guaranteed to be significant here being `:name`, which is matched against the short `:name` of available entities (see the next paragraph). The `#find` method returns an array of entities, which will be empty if no matches were found.
+
+### Repository Value Schemata
+
+Each entity returned from `#find` **must** have the following attributes:
+
+| Attribute | Type | Description | Example |
+| --------- | ---- | ----------- | ------- |
+| `name` | string | Short, unique name of a single Component Service | `apidemo` |
+| `description` | string | Non-empty descriptive text for the Component Service | `The API Demo Component Service` |
+| `api_versions` | array of object | Array of one or more API Version descriptor entities (see table below) |
+
+The Repository **must** return one or more API Version descriptor entities in the `api_versions` attribute above. In the event that a Component Service with the requested name nominally exists but has no API Versions preferably available, the Repository's `#find` method **must** return an **empty* array result.
+
+Each API Version descriptor entities **must** have attributes as follows:
+
+| Attribute | Type | Description | Example |
+| --------- | ---- | ----------- | ------- |
+| `base_url` | string | Service Base URL for this specific API Version of this specific Component Service. | `http://example.com:9876/api/` |
+| `content_type` | string | MIME content type sent in `Accept` header to explicitly specify this specific API Version of this specific Component Service. | `application/vnd.examplecorp.apidemo.v1+json` |
+| `restricted` | Boolean | Reserved for future use. Must be `false`. | `false` |
+| `deprecated` | Boolean | Reserved for future use. Must be `false`. | `false` |
+
+## Error Reporting
+
+If the attempt to retrieve information from the Repository using the value passed in the `service_name` parameter is unsuccessful, then the `ServiceComponentDescriber` will abort the Rack request processing, returning an HTTP status code [404](https://httpstatuses.com/404) (*Not Found*), with a response body that simply contains the text, *Service not found: "bad-service-name"*.
+
+# The `AcceptContentTypeSelector` Middleware Component
+
+The `AcceptContentTypeSelector` middleware component
+
+1. parses the JSON encoded into the `COMPONENT_DESCRIPTION` value by the `ServiceComponentDescriber` middleware component;
+2. parses and interprets the requested API Version as specified by the Content Type specified in the `Accept` HTTP header (available in the Rack environment at `HTTP_ACCEPT`);
+	1. if a suitable API Version is identified, encodes that API Version's details into a new `COMPONENT_API_VERSION_DATA` entry in the Rack environment;
+	2. if no suitable API Version is identified, returns a Rack response with status code [406](https://httpstatuses.com/406) (*Not Acceptable*), and a message body enumerating the Content Type values which would have resulted in a successful request for the Component Service in question;
+3. unless aborted with an error, proceeds on to the next component in the Rack middleware chain.
+
+## Inputs from Rack Environment
+
+The `AcceptContentTypeSelector` middleware component requires two entries to be set in the Rack environment (the `env` passed into its `#call` method).
+
+The `COMPONENT_DESCRIPTION` value contains a JSON-serialised object describing a Component Service and the API Versions presently operational and available for that Service. This is ordinarily set by the [`ServiceComponentDescriber`](#the-servicecomponentdescriber-middleware-component) component described above.
+
+The `HTTP_ACCEPT` value represents the standard `Accept` header used for HTTP content negotiation. It will normally have one or more segments of the format
+
+> `application/vnd.COMPANYORORG.APINAME.vSTR+json`
+
+where
+
+* `vnd` is a conventional abbreviation for "vendor"; i.e., for an application content type that is not part of the HTTP or related IETF Standards;
+* `COMPANYORORG` is the name of the company or organisation responsible for maintaining the application on whose behalf the Content Type is used. In our documentation for this gem, we have been using the example `acme`, for [Acme Corporation](https://en.wikipedia.org/wiki/Acme_Corporation);
+* `APINAME` is the name of the application programming interface (or *API*) which these middleware components are being used to support. In the documentation for this Gem, we have been using the example `apidemo`, for the *API Demo Component Service*; and
+* `STR` is an API-unique version identifier. Conventionally, and as demonstrated in this documentation, this has been an integer (which would presumably increment for each successive API Version release), giving an example such as `v1` or `v472`. In practice, it can be virtually *any* string-representable application-unique identifier; for those using [Semantic Versioning](http://semver.org), you might have an example such as `v1.0.0` or `v42.6.4-pre71`. As long as the version identifier is meaningful to you and your development team, it should be useable here.
+
+
+## Error Reporting
+
+The middleware component will abort processing of the request and return an HTTP error under any of the following conditions:
+
+* An HTTP [400](https://httpstatuses.com/400) (*Bad Request*) will be returned if there is no defined `COMPONENT_DESCRIPTION` value or if that value does not contain valid [Repository](#the-repository) data in JSON format with at least one API Version defined; or
+* An HTTP [406](https://httpstatuses.com/406) (*Not Acceptable*) will be returned if the API Version specifier in the `HTTP_ACCEPT` environment value does not match any API Versions reported as supported by parsing the `COMPONENT_DESCRIPTION` environment value.
+
+# The `ApiVersionRedirector` Middleware Component
+
+The `ApiVersionRedirector` middleware component parses the JSON encoded in the `COMPONENT_API_VERSION_DATA` value by the `AcceptContentTypeSelector` middleware component. It then builds a Rack response with
+
+* the status code [307](https://httpstatuses.com/307) (*Temporary Redirect*);
+* body content containing the markup `Please resend the request to <a href="LOCATION">LOCATION</a> without caching it.`, where `LOCATION` is replaced by the value of the `Location` header (see the next item); and
+* headers for
+  * `API-Version`, with a value of the API Version used to match the request (e.g., `v1` or `v2.14.6`); and
+  * `Location`, with a value of the full URL for the API Version-specific request as supplied to the AVIDA, including path information and query parameters, if any.
+
+## Error Reporting
+
+**None.** If the `COMPONENT_DESCRIPTION` entry in the Rack environment is missing, or is invalidly formatted, then this middleware component *will* fail. Adding error detection and reporting similar to that of [`AcceptContentTypeSelector`](#the-servicecomponentdescriber-middleware-component), above, *but* the question may reasonably be asked, *how useful would that be in practice?* If these three components are always used together in the correct sequence, then there should be no possible error path for this middleware component; if an error is encountered in operation, that is a strong indication that the *use* of the middleware in that particular AVIDA is incorrect.
+
+# Feasible Future Features
+
+1. The initial release of this Gem itself uses no encryption; if HTTPS rather than HTTP is used between Component Services, that would provide an increased level of security. HTTPS, however, is not presently **required,** but is **recommended.** An imminent future release is being considered which would use the [RbNaCl](https://github.com/cryptosphere/rbnacl) library's support for [public-key encryption](https://github.com/cryptosphere/rbnacl/wiki/SimpleBox#public-key-encryption-with-simplebox) to secure and authenticate HTTP payloads and, where practical, message data.
+2. Despite the explanation given for the deliberate omission of error reporting in the `ApiVersionRedirector` middleware component (immediately above), some intrepid soul may choose to implement it anyway. (It's open source; it's a platform for learning experiences.)
+3. Some misadventurous developer may choose to implement the three existing middleware components *as a single, unified component.* We considered that approach during initial development, and abandoned it because we strongly feel that the "boilerplate" of including two "extra" middleware components is *far* outweighed by the inner complexity that such a unified component would contain, and the likelihood that any future change would have effects beyond the intended change. ([SOLID](https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)) *is* a thing, you know.)
+
+## Other Ideas?
+
+Do you see something we missed that you'd find useful? Open an [issue and PR](https://github.com/jdickey/rack-service_api_versioning/#contributing) and let's have a chat about it!

data/doc/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers 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, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at jdickey@seven-sigma.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/