blog dot voxdolo dot me

Remote Pairing with Vim and TMux

2010-09-21T00:00:00-07:00

While it’s always best to pair program side-by-side with your pair, it’s not always feasible. Over the last couple of weeks, Jim Remsik and I needed to pair on a new project, but circumstances dictated that he be elsewhere.

What’s a Pair to Do?

Keep right on pairing, of course. We just had to figure out how. Our requirements were:

Collaborative Editing: the fundament of pairing, both people need to be able to type into the same editor.
Access to the Local Server: it’s pretty hard to develop an app you can’t see.
Ease of Communication: we need to be able to hear each other, preferably seeing each other as well (there’s a lot of nonverbal communication when pairing).
Light Weight: the internet connections would be of variable quality, so we required something that wouldn’t tax small pipes.

We’d previously used iChat Screen Sharing when we needed to do this at Hashrocket… it works great for numbers 1 and 2, gets us half way to number 3, but falls over entirely on number 4. The lag from sending so much data over the network starts out as merely grating, but quickly crescendos in abject frustration, tending to make the client of the pairing session little more than an observer.

Given that, the no-brainer for us was to use Vim inside a terminal-multiplexer that allowed multiple client connections, so we could attach to the session over SSH. That’d get us “Collaborative Editing”, but what about the other requirements? After a bit of discussion, we decided we could solve numbers 2 and 4 by forwarding port 3000 of the host machine to the client attaching via SSH. Being that this was such a lightweight solution, we opted for Skype (our communications weapon of choice) for video chat.

Our initial permutation involved opening a port in our SonicWALL firewall and manually forwarding the port to a machine inside the firewall with a static IP. This worked great, after the initial pain of configuring SonicWALL (which is, in my estimation, a FPOS). The shortcoming here is that we didn’t want to have to open up a port for every station we wanted to remote-pair from (some days Hashrocket is an elaborate game of musical chairs). tpope came to the rescue with his recommendation for using the ProxyCommand option for SSH.

Enough background.

Pairing Down the Configuration

The configuration we used makes several assumptions about your network’s environment:

At least one machine in your network is available at a public IP
The externally available machine understands MDNS (e.g. Bonjour)
The other machines on your network are available via MDNS

That said, it should be relatively easy to modify this to work with a direct peer-to-peer connection (provided the host has a routable IP address). If you’re so inclined, please contribute in the comments below.

`.ssh/config`

You’ll need an entry for the machine you’re tunneling into, ours looks like this:

  Host tunnels
    Hostname 0.0.0.0 # this should be an externally routable address
    User your_user

Now here’s the magic:

  Host *.hashrocket #*
    User your_user
    ProxyCommand ssh -ax tunnels nc `echo %h|sed -e 's/\.hashrocket$/.local/'` %p 2>/dev/null

Let me attempt to unravel what this is doing. ProxyCommand allows you to specify a command to use to connect to the host machine. In our case, we’re doing a wildcard match on anything at .hashrocket, the actual match is then used to figure out how to route the request inside the network. So in our case, tunneling to fry.hashrocket gets us to our tunnels machine, then we use netcat to echo the given command to fry.local.

Which brings us to the actual forwarding command:

  $ ssh fry.hashrocket -L 3000:localhost:3000

This drops us into a shell on fry.local and establishes the reverse tunnel, forwarding localhost:3000 on the host to localhost:3000 on the client machine.

tmux

If you’re interested in why we chose tmux over gnu screen, I’ll first refer you to the tmux FAQ and subsequently admit that I went with it primarily because it’s newer and shinier. You could easily substitute screen for tmux here, though my opinion after a few weeks use is that it’s much more intuitive and I won’t be making the move back.

The relevant commands for creating and attaching to a new session follow. On the host, you’ll need to create a session:

  $ tmux new -s mysession

On the client, you’ll need to attach to that session:

  $ tmux attach -t mysession

Once you’re connected, you’ll need to run Vim (or some other terminal-friendly editor, e.g. emacs, sorry TextMate people) in a window or pane. We opted to run Terminal full screen on an iMac, with two panes arranged vertically; a shell session in one, Vim in the other and new windows for long-running processes or utility shells.

`tmux.conf`

