Maître d’

Rack APIs powered by Sliver for managing Heroku add-ons.

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.

Installing

Add the following to your Gemfile:

gem 'maitre_d', '~> 0.7.1'

With Rails

Add the Rack app to your routes file:

mount MaitreD::API.new(MaitreD::Heroku) => '/heroku'

Without Rails

As shown above, you can use Maître d’ Rack API, mounting them to wherever you see fit. Once upon a time Heroku expected its endpoints to be at /heroku, but now things are a little more flexible.

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.

require 'maitre_d/heroku'

MaitreD::Heroku.configure do |config|
  config.id       = 'addon-id'
  config.password = 'random'
  config.sso_salt = 'gibberish'
  config.listener = HerokuListener
end

The listener that is mentioned in the code above is a class, which will handle valid API requests. Read on for more details on how to set them up.

Listeners

Your listener class should handle the following four methods:

provision(params)

This gets called when the provider is requesting an app be provisioned within your service, and expects a hash to be returned with the following keys:

id

Your local resource id, which the provider will use in related requests (to change plans, deprovision or initialise single-sign-on).

config

A hash of the newly provisioned resource’s configuration values (that are provided as environment variables to the app in question).

message

An optional message that will be displayed when your add-on is added via the command-line.

plan_change(resource_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:

config

A hash of the modified resource’s configuration values (that are provided as environment variables to the app in question).

message

An optional message that will be displayed when an app using your add-on is upgraded or downgraded via the command-line.

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.

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:

uri

The URI to redirect the user to, now that you’ve signed them in.

session

A hash of any session values you wish to be set.

Here’s a very basic example:

class HerokuListener
  def provision(params)
    plan   = Plan.find_by_name params["plan"]
    widget = Widget.create(
      :heroku_id    => params["uuid"],
      :callback_url => params["callback_url"],
      :plan         => plan,
      :region       => params["region"]
    )

    {
      :id      => widget.id,
      :config  => {'WIDGET_KEY' => widget.key},
      :message => 'Add-on provisioned!'
    }
  end

  def plan_change(resource_id, plan)
    plan   = Plan.find_by_name plan
    widget = Widget.find_by! heroku_id: resource_id
    widget.plan = plan
    widget.save

    {:config => {'WIDGET_KEY' => widget.key}}
  end

  def deprovision(resource_id)
    widget = Widget.find_by! heroku_id: resource_id
    widget.destroy
  end

  def single_sign_on(resource_id)
    widget = Widget.find_by! heroku_id: resource_id

    {
      :uri     => '/my/dashboard',
      :session => {:widget_id => widget.id}
    }
  end
end

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.

Contributing

Contributions are very much welcome – but keep in mind the following:

• Keep patches in a separate branch.
• Write tests for your patches.
• Don’t mess with the version or history file. I’ll take care of that when the patch is merged in.

Credits

Copyright © 2011-2020, Maître d’ is developed and maintained by Pat Allan, and is released under the open MIT Licence.