wooo
Hey everyone,
I’m excited to announce the release of Koala 1.2! This is a big update with a lot of cool features, plus support for Facebook’s upcoming authentication changes.
Read through this rather long announcement at your leisure and enjoy the new version 
October 1st
Koala 1.2 supports all of Facebook’s new authentication schemes, which will be introduced on October 1, 2011; the old Javascript library and older authentication schemes will be deprecated at the same time. If you have the appropriate calls to get_user_info_from_cookies (apps using the Javascript SDK) and/or parse_signed_params (for Canvas and tab apps), your application should work without a hitch.
To test your application ahead of time, upgrade to Koala 1.2 (see below) and configure your application according to Facebook’s OAuth 2.0 and HTTPS Migration guide.
Note: in their new secure cookie format, Facebook provides an OAuth code, which Koala automatically exchanges for an access token. Because this involves a call to Facebook’s servers, you should consider storing the user’s access token in their session and only calling get_user_info_from_cookies when necessary (access_token not present, you discover it’s expired, every 30 minutes, etc.). Otherwise, you’ll be calling out to Facebook each time the user loads a page, slowing down your site.
Faraday
With 1.2, Koala uses the Faraday library to make HTTP requests, replacing our homebrew Typhoeus and Net::HTTP adapters. This is a big change, so let’s go over it in detail.
What’s this about?
Faraday is a modular framework, patterned on Rack, which makes it easy to control how your app makes HTTP requests. By switching to Faraday, we get Koala out of the business of choosing which libraries and features to support, giving you more choices and letting us focus on building the best Facebook library we can.
How does this affect me?
Good news! Based on the 1.2 betas, this change should be non-breaking for almost everyone. All the old settings are still supported, though you’ll see deprecation warnings. There’s now only a single Koala::HTTPService module, which handles all communication.
Almost everyone?
Since Faraday settings are global (affecting other gems that use it, like Twitter), Koala no longer uses Typhoeus by default. To use that or any other supported library instead of Net::HTTP (the default), just set the default Faraday adapter:
# this could go in an initializer Faraday.default_adapter = :typhoeus
Also, if you’re hooking directly into Koala’s HTTPService framework, you’ll probably have to make some changes; check out the Extensions wiki page to learn more about the new internals.
People like options, right?
Faraday gives you a huge range of options, which you can provide either per-request or globally by setting the new Koala::HTTPService.http_options hash. The format for the hash maps directly to what Faraday expects, so if you haven’t used Faraday, check out the Koala wiki for some examples.
We still support all the old individual options on Koala.http_service (proxy, timeout, etc.), which read from and write to the new hash.
Even more sweetly, with Faraday you can write your own middleware to really fine-tune how your requests are made. (To take just one example, I recently wrote a module to log and analyze Facebook requests made through Koala — easy as pie.) Koala provides a default middleware stack with everything you need, but you can specify your own using Koala::HTTPService.faraday_middleware.
Learn more
For more information and a complete list of how to migrate old settings, check out the HTTPService wiki page. If you have any questions, feel free to write to the Koala user’s group.
API
Koala::Facebook::API class is now the main API class, containing both Graph and REST API methods. Since the GraphAndRestAPI class showed it’s possible to offer all methods from one object, there’s no reason to force you to keep track of and instantiate three different classes to use the Facebook API. All three old classes are now aliased to API, and will remain available for the foreseeable future.
api = Koala::Facebook::API.new(my_token)
api.get_object("me")
api.fql_query("select first_name where uid = me()")
# you can even use the new Timeline API
# see https://developers.facebook.com/docs/beta/opengraph/tutorial/
@graph.put_connections("me", "namespace:action", 
bject => object_url)
Other changes
- Koala is now on Travis, passing all tests under JRuby, Rubinius, and REE, as well as Ruby 1.8.7, 1.9.2, and 1.9.3!
- (My favorite update:) The live test suite now runs by default against test users, so you can run it as frequently as you want without having to update facebook_data.yml.
- To run it against a real user, add your OAuth token/session key/OAuth code to the YAML file.
- TestUsers#update lets you update the name or password of an existing test user
- API.get_page_access_token lets you easily fetch the access token for a page you manage
- API.put_picture now accepts URLs to images in addition to files
- GraphCollection use is smarter, fixing a problem with the Ads API
Check out the changelog for a complete list of changes. The diff since 1.1 is available here.
Thanks to…
Thanks to marcgg, johnbhall, and Will S. for their help with bugs and in keeping up with Facebook changes, and to Chris and everyone at Context Optional for their support, help, and feedback.
Installation
As always:
[sudo|rvm] gem install koala
Or with Bundler:
gem "koala", "~> 1.2"
What’s Next
With 1.2 out we’ve completed most of the work we had planned for Koala; in the immediate future we’ll be working on a few remaining features, bug reports, and keeping up with Facebook (did we mention Koala already supports publishing to the Timeline?).
If you have any ideas, issues, or suggestions, feel free to let us know on Github.
Have a great week and happy coding!
Best,
Alex and the Koala team
http://github.com/arsduo/koala
