Pancake

I’ve been getting some questions lately about what the difference is between generating a “micro” or generating a “short” stack is. So here it is:

Micro: Generates a structure that’s good to use with passenger out of the box
Short: Generates a structure that’s gemmable with Jeweler

They’re both Pancake Short Stacks. A micro just doesn’t have all the files / directories generated. Add them as needed and they’ll work.

Here’s the structures:

∴ pancake-gen micro foo
#snip
∴ tree foo
foo
|-- Rakefile
|-- config.ru
|-- foo.rb
|-- pancake_init.rb
|-- public
|-- tmp
`-- views
    `-- root.html.haml

And for a Short Stack:

∴ pancake-gen short bar
#snip
∴ tree bar
bar
|-- LICENSE
|-- README
|-- Rakefile
|-- VERSION
|-- lib
|   |-- bar
|   |   |-- bar.rb
|   |   |-- config
|   |   |   |-- config.rb
|   |   |   `-- environments
|   |   |       |-- development.rb
|   |   |       |-- production.rb
|   |   |       `-- staging.rb
|   |   |-- config.ru
|   |   |-- models
|   |   |-- mounts
|   |   |-- public
|   |   |-- tasks
|   |   |   `-- bar.rake
|   |   |-- tmp
|   |   `-- views
|   |       `-- root.html.haml
|   `-- bar.rb
|-- pancake_init.rb
`-- spec
    |-- bar_spec.rb
    `-- spec_helper.rb

The “micro” stack has a stack root in “foo/” and the “short” stack has a root at “bar/lib/bar”

This weekend I got to go to Railscamp 6. Railscamp is so much fun. There’s heaps of really cool ruby peeps there. I’d start to name them but there were over 120 people at this one so it may not make for the most interesting read to those who weren’t there.

The reason I’m writing this post though is not about Railscamp itself, but rather the project that I helped hack on. Lincoln Stoll flew all the way from Germany to be at Railscamp. I love catching up with him and as usual, he had plenty of interesting stuff happening. One that really caught my attention was his idea of having a proxy through to CouchDB. We’d love to be able to use CouchDB in applications with some authentication and whilst the Couch team are working on this, we’d still like the auth to come from within the ruby application via Warden or something so we’re not doubling up on auth logic. It’d also be awesome if we can mount couchdb in my applications url space so that we can use couch directly from the browser via ajax in my main application. Something that I’ve actually wanted to do for a while.

So I started hacking on implementing this in Pancake while Lincoln got over his jet lag. When he got up he showed me what he’d done on the plane as a lambda based rack application which sorted the issues I was having, and between the two of use we had a Pancake stack that was proxying to couchdb in pretty short order.

ProxyStack was born.

The first thing to do is get ProxyStack 0.2.0 or greater. It’s on gemcutter so

gem install proxy_stack

should do the job. This should bring in Pancake if you don’t already have it too.

Lets make a simple couchdb proxy from a config.ru file.

echo "require 'rubygems'; require 'proxy_stack'; run ProxyStack.stackup" > config.ru
unicorn -p 5000

Navigate on over to http://localhost:5000/ and http://localhost:5000/_utils to see your couch app proxied through your rubies 😀

That’s kinda cool. We could also mount it at a different url by setting up a container stack and mounting it in there.

require 'rubygems'
require 'proxy_stack'

class ::ProxyContainer < Pancake::Stacks::Short
  router.mount(ProxyStack, "/my_couch")
end

run ProxyContainer.stackup

Restart unicorn (or just use shotgun) and your couchdb is now available at http://localhost:5000/my_couch/ (note the trailing /)

You’ll see that when you mount it away from root, the /_utils resource doesn’t really work. That’s because couch doesn’t know it’s mounted and generates the urls without the mount path appended. That doesn’t matter for what I want though, which is accessing the database itself via json calls.

Now, say we want to augement that so that we have an “/admin/users” resource on our stack. Maybe we want to provide a signup form or something similar, or maybe a login form. You can just add actions to the stack like you normally would. For example, lets inherit the ProxyStack into our own stack, and make some tweaks:

require 'rubygems'
require 'proxy_stack'

class ::MyProxy  < ProxyStack
  get "/admin/users", :name => :admin_users do
    "You're in #{stack_class} at #{url(:admin_users)}"
  end

end

class ::ProxyContainer < Pancake::Stacks::Short

  router.mount(MyProxy, "/my_couch")
end

run ProxyContainer.stackup

You’ll notice that I’m prefixing the class definitions with “::”. This is to put them into the global space. When loading a rackup, they’re loaded into an anonymous class/module. You can get around that by not declaring classes directly in your config.ru file.

