stitches 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92db17e3cd6257c963b095a50458cfd637a259cf
-  data.tar.gz: 1671aa6e97c74fd316d3e3882062bd82c6a72e4c
+  metadata.gz: 62009fed84cc0754e785017cc928284f840b63fd
+  data.tar.gz: 4284223ca7d0b02b50de0ec7aed0027a85cd9f20
 SHA512:
-  metadata.gz: f6fa15947f707659a8395c34509be4f314265665311f99aa925c43d26d7a40ee78a56eedcb1605b7c9a2dabb3532244c7dabcb1c9afd0161dedceb2cb9bad6ac
-  data.tar.gz: db499c16dfb16a95bc605b91904918562164d838a6cc3b4c6a644768bb0d78a98f4f5839d61b37db222f048725eb7ef225b3bba1ff380c70c46d98852c9346d0
+  metadata.gz: b69a8d5c5bc964c70902d0becb072d69af02ed587e9b593ae972bc5df32baa3d9203aadf425791047527f68a9ced87d4f02b0f02eba51871e46604dbf63969fd
+  data.tar.gz: e375f477cf060d106d42ba8a5ff3644e70dd75c515c7840b68c1010e58aaeedcd16ac73089ccf45479abbbc623c6aa64c4b97ddb66247c2234407051b6c8807f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stitches (3.4.0)
+    stitches (3.5.0)
       apitome
       pg
       rails
@@ -11,39 +11,39 @@ PATH
 GEM
   remote: https://www.rubygems.org/
   specs:
-    actioncable (5.1.0)
-      actionpack (= 5.1.0)
+    actioncable (5.1.3)
+      actionpack (= 5.1.3)
       nio4r (~> 2.0)
       websocket-driver (~> 0.6.1)
-    actionmailer (5.1.0)
-      actionpack (= 5.1.0)
-      actionview (= 5.1.0)
-      activejob (= 5.1.0)
+    actionmailer (5.1.3)
+      actionpack (= 5.1.3)
+      actionview (= 5.1.3)
+      activejob (= 5.1.3)
       mail (~> 2.5, >= 2.5.4)
       rails-dom-testing (~> 2.0)
-    actionpack (5.1.0)
-      actionview (= 5.1.0)
-      activesupport (= 5.1.0)
+    actionpack (5.1.3)
+      actionview (= 5.1.3)
+      activesupport (= 5.1.3)
       rack (~> 2.0)
       rack-test (~> 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.1.0)
-      activesupport (= 5.1.0)
+    actionview (5.1.3)
+      activesupport (= 5.1.3)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activejob (5.1.0)
-      activesupport (= 5.1.0)
+    activejob (5.1.3)
+      activesupport (= 5.1.3)
       globalid (>= 0.3.6)
-    activemodel (5.1.0)
-      activesupport (= 5.1.0)
-    activerecord (5.1.0)
-      activemodel (= 5.1.0)
-      activesupport (= 5.1.0)
+    activemodel (5.1.3)
+      activesupport (= 5.1.3)
+    activerecord (5.1.3)
+      activemodel (= 5.1.3)
+      activesupport (= 5.1.3)
       arel (~> 8.0)