We’re Vimtarded, so putting the following in ~/.tmux.conf made us feel a bit more homey:

  setw -g mode-keys vi

  bind h select-pane -L
  bind j select-pane -D
  bind k select-pane -U
  bind l select-pane -R

The initial configuration puts navigation commands in Vim mode (you’ll see this in copy mode, the help screen, etc). The custom bindings below that make navigating the panes within a window work like navigating splits in Vim.

`tmux` crash course

The default binding for the command mode is ctrl-b. We will refer to it as <command> hereafter. <command>-d means: ctrl-b, then ‘d’.

  <command>-d # detach from current session
  <command>-" # split window into panes horizontally
  <command>-% # split window into panes vertically
  <command>-o # go to next pane
  <command>-x # close current pane
  <command>-? # display available keybindings
  <command>-c # create a new window
  <command>-n # go to next window
  <command>-p # go to next window

Pairing is Such Suite Sorrow

So now we’re editing text together, we’re looking at localhost on each end, we’re running some specs, writing some cucumbers, everything’s perfect. Until you need to save_and_open_page. You have two options: never make any errors or move those files somewhere that your pair can see them too.

Since we’ve yet to be issued our Ninja-Passes, we opted for the latter and since we’re using Capybara, we did it like so:

In features/support/env.rb:

  Capybara.save_and_open_page_path = "public/tmp"

Awesome, now they can just browse to http://localhost:3000/tmp and see Capybara temp pages! That is, if they can guess the name of them, or want to ls the directory, copy the name of the last file and paste it into the browser.

That would work, but how about this instead:

At the bottom of config/routes.rb:

  if Rails.env.development?
    Some::Application.routes.draw do
      match 'tmp/(:action)', :controller => 'tmp'
    end
  end

app/controllers/tmp_controller.rb:

  class TmpController < ApplicationController
    expose(:temp_pages) do
      Dir.glob(File.join('public','tmp','capybara-*'))
    end

    def latest
      render temp_pages.last, :layout => false
    end
  end

Adding an index view would be trivial if you needed to look at more than just the latest one¹.

The Pair Stare

As a side-note, we did use Skype to video chat as our primary means of communication. Jim claims that the best part of it was that I Skyped from my machine (a 13” MBP, with my iPhone headset) and hosted the tmux session on the iMac right beside it. This had the unintended side effect of me not “staring at him” all day long while I coded. It’s the little things that make all the difference :)

Check Out The Pair On This Guy

While my brief stint of remote pairing has come to a close, I’ve no doubt I’ll need to do it again at some point in the future and am interested in refining this process. So please, if you can think of a way to improve on or simplify any of this, leave a note in the comments!

Curious about that expose method? Check out decent_exposure.
↩

A Diatribe on Maintaining State

2010-09-03T00:00:00-07:00

TL;DR

If you’re interacting directly with an instance variable and it’s not inside an accessor or mutator method, you’re breaking encapsulation and promoting close coupling in the design of your object system. Just because an API encourages this behavior doesn’t mean that it’s a good design practice (see Rails for a great example of enshrining this bad habit).

The Discourse Proper

An object instance, while resident in memory, must have somewhere to store its state. In Ruby (as in most languages), the instance variable is our go-to guy. It’s so useful and its usage is so universally understood, in fact, that many people don’t look much further than it when determining how to store and subsequently access state.

A Common Approach

Let’s look at an example of an approach where we directly interact with state stored in an instance variable:

  class Message
    def initialize(body)
      @body = body
    end

    def to_html
      @body.gsub(/\n/,"<br/>")
    end
  end

I’ve got some state, I initialize my object with it, and I later access it. Clearly, this code isn’t the worst thing that has ever happened to the software world. In this simple example, it’s largely forgivable to use an approach like this.

The first principle from Design Patterns: Elements of Reusable Object-Oriented Software is:

Program to an interface, not an implementation.

Or as I like to dramatize it:

If you're not programming to an interface, you're coupling with an implementation.

When consuming code (be it your own or someone else’s) in an Object-Oriented system the thing we are meant to be concerned with is the state of the object itself. To wit: the fact that an object’s state is (or isn’t) stored in an instance variable, should be a detail of the implementation.

An Important Nuance