Now if you mosey on over to http://localhost:5000/my_couch/admin/users you’ll see the results of the new augmented action on the stack. Neat.

The other thing we wanted to be able to do is authenticate / authorize calls to couchapp from within our proxy. Lets say we’re using Warden for the authentication. We can use a before_proxy hook to add an authenticate! call, allowing a host application to specify what that means, and just using it in our proxy stack.

class ::MyProxy  :admin_users do
    "You're in #{stack_class} at #{url(:admin_users)}"
  end
end 

Here, we’ve added a before hook to show authentication via warden, and also to print out a little message to the log. The hook is run in the action context so it’s like we’re right inside the action. We’re not going to setup warden inside this article so we’ll leave it commented out. You can add as many before_proxy hooks, and after_proxy hooks as you like.

So now we’ve seen it as a raw rack app, inherited into a container app, augmented and authenticated. But what about actually using it in X% of ruby apps… Rails. Well, because it’s rack, you can use it in rails as a metal. Go on over to your application and generate a metal:

script/generate metal proxy_metal

Make sure to require proxy_stack in your environment in config.gem and setup your metal to look like this:

class ProxyMetal
  class MyProxy < ProxyStack
    before_proxy do
      puts "BEFORE PROXY FOR #{stack_class} with #{request.path_info}"
    end
  end

  class CouchProxy    < MyProxy; end

  class ProxyContainer < Pancake::Stacks::Short
    router do |r|
      r.mount(CouchProxy,   "/couchdb")
    end
  end

  def self.call(env)
    @app ||= ProxyContainer.stackup
    @app.call(env)
  end
end

Fire it up and head over to http://localhost:3000/couchdb/ and you’ve got your proxy from within rails. It’s important that you don’t mount it at “/” in rails, otherwise every request will first check couchdb before being passed onto your rails app!

But, why did I put so much cruft into the Rails Metal one? You could have setup the rails metal to be this

class ProxyMetal
  class ProxyContainer < Pancake::Stacks::Short; end
  ProxyContainer.mount(ProxyStack, "/couchdb")
  
  def self.call(env)
    @app ||= ProxyContainer.stackup
    @app
  end
end

but I wanted to demonstrate something else. Proxy stack it turns out, can proxy whatever http request you like. This is for demonstration purposes only however. Before you do this, get permission or own the other site. I take no responsibility for your actions if you decide to try and hijack content, which incidentally, would make you a complete douche bag.

class ProxyMetal
  class MyProxy < ProxyStack
    before_proxy do
      puts "BEFORE PROXY FOR #{stack_class} with #{request.path_info}"
    end
  end

  class CouchProxy    < MyProxy; end
  class TwitterProxy  < MyProxy
    configuration.proxy_domain = "twitter.com"
    configuration.proxy_port      = 80
  end

  class ProxyContainer < Pancake::Stacks::Short
    router do |r|
     r.mount(TwitterProxy, "/twitter_proxy")
     r.mount(CouchProxy,   "/couchdb")
    end
  end

  def self.call(env)
    @app ||= ProxyContainer.stackup
    @app.call(env)
  end
end

Now you have http://twitter.com mounted in your application at http://localhost:3000/twitter_proxy/

One of the useful things about Pancake is that you can inherit your full application. This includes routes, bootloaders, configuration, paths and a few other things I won’t expound heavily on here.

What I want to go through is how to use it. Before we get started, make sure you have at least pancake 0.1.20

Since my initial post, Jack Dempsey has written a small test blog for Pancake. It’s not going to upset wordpress at this point (maybe one day), but it will serve to demonstrate inheriting and mounting gem’d stacks. The test blog stack is at http://github.com/jackdempsey/pancake-blog

Install Pancake-Blog

$ git clone git://github.com/jackdempsey/pancake-blog.git
$ cd pancake-blog
$ gem build blog.gemspec
$ gem install blog-x.x.x.gem

Once we’ve got the blog gem installed in the system, lets do the bare minimum to get it running in a container app. Move to another directory:

$ pancake-gen micro blog_container
$ cd blog_container

In pancake, you can progressively add directories of a larger app and they will just work. Lets setup a config.rb file and include an AR connection.

$ mkdir config
touch config/config.rb

Here’s an example of what you can put in there to get the connection setup.

require 'activerecord'
require 'blog'

ActiveRecord::Base.establish_connection(
  :adapter  => "mysql",
  :username => "root",
  :password => "",
  :host     => "localhost",
  :database => "pancake_blog_development",
  :encoding => "utf8"
)

You’ll notice here that we’ve also included the blog gem. Next lets mount the blog in the application. Lets get the blog_container.rb file looking like this:

class BlogContainer < Pancake::Stacks::Short
  add_root(__FILE__)
  initialize_stack

  router.mount(Blog, "/blog")
end

Initializing the stack will load the config file and mount applications etc. That’s almost it. Before we actually fire it up though, we need to create the database.

$ rake -T
$ rake blog:bootstrap

Pancake will load the rake files from the gem and make them available to you once we’ve mounted the Blog in the router. Now we can start the application 🙂

$ unicorn -p 5000 

Head over to http://localhost:5000/blog and you should see a shiny new blog. Enter a few posts and you can see it’s a very very simple app.

Inheriting Stacks

It’s kinda cool that we can mount an app and stuff. But inheriting full apps could be a bit cooler. Lets get that happening. Lets get the blog_container.rb file looking like this:

class BlogContainer < Pancake::Stacks::Short
  add_root(__FILE__)
  initialize_stack

  get "/" do
    render :root
  end
end

class WagyuBlog     < Blog; end
class VegetableBlog < Blog; end

BlogContainer.router do |r|
  r.mount(WagyuBlog,      "/wagyu")
  r.mount(VegetableBlog,  "/veggies")
end

We’ll also need to add this to the bottom of the config/config.rb file.

Blog.initialize_stack

This makes sure all the models in Blog are loaded before we inherit.

Ok, so lets start up the app again (with unicorn) and head over to http://localhost:5000/wagyu Aaaannnddd… The posts from before have disappeared… That’s actually intentional. It’s done that way in pancake-blog so you can mount multiple blogs in the one process without clashing the posts.
The model Blog::BlogEntry (the post) is inherited along with Blog so we end up with WagyuBlog::BlogEntry and VegetableBlog::BlogEntry. By doing this we’re segregating the data via STI.

Try it… Go to http://localhost:5000/wagyu and make some posts. Now scoot on over to http://localhost:5000/veggies and put in some posts there. Flip about a bit and you’ll see it’s actually separate.

That’s kinda cool, but we can do better. It’s not much good to have them all behaving the same all the time, and having all the stuff in the blog_container.rb file isn’t the most awesome. Lets mount them through the mounts directory. Create a “mounts” directory and a sub-directory for each blog:

$ mkdir -p mounts/wagyu-blog
$ mkdir -p mounts/vegetable-blog

Now, lets make the blog_container.rb file look like this by removing the inherit calls:

class BlogContainer < Pancake::Stacks::Short
  add_root(__FILE__)
  initialize_stack

  router do |r|
    r.mount(WagyuBlog,      "/wagyu")
    r.mount(VegetableBlog,  "/veggies")
  end

  get "/" do
    render :root
  end
end

Now, lets create a pancake_init.rb file in each of the sub-directories in “mounts” In them, we’ll put

# mounts/wagyu-blog/pancake_init.rb
class WagyuBlog < Blog
  add_root(__FILE__)
end

# mounts/vegetable-blog/pancake_init.rb
class VegetableBlog < Blog
  add_root(__FILE__)
end

Start the applciation again. You’ll see that the behavior is the same as doing it the other way. So, what exactly did that buy us? We’ve added a root to each of the blogs. That means we can start tweaking the views and add models / other files etc. We’ll just do one, but it will work for either, or both.

If you look at the pancake-blog source. You’ll see that the view inherits_from :base. Lets replace the base of the wagyu blog. Make a views directory in mounts/wagyu-blog/views and create a base.html.haml file. erb and erubis works just as well. Create your template, remember that you need to create a content block for at least :content (because of the child template in pancake-blog) That means you’ll need something like:

# snip template stuffs
- content_block :content do 
  %p
    No Posts Found

# snip

When you’re playing with templates, it’s a good idea to restart the app with shotgun so that the templates are re-compiled on each request.

shotgun -s thin -p 5000

I’ve made my mounts/waygu-blog/views/base.html.haml look like this:

!!!
%html
  %title A blog about Wagyu

  %body
    %h1 A Blog about Wagyu

    - content_block :content do
      %p
        No Posts Found

    %hr/

    .footer
      Here's My Footer

Not a very dramatic template I know, but you can see that it’s different when you render it. The VegetablesBlog at http://localhost:5000/veggies and see that it’s still the same as it was before we modified the templates for the WagyuBlog.

You can change any and all of the templates as you see fit for each inherited mount individually. You can even add a common root to both of them (or the parent class) and tweak there to have it affect both of them.