= Oso

* http://github.com/audiosocket/oso

== Description

Audiosocket's minimal URL shortener. It's named "oso" because those
three letters look a bit like our logo.

== Configuring

We deploy 1.9.2, so Oso expects it. It shouldn't be too hard to port
to 1.8 if you feel the need.

If you install the deps in the <tt>.gems</tt> file you can run
<tt>rackup</tt> by itself.

Oso needs Redis. Set the <tt>OSO_REDIS_URL</tt> environment variable,
which defaults to <tt>redis://localhost:6379</tt>. All keys are
namespaced under <tt>oso:</tt>.

== Using

There's a static HTML index that'll let you shorten URLs by hand, but
we mostly use Oso inside other apps. To shorten a URL, <tt>POST</tt>
to <tt>/</tt> with a <tt>url</tt> parameter. It'll return a
<tt>201</tt> with the shortened URL in the body.

You can optionally pass a <tt>life</tt> parameter, which is the
lifetime of the shortened URL in seconds.

You can optionally pass a <tt>limit</tt> parameter, which is the number
of times you want the shortened URL to work. After the limit is
reached <tt>404</tt>'s are returned.

You can optionally pass a <tt>name</tt> parameter, which will be used
instead of generating a token for the shortened URL. Names can only
contain alphanumerics and dashes.

=== From Ruby

If you install the <tt>oso</tt> RubyGem:

    require "oso"

    Oso.shorten "github.com"             # => "http://oso.local/Acf"
    Oso.shorten "github.com", life: 30   # => "http://oso.local/Ad0"

Set the <tt>OSO_URL</tt> environment variable to control where the
client looks for the server, or see the RDocs for information on
creating multiple instances.

== Deploying

If you fork it, Oso is already prepped for Heroku. It has an
up-to-date <tt>.gems</tt> manifest, and it'll use the
<tt>REDISTOGO_URL</tt> env var if it exists.

If you'd like to use it in your own <tt>config.ru</tt> file via the
gem, you'll need to provide the server's dependencies yourself. The
gem doesn't express any runtime dependencies since it's primarily used
as a client.

Assuming you've provided the server dependencies (see the
<tt>.gems</tt> file), using the gem from Rack is simple:

    require "oso/server"
    run Sinatra::Application

Pull requests making Oso a mountable <tt>Sinatra::Base</tt> app are
most welcome.

== License

Copyright 2011 Leopona Inc.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.