People tend to think of APIs in terms of how they’re consumed externally. It’s equally important to consume them internally. Let’s add the requirement that our Message object must remove leading, trailing and repetitive space.

  class Message
    def initialize(body)
      @body = body.squeeze(' ').strip
    end

    def to_html
      @body.gsub(/\n/,"<br/>")
    end
  end

Still a very straightforward implementation, but we start to see a lack of cohesion here as the initializer is now responsible for both storing and manipulating this state. We have yet to declare an interface though, so there’s really little recourse at this point.

Refactoring To An Interface

I mentioned earlier that interacting directly with instance variables is largely forgivable in the simple case. That is not to be confused with an endorsement. Ruby makes it so simple to abstract away state maintenance, that it feels irresponsible not to. Here’s how we might refactor that given our previous case:

  class Message
    attr_reader :body

    def initialize(body)
      self.body = body
    end

    def body=(body)
      @body = body.squeeze(' ').strip
    end

    def to_html
      body.gsub(/\n/,"<br/>")
    end
  end

With this factoring, we need never know that our state has been stored in that instance variable. It becomes a detail of the implementation. Additionally, we’ve moved the responsibility for cleaning up the excess whitespace in the message body into the setter.

Now that we’ve declared an interface, it becomes significantly easier to make substantial refactors, such as upgrading your state maintenance to allow for persistence:

  class Message
    def initialize(body)
      self.body = body
    end

    def body=(body)
      cache.transaction{|c| c[:body] = body.squeeze(' ').strip }
    end

    def body
      cache.transaction{|c| c[:body] }
    end

    def to_html
      body.gsub(/\n/,"<br/>")
    end

    private
    def cache
      @cache ||= PStore.new('message_cache.pstore')
    end
  end

Here we begin to see advantages of declaring an interface. By defining an interface, you effectively declare the “surface area” of your internal API. This also goes a long way toward making methods that are both atomic and highly cohesive.

This example is still very simple. In interest of fairness, an equivalent class (assuming you only really care about the value of to_html) which employs direct access to instance variables might be within your threshold of acceptable use:

  class Message
    def initialize(body)
      @cache = PStore.new('message_cache.pstore')
      @cache.transaction{|c| c[:body] = body.squeeze(' ').strip }
    end

    def to_html
      @cache.transaction{|c| c[:body] }.gsub(/\n/,"<br/>")
    end
  end

Given the simplicity (and brevity) of this implementation, why is there any issue with this approach? At this scale, there probably isn’t. The previous objection to this approach regarding the ease of declaring an interface in Ruby still stands, but it’s truly not until the software system exists at a sufficient level of complexity that you’ll start to experience the detriment of this approach.

A Slightly More Complex Use Case

Let’s add support for finding and storing multiple Message object instances.

  class Message
    def self.find(id)
      cache = PStore.new('message_cache.pstore')
      new(id,cache.transaction{|c| c[id] })
    end

    def initialize(id, body)
      @cache = PStore.new('message_cache.pstore')
      @id = id
      @cache.transaction{|c| c[@id] = body.squeeze(' ').strip }
    end

    def save
      @cache.transaction{|c| c[@id] = @body }
    end

    def to_html
      @body.gsub(/\n/,"<br/>")
    end
  end

Now let’s see what that might look like when declaring an interface:

  class Message
    attr_reader :body
    attr_accessor :id

    def self.find(id)
      new(id, cache.transaction{|c| c[id] })
    end

    def initialize(id, body)
      self.id = id
      self.body = body
    end

    def body=(body)
      @body = body.squeeze(' ').strip
    end

    def to_html
      body.gsub(/\n/,"<br/>")
    end

    def save
      self.class.cache.transaction{|c| c[id] = body }
    end

    private
    def self.cache
      @cache ||= PStore.new('message_cache.pstore')
    end
  end

Analyzing The Implementations

In the first example, you end up with some some incidental coupling in the initializer. It takes on the responsibility for assigning internal attributes, manipulating them where necessary, as well as initializing a persistent reference to the cache itself. Additionally, there’s no ability to manipulate the state of an instantiated object, so another object interacting with an instance of Message wouldn’t be able to change the value of its @body.

Conversely, the implementation which has declared an interface is ready to behave as a good citizen within an object system. It allows other objects to interact with it at all stages of its life cycle in a specified fashion (it has declared its “surface area”). It retains atomicity and expresses no signs of coupling.

