Five Tool Development

Consulting and Custom Software Development Washington, DC

[fivetool]

We're hiring!

Our business is growing, and it's time to add a designer and at least one Rails developer. If you have the tech chops and want to work on new projects from scratch with great teammates, check out our job postings for developers and designers.

Visit us at the Five Tool Development jobs page.

[fivetool]

Upgrading your Ruby release on Heroku without pushing new code

On Friday a security vulnerability was announced in the (then) latest versions of the MRI Ruby interpreter. Developers were advised to upgrade their applications to the latest patch of their Ruby release immediately. For applications hosted on Heroku, a Ruby update is triggered by pushing from your Git repository to Heroku. How do trigger an upgrade if you don't have anew code to push?

One way to address this issue would be to update your gems, commit the updated Gemfile.lock, and then push to Heroku: 

bundle update git add Gemfile.lock git commit -m "Bundle update: [updated gems]"

This approach works if you have your gems locked such that only safe (patch or in some cases minor) updates are allowed, and your test suite is comprehensive enough to give you confidence that nothing has broken. However, this approach will not work if updating breaks code or if you have nothing to upgrade. In those cases you need a way to force Heroku to restart the application using the latest patchlevel of the assigned Ruby version.

The solution lies in a rarely-used option flag on the git commit  command. The --allow-empty flag (documentation here) allows you to create a commit that has the exact same tree as its parent in the Git history tree. Usually this behavior would be an error, as you ordinarily wouldn't want to record a lack of changes as a new revision in your version control. However, this trick allows you to push a new commit with no changes to Heroku, saving you the trouble of having to upgrade, test, verify, and deploy under duress. Here are the commands:

git commit --allow-empty -m "Upgrade Ruby due to CVE-2013-4164" git push heroku master

The push will cause Heroku to restart your application after applying the newest patchlevel of Ruby along with re-bundling your gems for the appropriate patchlevel.

