maitre_d 0.0.1 → 0.1.0

data/HISTORY

@@ -1,2 +1,5 @@
+0.1.0 - January 11th 2012
+* Tentative Heroku support.
+
 0.0.1 - December 27th 2011
 * Initial release - nothing particularly functional, just claiming the name on rubygems.org.

data/README.textile

@@ -2,6 +2,127 @@ h1. Maître d'
 
 Rack APIs powered by Grape for managing Heroku and Opperator add-ons. If used within a Rails application, it'll automatically be mounted as a Rails engine at the appropriate paths.
 
+Maître d' manages all the authorisation checking for API requests and provides simple hooks for you to write just the code you need to handle provisioning, plan changes, deprovisioning and single-sign-on (SSO) requests.
+
+h2. Installing
+
+h3. With Rails
+
+Because there's a Rails engine as part of Maître d', the API routing is set up automatically. Jump forward to the configuration and listener setup below.
+
+h3. Without Rack
+
+This library provides two APIs as mountable Rack applications for you - so you'll want to mount them at the appropriate paths: @MaitreD::Heroku::API@ at @/heroku@, and/or @MaitreD::Opperator::API@ at @/opperator@.
+
+h2. Configuration
+
+You'll need to provide Maître d' with the appropriate provider credentials - in a Rails app, this would go in an initializer, but for Rack/Sinatra apps just get the values set before the routing is defined.
+
+<pre><code>MaitreD::Heroku.configure do |config|
+  config.id       = 'addon-id'
+  config.password = 'random'
+  config.sso_salt = 'gibberish'
+  config.listener = HerokuListener
+end
+
+MaitreD::Opperator.configure do |config|
+  config.shared_secret = 'something-special'
+  config.listener      = OpperatorListener
+end</code></pre>
+
+The listeners that are mentioned in the code above are classes, which will handle valid API requests. Read on for more details on how to set them up.
+
+h2. Heroku Listener
+
+Your Heroku listener class should be a subclass of @MaitreD::Heroku::Listener@, and handle the following four methods:
+
+h3. @provision(heroku_id, plan, callback_url, logplex_token, options)@
+
+This gets called when Heroku's requesting an app be provisioned within your service, and expects a hash to be returned with the following keys:
+
+<dl>
+  <dt><code>id</code></dt>
+  <dd>Your local resource id, which Heroku will use in related requests (to change plans, deprovision or initialise single-sign-on).</dd>
+  <dt><code>config</code></dt>
+  <dd>A hash of the newly provisioned resource's configuration values (that are provided as environment variables to the app in question).</dd>
+  <dt><code>message</code></dt>
+  <dd>An optional message that will be displayed when your add-on is added via the command-line.</dd>
+</dl>
+
+h3. @plan_change(resource_id, heroku_id, plan)@
+
+This gets called when an app is upgrading or downgrading from their current plan. You need to return a hash with the following keys:
+
+<dl>
+  <dt><code>config</code></dt>
+  <dd>A hash of the modified resource's configuration values (that are provided as environment variables to the app in question).</dd>
+  <dt><code>message</code></dt>
+  <dd>An optional message that will be displayed when an app using your add-on is upgraded or downgraded via the command-line.</dd>
+</dl>
+
+h3. @deprovision(resource_id)@
+
+This gets called when an app is removing your add-on from itself. You don't have to return anything in particular for this, though Heroku may pass through the @message@ argument like it does for the @provision@ and @plan_change@ calls.
+
+h3. @single_sign_on(resource_id)@
+
+Maître d' will check the token and timestamp provided, and sets up the nav-data cookie, but you'll need to decide where the user gets redirected to and what other details you wish to track via their session. To do this, just return a hash with the following keys:
+
+<dl>
+  <dt><code>uri</code></dt>
+  <dd>The URI to redirect the user to, now that you've signed them in.</dd>
+  <dt><code>session</code></dt>
+  <dd>A hash of any session values you wish to be set.</dd>
+</dl>
+
+Here's a very basic example:
+
+<pre><code>class HerokuListener < MaitreD::Heroku::Listener
+  def provision(heroku_id, plan, callback_url, logplex_token, options)
+    plan   = Plan.find_by_name plan
+    widget = Widget.create(
+      :heroku_id    => heroku_id,
+      :callback_url => callback_url,
+      :plan         => plan
+    )
+
+    {
+      :id      => widget.id,
+      :config  => {'WIDGET_KEY' => widget.key},
+      :message => 'Add-on provisioned!'
+    }
+  end
+
+  def plan_change(resource_id, heroku_id, plan)
+    plan   = Plan.find_by_name plan
+    widget = Widget.find resource_id
+    widget.plan = plan
+    widget.save
+
+    {:config => {'WIDGET_KEY' => widget.key}}
+  end
+
+  def deprovision(resource_id)
+    widget = Widget.find resource_id
+    widget.destroy
+  end
+
+  def single_sign_on(resource_id)
+    widget = Widget.find resource_id
+
+    {
+      :uri     => '/my/dashboard',
+      :session => {:widget_id => widget.id}
+    }
+  end
+end</code></pre>
+
+You can have the listener class wherever you like - as long as it's available within the context of your Rails/Rack site, it'll work as expected.
+
+h2. Opperator Listener
+
+This listener is currently in progress as the Opperator API is established.
+
 h2. Contributing
 
 Contributions are very much welcome - but keep in mind the following:

