stitches 3.0.0

data/lib/stitches/api_key.rb

@@ -0,0 +1,59 @@
+require_relative 'whitelisting_middleware'
+
+module Stitches
+  # A middleware that requires an API key for certain transactions, and makes its id available
+  # in the enviornment for controllers.
+  #
+  # This follows http://www.ietf.org/rfc/rfc2617.txt for use of custom authorization methods, namely
+  # the specification of an API key.
+  #
+  # Apps are expected to set the Authorization header (available to Rack apps as the environment
+  # variable HTTP_AUTHORIZATION) to
+  #
+  #     MyInternalRealm key=<<api key>>
+  #
+  # where MyInternalRealm is the value returned by Stitches.configuration.custom_http_auth_scheme and
+  # <<api key>> is the UUID provided to the caller.  It's expected that there is an entry
+  # in the API_CLIENTS table with this value for "key".
+  #
+  # If that is the case, env[Stitches.configuration.env_var_to_hold_api_client_primary_key] will be the primary key of the
+  # ApiClient that it maps to.
+  class ApiKey < Stitches::WhitelistingMiddleware
+
+    def initialize(app,options = {})
+      super(app,options)
+      @realm = Rails.application.class.parent.to_s
+    end
+
+  protected
+
+    def do_call(env)
+      authorization = env["HTTP_AUTHORIZATION"]
+      if authorization
+        if authorization =~ /#{@configuration.custom_http_auth_scheme}\s+key=(.*)\s*$/
+          key = $1
+          client = ::ApiClient.where(key: key).first
+          if client.present?
+            env[@configuration.env_var_to_hold_api_client_primary_key] = client.id
+            @app.call(env)
+          else
+            UnauthorizedResponse.new("key invalid",@realm,@configuration.custom_http_auth_scheme)
+          end
+        else
+          UnauthorizedResponse.new("bad authorization type",@realm,@configuration.custom_http_auth_scheme)
+        end
+      else
+        UnauthorizedResponse.new("no authorization header",@realm,@configuration.custom_http_auth_scheme)
+      end
+    end
+
+  private
+
+    class UnauthorizedResponse < Rack::Response
+      def initialize(reason,realm,custom_http_auth_scheme)
+        super("Unauthorized - #{reason}", 401, { "WWW-Authenticate" => "#{custom_http_auth_scheme} realm=#{realm}" })
+      end
+    end
+
+  end
+end

data/lib/stitches/api_version_constraint.rb

@@ -0,0 +1,32 @@
+module Stitches
+  # A routing constraint to route versioned requests to the right controller.
+  # This allows you to organize your code around version numbers without requiring that clients
+  # put version numbers in their URLs.  It's expected that you've set up ValidMimeType
+  # as a middleware to ensure these numbers exist
+  #
+  # Example
+  #
+  #    namespace :api do
+  #      scope module: :v1, constraints: Stitches::ApiVersionConstraint.new(1) do
+  #        resource 'ping', only: [ :create ]
+  #      end
+  #      scope module: :v2, constraints: Stitches::ApiVersionConstraint.new(2) do
+  #        resource 'ping', only: [ :create ]
+  #      end
+  #    end
+  #
+  # This will route requests with ;version=1 to +Api::V1::PingsController+, while those
+  # with ;version=2 will go to +Api::V2::PingsController+.
+  #
+  class ApiVersionConstraint
+    def initialize(version)
+      @version = version
+    end
+
+    def matches?(request)
+      request.headers.fetch(:accept).include?("version=#{@version}")
+    rescue KeyError
+      false
+    end
+  end
+end

data/lib/stitches/configuration.rb