Another notion that I haven’t addressed is that of Code Beauty. This is an entirely subjective topic, but I contend that a well-specified interface creates more beautiful code. I’ll leave that to you to decide, but I think the examples do a fair job of showing this.

Wrapping Up

This is such a simple topic that it’s easy to take for granted. To reiterate: the issues with accessing instance variables directly become most obvious when a software system attains some basic scale and complexity. Generally speaking, once objects in a system begin to interact in any significant manner, the coupling created by not specifying and adhering to an interface starts to become clear. This coupling makes it more difficult to adhere to Single Responsibility Principle, which subsequently increases rigidity.

The intended takeaway is that you can improve the overall design of your software system at every stage of its evolution by specifying and adhering to an interface. One simple way you can do that is to ensure that you’re not manipulating state maintained in instance variables directly.

Gibbon

2009-10-10T00:00:00-07:00

At work, I’ve recently been downplaying the importance of Gibbon being distributed as a library, since I don’t really think it’s the code that’s important… the technique is where it’s at. As such, I’m not going to give the hack itself or its configuration any stage time in order to jump in and talk about how to use it and what its limitations are.

Monkeying Around

By and large, Gibbon’s syntax apes Cucumber’s take on Given/When/Then Templates.

There are, however, some gotcha’s and limitations and that’s what I’d like to focus on. Let’s start off with an example:

  Feature "A Tomatoist does a pomodoro" do
    Story <<-eos
    In order to perform a focused unit of work
    As a Tomatoist
    I want to start a pomodoro
    eos

    Scenario "Starting a pomodoro" do
      When "I go to the home page" do
        executes { visit '/' }

        Then "I should be sent to a new session" do
          current_url.should =~ /\/\w{3,}/
        end

        And "I should see an unstarted timer" do
          response.should have_tag('#timer .countdown_row','00:00')
        end

        And "I should see a pomdoro button" do
          response.should have_tag('input[type=submit][value=?]','Pomdoro')
        end

        When "I click the pomodoro button" do
          executes do
            @session_url = current_url
            click_button 'Pomodoro'
          end

          Then "I should be on my session's page" do
            current_url.should == @session_url
          end

          And "my timers should have been initialized" do
            response.should have_tag('#timer .countdown_row','25:00')
          end

          And "my timer history should show the current pomdoro" do
            response.should have_tag('#history ul li', /Pomodoro/, 1)
          end

          And "the pomodoro button should be highlighted" do
            response.should have_tag('form.current input[type=submit][value=?]','Pomdoro')
          end
        end
      end
    end
  end

And here’s what the output of that feature looks like using RSpec’s built in nested formatter:

A Tomatoist does a pomodoro
  In order to perform a focused unit of work
  As a Tomatoist
  I want to start a pomodoro

  Scenario: Starting a pomodoro
    When I go to the home page
      Then I should be sent to a new session
      And I should see an unstarted timer
      And I should see a pomdoro button
      When I click the pomodoro button
        Then I should be on my session's page
        And my timers should have been initialized
        And my timer history should show the current pomdoro
        And the pomodoro button should be highlighted

Flinging Poo

There are a couple of things you should note about the syntax straight off:

It’s verbose.
It relies heavily on nesting (sometimes in ways that feel awkward).

It’s also noteworthy that the primary means of interrogating the response is through either the have_tag matchers or using something like contain to look for text. This is not necessarily a bad thing, but it can lead quickly to close coupling unless you are constantly vigilant. I’m still mulling this aspect over, but as it stands, I haven’t thought of a better way to handle it.

Monkey wrenches

I’ve talked some to Tim Pope about Gibbon, since he’s a big fan of Cucumber driven development. His criticism, in a nutshell, is that the English text is not executable. He asserts that Cucumber keeps you honest by actually mapping the text to executable code. This is definitely valid; I frequently make the same argument about comments: “they’re lies waiting to happen”. It’s only a matter of time ‘til they become stale and the code itself is more recent. I would argue though, that Cucumber only separates you from that same fate by virtue of the author’s diligence.