data/Rakefile

@@ -1 +1 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'

data/addon-manifest.json

@@ -0,0 +1,10 @@
+{
+  "id": "foo",
+  "api": {
+    "config_vars": [ "FOO_PROVISIONED" ],
+    "password": "bar",
+    "sso_salt": "sea salt",
+    "production": "https://yourapp.com/",
+    "test": "http://localhost:9292/"
+  }
+}

data/config/routes.rb

@@ -1,3 +1,4 @@
 Rails.application.routes.draw do
+  mount MaitreD::Heroku::API    => '/heroku'
   mount MaitreD::Opperator::API => '/opperator'
 end

data/lib/maitre_d/heroku/api.rb

@@ -0,0 +1,42 @@
+class MaitreD::Heroku::API < Grape::API
+  helpers MaitreD::Heroku::APIHelpers
+
+  resources :resources do
+    get ':id' do
+      error!('403 Forbidden', 403) unless valid_token? && valid_timestamp?
+
+      hash = MaitreD::Heroku.listener.new.single_sign_on(params[:id])
+
+      hash[:session] ||= {}
+      hash[:session].each { |key, value| session[key] = value }
+
+      status 302
+      header 'Location', hash[:uri]
+      Rack::Utils.set_cookie_header! header, 'heroku-nav-data',
+        :value => params['nav-data']
+    end
+
+    post do
+      authenticate!
+
+      MaitreD::Heroku.listener.new.provision(
+        params[:heroku_id],     params[:plan], params[:callback_url],
+        params[:logplex_token], params[:options]
+      )
+    end
+
+    put ':id' do
+      authenticate!
+
+      MaitreD::Heroku.listener.new.plan_change(
+        params[:id], params[:heroku_id], params[:plan]
+      )
+    end
+
+    delete ':id' do
+      authenticate!
+
+      MaitreD::Heroku.listener.new.deprovision params[:id]
+    end
+  end
+end

data/lib/maitre_d/heroku/api_helpers.rb

@@ -0,0 +1,36 @@
+module MaitreD::Heroku::APIHelpers
+  def authenticate!
+    error!('401 Unauthorized', 401) unless valid_authorization?
+  end
+
+  def session
+    env['rack.session']
+  end
+
+  def valid_timestamp?
+    params[:timestamp].to_i >= (Time.now - 5*60).to_i
+  end
+
+  def valid_token?
+    expected_token == params[:token]
+  end
+
+  private
+
+  def expected_token
+    @expected_token ||= Digest::SHA1.hexdigest(
+      "#{params[:id]}:#{MaitreD::Heroku.sso_salt}:#{params[:timestamp]}"
+    ).to_s
+  end
+
+  def valid_authorization?
+    valid_authorization.strip == env['HTTP_AUTHORIZATION'].strip
+  end
+
+  def valid_authorization
+    encoded_authorization = Base64.encode64(
+      "#{MaitreD::Heroku.id}:#{MaitreD::Heroku.password}"
+    )
+    "Basic #{encoded_authorization}"
+  end
+end

data/lib/maitre_d/heroku/listener.rb

@@ -0,0 +1,17 @@
+class MaitreD::Heroku::Listener
+  def provision(heroku_id, plan, callback_url, logplex_token, options)
+    #
+  end
+
+  def plan_change(resource_id, heroku_id, plan)
+    #
+  end
+
+  def deprovision(resource_id)
+    #
+  end
+
+  def single_sign_on(resource_id)
+    #
+  end
+end

data/lib/maitre_d/heroku.rb