-    activesupport (5.1.0)
+    activesupport (5.1.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (~> 0.7)
       minitest (~> 5.1)
@@ -56,49 +56,49 @@ GEM
     builder (3.2.3)
     concurrent-ruby (1.0.5)
     diff-lcs (1.3)
-    erubi (1.6.0)
+    erubi (1.6.1)
     globalid (0.4.0)
       activesupport (>= 4.2.0)
-    i18n (0.8.1)
-    kramdown (1.13.2)
+    i18n (0.8.6)
+    kramdown (1.14.0)
     loofah (2.0.3)
       nokogiri (>= 1.5.9)
-    mail (2.6.5)
+    mail (2.6.6)
       mime-types (>= 1.16, < 4)
     method_source (0.8.2)
     mime-types (3.1)
       mime-types-data (~> 3.2015)
     mime-types-data (3.2016.0521)
-    mini_portile2 (2.1.0)
-    minitest (5.10.1)
+    mini_portile2 (2.2.0)
+    minitest (5.10.3)
     mustache (1.0.5)
-    nio4r (2.0.0)
-    nokogiri (1.7.1)
-      mini_portile2 (~> 2.1.0)
-    pg (0.20.0)
-    rack (2.0.2)
+    nio4r (2.1.0)
+    nokogiri (1.8.0)
+      mini_portile2 (~> 2.2.0)
+    pg (0.21.0)
+    rack (2.0.3)
     rack-test (0.6.3)
       rack (>= 1.0)
-    rails (5.1.0)
-      actioncable (= 5.1.0)
-      actionmailer (= 5.1.0)
-      actionpack (= 5.1.0)
-      actionview (= 5.1.0)
-      activejob (= 5.1.0)
-      activemodel (= 5.1.0)
-      activerecord (= 5.1.0)
-      activesupport (= 5.1.0)
-      bundler (>= 1.3.0, < 2.0)
-      railties (= 5.1.0)
+    rails (5.1.3)
+      actioncable (= 5.1.3)
+      actionmailer (= 5.1.3)
+      actionpack (= 5.1.3)
+      actionview (= 5.1.3)
+      activejob (= 5.1.3)
+      activemodel (= 5.1.3)
+      activerecord (= 5.1.3)
+      activesupport (= 5.1.3)
+      bundler (>= 1.3.0)
+      railties (= 5.1.3)
       sprockets-rails (>= 2.0.0)
-    rails-dom-testing (2.0.2)
-      activesupport (>= 4.2.0, < 6.0)
-      nokogiri (~> 1.6)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
     rails-html-sanitizer (1.0.3)
       loofah (~> 2.0)
-    railties (5.1.0)
-      actionpack (= 5.1.0)
-      activesupport (= 5.1.0)
+    railties (5.1.3)
+      actionpack (= 5.1.3)
+      activesupport (= 5.1.3)
       method_source
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
@@ -124,7 +124,7 @@ GEM
       rspec-mocks (~> 3.6.0)
       rspec-support (~> 3.6.0)
     rspec-support (3.6.0)
-    rspec_api_documentation (4.9.0)
+    rspec_api_documentation (5.0.0)
       activesupport (>= 3.0.0)
       mustache (~> 1.0, >= 0.99.4)
       rspec (~> 3.0)
@@ -135,7 +135,7 @@ GEM
       actionpack (>= 4.0)
       activesupport (>= 4.0)
       sprockets (>= 3.0.0)
-    thor (0.19.4)
+    thor (0.20.0)
     thread_safe (0.3.6)
     tzinfo (1.2.3)
       thread_safe (~> 0.1)
@@ -151,4 +151,4 @@ DEPENDENCIES
   stitches!
 
 BUNDLED WITH
-   1.14.6
+   1.15.3

data/README.md

@@ -1,12 +1,16 @@
-You'll be in stitches at how easy it is to get your API service up and running!
+Create Microservices in Rails by pretty much just writing regular Rails code.
 
 ![build status](https://travis-ci.org/stitchfix/stitches.svg?branch=master)
 
 This gem provides:
 
-* Rails plugin to handle api key and versioned requests
-* Generator to get you set up and validate your API before you write any code
-* Spec helpers to use when building your API
+* transparent API key authentication.
+* router-level API version based on headers.
+* a way to document your microservice endpoints via acceptance tests.
+* structured errors, buildable from invalid Active Records, Exceptions, or by hand.
+
+This, plus much of what you get from Rails already, means you can create a microservice Rails application by just writing the
+same Rails code you write today.  Instead of rendering web views, you render JSON (which is built into Rails).
 
 ## To install
 
@@ -16,218 +20,80 @@ Add to your `Gemfile`:
 gem 'stitches'
 ```
 
-Then of course:
+Then:
 
 ```
 bundle install
 ```
 
-If your app is brand new or you don't already have rspec or Apitome, be sure to run those generators and set them up first. You can skip this if you've done either of these before:
-
-```
-rails generate rspec:install
-rails generate apitome:install
-```
-
-Then, run the Stitches generator:
-
-```
-rails g stitches:api
-```
-
-Run database migrations (do `rake db:create` first if you haven't yet set up a database)
-
-```
-rake db:migrate
-```
-
-### Upgrading from older verison of Stitches
-
-If you have used stitches before the `enabled` field was added to `ApiClients`, you need to add that field to your database.  You can do this by running
-the included generator:
-
-```
-rails g stitches:add_enabled_to_api_clients
-```
-
-And then:
-
-```
-rake db:migrate
-```
-
-## Test the install
-
-In your app run:
-
-```
-rake generate_api_key[some_name_you_pick]
-```
-
-Then follow the instructions it outputs.
-
-If you are doing this locally and get an error like the following:
-
-> WEBrick::HTTPStatus::LengthRequired
-
-that's because WEBrick doesn't want an empty body. Throw on a `-d ''` to the end of the command.
-
-## Rails Plugin
-
-Just using this gem will get you:
-
-* Middleware that requires an api key in the request.  See `Stitches::ApiKey`.
-* Middleware that requires a versioned JSON mime type.  We aren't using version numbers in the URLs but putting versions in the `Accept` header.  See `Stitches::ValidMimeType`.
-* Monkeypatch ActiveSupport's `TimeWithZone` to use ISO8601 UTC as the encoding for all timestamps.  This ensures that every JSON response is using the same timezone and can be parsed properly with JavaScript.
-* `Error` and `Errors` objects for creating error reponses that will be rendered properly in API responses.  These can work with exceptions, ActiveRecord objects, or whatever you like.
-
-The plugin works in conjunction with other pieces of this gem set up by using the generator.
-
-### A word on errors
-
-The error format generated by `Errors` and friends is designed for two purposes:
-
-* provide a "programmer key" upon which logic can be based for each error
-* provide a message to explain the error to the programmer and, in times of desperation, the user
-
-The idea is that the caller should not have made a call that generates an error, although this isn't always 100% possible to avoid.  As such, the error messages that come back are not as "rich" as you might get
-from ActiveRecord.  APIs aren't intended to be used for validating user input.  The messages are aimed at a programmer trying to understand why a call failed.
-
-## Generator
-
-When you run the generator via `rails g stitches:api`, you'll get a lot of handy setup done for you:
-
-* Two "ping" controllers that do nothing but respond to requests.  This are useful when creating an API client or when validating
-a deployed instance, as they will succeed when all the moving parts are working, but won't actually hit a database or depend on
-any particular business logic.
-* Routes configured using `Stitches::ApiVersionConstraint` to route to your ping controllers based on the version in
-the `Accept` header.  This allows your api client to fully validate that it's using the versioning system properly.
-* An `ApiClient` model and migration for your database.  This additionally sets up UUID support in Postgres.
-* An `api_spec.rb` spec that will spin up your application and check that all the RESTful/HTTP stuff is working as designed.
-* A means to write API documentation via [rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation), and serve it nicely via [apitome](https://github.com/modeset/apitome).  You write tests using a slightly modified DSL that allows you to document the API.  The produced documentation shows the headers and wire formats with your test data.
-
-Once this is done, you can (and possibly should) deploy your app to validate everything's working before you get too into your
-business logic.
-
-Once you start writing your app, there's a few spec helpers available.
-
-## Generator-provided tests
-
-The generator will provide some tests for your app to test a base level of functionality. To use them, add the Capybara gem to your app:
-
-```
-gem 'capybara'
-```
-
-And in your `spec_helper.rb`:
+Then, set it up:
 
-```ruby
-require 'capybara/rails'
 ```
-
-## Spec Helpers
-
-```ruby
-# in your spec_helper.rb
-require 'stitches/spec'
+> bin/rails generate rspec:install
+> bin/rails generate apitome:install
+> bin/rails generate stitches:api
+> bundle exec rake db:migrate
 ```
 
-### `have_api_error` 
-
-This can be used in a feature spec on a response object to check that the error format is in our "canonical" format, which is as
-follows:
-
-```json
-{
-  "errors": [
-    {
-      "code": "some_code",
-      "message": "some readable message"
-    },
-    {
-      "code": "some_other_code",
-      "message": "some other readable message"
-    }
-    # etc.
-  ]
-}
-```
+## Example Microservice Endpoint
 
-To assert this in your specs:
+Suppose we wish to allow our consumers to create Widgets
 
 ```ruby
-expect(response).to have_api_error(status: 404,
-                                   code: "not_found",
-                                   message: "the exact error message")
-
-# regexps also work
-expect(response).to have_api_error(status: 404,
-                                   code: "name_invalid",
-                                   message: /can't be blank/)
-```
-
-Omitting `status` will use a default of 422, which is Rails' default for validation errors.
-
-### `be_iso8601_utc_encoded`
-
-This can be used to ensure that your JSON-encoded timestamps meet the recommended format of IS8601 UTC-encoded strings.
-
-```ruby
-expect(json["created_at"]).to be_iso8601_utc_encoded
-```
-
-### `TestHeaders`
-
-This class is useful when creating headers in feature specs that will conform to what's needed by the API you are building.
-The generated `api_spec.rb` is a complete example, but here's a sampling:
-
-```ruby
-# Create headers for a version 2 request
-headers = TestHeaders.new(version: 2)
-post "/api/ping", {}.to_json, headers.headers
-
-# Create headers that have the wrong mime type in them
-headers = TestHeaders.new(mime_type: "application/foobar")
-post "/api/ping", {}.to_json, headers.headers
+class Api::V1::WidgetsController < ApiController
+  def create
+    widget = Widget.create(widget_params)
+    if widget.valid?
+      head 201
+    else
+      render json: { 
+        errors: Stitches::Errors.from_active_record(widget) 
+      }, status: 422
+    end
+  end
+
+private
+
+  def widget_params
+    params.require(:widget).permit(:name, :type, :sub_type)
+  end
+end
 ```
 
-### `ApiClients` module
+If you think there's nothing special about this—you are correct.  This is the vanillaest of vanilla Rails controllers, with a few
+notable exceptions:
 
-Mixing this in provides the method `api_client` that will return the one api client.  This is because fixtures have been so flaky
-in our tests, and factories don't always work for stuff like this.  Also, why require the use of factories?
+* We aren't checking content type.  A stitches-based microservice always uses JSON and refuses to route requests for non-JSON to
+you, so there's zero need to use `respond_to` and friends.
+* The error-building is structured and reliable.
+* This is an authenticated request.  No request without proper authentication will be routed here, so you don't have to worry
+about it in your code.
+* This is a versioned request.  While the URL will *not* contain `v1` in it, the `Accept` header will require a version and get
+routed here.  If you make a V2, it's just a new controller and this concern is handled at the routing layer.
 
-## Configuration
+All this means that the Rails skills of you and your team can be directly applied to building microservices.  You don't have to make a bunch of boring decisions about auth, versioning, or content-types.  It also means you can start deploying and creating microservices with little friction.  No need to deal with a complex DSL or new programming language to get yourselves going with Microservices.
 
-You'll see in the initializer that you can configure aspects of the library globally.  `Stitches::Configuration` documents the available
-options.
+## More Info
 
-## Avoiding auto-magical Set-up
+See [the wiki](https://github.com/stitchfix/stitches/wiki/Setup) for how to setup stitches.
 
-Instead of requiring `stitches`, you can avoid the railtie and configure things yourself:
+* [Stitches Features](https://github.com/stitchfix/stitches/wiki/Features-of-Stitches) include:
+  - Authorization via API key
+  - Versioned requests via HTTP content types
+  - Structured Errors
+  - ISO 8601-formatted dates
+* The [Generator](https://github.com/stitchfix/stitches/wiki/Generator) sets up some code in your app, so you can start writing
+APIs using vanilla Rails idioms:
+  - a "ping" controller that can vaidate your app is working
+  - version routing based on content-type (requests for V2 use the same URL, but are serviced by a different controller)
+  - An ApiClient Active Record
+  - Acceptance tests that can produce API documentation as they test your app.
+* Stitches provides [testing support](https://github.com/stitchfix/stitches/wiki/Testing)
 
-```
-# Gemfile
-gem 'stitches', require: false
-
-# config/initializers/stitches.rb
-require 'stitches_norailtie'
-
-Stitches.configure do |config|
-  config.whatever = :foo
-end
-
-# config/application.rb
-config.app_middleware.use Stitches::ApiKey, except: %r{/super-secret}
-config.app_middleware.use Stitches::ValidMimeType, except: %r{/super-secret}
-# or whatever you want to do
-```
 
 ## Developing
 
-Although `Stitches.configuration` is global, do not depend directly on that in your logic.  Instead, allow all classes to receive a
-configuration object in their constructor.  This makes the classes easier to deal with and change, without incurring much of a real cost to development.
-Global symbols suck, but are convienient.  This is how you make the most of it.
-
+Although `Stitches.configuration` is global, do not depend directly on that in your logic.  Instead, allow all classes to receive a configuration object in their constructor.  This makes the classes easier to deal with and change, without incurring much of a real cost to development.  Global symbols suck, but are convienient.  This is how you make the most of it.
 
 ---
 

data/lib/stitches/errors.rb

@@ -46,7 +46,7 @@ module Stitches
   #     if person.valid?
   #       render json: { person: person }, status: 201
   #     else
-  #       render json: { errors: Stitches::Errors.from_active_record_object(person)
+  #       render json: { errors: Stitches::Errors.from_active_record_object(person) }, status: 422
   #     end
   #
   # This will create one error for each field of the main object.  The code will be "field_invalid" and
@@ -98,4 +98,4 @@ module Stitches
       end
     end
   end
-end
+end

data/lib/stitches/generator_files/db/migrate/add_enabled_to_api_clients.rb

@@ -1,4 +1,8 @@
+<% if Rails::VERSION::MAJOR >= 5 %>
+class AddEnabledToApiClients < ActiveRecord::Migration[<%= Rails::VERSION::MAJOR %>.<%= Rails::VERSION::MINOR %>]
+<% else %>
 class AddEnabledToApiClients < ActiveRecord::Migration
+<% end %>
   def change
     add_column :api_clients, :enabled, :bool, null: false, default: true
     remove_index :api_clients, [:name ] # existing one would be unique

data/lib/stitches/generator_files/db/migrate/create_api_clients.rb

@@ -1,4 +1,8 @@
+<% if Rails::VERSION::MAJOR >= 5 %>
+class CreateApiClients < ActiveRecord::Migration[<%= Rails::VERSION::MAJOR %>.<%= Rails::VERSION::MINOR %>]
+<% else %>
 class CreateApiClients < ActiveRecord::Migration
+<% end %>
   def change
     create_table :api_clients do |t|
       t.string :name, null: false

data/lib/stitches/generator_files/db/migrate/enable_uuid_ossp_extension.rb

@@ -1,4 +1,8 @@
+<% if Rails::VERSION::MAJOR >= 5 %>
+class EnableUuidOsspExtension < ActiveRecord::Migration[<%= Rails::VERSION::MAJOR %>.<%= Rails::VERSION::MINOR %>]
+<% else %>
 class EnableUuidOsspExtension < ActiveRecord::Migration
+<% end %>
   def change
     enable_extension 'uuid-ossp'
   end

data/lib/stitches/version.rb

@@ -1,3 +1,3 @@
 module Stitches
-  VERSION = '3.4.0'
+  VERSION = '3.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stitches
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Stitch Fix Engineering
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-09 00:00:00.000000000 Z
+date: 2017-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails