One of the projects that I have been working on recently had a (fairly common) requirement to paginate a list of news items. The original controller and route looked something like this:

1
2
3
4
5
6
7

App.NewsController = Em.ArrayController.extend
  sortProperties: ['postedAt']
  sortAscending:  false

App.NewsRoute      = Em.Route.extend
  model: ->
    @modelFor('currentUser').get('news')

This is pretty simple, and it’s obviously making use of Ember.SortableMixin to sort each news item in reverse chronological order.

So the first thing we need is a two properties which will specify the current page and the number of items to show per page:

1
2
3
4

App.NewsController = Em.ArrayController.extend
  # ...
  page:           1
  perPage:        25

Straight forward enough. Now we need a computed property that contains only the news items for the current page:

1
2
3
4
5
6
7
8
9

App.NewsController = Em.ArrayController.extend
  # ...
  paginatedContent: (->
    page    = @get('page')
    perPage = @get('perPage')
    start   = (page - 1 ) * perPage
    end     = page * perPage
    @get('content').slice(start, end)
  ).property('content.[]', 'page', 'perPage')

But wait, what’s happened here? We’ve lost our sorting! A quick read of the Em.SortableMixin source shows us that the property arrangedContent is where the sorted contents of our controller are stored, so let’s change our code to use that property instead:

1
2
3
4
5
6
7
8
9

App.NewsController = Em.ArrayController.extend
  # ...
  paginatedContent: (->
    page    = @get('page')
    perPage = @get('perPage')
    start   = (page - 1 ) * perPage
    end     = page * perPage
    @get('arrangedContent').slice(start, end)
  ).property('arrangedContent.[]', 'page', 'perPage')

In order to build our pagination links, we probably want to know how many pages are available also, so let’s add a pages property:

1
2
3
4
5
6
7

App.NewsController = Em.ArrayController.extend
  # ...
  pages: (->
    result = parseInt(@get('content.length') / @get('perPage'))
    ++result if @get('content.length') % @get('perPage') > 0
    result
  ).property('content.[]', 'perPage')

“But James!” you cry, “you forgot to depend on arrangedContent.” Nope. The number of items doesn’t change when the sort order changes, so we forgo the cost of recalculating the number of pages if the controller changes the sort order.

This is pretty cool, but let’s extract this into a mixin so that we can re-use this in other ArrayControllers:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

App.PaginatableMixin = Em.Mixin.create
  paginatedContent: (->
    page    = @get('page')
    perPage = @get('perPage')
    start   = (page - 1 ) * perPage
    end     = page * perPage
    @get('arrangedContent').slice(start, end)
  ).property('arrangedContent.[]', 'page', 'perPage')

  pages: (->
    result = parseInt(@get('content.length') / @get('perPage'))
    ++result if @get('content.length') % @get('perPage') > 0
    result
  ).property('content.[]', 'perPage')

App.NewsController = Em.ArrayController.extend App.PaginatableMixin,
  sortProperties: ['postedAt']
  sortAscending:  false
  page:           1
  perPage:        25

One thing to note about the paginatedContent property is that it might not be very performant on very large collections - because it creates a new array every time the original content is changed. That’s because we’re creating a simple Ember.computed instead of an Ember.arrayComputed to handle adding and removing elements without iterating the entire collection. This functionality will be appearing (alongside a handy paginate() function) soon in an updated version of ember-enumerology as a result of a bunch of peer-coding with David J. Hamilton. Thanks David!

So now we have our pagination taken care of, we need to show our pagination links. This is an excellent use-case for Ember’s Components.

Let’s start by creating a pagination-links component, to house all our controls. First a template using simple Bootstrap controls (templates/components/pagination-links.handlebars):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{{# if showPagination}}
  <div class="pagination pagination-centered">
    <ul>
      <li {{bind-attr class="hasPrevious::disabled"}}>
        <a {{action goToPreviousPage}}>&laquo;</a>
      </li>
      {{#if showBeforeEllipsis}}
        {{pagination-page page=1 currentPage=page}}
        <li class="disabled"><a>&hellip;</a></li>
      {{/if}}
      {{#each pageNumber in visiblePages}}
        {{pagination-page page=pageNumber currentPage=page}}
      {{/each}}
      {{#if showAfterEllipsis}}
        <li class="disabled"><a>&hellip;</a></li>
        {{pagination-page page=lastPage currentPage=page}}
      {{/if}}
      <li {{bind-attr class="hasNext::disabled"}}>
        <a {{action goToNextPage}}>
          &raquo;
        </a>
    </ul>
  </div>
{{/if}}

So, this is pretty straight forward, and we’ve discovered that in order to dry up our template we need an additional component, which I’ve called pagination-page.

At this point I’d like to point out the fact that Ember requires you to to have at least one - in the name of your component, thus we have a component named pagination-links instead of just paginate.

Our pagination-page template looks pretty simple:

1

<a {{action pageClicked}}>{{page}}</a>

Wait, where’s the <li>? We’ll tell our component to call itself li instead of div as having spurious divs lying around will interfere with Bootstrap’s CSS.

1
2
3
4

App.PaginationPageComponent = Em.Component.extend
  isCurrent: (-> @get('currentPage') == @get('page')).property('currentPage', 'page')
  tagName: 'li'
  classNameBindings: 'isCurrent:disabled'

So now our pagination-page component will appear inside an li tag, with a class of disabled if the page we’re linking to is the current page.

Actions triggered on a component do not bubble up. This makes sense from a certain point of view (in that components are actually just views with a little sugar on top), however this certainly violated the principle of least surprise for me.

Since actions don’t bubble from within components, my initial plan of leaving the pageClicked action to the PaginationLinksComponent to deal with won’t work. So we need to teach the PaginationPageComponent how to deal with it:

1
2
3
4
5

App.PaginationPageComponent = Em.Component.extend
  #...
  actions:
    pageClicked: ->
      @get('parentView').send('goToPage', @get('page'))

The trick here is that the enclosing component (in this case pagination-links) is really the parentView of our component, we can call send on it to send an action.

Next lets start implmenting our PaginationLinksComponent. Let’s start by doing the simplest properties first:

1
2
3
4
5

App.PaginationLinksComponent = Em.Component.extend
  hasPrevious:    (-> @get('page') > 1).property('page')
  hasNext:        (-> @get('page') + 1 < @get('pages')).property('page', 'pages')
  showPagination: Em.computed.gt('pages', 1)
  lastPage:       Em.computed.alias('pages')

This is pretty cool. What about visiblePages? This is a slightly complicated function, it needs to:

1. If there are more than five pages, then only show five pages to link to.
2. If there are less than five pages, then only show the pages there are.
3. Center the list of pages around the current page, unless that would show negative page numbers, or numbers greater than the total number of pages.

Let’s give this a go:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

App.PaginationLinksComponent = Em.Component.extend
  # ...
  visiblePages: (->
    pages = @get('pages')
    page  = @get('page')

    # limit the number of pages to five, or the number of pages
    # if that is smaller.
    limit = 5
    limit = pages if pages < 5

    # function to calculate the last page given a start position
    # and a limit
    finish   = (start,limit)-> start + limit - 1

    # start at page - half the limit
    start = page - parseInt(limit / 2)
    # if that puts the last page shown as greater than the number
    # of pages, then move it back to the first start point that
    # doesn't cause an overrun.
    start = pages - limit + 1 if finish(start,limit) > pages
    # force start to the first page if the start is less than 1.
    start = 1 if start < 1

    [start..finish(start,limit)]
  ).property('page', 'pages')

The only other properties we need now are our show{Before,After}Ellipsis properties. These are pretty straight forward now that we know which pages are being shown:

1
2
3
4

App.PaginationLinksComponent = Em.Component.extend
  # ...
  showBeforeElipsis: (-> @get('visiblePages.firstObject') > 3).property('visiblePages.[]')
  showAfterElipsis:  (-> Math.abs(@get('lastPage') - @get('visiblePages.lastObject')) > 2).property('visiblePages.[]', 'lastPage')

Cool, now we can insert our pagination-links component into our news template:

1
2
3
4
5

{{#each newsItem in paginatedContent}}
  {{render news newsItem}}
{{/each}}

{{pagination-links page=page pages=pages}}

Lastly, we need to add actions to our PaginationLinksComponent:

1
2
3
4
5
6
7
8
9
10
11

App.PaginationLinksComponent = Em.Component.extend
  # ...
  actions:
    goToNextPage: ->
      @incrementProperty('controller.page') if @get('hasNext')

    goToPreviousPage: ->
      @decrementProperty('controller.page') if @get('hasPrevious')

    goToPage: (pageNumber)->
      @set('controller.page', pageNumber) if pageNumber >= 1 && pageNumber <= @get('lastPage')

A note on performance: loading a large collection from your server into the client as JSON isn’t going to be terribly performant, and because we’ve not used arrayComputed Ember isn’t able to show incremental results as that data streams in. This solution works fine for smaller datasets, but when the amount of data grows you will need to look at ways of loading the data in a paginated way also. This should be do-able without rewriting any of our pagination code.

Well, we’ve come to the end of our little exploration of building pagination with Ember. There’s been a couple of niggles along the way, but we got there. I hope this comes in handy to others, and I’d love to read any comments you may have.

Several times now I have found myself writing specs with a lot of context blocks to describe various scearios under which a piece of code might be exected. The prototypical example is a controller spec:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# spec/controllers/projects_controller_spec.rb

describe ProjectsController do
  let(:project)    { Fabricate(:project) }
  let(:project_id) { project.id }
  let(:user)       { Fabricate(:confirmed_user) }

  describe '#show' do
    subject { get :show, id: project_id, format: :json; response }

    context "when a user is logged in" do
      before { login user }

      context "and the project exists" do
        context "and the project belongs to the user" do
          before { project.user = user; project.save }

          its(:status) { should eq 200 }
        end

        context "otherwise" do
          its(:status) { should eq 404 }
        end
      end

      context "otherwise" do
        let(:project_id) { MicroToken.generate }

        its(:status) { should eq 404 }
      end
    end

    context "otherwise" do
      context "and the project exists" do
        context "and the project belongs to someone" do
          before { project.user = user; project.save }

          its(:status) { should eq 404 }
        end

        context "otherwise" do
          its(:status) { should eq 200 }
        end
      end

      context "otherwise" do
        let(:project_id) { MicroToken.generate }

        its(:status) { should eq 404 }
      end
    end
  end
end

There are two main decisions - is there a logged in user? If so then we apply a different criteria for locating and returning the requested resource.

This is a reasonably clear specification, however the repeated use of context hinders readability. Don’t be afraid to patch RSpec with a few extra context methods to improve readability:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# spec/support/context_helpers.rb

module ContextHelpers
  def When(msg,&block)
    context("When#{left_pad msg}", &block)
  end

  def Otherwise(msg,&block)
    context("Otherwise#{left_pad msg}", &block)
  end

  def And(msg,&block)
    context("And#{left_pad msg}", &block)
  end

  private

  def left_pad(msg)
    msg ? " #{msg}" : ""
  end
end

1
2
3
4
5
6
7

# spec/spec_helper.rb

Dir[Rails.root.join("spec/support/**/*.rb")].each {|f| require f}

RSpec.configure do |config|
  config.extend ContextHelpers
end

With these helpers in place we can now drastically improve readability of our tests:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# spec/controllers/projects_controller_spec.rb

describe ProjectsController do
  let(:project)    { Fabricate(:project) }
  let(:project_id) { project.id }
  let(:user)       { Fabricate(:confirmed_user) }

  describe '#show' do
    subject { get :show, id: project_id, format: :json; response }

    When "a user is logged in" do
      before { login user }

      And "the project exists" do
        And "the project belongs to the user" do
          before { project.user = user; project.save }

          its(:status) { should eq 200 }
        end

        Otherwise do
          its(:status) { should eq 404 }
        end
      end

      Otherwise do
        let(:project_id) { MicroToken.generate }

        its(:status) { should eq 404 }
      end
    end

    Otherwise do
      And "the project exists" do
        And "the project belongs to someone" do
          before { project.user = user; project.save }

          its(:status) { should eq 404 }
        end

        Otherwise do
          its(:status) { should eq 200 }
        end
      end

      Otherwise do
        let(:project_id) { MicroToken.generate }

        its(:status) { should eq 404 }
      end
    end
  end
end

Now, I know that not everyone is going to be super pleased with this idea. I think I am probably expressing a deep preference for BDD-style testing. Regardless, I am keen to hear feedback about this style of testing from both Rubyists and non-Rubyists alike.

I seem to spend a lot of time writing code in my Ember apps that looks a lot like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

App.CommentController = Em.ArrayController.extend

  numberOfComments: (-> @get('content.length') ).property('content.[]')

  byPopularity: (->
    # Have to manually implement our compare function because by default
    # JavaScript compares lexigraphically.
    @get('content').sort (a,b)->
      if a.get('upVotes') > b.get('upVotes')
        1
      else if a.get('upVotes') < b.get('upVotes')
        -1
      else
        0
  ).property('content.@each.upVotes')

i.e. manipulating and filtering collections of data in computed properties, so I thought it would be cool if there was a more composable way of creating these chains for computed properties.

Enter ember-enumerology, a small library to do just this. It let’s you write the following code:

1
2
3

App.CommentController = Em.ArrayController.extend
  numberOfComments: Enumerology.create('content').length().finalize()
  byPopularity:     Enumerology.create('content').sortNumericallyBy('upVotes').finalize()

Which seems like a pretty clear win for composition and reusability to me.

I’ve been writing a lot of JavaScript lately (actually, CoffeeScript, but thats beside the point). The things that threw me when I first learned JavaScript late last century was… well everything actually. When I learned JavaScript my previous programming experience was BASIC, Pascal, C and Perl. All of which are basically proceedural languages (don’t get me started on perl’s bless function). Thus, I spent a lot of time (like a decade!) not understanding JavaScript’s object model, or closures.

Over the last few years I’ve been rediscovering the joy of programming in JavaScript that I first felt back when it was called LiveScript and we could actually dynamically change the contents of the page in a limited way. These days I bring with me a much better understanding of OO and Functional principals as well as JavaScript’s take on these.

One of the things I have always loved about Ruby is the way that you can bend it to your will, no matter how insane that will may be. So yesterday while I was in the shower I suddenly wondered how hard it would be to get Ruby to behave as it if had a prototypical object model and properties like JS.

Functions

So how are we going to implement our functions in Ruby? Well Ruby already has something that behaves very like functions. Blocks. Importantly for us, blocks are also closures in Ruby, which bring us a bunch of extra functionality for free, meaning we don’t have to reach into any bindings to simulate them. Phew!

So let’s just start by defining a function method that captures and returns the block passed to it:

1
2
3

def function(&block)
  block
end

So far so good.

Objects

Next we need an object class that implements JavaScript style properties. Well JavaScript objects are in many ways very similar to Ruby’s Hash class, except for using the dot notation for property look-up. This is easily simulated Ruby’s method_missing to dynamically simulate getters and setters.

1
2
3
4
5
6
7
8
9
10

class Hash
  def method_missing(method, *args)
    if method =~ /=$/
      # Protip: $` means "the string before the last Regex match"
      self[$`.to_sym] = args[0]
    else
      self[method.to_sym]
    end
  end
end

Okay, this is pretty cool. We can now call getter and setter methods on our Ruby hashes and they’ll behave as if they’re properties behind the scenes. And because we’ve “duck punched” this behaviour into Ruby’s Hash class we can take advantage of Ruby’s hash literal syntax that looks a hell of a lot like the JavaScript object literal syntax:

1
2
3
4
5

lol = {
        whatLang: function() {
          console.log("Is this Ruby, or JavaScript?")
        }
      }

In order to further confuse the gentle reader, let’s implement console.log in Ruby:

1
2
3
4
5
6
7

  def console
    Object.new.tap do |o|
      def o.log(*args)
        puts(*args)
      end
    end
  end

Now we can even call our object’s function. We can’t call the function using () because Ruby will think they’re for arguments to our simulated whatLang method, not the function. However, we can use the fact that Proc aliases [] to call to give us a close simulcrum.

1

lol.whatLang[]

1

Is this Ruby, or JavaScript?

Prototypes

Early on, one of the things I said I wanted was to give objects prototypes, well, it turns out this is pretty easy to do. We just need to modify Hash’s [] property accessor slightly to check for a prototype property and if it’s there ask the prototype for it’s property when it’s not present on the child object:

1
2
3
4
5
6
7
8
9
10
11

class Hash
  alias _retrieve_property []

  def [](key)
    if has_key? :prototype
      _retrieve_property(key) or _retrieve_property(:prototype)[key]
    else
      _retrieve_property(key)
    end
  end
end

Now Hash will ask it’s prototype for a property that it doesn’t have.

1
2
3
4
5
6
7
8
9
10
11
12
13

person = {
  fullName: function() {
              console.log(this.firstName + " " + this.lastName)
            }
}

james = {
  firstName: 'Emmett',
  lastName: 'Brown'
}
james.prototype = person

console.log(james.fullName.inspect)

1

#<Proc:0x007fadf738b808@(irb):33>

this and function calling.

So this is pretty sweet, we can create an object with some properties, set it as the prototype of another object and that object will now retrieve properties from its prototype (and its prototype’s prototype, on and on up the chain).

The only problem we have is that of context. When you call a function via a property you want this to refer to that property’s object. But there is no this variable in the execution context of the block when we call it, so we need a way to inject it. The best way to do this is to use Ruby’s instance_exec to allow us to call a proc in the context of an arbitrary object.

So firstly, let’s create a Function class, which will store away the block and allow us to execute it in it’s own context:

1
2
3
4
5
6

Function = Struct.new(:this,:__block__) do
  def call(*args)
    instance_exec(*args,&__block__)
  end
  alias [] call
end

Next we need to modify our function method so that our block is wrapped in our new Function object:

1
2
3

def function(&block)
  Function.new(nil, block)
end

Now we need to modify the [] method on Hash to inject itself on property retrieval:

1
2
3
4
5
6
7
8
9
10
11

class Hash
  def [](key)
    value = if has_key? :prototype
              _retrieve_property(key) or _retrieve_property(:prototype)[key]
            else
              _retrieve_property(key)
            end

    value.is_a?(Function) ? Function.new(self, value.__block__) : value
  end
end

Now we should be able to call our fullName function and get the correct result:

1
2
3
4
5
6
7
8
9
10
11
12
13

person = {
  fullName: function() {
              console.log(this.firstName + " " + this.lastName)
            }
}

james = {
  firstName: 'Emmett',
  lastName: 'Brown'
}
james.prototype = person

console.log(james.fullName[])

Outputs:

1

Emmett Brown

And finally, an apology

So there’s my whirlwind tour of implementing prototypical inheritance and a (very simplified) portion of the JavaScript object model in Ruby. I need to take a moment to apologise to Matz for doing this to his beautiful language.

Needless to say, if I ever see code like this in production I will mock you mercilessly. You have been warned.

I’ve been building a lot of Ember.js authentication mechanisms for several projects, and I’m starting to think that I’ve got it down to a fine art. I’ve been treating my front-end apps as simply an API consumer, which means that they need a similar method of authenticating their API access as that of a tradition (service-based) API client.

A lot of my current thinking on how to put this together can be found in Blogomat, an example application I’m using as a test-bed for ideas of how to build apps with Ember and Rails.

Let’s have a look at our requirements for how we’re going to authorise API client accesses:

• Some sort of short-lived session token which can be acquired by the API client to use when accessing API resources to authorise the client.
• A way of authenticating a user with their username and password to attach it to our session token.
• A way of authenticating a service with a secret that is shared by the server and the client, without that secret being transmitted over the wire.

Some additional design goals include:

• Write the minimum amount needed to implement the required features without adding any overly complicated dependencies to our application (ie Devise).
• Authentication methanisms should be easily understood so that those writing API clients don’t have to struggle to understand what’s going on.
• Try and stay as close to RESTful ideals, and compatible with JSON API as possible.

So, in Blogomat, I have a simple (non-versioned) API namespace in my routes file:

1
2
3
4
5

Blogomat::Application.routes.draw do
  namespace :api, defaults: {format: :json} do
    resource :sessions, only: [:create, :show, :destroy]
  end
end

Seems straight forward enough, let’s create our Api::SessionsController. The first thing I do is create a abstract ApiController class, which (much like the conventional ApplicationController can encapsulate shared behaviour across all API endpoints).

1
2
3
4
5
6

class Api::SessionsController < ApiController

  def create
  end

end

API Session Tokens

We know at this point that we’re going to need some sort of api token object for the Api::SessionsController to create and return, let’s think about this object a little. What do we know about it from the requirements?

• We know that it needs some sort of unique identifier.
• We know that it is short-lived, so needs to have a TTL.
• We know that it needs to be able to refer to a user object.

One thing we don’t know is that it needs to be stored in the database, and in fact, since we know that we will be checking this token every time we receive an API request, it’s probably overkill.

We also think that it would be nice if we could store tokens in some sort of fast, shared storage so that if we need to scale our app horizontally we have that capability without massively changing the underlying authorisation scheme. In this vein, I have chosen to store the session tokens in Redis, however you could choose to use Memcache or even just in a Hash, should you want (and in fact, in my tests I have it using a faked-out Redis client backed by a Hash).

The main reason I chose Redis is that it’s reasonably ubiquitous, and has the handy ability to expire keys, so that we don’t have to worry garbage collecting our ApiSessionTokens. This example simply uses a hash to cut it down to a reasonable size to demo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

class ApiSessionToken
  TTL = 20.minutes

  def self.store
    @store ||= Hash.new
  end

  def initialize(existing_token=nil)
    @token = existing_token
    self.last_seen = Time.now unless expired?
  end

  def token
    @token ||= MicroToken.generate 128
  end

  def ttl
    return TTL unless last_seen
    elapsed   = Time.now - last_seen
    remaining = (TTL - elapsed).floor
    remaining > 0 ? remaining : 0
  end

  def last_seen
    store[:last_seen_at]
  end

  def last_seen=(as_at)
    store[:last_seen_at] = as_at
  end

  def user
    return if expired?
    store[:user]
  endo

  def user=(user)
    store[:user] = user
  end

  def expired?
    ttl < 1
  end

  def valid?
    !expired?
  end

  private

  def store
    self.class.store[token] ||= {}
  end
end

Now that we have an object we can use, let’s alter our sessions controller to return it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

class Api::SessionsController < ApiController

  def create
    if params[:username]
      @user = User.find_by_username(params[:username])
      token.user = @user if _provided_valid_password? || _provided_valid_api_key?
    end

    respond_with token
  end

  private

  def _provided_valid_password?
    params[:password] == 'foo password'
  end

  def _provided_valid_api_key?
    params[:api_key] == 'foo key'
  end

end

So this is pretty cool. Now if we have receive a POST it’ll return a valid API session token, which will last for 20 minutes and then drop off the map after that.

If they post again with a username and password, or username and api key then we’ll let then sign in as that user for the duration of their session, provided they have provided valid credentials.

Now we can go back and write some helpers in ApiController to make working with these sessions easier, and add a before filter to protect API actions from access without a session token.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

class ApiController < ApplicationController

  before_filter :api_session_token_authenticate!

  private

  def signed_in?
    !!current_api_session_token.user
  end

  def current_user
    current_api_session_token.user
  end

  def api_session_token_authenticate!
    return _not_authorized unless _authorization_header && current_api_session_token.valid?
  end

  def current_api_session_token
    @current_api_session_token ||= ApiSessionToken.new(_authorization_header)
  end

  def _authorization_header
    request.headers['HTTP_AUTHORIZATION']
  end

  def _not_authorized message = "Not Authorized"
    render json: {error: message}, status: 401
  end

end

class Api::SessionsController < ApiController
  skip_before_filter :api_session_token_authenticate!, only: [:create]

end

Password Authentication

The next task is to get password authentication working. We’ve decided to run with the herd and use bcrypt, which saves us having to write our own hashing algorythm. Phew!

1
2
3
4
5
6
7
8
9
10
11
12
13

class User < ActiveRecord::Base

  validates_presence_of   :username,      on: :create
  validates_uniqueness_of :username,      on: :create
  validates_presence_of   :email_address, on: :create
  validates_uniqueness_of :email_address, on: :create
  validates_presence_of   :password,      on: :create

  def password=(secret)
    write_attribute(:password, BCrypt::Password.create(secret))
  end

end

Now we can create a UserAuthenticationService to encapsulate our authentication logic. Basically we just delegate to bcrypt-ruby.

1
2
3
4
5
6
7

module UserAuthenticationService
  module_function

  def authenticate_with_password(user, attempt)
    user && BCrypt::Password.new(user.password) == attempt
  end
end

And wire it up to our sessions controller.

1
2
3
4
5
6
7

class Api::SessionController < ApiController

  def _provided_valid_password?
    params[:password] && UserAuthenticationService.authenticate_with_password!(@user, params[:password])
  end

end

Great! Now our user an send an API request to authenticate with their password in order to be able to access the API.

API Key Authentication

The next step is to provide a way of authenticating with a shared-secret, which isn’t transmitted between the client and the API during normal API usage. This sort of authentication is usually used by services trying to consume your API, rather than users themselves.

So, our design goals are as follows:

• Based on a secret shared between the client and server.
• Must be easily computed by both the server and client.
• Must be unique enough that it’s not succeptable to a MITM or Replay attack.

Of course, your API is running over SSL, right?!

With our requirements mapped out, we can implmenent our API key authentication and wire it up to our controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

module UserAuthenticationService
  module_function

  def authenticate_with_api_key(user, key, current_token)
    user && key && current_token && OpenSSL::Digest::SHA256.new("#{user.username}:#{user.api_secret}:#{current_token}") == key
  end
end

class Api::SessionsController < ApiController

  def _provided_valid_api_key?
    params[:api_key] && UserAuthenticationService.authenticate_with_api_key!(@user, params[:api_key], current_api_session_token.token)
  end

end

Summary

This has been a much longer blog post than I had initially sat down to write, so I’ll stop here. I plan to follow up soon with an entry about implementing the client-side API session token logic in Ember.js.

Thanks for taking the time to read all this!

Last night I was wondering how much work is involved in taking a stock Rails 4 application, removing turbolinks and turning it into something ready for doing BDD of an Ember.js application. “Can’t take too long” I thought to myself. Famous last words.

Baseline is just this, an empty Rails 4 app, with the environment configured to allow you to immediately start adding your features with Ember on the front-end and a Rails API on the backend. I realise this is a pretty opinionated project, but we all love opinions, right? That’s why we use Rails and Ember in the first place. Let’s talk about some of the things that I’ve added:

RSpec

In the Rails community, it’s kind of a standing gag that it’s the convention of the community to break with convention and remove the minitest test suite that Rails defaults to and add RSpec. We use RSpec for unit testing our code, and doing functional tests of controller actions. What I love about RSpec is the way that it allows us to build up execution contexts by nesting describe and context blocks which are then lazily evaluated for each execution context, for example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

describe Api::RootController do
  describe '#index' do
    let(:query) { get :index, format: :json }
    subject { query; response }

    it { should be_success }

    describe 'JSON' do
      subject { query; JSON.parse(response.body) }

      it { should have_key('current_user_url') }
    end
  end
end

Cucumber

We use Cucumber as our acceptance testing system. It’s pre-configured with Poltergeist to drive the headless webkit brower PhantomJS to make sure that our front-end application behaves as expected. One of the nice things about Cucumber is that it uses a plain-english style syntax (called gherkin) to allow us to write our test scenarios in plain english, for example:

1
2
3
4
5
6
7
8

Feature: Contact page.

  Scenario: A user visits the contact page.

    When I visit '/'
    And I click the "Contact Us" link
    Then I should see 'Contact'
    And the "Contact Us" link should be active

Jasmine

Jasmine is a test framework for JavaScript with a syntax that closely models RSpec’s “spec” style. It uses JavaScript functions in a similar way to the way that RSpec uses blocks to build up execution contexts. When you mix that with CoffeeScript you get a pretty reasonable spec syntax:

1
2
3

describe 'Ember.js', ->
  it 'is the expected version', ->
    expect(Ember.VERSION).toEqual('1.0.0-rc.6')

Guard

Guard is a ruby-based file watcher. This doesn’t sound that amazing, but it has a great plugin architecture and great support from the Ruby community meaning that there are a whole lot of guard plugin gems available. I’ve wired up Guard with the various plugins to have it start a complete development environment, including Rails, Sidekiq, RSpec, Cucumber and Jasmine. Guard watches for file changes, and then uses the rules in it’s Guardfile to start, restart or run the various plugins. For example, when you modify any files in config/ it restarts Rails & Sidekiq, when you modify something in app/models/ it runs the corresponding unit tests in RSpec, and when you modify something in app/assets/javascripts/ it runs the corresponding unit tests in Jasmine. This gives you the instant feedback needed to do effective BDD and TDD.

Continuous Flow

I’m a strong proponent of the continuous flow style of Agile software development and along with that I feel that continuous integration (ie automatically running the full test suite every time you commit) and continuous deployment (automatically deploying your code to production whenever you merge to master and the tests pass), so I’ve made a point of setting up Baseline on Codeship (an excellent cloud-based service for CI and CD) to automatically test and deploy any changes as they happen to Heroku, so that you can see straight away any changes that you make. You can see the current build of Baseline running at http://baseline-rails.herokuapp.com/.

There’s much much more to talk about in Baseline, and I expect it to be the subject of a number of blog entries in the future. Watch this space.

Over the last week or so I’ve been experimenting with Ember-Model as a possible replacement for Ember-Data which has been causing me a few headaches recently (which is fair enough, it is alpha software).

One of the things I need from whichever persistence mechanism I use is client-side validations. Of course, you still have to validate your incoming data on the server, but doing it on the client-side allows a good UI to be built around the editing process, without having to wait for the data be sent to the server and back.

I decided to add (very simple) validation support to Ember-Model, and spent a few hours whipping something up as a proof-of-concept pull request, however Erik thinks that validations are outside the scope of Ember-Model (and upon some reflection I agree with him). I’ve split it off into a small package called Ember-Validatable.

Ember-Validatable allows you to easily add validations to any object using the Ember.Validatable mixin. Once you have mixed in EV you can add a special fooValidation or fooValidations property which to which you can pass a subclass of Ember.Validator:

1
2
3
4
5
6
7
8
9
10
11
12

var TimeTravelValidation = Ember.Validator.extend({
  message: 'must be at least 88mph',

  isValid: function() {
    return parseInt(this.get('content')) >= 88;
  }.property('content')
});

App.TimeTravel = Ember.Object.extend(Ember.Validatable, {
  speed: '17mph',
  speedValidation: TimeTravelValidation
})

This will set an instance of App.TimeTravel’s isValid property to false and add an error message to it’s errors property. These will be cleared as soon as the speed property is set to something greater than or equal to 88.

There is more thorough documentation in the readme should you need it.

EV is brand new, so please send bug reports and pull requests on the GitHubs if you have problems or suggestions.

I took the liberty of making this jcog:secure badge for when all those other service badges just aren’t trolling you enough.

Reasons you should use Rubby

1. o_O

A couple of weeks ago I had the pleasure of attending RailsCamp NZ 2013 at the beautiful Camp Kaitoke. I knew that it was RailsCamp tradition to have a project to work on over the course of the weekend and although I have plenty of rails related projects I decided that I wanted to work on my own language. I’ve had this idea for a little language, much like CoffeeScript, sloshing around in the back of my brain for a while, and I thought it about time I got it out. Thus Rubby was born.

Rubby consists of a transpiler that converts Rubby code into idiomatic Ruby, for example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class Dog
  attr_accessor :breed, :name

  initialize -> (@breed, @name)

  bark ->
    <- if breed == 'Basenji'
    puts('Ruff! Ruff!')

  display ->
    puts "I am of #{breed} breed and my name is #{name}"

('Tinsley': 'Great Dane', 'Rufus': 'Basenji', 'Ayla': 'Malamute').each &> (name,breed)
  d = Dog.new(breed,name)
  d.bark
  d.display

Which transpiles into the following Ruby:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

class Dog
  attr_accessor(:breed, :name)
  def initialize(breed, name)
    @breed = breed
    @name = name
  end
  def bark
    return if breed == 'Basenji'
    puts('Ruff! Ruff!')
  end
  def display
    puts("I am of #{breed} breed and my name is #{name}")
  end
end
({ 'Tinsley' => 'Great Dane', 'Rufus' => 'Basenji', 'Ayla' => 'Malamute' }).each do |name, breed|
  d = Dog.new(breed, name)
  d.bark
  d.display
end

And while the output obviously still needs a little tweaking (specifically adding whitespace between methods, etc, and when to put parens on method arguments) it’s mostly complete feature wise.

I worked almost non-stop on Rubby at RailsCamp, but would probably would have given it up if it wasn’t for the quiet enthusiasm of Bardoe and Brett. Over the weekend, Rubby went from a barely passable lexer and parser to having a basically functional transpiler and REPL. I was hugely proud to be able to stand up on Sunday night and demonstrate our achievement to the other campers.

How it works

Rubby is based around Chris Wailes’ RLTK library, although with a number of Rubby-specific patches. Rubby code is run through the lexer which processes the input into a stream of tokens with an optional value (eg <- emits just a RETURN token, 'foo' emits a STRING token with the value 'foo'). The only real magic in the lexer is in Rubby::Lexer::Environment#indent_token_for where it attempts to measure whitespace after a newline and emit the correct number of INDENT, OUTDENT or NEWLINE tokens.

The token stream is then passed into the parser which is in essense a massive state machine; given a particular token it builds a list of possible next tokens, if there are multiple possible actions then it tries each one until it succeeds in consuming the entire token stream or it runs out of actions (a syntax error). The parser emits an abstract syntax tree, the classes for which are defined in lib/rubby/nodes.

Next, the transpiler walks through every node in the syntax tree calling #modify_ast on each which allows nodes to make modifications to other nodes in the ast (for example the InstanceArgument node modifies it’s parent method definition to contain instance variable assignments). This can’t be done at the same time collapsing the AST into Ruby because a node may need to modify an already collapsed peer to implement a language feature.

Once all this is done, the transpiler then calls #to_ruby on the root node of the AST, which in turn will call #to_ruby on it’s children (if required) and will return a large nested array of ruby statements, where an increase in nesting corresponds to an increase in indentation. This array is then passed into the RubyFormatter which joins these arrays with the correct indenting and returns the final Ruby representation of the program.

Next steps

Rubby still has a bunch of features needed before I can contemplate a 1.0 release; most pressingly support for interpolated regular expressions and a convincing rescue/ensure syntax. I also want to submit a pull request for ActiveSupport::Dependencies to be language agnostic, something that the existing Polyglot hook gets us near to, but not all the way. If you’d like to help with that, or with Rubby in general (there are a bunch of Cucumber features tagged as @todo) then I could really use your help.

I hope people enjoy programming in Rubby as much as I enjoyed writing it and I’m really keen for any feedback whatsoever.