A service that sits on the ESB and expands shortened URLs into their real URLs
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
config
.gitignore
LICENCE
README
TODO

README

Epanding URLs
==============

A service that sits on the enterprise service bus and swaps shortened URLs for
their actual destinations.


Service Configuration
---------------------

There are two pretty small files that you'll need to create. Both these files
have example files in the config/ directory.

file:config/message_queue.yml

  SMQueue configuration for the input of this service. SMQueue configuration
  is a fairly in-depth subject but if you're already using it elsewhere you
  can pretty much copy and paste the details.

  If you'd just like to use Starling then the example configuration file
  contains enough to get you started. Copy that to config/message_queue.yml
  and start Starling.


Using the service
-----------------

If you use this service you'll be using Enterprise Integration Patterns for:
Request-Reply, Return-Address and Correlation-Identifier. How fancy is that?

I'll assume you're familiar with a message bus and SMQueue and skip straight
to how to use this service.

1. Pick a job identifier. A job is a single request to geocode an address.
   This identifier will be used in all communications with the service about
   your geocoding request. Make it good and unique - don't want to get your
   jobs mixed up or you'll end up getting back documents that have completely
   different text rather than just having their URLs expanded. Make it hard to
   guess too - don't make it sequential! I'd normally use something like the
   UUID gem to generate these identifiers. It needs to be a String.

   When you request that an expansion is performed you'll tell the service
   what this number is by calling it a request_id. When the service sends
   you a reply you'll get exactly the same identifier back but it'll be
   called the correlation_id.

2. Pick a reply channel. Somehow you're going to want to find out what the
   service translates the URLs to. At the moment the reply channel will
   receive messages on the same broker that the URL expansion service receives
   requests from. I'm not sure it that will always be the case. See the
   documentation for your broker if you'd like to move the message from here
   to somewhere else.

   Normally I'd pick a queue name that is unique to the application that
   requests the expansions and have a consumer listening there. Something
   like `barkingiguana.messages.expanded_urls`. How you specify your reply
   channel depends on your broker implementation.

3. Send your request. The service is expecting JSON that looks like this:

    {
      request_id: "88d55b90-29e7-012c-0810-001b63b8611d",
      reply_to: "barkingiguana.messages.expanded_urls",
      document: "Lorem ipsum dolor http://tinyurl.com/o3yn98"
    }

4. Receive a response on the reply channel. Something somewhere that you
   write must be listening to this! Responses will be in JSON.

   Replies look like this:

    {
      correlation_id: "88d55b90-29e7-012c-0810-001b63b8611d",
      document: "Lorem ipsum dolor http://barkingiguana.com"
    }

   Sometimes things go wrong - maybe the one of the required services couldn't
   be reached. If that happens you'll get a message that looks a like this:

    {
      correlation_id: "88d55b90-29e7-012c-0810-001b63b8611d",
      message_type: "error"
      message: "service down"
    }

  These will be put on the same reply channel as successful responses. It's
  your job to find out if a message is an error or not before processing it.


Examples
--------

file:bin/expand_urls

  Reads a document from STDIN, asks the service to expand any URLs it, then
  prints the result to STDOUT.

  To run the example first configure the service as described above then run:

    bin/expand_urls < document

To classify the README you might run:

    bin/expand_urls < README


Contributing
------------

See file:TODO for a number of things that are still outstanding. If you fancy
tackling any of these please do. Fire me a pull request when you're done.


Authors
-------

Craig R Webster <http://barkingiguana.com/~craig>


Licence
-------

Copyright (C) 2009 Craig R Webster. Release under the MIT licence.

See file:LICENCE for the full text of the MIT Licence.