@@ -0,0 +1,77 @@
+module Stitches
+end
+
+class Stitches::Configuration
+
+  def initialize
+    reset_to_defaults!
+  end
+
+  # Mainly for testing, this resets all configuration to the default value
+  def reset_to_defaults!
+    @whitelist_regexp = nil
+    @custom_http_auth_scheme = UnsetString.new("custom_http_auth_scheme")
+    @env_var_to_hold_api_client_primary_key = NonNullString.new("env_var_to_hold_api_client_primary_key","STITCHES_API_CLIENT_ID")
+  end
+
+  # A RegExp that whitelists URLS around the mime type and api key requirements.
+  # nil means that ever request must have a proper mime type and api key.
+  attr_reader :whitelist_regexp
+  def whitelist_regexp=(new_whitelist_regexp)
+    unless new_whitelist_regexp.nil? || new_whitelist_regexp.is_a?(Regexp)
+      raise "whitelist_regexp must be a Regexp, not a #{new_whitelist_regexp.class}"
+    end
+    @whitelist_regexp = new_whitelist_regexp
+  end
+
+  # The name of your custom http auth scheme.  This must be set, and has no default
+  def custom_http_auth_scheme
+    @custom_http_auth_scheme.to_s
+  end
+
+  def custom_http_auth_scheme=(new_custom_http_auth_scheme)
+    @custom_http_auth_scheme = NonNullString.new("custom_http_auth_scheme",new_custom_http_auth_scheme)
+  end
+
+  # The name of the environment variable that the ApiKey middleware should use to 
+  # place the primary key of the authenticated ApiKey.  For example, if a user provides
+  # the api key 1234-1234-1234-1234, and that maps to the primary key 42 in your database,
+  # the environment will contain "42" in the key provided here.
+  def env_var_to_hold_api_client_primary_key
+    @env_var_to_hold_api_client_primary_key.to_s
+  end
+
+  def env_var_to_hold_api_client_primary_key=(new_env_var_to_hold_api_client_primary_key)
+    @env_var_to_hold_api_client_primary_key = NonNullString.new("env_var_to_hold_api_client_primary_key",new_env_var_to_hold_api_client_primary_key)
+  end
+
+private
+
+  class NonNullString
+    def initialize(name,string)
+      unless string.nil? || string.is_a?(String)
+        raise "#{name} must be a String, not a #{string.class}"
+      end
+      if String(string).strip.length == 0
+        raise "#{name} may not be blank"
+      end
+      @string = string
+    end
+
+    def to_s
+      @string
+    end
+    alias :to_str :to_s
+  end
+
+  class UnsetString
+    def initialize(name)
+      @name = name
+    end
+
+    def to_s
+      raise "You must set a value for #{@name} "
+    end
+    alias :to_str :to_s
+  end
+end

data/lib/stitches/error.rb

@@ -0,0 +1,9 @@
+module Stitches
+  class Error
+    attr_reader :code, :message
+    def initialize(code:, message:)
+      @code    = code
+      @message = message
+    end
+  end
+end

data/lib/stitches/errors.rb