@@ -0,0 +1,41 @@
+module MaitreD::Heroku
+  def self.configure
+    yield self
+  end
+
+  def self.listener
+    @listener
+  end
+
+  def self.listener=(listener)
+    @listener = listener
+  end
+
+  def self.id
+    @id
+  end
+
+  def self.id=(id)
+    @id = id
+  end
+
+  def self.password
+    @password
+  end
+
+  def self.password=(password)
+    @password = password
+  end
+
+  def self.sso_salt
+    @sso_salt
+  end
+
+  def self.sso_salt=(salt)
+    @sso_salt = salt
+  end
+end
+
+require 'maitre_d/heroku/api_helpers'
+require 'maitre_d/heroku/api'
+require 'maitre_d/heroku/listener'

data/lib/maitre_d/opperator/api.rb

@@ -5,15 +5,15 @@ class MaitreD::Opperator::API < Grape::API
 
   resources :instances do
     post do
-      MaitreD::Opperator.subscribe params[:features]
+      MaitreD::Opperator.listener.new.provision params[:features]
     end
 
     delete ':id' do
-      # MaitreD::Opperator.cancel params[:id]
+      MaitreD::Opperator.listener.new.deprovision params[:id]
     end
 
     put ':id' do
-      # MaitreD::Opperator.update params[:id], params[:features]
+      MaitreD::Opperator.listener.new.change_plan params[:id], params[:features]
     end
   end
 

data/lib/maitre_d/opperator/listener.rb

@@ -0,0 +1,13 @@
+class MaitreD::Opperator::Listener
+  def provision(features)
+    #
+  end
+
+  def deprovision(resource_id)
+    #
+  end
+
+  def change_plan(resource_id, features)
+    #
+  end
+end

data/lib/maitre_d/opperator.rb

@@ -1,4 +1,16 @@
 module MaitreD::Opperator
+  def self.configure
+    yield self
+  end
+
+  def self.listener
+    @listener
+  end
+
+  def self.listener=(listener)
+    @listener = listener
+  end
+
   def self.shared_secret
     @shared_secret
   end
@@ -6,14 +18,8 @@ module MaitreD::Opperator
   def self.shared_secret=(secret)
     @shared_secret = secret
   end
-
-  def self.subscribe(features = {})
-    {
-      'id'      => '321',
-      'config'  => {}
-    }
-  end
 end
 
 require 'maitre_d/opperator/api_helpers'
 require 'maitre_d/opperator/api'
+require 'maitre_d/opperator/listener'

data/lib/maitre_d/version.rb

@@ -1,3 +1,3 @@
 module MaitreD
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/lib/maitre_d.rb

@@ -3,6 +3,7 @@ require 'grape'
 module MaitreD
 end
 
+require 'maitre_d/heroku'
 require 'maitre_d/opperator'
 require 'maitre_d/version'
 

data/maitre_d.gemspec

@@ -1,6 +1,6 @@
 # -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "maitre_d/version"
+$:.push File.expand_path('../lib', __FILE__)
+require 'maitre_d/version'
 
 Gem::Specification.new do |s|
   s.name        = 'maitre_d'
@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ['lib']
 
+  s.add_development_dependency 'kensa',       '1.3.0'
   s.add_development_dependency 'rails',       '3.1.3'
   s.add_development_dependency 'rspec-rails', '2.7.0'
 end

