spokes 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b2871efe83be8086d0e0117a1e6f941776a364e8
+  data.tar.gz: 5505a9ff74b657dea7d197c109ecb10e6af57f81
+SHA512:
+  metadata.gz: 91e66451fc8794a775362eeda928c5889391294c7c3c954e50ffdaeef2b349759440fd46b956d8276797ecdcfb6c3ccc74093a1d860e0b890b533741d844ae9b
+  data.tar.gz: 3180c2e60f220d3b281460fa0396c32ef8b9350760469ab4020a878715a076e4eb03c329116fa8e9208ff3b420574ad421cc463c1cdbae36d451c5793d0eb7dd

data/.gitignore

@@ -0,0 +1,17 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+.DS_Store
+/.bundle
+/pkg
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp
+/coverage
+/.sass-cache
+Gemfile.lock

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  Excludes:
+    - spec/**/*
+Documentation:
+  Enabled: false
+LineLength:
+  Max: 120
+Metrics/MethodLength:
+  CountComments: false
+  Max: 80
+Metrics/AbcSize:
+  Max: 50

data/.ruby-gemset

@@ -0,0 +1 @@
+spokes

data/.ruby-version

@@ -0,0 +1 @@
+2.2.3

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/README.md

@@ -0,0 +1,137 @@
+
+<img src="https://raw.githubusercontent.com/khaight/spokes/master/logo/spokes_logo.png" alt="Spokes Logo"/>
+
+A set of utilities for helping creating apis
+
+- [Configuration](#configuration)
+- [Middleware](#middleware)
+    - [Health](#health)
+    - [CORS](#cors)
+    - [Service Name](#service_name)
+- [Versioning](#versioning)
+    - [Minor Versioning](#minor-versioning)
+
+## Configuration
+
+Provides an easy to use set of configuration methods to manage environment variables.
+
+Example:
+
+```
+# config/application.rb
+
+Spokes::Config::Env.load do
+  mandatory :homer, string
+  default :krusty, :clown, symbol
+  optional :duffman, boolean
+end
+```
+
+The above example will look for the following environment variables when booting your application as well as try to perform type coercion:
+
+```
+ENV['HOMER'] # will raise KeyError if variable does not exist; will 'cast' value to a string if exists
+
+ENV['KRUSTY'] # will try to 'cast' value to a symbol if exists; otherwise will populate with the default value :clown
+
+ENV['DUFFMAN'] # will try to 'cast' value to a boolean if exists and will do nothing otherwise
+```
+
+## Middleware
+
+### Health
+
+Provides a `/status` endpoint on your API.
+
+#### Installation
+
+Add the following to your Rails project:
+
+```ruby
+# config/application.rb
+class Application < Rails::Application
+    config.middleware.use Spokes::Middleware::Health
+end
+```
+
+#### Configuration Arguments
+
+| name           |  description                                                                                                                            |
+| -------------- |  -----------                                                                                                                            |
+| `fail_if`      |  Mechanism for putting the service into a "failing" state                                                                               |
+| `content_type` |  Establishes content types returned for the different representations of the health response. Requires two keys: `simple` and `details` |
+| `details`      |  Override the body content returned in details view                                                                                     |
+| `status_code`  |  Override the body content returned in simple view                                                                                      |
+| `headers`      |  Override the headers in health responses. Takes `Content-Type` header value as a parameter.                                            |
+
+### CORS
+
+Provides CORS HTTP access control headers in all responses.
+
+#### Installation
+
+Add the following to your Rails project:
+
+```ruby
+# config/application.rb
+class Application < Rails::Application
+    config.middleware.use Spokes::Middleware::CORS
+end
+```
+
+
+#### Installation
+
+Add the following to your Rails project:
+
+```ruby
+# config/application.rb
+class Application < Rails::Application
+    config.middleware.use Spokes::Middleware::OrganizationId
+end
+```
+
+### Service Name
+
+Requires and validates `Service-Name` header in all requests. Appends the current service's name to all outbound
+responses.
+
+#### Installation
+
+Add the following to your Rails project:
+
+```ruby
+# config/application.rb
+class Application < Rails::Application
+    config.middleware.use Spokes::Middleware::ServiceName
+end
+```
+
+## Versioning
+
+### Minor Versioning
+
+Parses the `API-Version` HTTP header and makes it available in controllers via the `minor_version` helper method.
+This concern also adds the `API-Version` header to all outgoing responses.
+
+#### Installation
+
+1. Add the following to your Rails project:
+
+    ```ruby
+    # app/controllers/application_controller.rb
+    class ApplicationController < ActionController::Base
+        include Spokes::Versioning::MinorVersioning
+    end
+    ```
+2. Execute the following in your Rails project's directory:
+
+    ```bash
+    $ bundle exec rake spokes:versioning:setup
+    ```
+3. You'll now have a file created at `config/minor_versions.yml`. Edit this file as needed to set up the default
+   version for your API. Any subsequent versions will be listed there as well.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/khaight/spokes. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/lib/spokes.rb

@@ -0,0 +1,13 @@
+require_relative 'spokes/middleware/concerns/bad_request.rb'
+require_relative 'spokes/middleware/concerns/header_validation.rb'
+
+require_relative 'spokes/middleware/cors.rb'
+require_relative 'spokes/middleware/health.rb'
+require_relative 'spokes/middleware/service_name.rb'
+require_relative 'spokes/middleware/request_id.rb'
+
+require_relative 'spokes/config/env.rb'
+require_relative 'spokes/versioning/minor_versioning.rb'
+
+module Spokes
+end

data/lib/spokes/config/env.rb

@@ -0,0 +1,65 @@
+module Spokes
+  module Config
+    class Env
+      def self.load(&blk)
+        new(&blk)
+      end
+
+      def initialize(&blk)
+        instance_eval(&blk)
+      end
+
+      def mandatory(name, method = nil)
+        value = cast(ENV.fetch(name.to_s.upcase), method)
+        create(name, value)
+      end
+
+      def optional(name, method = nil)
+        value = cast(ENV[name.to_s.upcase], method)
+        create(name, value)
+      end
+
+      def default(name, default, method = nil)
+        value = cast(ENV.fetch(name.to_s.upcase, default), method)
+        create(name, value)
+      end
+
+      def array
+        ->(v) { v.nil? ? [] : v.split(',') }
+      end
+
+      def int
+        ->(v) { v.to_i }
+      end
+
+      def float
+        ->(v) { v.to_f }
+      end
+
+      def bool
+        ->(v) { v.to_s == 'true' }
+      end
+
+      def string
+        nil
+      end
+
+      def symbol
+        ->(v) { v.nil? ? nil : v.to_sym }
+      end
+
+      private
+
+      def cast(value, method)
+        method ? method.call(value) : value
+      end
+
+      def create(name, value)
+        instance_variable_set(:"@#{name}", value)
+        instance_eval "def #{name}; @#{name} end", __FILE__, __LINE__
+        return unless value.is_a?(TrueClass) || value.is_a?(FalseClass) || value.is_a?(NilClass)
+        instance_eval "def #{name}?; !!@#{name} end", __FILE__, __LINE__
+      end
+    end
+  end
+end

data/lib/spokes/middleware/concerns/bad_request.rb

@@ -0,0 +1,22 @@
+require 'multi_json'
+
+module Spokes
+  module Middleware
+    module Concerns
+      module BadRequest
+        def bad_request(errors)
+          errors = [errors] unless errors.is_a?(Array)
+          [400, bad_request_headers, [bad_request_body(errors)]]
+        end
+
+        def bad_request_headers
+          { 'Content-Type' => 'application/json; charset=utf-8' }
+        end
+
+        def bad_request_body(errors)
+          MultiJson.dump(errors: errors)
+        end
+      end
+    end
+  end
+end

data/lib/spokes/middleware/concerns/header_validation.rb

@@ -0,0 +1,23 @@
+module Spokes
+  module Middleware
+    module Concerns
+      module HeaderValidation
+        class NotValid < StandardError; end
+
+        def validate_header_presence(env:, header_name:, message: 'is required')
+          value = env[env_header_name(header_name)]
+          raise NotValid, "#{header_name} #{message}" if value.nil? || value.empty?
+        end
+
+        def validate_header_pattern(env:, header_name:, pattern:, message: 'is invalid')
+          value = env[env_header_name(header_name)]
+          raise NotValid, "#{header_name} #{message}" unless value =~ pattern
+        end
+
+        def env_header_name(name)
+          "HTTP_#{name.upcase.tr('-', '_')}"
+        end
+      end
+    end
+  end
+end

data/lib/spokes/middleware/cors.rb

@@ -0,0 +1,71 @@
+module Spokes
+  module Middleware
+    # Provides CORS HTTP access control.
+    #
+    # Usage:
+    #
+    #   class Application < Rails::Application
+    #     config.middleware.use Spokes::Middleware::CORS
+    #   end
+    #
+    # Example response:
+    #
+    #   $ curl -v -L http://localhost:3000/ -H "Origin: http://elsewhere" -X OPTIONS
+    #   > OPTIONS / HTTP/1.1
+    #   > User-Agent: curl/7.37.1
+    #   > Host: localhost:3000
+    #   > Accept: */*
+    #   > Origin: http://elsewhere
+    #   >
+    #   < HTTP/1.1 200 OK
+    #   < Access-Control-Allow-Origin: http://elsewhere
+    #   < Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
+    #   < Access-Control-Allow-Headers: *, Content-Type, Accept, AUTHORIZATION, Cache-Control
+    #   < Access-Control-Allow-Credentials: true
+    #   < Access-Control-Max-Age: 1728000
+    #   < Access-Control-Expose-Headers: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma
+    #   < Cache-Control: no-cache
+    #   < X-Request-Id: 1d388184-5dd6-4150-bf47-1729f33794ec
+    #   < X-Runtime: 0.001269
+    #   < Transfer-Encoding: chunked
+    #
+    class CORS
+      ALLOW_METHODS  =
+        %w[GET POST PUT PATCH DELETE OPTIONS].freeze
+      ALLOW_HEADERS  =
+        %w[* Content-Type Accept AUTHORIZATION Cache-Control].freeze
+      EXPOSE_HEADERS =
+        %w[Cache-Control Content-Language Content-Type Expires Last-Modified Pragma].freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        # preflight request: render a stub 200 with the CORS headers
+        if cors_request?(env) && env['REQUEST_METHOD'] == 'OPTIONS'
+          [200, cors_headers(env), ['']]
+        else
+          status, headers, response = @app.call(env)
+          headers.merge!(cors_headers(env)) if cors_request?(env)
+          [status, headers, response]
+        end
+      end
+
+      def cors_request?(env)
+        env.key?('HTTP_ORIGIN')
+      end
+
+      def cors_headers(env)
+        {
+          'Access-Control-Allow-Origin'      => env['HTTP_ORIGIN'],
+          'Access-Control-Allow-Methods'     => ALLOW_METHODS.join(', '),
+          'Access-Control-Allow-Headers'     => ALLOW_HEADERS.join(', '),
+          'Access-Control-Allow-Credentials' => 'true',
+          'Access-Control-Max-Age'           => '1728000',
+          'Access-Control-Expose-Headers'    => EXPOSE_HEADERS.join(', ')
+        }
+      end
+    end
+  end
+end

data/lib/spokes/middleware/health.rb

@@ -0,0 +1,79 @@
+module Spokes
+  module Middleware
+    # Provides `/status` route.
+    #
+    # Example setup:
+    #
+    #   class Application < Rails::Application
+    #     config.middleware.use Spokes::Middleware::Health
+    #   end
+    #
+    # Example responses:
+    #
+    #   $ curl -v -L http://localhost:3000/status
+    #   > GET /status HTTP/1.1
+    #   > User-Agent: curl/7.37.1
+    #   > Host: localhost:3000
+    #   > Accept: */*
+    #   >
+    #   < HTTP/1.1 200 OK
+    #   < Content-Type: text/plain
+    #   < Cache-Control: must-revalidate,no-cache,no-store
+    #   < X-Request-Id: 8916fc91-b773-4002-9a9a-59870894715c
+    #   < X-Runtime: 0.001055
+    #   < Transfer-Encoding: chunked
+    #   <
+    #   OK
+    #
+    #   $ curl -v -L http://localhost:3000/status -H "Content-Type: application/json"
+    #   > GET /status HTTP/1.1
+    #   > User-Agent: curl/7.37.1
+    #   > Host: localhost:3000
+    #   > Accept: */*
+    #   > Content-Type: application/json
+    #   >
+    #   < HTTP/1.1 200 OK
+    #   < Content-Type: application/json
+    #   < Cache-Control: must-revalidate,no-cache,no-store
+    #   < X-Request-Id: 0a598c48-ca37-4b61-9677-20d8a8a4d637
+    #   < X-Runtime: 0.001252
+    #   < Transfer-Encoding: chunked
+    #   <
+    #   {"status":"OK"}
+    #
+    class Health
+      PATH = '/status'.freeze
+
+      def initialize(app, options = {})
+        @app = app
+        @options = {
+          content_type: { simple: 'text/plain', details: 'application/json' },
+          fail_if: -> { false },
+          simple: ->(healthy) { healthy ? 'OK' : 'FAIL' },
+          details: ->(healthy) { healthy ? { 'status': 'OK' }.to_json : { 'status': 'FAIL' }.to_json },
+          status_code: ->(healthy) { healthy ? 200 : 503 },
+          headers: lambda do |content_type|
+            { 'Content-Type' => content_type, 'Cache-Control' => 'must-revalidate,no-cache,no-store' }
+          end
+        }.merge(options)
+      end
+
+      def call(env)
+        return @app.call(env) unless env['REQUEST_METHOD'] == 'GET' && env['PATH_INFO'] == PATH
+        healthy = !@options[:fail_if].call
+        status = get_status(env, healthy)
+        [status[:status], status[:headers], status[:body]]
+      end
+
+      private
+
+      def get_status(env, healthy)
+        d = env['CONTENT_TYPE'] == @options[:content_type][:details]
+        body = [@options[(d ? :details : :simple)].call(healthy)]
+        status = @options[:status_code].call(healthy)
+        headers = @options[:headers].call(d ? @options[:content_type][:details] : @options[:content_type][:simple])
+        { body: body, status: status, headers: headers }
+      end
+    end
+  end
+end