@@ -0,0 +1,101 @@
+module Stitches
+  # A container for error messages you intend to send as a response to an API request.
+  # The canonical error format is a list of all errors that occured, with each error consistent of a code
+  # (useful for programmatic logic based on error condition) and a message (useful for displaying to
+  # either a log or a human, as documented by the API).
+  #
+  # The general usage of this is:
+  #
+  #     type.json do
+  #       render json: {
+  #           errors: Stitches::Errors.new([
+  #             Stitches::Error.new(code: "name_required", message: "The name is required")
+  #             Stitches::Error.new(code: "numeric_age", message: "The age should be a number")
+  #           ])
+  #         },
+  #         status: 404
+  #     end
+  #
+  # More likely, you will create these from an exception or from an ActiveRecord::Base.
+  #
+  # == Exceptions
+  #
+  # If you create exceptions for the various known errors in your app, you can rely
+  # on the logic in +from_exception+ to generate your code and message.
+  #
+  #     rescue BadPaymentTypeError => ex
+  #       Stitches::Errors.from_exception(ex)
+  #     end
+  #
+  # This will create an errors array with one element, which is an error with code "bad_payment_type"
+  # and the message of whatever the exception message was.
+  #
+  # So, by judicious use and naming of your exceptions, you could do something like this in your controller:
+  #
+  #     rescue_from MyAppSpecificExceptionBase do |ex|
+  #       render json: { errors: Stitches::Errors.from_exception(ex) }, status: 400
+  #     end
+  #
+  # And the codes will match the hierarchy of exceptions inheriting from +MyAppSpecificExceptionBase+.
+  #
+  # == ActiveRecord
+  #
+  # You can also create errors from an ActiveRecord object:
+  #
+  #     person = Person.create(params)
+  #     if person.valid?
+  #       render json: { person: person }, status: 201
+  #     else
+  #       render json: { errors: Stitches::Errors.from_active_record_object(person)
+  #     end
+  #
+  # This will create one error for each field of the main object.  The code will be "field_invalid" and
+  # the message will a comma-joined list of what's wrong with that field, e.g. "Amount can't be blank, Amount must be a number".
+  #
+  # Remember, for APIs, you don't want to send bad user data directly to the API, so this mechanism isn't designed for form fields and
+  # all the other things Rails gives you.  It's for the API client to be able to tell the programmer what went wrong.
+  class Errors
+    include Enumerable
+
+    def self.from_exception(exception)
+      code = exception.class.name.underscore.gsub(/_error$/,'')
+      self.new([
+        Error.new(
+          code: code,
+          message: exception.message
+        )
+      ])
+    end
+
+    def self.from_active_record_object(object)
+      errors = object.errors.to_hash.map { |field,errors|
+        code = "#{field}_invalid".parameterize
+        message = if object.send(field).respond_to?(:errors)
+                    object.send(field).errors.full_messages.sort.join(', ')
+                  else
+                    object.errors.full_messages_for(field).sort.join(', ')
+                  end
+        Stitches::Error.new(code: "#{field}_invalid".parameterize, message: message)
+      }
+      self.new(errors)
+    end
+
+    def initialize(individual_errors)
+      @individual_errors = individual_errors
+    end
+
+    def size
+      @individual_errors.size
+    end
+
+    def each
+      if block_given?
+        @individual_errors.each do |error|
+          yield error
+        end
+      else
+        @individual_errors.each
+      end
+    end
+  end
+end

data/lib/stitches/generator_files/app/controllers/api.rb

@@ -0,0 +1,2 @@
+module Api
+end

data/lib/stitches/generator_files/app/controllers/api/api_controller.rb

@@ -0,0 +1,19 @@
+class Api::ApiController < ActionController::Base
+  rescue_from ActiveRecord::RecordNotFound do |exception|
+    respond_to do |type|
+      type.json { render json: { errors: Stitches::Errors.new([ Stitches::Error.new(code: "not_found", message: exception.message) ]) }, status: 404 }
+      type.all  { render :nothing => true, :status => 404 }
+    end
+  end
+
+  def current_user
+    api_client
+  end
+
+protected
+
+  def api_client
+    @api_client ||= ::ApiClient.find(request.env[Stitches.configuration.env_var_to_hold_api_client_primary_key])
+  end
+
+end

data/lib/stitches/generator_files/app/controllers/api/v1.rb

@@ -0,0 +1,2 @@
+module Api::V1
+end

data/lib/stitches/generator_files/app/controllers/api/v1/pings_controller.rb

@@ -0,0 +1,20 @@
+class Api::V1::PingsController < Api::ApiController
+
+  def create
+    respond_to do |format|
+      format.json do
+        if ping_params[:error]
+          render json: { errors: Stitches::Errors.new([ Stitches::Error.new(code: "test", message: ping_params[:error]) ])} , status: 422
+        else
+          render json: { ping: { status: "ok" } }, status: (ping_params[:status] || "201").to_i
+        end
+      end
+    end
+  end
+
+private
+
+  def ping_params
+    params.permit(:error, :status)
+  end
+end

data/lib/stitches/generator_files/app/controllers/api/v2.rb

@@ -0,0 +1,2 @@
+module Api::V2
+end

data/lib/stitches/generator_files/app/controllers/api/v2/pings_controller.rb

@@ -0,0 +1,20 @@
+class Api::V2::PingsController < Api::ApiController
+
+  def create
+    respond_to do |format|
+      format.json do
+        if ping_params[:error]
+          render json: { errors: Stitches::Errors.new([ Stitches::Error.new(code: "test", message: ping_params[:error]) ])} , status: 422
+        else
+          render json: { ping: { status_v2: "ok" } }, status: (ping_params[:status] || "201").to_i
+        end
+      end
+    end
+  end
+
+private
+
+  def ping_params
+    params.permit(:error, :status)
+  end
+end

data/lib/stitches/generator_files/app/models/api_client.rb

@@ -0,0 +1,2 @@
+class ApiClient < ActiveRecord::Base
+end

data/lib/stitches/generator_files/config/initializers/stitches.rb

@@ -0,0 +1,14 @@
+require 'stitches'
+
+Stitches.configure do |configuration|
+  # Regexp of urls that do not require ApiKeys or valid, versioned mime types
+  configuration.whitelist_regexp = %r{\A/(resque|docs|assets)(\Z|/.*\Z)}
+
+  # Name of the custom Authorization scheme.  See http://www.ietf.org/rfc/rfc2617.txt for details,
+  # but generally should be a string with no spaces or special characters.
+  configuration.custom_http_auth_scheme = "CustomKeyAuth"
+
+  # Env var that gets the primary key of the authenticated ApiKey
+  # for access in your controllers, so they don't need to re-parse the header
+  # configuration.env_var_to_hold_api_client_primary_key = "YOUR_ENV_VAR"
+end

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

@@ -0,0 +1,11 @@
+class CreateApiClients < ActiveRecord::Migration
+  def change
+    create_table :api_clients do |t|
+      t.string :name, null: false
+      t.column :key, "uuid default uuid_generate_v4()", null: false
+      t.column :created_at, "timestamp with time zone default now()", null: false
+    end
+    add_index :api_clients, [:name], unique: true
+    add_index :api_clients, [:key], unique: true
+  end
+end

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

@@ -0,0 +1,5 @@
+class EnableUuidOsspExtension < ActiveRecord::Migration
+  def change
+    enable_extension 'uuid-ossp'
+  end
+end

data/lib/stitches/generator_files/lib/tasks/generate_api_key.rake

@@ -0,0 +1,10 @@
+desc "Generates a new API Key.  Requires a name, e.g. rake generate_api_key[YOUR_APP_NAME_HERE]"
+task :generate_api_key, [:name] => :environment do |t, args|
+  fail "You must provide a name" unless args.name
+  api_client = ::ApiClient.create!(name: args.name)
+  api_client.reload
+  puts "Your key is #{api_client.key}"
+  puts
+  puts "You can test it via curl:"
+  puts "curl -v -X POST -H 'Accept: application/json; version=1' -H 'Content-type: application/json; version=1' -H 'Authorization: CustomKeyAuth key=#{api_client.key}' https://your_app.herokuapp.com/api/ping"
+end

data/lib/stitches/generator_files/spec/acceptance/ping_v1_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+require 'rspec_api_documentation/dsl'
+
+resource "Ping (V1)" do
+  include ApiClients
+  header "Accept", "application/json; version=1"
+  header "Content-Type", "application/json; version=1"
+
+  post "/api/ping" do
+    response_field :ping, "The name of the ping", "Type" => "Object"
+    response_field :status, "The status of the ping", scope: "ping", "Type" => "String"
+    example "ping the server to validate your client's happy path" do
+
+      header "Authorization", "CustomKeyAuth key=#{api_client.key}"
+      do_request
+
+      result = JSON.parse(response_body)
+      expect(result).to eq({ "ping" =>  { "status" => "ok" }})
+
+      status.should == 201
+
+    end
+  end
+  post "/api/ping" do
+    parameter :error, "If set, will return an error instead of ok", "Type" => "Object"
+
+    response_field :errors, "Array of errors", "Type" => "Array"
+    response_field :code, "Programmer key describing the error (useful for logic)", scope: "errors", "Type" => "String"
+    response_field :message, "Human-readable error message", scope: "errors", "Type" => "String"
+
+    let(:error) { "OH NOES!" }
+    let(:raw_post) { params.to_json }
+
+    example "ping the server to validate your client's error handling" do
+
+      header "Authorization", "CustomKeyAuth key=#{api_client.key}"
+      do_request
+
+      result = JSON.parse(response_body)
+      expect(result).to eq({ "errors" => [ { "code" => "test", "message" => "OH NOES!" }]})
+
+      status.should == 422
+
+    end
+  end
+end