data/spec/api/heroku/provisioning_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+
+describe 'Heroku Provisioning API' do
+  let(:authorisation) { "Basic #{Base64.encode64('foo:bar')}" }
+  let(:json_response) { JSON.parse response.body }
+
+  describe 'Provisioning' do
+    let(:params) {
+      {
+        :plan         => 'basic',
+        :callback_url => 'https://domain/vendor/apps/app123%40heroku.com',
+        :heroku_id    => 'app123@heroku.com'
+      }
+    }
+
+    it "returns a 401 if the HTTP authorisation does not match" do
+      post '/heroku/resources', params,
+        {'HTTP_AUTHORIZATION' => 'Basic foobarbaz'}
+
+      response.status.should == 401
+    end
+
+    it "returns the resource id" do
+      post '/heroku/resources', params, {'HTTP_AUTHORIZATION' => authorisation}
+
+      json_response['id'].should == '123'
+    end
+
+    it "returns the resource configuration" do
+      post '/heroku/resources', params, {'HTTP_AUTHORIZATION' => authorisation}
+
+      json_response['config'].should == {'FOO_PROVISIONED' => "true"}
+    end
+
+    it "returns a custom message" do
+      post '/heroku/resources', params, {'HTTP_AUTHORIZATION' => authorisation}
+
+      json_response['message'].should == 'Add-on provisioned!'
+    end
+  end
+
+  describe 'Changing Plans' do
+    let(:params) {
+      {:heroku_id => 'app123@heroku.com', :plan => 'premium'}
+    }
+
+    it "returns a 401 if the HTTP authorisation does not match" do
+      put '/heroku/resources/7', params,
+        {'HTTP_AUTHORIZATION' => 'Basic foobarbaz'}
+
+      response.status.should == 401
+    end
+
+    it "returns the new resource configuration" do
+      put '/heroku/resources/7', params, {'HTTP_AUTHORIZATION' => authorisation}
+
+      json_response['config'].should == {'FOO_PROVISIONED' => "false"}
+    end
+
+    it "returns a custom message" do
+      put '/heroku/resources/7', params, {'HTTP_AUTHORIZATION' => authorisation}
+
+      json_response['message'].should == 'Add-on upgraded or downgraded.'
+    end
+  end
+
+  describe 'Deprovisioning' do
+    it "returns a 401 if the HTTP authorisation does not match" do
+      delete '/heroku/resources/28', {},
+        {'HTTP_AUTHORIZATION' => 'Basic foobarbaz'}
+
+      response.status.should == 401
+    end
+
+    it "returns with a status of 200" do
+      delete '/heroku/resources/28', {}, {'HTTP_AUTHORIZATION' => authorisation}
+
+      response.status.should == 200
+    end
+
+    it "returns a custom message" do
+      delete '/heroku/resources/28', {}, {'HTTP_AUTHORIZATION' => authorisation}
+
+      json_response['message'].should == 'Add-on removed.'
+    end
+  end
+end

data/spec/api/heroku/single_sign_on_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+describe 'Heroku SSO API' do
+  let(:timestamp) { Time.now.to_i }
+  let(:nav_data)  { 'heroku-nav-data-goes-here' }
+  let(:token)     {
+    pre_token = "789:sea salt:#{timestamp.to_s}"
+    Digest::SHA1.hexdigest(pre_token).to_s
+  }
+
+  it "renders a 403 if the token is incorrect" do
+    get '/heroku/resources/789', :token => 'foo',
+      :timestamp => timestamp, 'nav-data' => nav_data
+
+    response.status.should == 403
+  end
+
+  it "renders a 403 if the timestamp is older than 5 minutes" do
+    timestamp = 5.minutes.ago.to_i - 1
+    pre_token = "789:sea salt:#{timestamp.to_s}"
+    token     = Digest::SHA1.hexdigest(pre_token).to_s
+
+    get '/heroku/resources/789', :token => token,
+      :timestamp => timestamp, 'nav-data' => nav_data
+
+    response.status.should == 403
+  end
+
+  it "sets the heroku nav data cookie" do
+    get '/heroku/resources/789', :token => token,
+      :timestamp => timestamp, 'nav-data' => nav_data
+
+    cookies['heroku-nav-data'].should == nav_data
+  end
+
+  it "redirects to the appropriate URL" do
+    get '/heroku/resources/789', :token => token,
+      :timestamp => timestamp, 'nav-data' => nav_data
+
+    response.should redirect_to('/my/dashboard')
+  end
+  
+  it "should set the provided session variables" do
+    get '/heroku/resources/789', :token => token,
+      :timestamp => timestamp, 'nav-data' => nav_data
+    
+    session[:app_id].should == '789'
+  end
+end

data/spec/api/opperator/provisioning_spec.rb

@@ -22,7 +22,7 @@ describe 'Opperator Provisioning API' do
       post '/opperator/instances', {'features' => {}},
         {'X-Opperator-Shared-Secret' => 'something-special'}
 
-      json_response['config'].should be_a(Hash)
+      json_response['config'].should == {'provisioned_for' => 'opperator'}
     end
   end
 

data/spec/internal/app/listeners/heroku_listener.rb

@@ -0,0 +1,29 @@
+class HerokuListener < MaitreD::Heroku::Listener
+  def provision(heroku_id, plan, callback_url, logplex_token, options)
+    {
+      :id      => '123',
+      :config  => {'FOO_PROVISIONED' => 'true'},
+      :message => 'Add-on provisioned!'
+    }
+  end
+
+  def plan_change(resource_id, heroku_id, plan)
+    {
+      :config  => {'FOO_PROVISIONED' => 'false'},
+      :message => 'Add-on upgraded or downgraded.'
+    }
+  end
+
+  def deprovision(resource_id)
+    {
+      :message => 'Add-on removed.'
+    }
+  end
+
+  def single_sign_on(resource_id)
+    {
+      :uri     => '/my/dashboard',
+      :session => {:app_id => resource_id}
+    }
+  end
+end