(Note: Some of these instructions were adopted from Heroku's latest security bulletin for Ruby, which was only available in email form and not on the web.)

[fivetool]

iOS Push Messaging with ZeroPush

I have recently been working on two applications that deliver push messages to subscribed iPhones and iPads. While building out the infrastructure, I learned quite a bit about the idiosyncrasies of the Apple Push Notificiation System and various solutions that have sprung up to provide a better interface to APNS.

Your ideas are intriguing to me and I wish to subscribe to your newsletter

When you allow an application to subscribe you to their push messages, here's what happens in a nutshell:

Your application sends a subscription request to Apple's APNS gateway

APNS responds with a unique token. This token is what ties your device to a registered iOS application.

Your application then takes that token and sends it to some server-backed application.

One long-time iOS developer I talked to expressed surprise and disappointment that Apple still hasn't provided their own service to execute delivery of pushes. As it stands, if you want to send pushes to your app users, you must have your own server-side application or register with a service like Urban Airship or ZeroPush. You send push messages to a given application by sending APNS a message that consists of the token along with some combination of message text, an update for the application's badge count, a sound to be played, and some optional data that can be used to determine things such as where to go in the application when the push message is swiped. It's important that you don't know anything about the user from their token other than that they registered. If you want to tie the subscription to a specific user (which you'll want to do if any of your messaging is targeted or individualized rather than just broadcasts to all users), you'll want to send a UID or email address or other identifier to your server application at the same time you forward along the token.

Asynchronicity

The biggest challenge with push messaging is dealing with Apple's quirky behavior when you start sending push messages at any kind of volume. When you send a push message through APNS, you open a socket connection to the APNS gateway, send your message, and then close the socket. If you are opening and closing sockets too frequently, Apple will think you are a potential DOS attacker and temporarily ban you from connecting. The way around this is to open your socket and then send many messages on a single connection.

Here's the problem: This connection is asynchronous, which means you're sending data over the socket and not waiting for a response from Apple for any particular message. If this sounds perilous, you're right! If you send a message that is declined for any reason, such as sending a bad token, etc., APNS unceremoniously terminates the socket without any error message. Because the connection is asynchronous, APNS may terminate the socket due to a message that is not the last one you sent, which makes it very difficult to know which message or token was the culprit.

After experimenting with APNS on Rails, Grocer, Orbiter (via Helios) and Houston, I was extremely frustrated. None of the gems handled the issue of bad tokens (all of which had entered my database during user testing with my client's client) causing APNS to kill my socket. A pull request to Houston that has since been accepted appears to have solved the issue, but at the time of our development, but we began by using a combination of a fork of Houston including the socket fix pull request. Apple requires app developers to clean out bad tokens, which are usually the result of users unsubscribing from push messages, so we were also using a small part of the Grocer to managing the sweeping and removal of bad tokens. Many of these gems are still very immature, and there isn't yet a clear standard in this space.

Using ZeroPush

I began to investigate using a service rather than home-built code to abstract away the rougher edges of dealing with APNS. UrbanAirship is the dominant player in this space, but their pricing for lower-volume senders is fairly high. Through the Heroku addons portal we found ZeroPush. 

ZeroPush is still in beta, but we found that they had the holy trinity of service-layer software: an easy API, cheap pricing, and awesome customer service. After some initial testing with ZeroPush and their gem, I found that it wasn't designed for multi-threaded operation. My client has multiple iOS applications powered by our backend, so I needed to be able to open multiple simultaneous connections to APNS, one for each application that might be sending messages. I sent a message to ZeroPush's customer service address, and minutes later Stefan at ZeroPush called me to discuss the problem. Less than two hours later I had a recommended workaround in place. Less than two days later, ZeroPush had already made upgrades to their gem that helped solve my problem without the workaround we had created. I cannot recommend ZeroPush highly enough. Their API is very simple, has good documentation, and we found that it was a very reliable way to interface with APNS.

Using ZeroPush's interface, we were able to trim our APNS code down to just a few classes. Here's how we send batch messages to ZeroPush:

## # Delivers push notifications to APNS. ## class PushNotificationsDelivery def initialize(organization)     @organization = organization     @connection = ZeroPushConnection.new(organization)   end def deliver deliver_and_mark_notifications end private attr_reader :connection, :organization delegate :apns_notifications, :ios_application, to: :organization def deliver_and_mark_notifications unsent_notifications.each do |notification| connection.notify(notification.parameters_for_zero_push) notification.mark_delivered end end def unsent_notifications apns_notifications.unsent_and_ready_for_delivery end end

ZeroPush handles the socket connection for us, sparing us from the worry of having to manage the connection. We just send messages to ZeroPush, and they handle delivery and reporting unsubscribed tokens for us. It's worth noting that the PushNotificationsDelivery class described above is provides us with a layer of abstraction that will allow us to change providers or add Android push messages (as the client will be doing this month) easily without huge changes to our code. Using a third party service also keeps our specs clean. Our model test verifies that the right message gets sent to the ZeroPush client object, and integration tests verify that we are hitting the ZeroPush sandbox gateway.

Give it a try with your own app.

[fivetool]

Five Tool Dev Homepage refresh

It's almost our birthday, and one year is as good a time as any to go for a new look. This weekend we rolled out a redesign of the Five Tool Development Website.

For the redesign, I wanted to try using thoughtbot's Bourbon and Neat in place of Bootstrap 2. Bootstrap remains a great way for non-designer developers to get a decent-looking site up quickly, but Bootstrap's opinionated and deep decision-making makes customization much more difficult. Some of these decisions, such as a using non-semantic classes for column alignment and eschewing mixins, look like they will be addressed in the upcoming Bootstrap 3 release. 

Designing with Bourbon was a pleasure. After frustration on several recent projects coding around or un-coding CSS styles in order to get a particular flat aesthetic that I've been pursuing, Bourbon and Neat made getting a responsive, flexible design done easily. Bourbon's mixins made it easier to DRY my CSS than I've ever been able to before, and the golden ratio and modular ratio functions were a big help in dynamically determining proportions throughout the site. The site looks great in mobile as well, as the left-right alternation of the logos in the portfolio section simplifies to a centered, one-column layout on thinner browsers and phones.

As part of the redesign, we'll also be showing off recent client work more thoroughly, including work we're doing with the AFT, District Karaoke, New City Energy, The Wheelhouse Review, Velocity, and more. Stay tuned in future weeks, or follow our blog via RSS to stay updated on our recent news. In just five weeks we'll be wishing ourselves a happy first birthday. We hope those of you in DC will join us to bring in year two.

[fivetool]

Recent Work: District Karaoke

District Karaoke is a social, team-based karaoke league in DC. In addition to being awesome, they have experienced fantastic growth in their first year, growing to five separate nights of competition each week in DC and nearby Arlington, VA. We have been working with District Karaoke since their second season of competition, helping them expand and refine their voting and standings application. For the spring 2013 season, District Karaoke wanted to make some big changes. Responding to their participants, they refined their voting to use a clearer and easier to understand format. Each week the six teams at each venue are paired into one-on-one matchups, and each performance is ranked by total number of votes from the crowd at the bar.

A key requirement for District Karaoke was to have the voting pages work well with the widest possible selection of mobile phones. District Karaoke's previous voting system used sliders that were hard to use even on modern phones, but depended on a JavaScript framework with poor cross-browser functionality. As a result, some voters at the bar each night were forced to fill out paper voting forms, or worse, refrained from voting.

To support District Karaoke's new voting and expanding requirements, we replaced significant portions of their existing Rails application that supported voting and standings. On the back-end, District Karaoke staff and weekly MCs now have a full administrative interface that allows admins to start and stop voting, create new songs in the District Karaoke songbook as new hits are added to the catalog, and review voting data. A new data importer allows the commissioner to load the entire season of data (divisions, venues, teams, performers, captains) through the use of an Excel sheet import.

District Karaoke's commissioner wanted the mobile voting page to have a cleaner, flatter appearance. We worked with District Karaoke's co-founder, who is a designer, to give the site a much-needed refresh. We chose to use Five Tool Development's flatstrap-rails gem to get a flat look across the site. We did away with shiny, "lickable" buttons, and adopted two-dimensional iconography and logos.

On the front-end, the voting application now supports a responsive layout and relies on much simpler JavaScript that works on many more phones. Voting can be conducted at multiple venues simultaneously (a big need that was not addressed in District Karaoke's initial MVP), and users can browse and search the song catalog from their phones. District Karaoke no longer needs to spend significant funds on printing and updating songbooks that are passed around the bar as participants look to choose their next performance. 

We are very excited to be working with District Karaoke, and are looking forward to their forthcoming expansion to other cities around the country. If you're lucky (or unlucky), you may even be able to find Five Tool co-founder Geoff Harcourt singing "... Baby One More Time" at a District Karaoke event.

If you're interested in playing next season, registration begins in July. Follow District Karaoke on Twitter and Instagram (the photos are great).

[fivetool]

Recent Work: CTU Compensation Calculator

Last month, the American Federation of Teachers approached us about building a web app. They and their Cleveland affiliate, Local 279, had just reached a tentative agreement with the Cleveland Metropolitan School District that would raise the compensation of all of their members and dramatically simplify the current salary step ladder, which consisted of a complicated matrix of 36 steps each for six different grades. The union negotiators now had to convince their membership that the agreement was the best deal that could be achieved, and then ratify the agreement through a membership vote.

The challenge was how to efficiently and clearly inform members with information customized for their specific situation: each employee, depending on their current salary and their future accumulation of "Achievement Credits" could go on to have as many as six different outcomes over the three years the agreement would govern. AFT and Local 279 wanted a clear way to display this information to members so that they could understand what factors would affect a member's compensation in years 1, 2, and 3 of the agreement. The changes to compensation could not be calculated with a simple formula, as the old and new salary scales did not match up neatly.

The Calculator

Although the AFT expected that most of the viewers of the compensation calculator would be using desktop browsers, it was a requirement that the site be clear, legible, and usable on mobile browsers.

You can see the result at the CTU Salary Calculator site. Five Tool Development built this project for the AFT and CTU using Rails and Bootstrap. The site is deployed to Heroku to minimize any ongoing cost for the AFT as they host the site for continuing member education.

Bootstrap helped us quickly build a site that would behave well on a variety of mobile devices. However, most of our styling obstacles before launch came from some issues that the current version of Bootstrap has with nested rows and wells. In the desktop version of the results, you can see the nested wells in the layout.

The upcoming Bootstrap 3 release looks like it solves many of these building issues, and incorporates flat design by default, making it easier for developers to choose whether they want to have a flat or shiny design without having to undo lots of styling code. We're looking forward to its release later this year.

Success for the AFT

The agreement passed a vote by the union last week. We congratulate the AFT and Local 279 on their accomplishment.

[fivetool]

A Ruby Summer Reading List

Books are not a great way to learn basic programming technique (your coworkers and the Internet are your best friends there), but they can be a great way to consume and digest the philosophy and principles that drive other developers' work. Since I'm a huge nerd, and still have (mostly) positive feelings about school, I wanted to pass on my favorite books that have read since starting Five Tool Development.

Here's a list of books I read over the past year that have helped me to become a better coder:

Practical Object-Oriented Ruby Design (still working on this one)

The Rails View: Create a Beautiful and Maintainable User Experience

Ruby Science (still in progress, but you can buy it and see the work as it is written and edited)

RubyMotion: iOS Development With Ruby

Objects on Rails

Backbone.js on Rails

The Lean Startup (not about code, but presses home the message of "always be shipping")

In a follow-up post, I'll link to the best blogs and conference talks I've seen this year.

[fivetool]

Flatstrap in the pipeline

I'm a huge fan of Twitter Bootstrap. Being able to build a quick basic responsive scaffold for a Rails project is a huge help during the prototyping phase. For those projects where there isn't a separate budget for a mobile stylesheet, Bootstrap's responsive features provide developers with the capability to add some screen dimension-dependent behaviors. Bootstrap is easy to add to Rails with the gem twitter-bootstrap-rails. The gem provides some generators and view helpers that help integrate Bootstrap's features such as modal dialogs and breadcrumbs with Rails.

Non-designers don't use this term, but occasionally I get a response that Bootstrap-based prototypes are a bit too "lickable". For occasions when I need a design with more of a flat aesthetic but you still want the structure and JavaScript plugins from Bootstrap, there's LittleSpark's Flatstrap. Flatstrap is the latest Bootstrap with the rounded corners and gradients removed.

This weekend I pushed out the first version of flatstrap-rails. Flatstrap takes advantage of the helpers and generators of twitter-bootstrap-rails, but includes the Flatstrap CSS in the Rails 3.1 asset pipeline. Give it a try for those Rails projects where you want a flatter look.

[fivetool]

Loved the description at the end about why screenwriters prefer Courier due to the weight of screenplay text and the need for whitespace.

[fivetool]

Sydney knows your alias

Over the weekend I was working on a system to process my zsh aliases file to put the commands and their comments into HTML for cheaters. I wanted my aliases cheatsheet to be easy to synchronize with current alias file, because once they fall out of sync I will just stop using the cheatsheet at all.

The tool I built is Sydney, a Ruby gem that uses a custom Treetop grammar to parse shell alias files. Treetop is domain-specific language (DSL) for writing parsers. Grammars use a combination of regular expressions and some Treetop-specific rules to help distinguish all the elements and syntax in your input from each other.

When Treetop parses input, it creates a tree of notes. Each node type in your tree is a subclass of Treetop::Runtime:SyntaxNode. For any of these node types defined in your grammar, you can define custom node extension methods. The node extension methods have access to declared component pieces of the node, including the enclosed text and any children nodes. In the case of alias definitions, this makes it easy to separate the 'alias' from the alias definition itself, and to print the shortcut and aliased command separately or in combination as needed. The hierarchy of nodes in the tree created by Sydney is Document -> Section -> SectionComment / AliasEntry -> AliasComment / AliasDefinition.

Sydney will organize comments along with the alias declarations, making output to another format like HTML easy. Group aliases into sections by starting section heading comments with a double-bang ('##'). Any comments preceding an alias will be tied to the alias definition in an AliasEntry node. Alias definitions can be printed in a custom format (omitting the 'alias' portion of the definition) easily.

Sydney helps me turn a portion of an alias file that looks like this:

## Unix # Continuously tail file alias tlf="tail -f" # Create a directory, do not raise an error if the directory already exists alias mkdir='mkdir -p'

Into this HTML:

<div class="inner">    <header><h4>Unix</h4></header>      <dl>        <dt><code>tlf="tail -f"</code></dt>        <dd>Continuously tail file        <dt><code>mkdir='mkdir -p'</code></dt>        <dd>Create a directory, do not raise an error if the directory already exists</dd>      </dl>    </header> </div>

Give it a try with your own alias file, and start making better use of cheatsheets as part of a new year of better development habits.

[fivetool]

Quiet Assets

One of my favorite gems that I like to add to any Rails project I'm working on is Quiet Assets. Quiet Assets helps solve a problem in development where the Rails asset pipeline is serving up each asset separately, and the log gets quite crowded with mostly useless information about each asset's request and response from the server.

This cruft makes the logs hard to read. It takes up needless space and obscures what's really going on in your application. Fortunately, the quiet_assets gem solves this problem with minimal setup. Just add gem 'quiet_assets' to your development group in your Gemfile, and watch as your logs are now populated with much more relavant information.

[fivetool]

Our new logo.