Tackling the problem of example descriptions diverging from implementation from the opposite direction is Jim Weirich’s recent entry into this field, Given. Given eshew’s explanatory text altogether, preferring to let the code speak for itself. Now we’re talking! Combine that with something like Stories’ ability to convert code to plain English for output and you’d have a really nice offering. What this solution still lacks though is the facility of RSpec’s matchers, as Given is built on top of Test::Unit (as is Stories).

Monkey Gone to Heaven

For now, I’ll be sticking with Gibbon, since it provides me access to RSpec’s matchers, is crazy simple and gives me pretty much everything I require:

Expressing business value using Given/When/Then templates
English language output for deliverables
Access to RSpec’s matchers

I’d love to hear from you in the comments about what your experience is with integration testing in general and how you’re scratching that itch these days.

You Say Tomato

2009-10-05T00:00:00-07:00

I say Pomodoro!

After a significant amount of time and effort and the gracious help of several contributors, I’m proud to officially announce tomatoi.st.

For those in a hurry

tomatoi.st is a simple timer application that helps you implement the Pomodoro Technique. You should totally use it.

The Story

While pairing with Corey Grusden a few months ago, we decided to experiment with the Pomodoro Technique. We immediately found that it helped improve our productivity and fight off project fatigue. Plus it gave Corey some officially sanctioned time in which to deal with his digital logorrhea (SMS much?). Needless to say, we were hooked!

The immediate hurdle was that the software available for doing the timing was lackluster (fwiw, decent software has since been developed). In light of this, we spent the first few days working with a simple sleep 1500 && growlnotify type solutioni which was inelegant at best. More importantly, it was missing an utterly essential piece of functionality: the ability to start a timer at my desk, go to the john, and check up on the time left in a break whilst on the throne!

And so, in pursuit of this lofty goal, a tomato was born.

What it does

tomatoi.st does very little, but we like to think it does it very well. ahem.

Visit http://tomatoi.st
Click the “Pomodoro” button
Start a focused unit of work
When you hear the “ding!”, click “Short Break”
Take a break, go to the john, whatever
Rinse and repeat

It is suggested that you do 4 sets of Pomodoros. The first three are followed by a short break, the last by a long one. tomatoi.st makes the assumption that you’ll be doing them in that order and handily suggests the next timer you should do by highlighting it’s button in green when the previous timer expires. Your current timer is highlighted in yellow while it’s underway and then red once it’s expired. Your timer history is tracked just below the big ticker.

Timers out of sync with reality (say, after a long lunch)? Click the “Reset” button to start fresh.

Want to come back to this set of timers tomorrow? Customize the name of the timer and then “rename” it so it’s easy to remember.

What it doesn’t do

It is not intended to be a full implementation of the Pomodoro Technique. Notably absent are things like task planning and daily review.

What’s next

Coming up promptly is integration with Fluid’s javascript API to provide neat things like Growl integration.

Want to help shape the face of what tomatoi.st will become? There are a number of ways you can help do so:

scratch your own itch and fork it on github
file a github issue
peruse and/or add to our tracker project
or make a request below in the comments

Shout Outs

A number of people have contributed to making this application what it is and I’d like take a second to thank them all.

Sandro Turriate: for adding server side polling to keep multiple people watching the same timer in sync as new timers are started.
Wes Gibbs and Les Hill: for adding timer countdown in the title bar (one of my favorite features).
Corey Haines: for his general good will toward the app and for helping to spread the word about it.
Andrew Maier: for taking the app from plain to fantastic! His design is what made the official release a possiblity.

Given Due Consideration

2009-09-21T00:00:00-07:00

Or: Just Say No to Cukes

As alluded to by veez, the undercurrent from some of us at Hashrocket has been decidedly anti-cucumber. Here’s my brief littany:

A well developed cucumber suite is invariably slow to run
For me, at least, it makes development feel slower (this is almost certainly perceptual, but that doesn’t mean it’s not actual as well)
The indirection makes debugging laborious
Matching plain english to executable code via regular expressions just feels wrong

All of these things (and more) have been excused for quite some time because Cucumber is thought of as a necessary tax. If you want to do full stack integration testing in Ruby… this is how it’s done.

Here’s the good news: it’s not the only way! Veez has gone over the basics in the post I linked above, so I won’t belabor the setup, though I will give you the latest version. Here are the relevant bits of my spec/spec_helper.rb:

  require 'webrat'
  require 'spec/support/integration'

  Webrat.configure do |config|
    config.mode = :rails
  end

  Spec::Runner.configure do |config|
    config.include(Webrat::Matchers, :type => [:integration])
  end

  class ActionController::Integration::Session; include Spec::Matchers; end

Interleaving the above into your existing spec_helper.rb is all you need to get going.

Let’s use this user story from a project I’m working on now as the backdrop to our discussion:

In order to dissolve a business relationship
As a user
I want to be able to remove a colleague

Scenario:
Given a user with colleagues
When I click a colleagues “Remove colleague” button
Then I should be on the colleagues list
And I should not see the colleague
And the colleague should not see me in their colleague list

Here’s how you might implement that using RSpec and Webrat:

  describe "User removes colleague" do
    before do
      login_as @user
      visit colleauges_path
      click_button 'Remove colleague'
    end

    it "redirects you to the colleagues list" do
      current_url.should == colleagues_url
    end

    it "removes them from my colleagues list" do
      response.body.should_not have_tag('#colleagues .colleague')
    end

    it "removes me from their colleague list" do
      logout
      login_as(@colleague)
      visit colleauges_path
      response.body.should_not have_tag('#colleagues .colleague')
    end
  end

That’s all well and good, but you may be saying to yourself (or your co-worker, or your poor, terrified cat): “But, that doesn’t capture the plain english user story! Darn it all to Bethesda!”. And you’re absolutely right… but how’s this strike you:

  Feature "User removes colleague" do
    Given do
      login_as @user
      visit colleagues_path
      click_button 'Remove colleague'
    end

    Scenario "removal" do
      When "I press remove" do
        Then "I should be on my collegues list" do
          current_url.should == colleagues_url
        end

        And "I should not see the user in my colleagues list" do
          response.body.should_not have_tag('#colleagues .colleague')
        end

        And "My colleague should not see me in their colleague list" do
          logout
          login_as @colleague
          visit colleagues_path
          response.body.should_not have_tag('#colleagues .colleague')
        end
      end
    end
  end

@l4rk and I came up with this clever bit of aliasing to get you where you want to go. Just add this at the bottom of your spec_helper.rb:

  module Spec::DSL::Main
    alias :Feature :describe
  end

  module Spec::Example::ExampleGroupMethods
    alias :Scenario :describe
    alias :When :describe
    alias :Given :before #TODO: make Given take :before or :after and :each or :all
    alias :Then :example
    alias :And :example
  end

The failing of this technique, for the time being, is the round-trip output:

User removes colleague removal I press remove

I should be on my collegues list

I should not see the user in my colleagues list

My colleague should not see me in their colleague list

But we’re already scheming up a way to improve that situation, so stay tuned as the story develops.

Twiki

2009-09-17T00:00:00-07:00

While pairing with @wesgibbs on a project at hashrocket, we got in the habbit of ‘testing’ our migrations by doing the following:

    rake db:migrate db:migrate:redo db:test:prepare

At some point; frazzled and dealing with a migration that kept breaking while running the above, I uttered: “db-db-db”, which was subsequently flipped around to “bidi-bidi-bidi”. Now, as a proud (well, kinda) son of the 80’s, my mind went immediately to Pamela Hensley… and soon thereafter, to Twiki of Buck Rodgers and his perennial tag line.

And so the following shell script was born (Mac only, sorry windozers):

    twiki () {
      say -v Zarvox 'beedee-beedee-beedee'
      rake db:migrate && rake db:migrate:redo && rake db:test:prepare
    }

The speed and voice aren’t quite right, but the sheer cheese factor cracks me up on the regular, so I figured I’d spread the wealth ;)

Also of note: the Twiki throwback dance mix

(re-)Introduction

2009-05-30T00:00:00-07:00

What’s this all about then?

This is yet another attempt (my fourth) to maintain a blog. I haven’t settled on what sort of content I intend to post here as of yet. It’s a safe bet, however, that posts will be primarily technical in nature. No link or micro blogging, strictly full articles.

So, yeah… Welcome to the new digs and please do subscribe to my atom feed if you fancy that sort of thing.

Oh! and you can blame the sites utter lack of design on @andrewmaier’s copious lack of free time ;) I kid, I kid! I’ll try and beat things into shape promptly.