data/spec/internal/app/listeners/opperator_listener.rb

@@ -0,0 +1,16 @@
+class OpperatorListener < MaitreD::Opperator::Listener
+  def provision(features)
+    {
+      'id'      => '321',
+      'config'  => {'provisioned_for' => 'opperator'}
+    }
+  end
+  
+  def deprovision(resource_id)
+    #
+  end
+
+  def change_plan(resource_id, features)
+    #
+  end
+end

data/spec/internal/config/initializers/heroku.rb

@@ -0,0 +1,6 @@
+MaitreD::Heroku.configure do |config|
+  config.id       = 'foo'
+  config.password = 'bar'
+  config.sso_salt = 'sea salt'
+  config.listener = HerokuListener
+end

data/spec/internal/config/initializers/opperator.rb

@@ -1 +1,4 @@
-MaitreD::Opperator.shared_secret = 'something-special'
+MaitreD::Opperator.configure do |config|
+  config.shared_secret = 'something-special'
+  config.listener      = OpperatorListener
+end

data/spec/internal/config/routes.rb

@@ -0,0 +1,9 @@
+Rails.application.routes.draw do
+  class Dashboard
+    def self.call(env)
+      [200, {'Content-Type' => 'text/plain', 'Content-Length' => '9'},
+        ['Dashboard']]
+    end
+  end
+  match '/my/dashboard' => Dashboard
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: maitre_d
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-27 00:00:00.000000000 Z
+date: 2012-01-11 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: kensa
+  requirement: &70319103578580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - =
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :development
+  prerelease: false
+  version_requirements: *70319103578580
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70351599375300 !ruby/object:Gem::Requirement
+  requirement: &70319103578080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -21,10 +32,10 @@ dependencies:
         version: 3.1.3
   type: :development
   prerelease: false
-  version_requirements: *70351599375300
+  version_requirements: *70319103578080
 - !ruby/object:Gem::Dependency
   name: rspec-rails
-  requirement: &70351599374160 !ruby/object:Gem::Requirement
+  requirement: &70319103577620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -32,7 +43,7 @@ dependencies:
         version: 2.7.0
   type: :development
   prerelease: false
-  version_requirements: *70351599374160
+  version_requirements: *70319103577620
 description: A Rack API (through Grape) for Heroku and Opperator add-on providers
   - which can also be attached as a Rails Engine.
 email:
@@ -47,20 +58,31 @@ files:
 - LICENCE
 - README.textile
 - Rakefile
+- addon-manifest.json
 - config.ru
 - config/routes.rb
 - lib/maitre_d.rb
 - lib/maitre_d/engine.rb
+- lib/maitre_d/heroku.rb
+- lib/maitre_d/heroku/api.rb
+- lib/maitre_d/heroku/api_helpers.rb
+- lib/maitre_d/heroku/listener.rb
 - lib/maitre_d/opperator.rb
 - lib/maitre_d/opperator/api.rb
 - lib/maitre_d/opperator/api_helpers.rb
+- lib/maitre_d/opperator/listener.rb
 - lib/maitre_d/version.rb
 - maitre_d.gemspec
+- spec/api/heroku/provisioning_spec.rb
+- spec/api/heroku/single_sign_on_spec.rb
 - spec/api/opperator/provisioning_spec.rb
+- spec/internal/app/listeners/heroku_listener.rb
+- spec/internal/app/listeners/opperator_listener.rb
+- spec/internal/config/initializers/heroku.rb
 - spec/internal/config/initializers/opperator.rb
+- spec/internal/config/routes.rb
 - spec/internal/log/.gitignore
 - spec/internal/public/favicon.ico
-- spec/spec/internal/log/test.log
 - spec/spec_helper.rb
 homepage: http://github.com/flying-sphinx/maitre_d
 licenses: []
@@ -87,10 +109,15 @@ signing_key:
 specification_version: 3
 summary: Rack API and Rails Engine for Heroku and Opperator add-ons
 test_files:
+- spec/api/heroku/provisioning_spec.rb
+- spec/api/heroku/single_sign_on_spec.rb
 - spec/api/opperator/provisioning_spec.rb
+- spec/internal/app/listeners/heroku_listener.rb
+- spec/internal/app/listeners/opperator_listener.rb
+- spec/internal/config/initializers/heroku.rb
 - spec/internal/config/initializers/opperator.rb
+- spec/internal/config/routes.rb
 - spec/internal/log/.gitignore
 - spec/internal/public/favicon.ico
-- spec/spec/internal/log/test.log
 - spec/spec_helper.rb
 has_rdoc: