Haskell language binding for IronMQ. IronMQ is an elastic message queue for managing data and event flow within cloud applications and between systems. See How It Works

Getting Started

Get credentials

To start using iron_mq_python, you need to sign up and get an OAuth2 token.

1. Go to http://iron.io/ and sign up.
2. Get an OAuth2 Token at http://hud.iron.io/tokens

Install iron_mq_haskell

cabal install iron-mq

Configure

Create a client which stores your authentication information and server settings/

client = Client {
    server = "mq-aws-us-east-1.iron.io",
    porjectID = "500f7b....b0f302e9",
    token = "Et1En7.....0LuW39Q",
    api_version="1"
}

The Basics

Listing queues

queues :: Client -> QueueSummary
queues client

returns list of queue names available to the client.

we get a specific queue by name:

getQueue :: Client -> QueueName -> IO Queue
myQueue = getQueue client "test_queue"

Push messages on the queue

We can change the default options of a message like so:

postMessages :: Client -> QueueName -> [Message] -> IO IronResponse
postMessages client "queueName" [message {body = "message1"}, message {body = "message2"}]

We can change the default settings for a message like so:

unorthoDoxMessage = message {
    body = "axxon body",
    timeout = 120 -- Timeout, in seconds. After timeout, item will be placed back on queue. Defaults to 60.
    delay = 5 -- The item will not be available on the queue until this many seconds have passed. Defaults to 0.
    expiresIn = 2*24*3600 -- How long, in seconds, to keep the item on the queue before it is deleted.
}

main = postMessage "queueName" [unorthodoxMessage]

Pop messages off the queue

getMessages :: Client -> QueueName -> IO MessageList
getMessages client "queneName"
{- 
MessageList 
    {
        messages = [Message {mId = Just "...", mBody = "Word up!", mTimeout = Just 60, mReservedCount = Just 1}]
    }
-}

Set max to the number of messages to return, 1 by default. A timeout parameter can be used to specify a per-message timeout, or the timeout the message was posted with will be used.

When you pop/get a message from the queue, it will NOT be deleted. It will eventually go back onto the queue after a timeout if you don't delete it (default timeout is 60 seconds).

Get message by id

getMessageByID :: Client -> QueueName -> ID -> IO Message
main = getMessageById client "test_queue" "1234567789abcdef"
{-
    Message {mId = Just "...", mBody = "Hey yo!", mTimeout = Just 60, mReservedCount = Just 1}
-}

Delete messages from the queue

deleteMessages :: Client -> QueueName -> [ID] -> IO IronResponse
deleteMessages client "test_queue" ["123456789abcdef", "fedcba987654321"]

Clear a queue

clear :: Client -> QueueName -> IO IronResponse
clear client "test_queue"

Get queue size, id, total_messages and whole info

main = do
-- | getQueue client queueName
myQueue <-  getQueue client queueName
{-
Queue {
    qId = Just "541451a958a847405bfa6316",
    qProjectId = "53f691bd45d4960005000082",
    qName = "test_queue",
    qSize = Just 1,
    qTotalMessages = Just 8,
    qSubscribers = Nothing,
    qRetries = Nothing,
    qPushType = Nothing,
    qRetriesDelay = Nothing
}
-}

-- | qSize queue
qSize myQueue -- Just 1

-- | qName queue
qName myQueue -- "test_queue"

-- | qTotalMessages queue
qTotalMessages -- Just 8

-- | qID queue
qID myQueue -- "541451a958a847405bfa6316"

Peek at messages

To view messages without reserving them, use peek:

peek :: Client -> QueueName -> Int -> IO MessageList
peek client "test_queue" 10
{-
    MessageList {messages = [Message {mId = Just "...", mBody = "Word up!", mTimeout = Just 60, mReservedCount = Just 1}]}
-}

The third parameter is an integer specifying the maximum number of messages to retrieve.

Touch a message

To extend the reservation on a reserved message, use touch. The message reservation will be extended by the message's timeout.

touch :: Client -> QueueName -> ID -> IO IronResponse
touch client "test_queue" messageID

Release a reserved message

To release a message that is currently reserved, use release:

release :: Client -> QueueName -> ID -> Int -> IO IronResponse
release client "test_queue" "123456789abcdef" 120 -- message will be released after delay seconds

The last parameter is the delay time before the message is released.

Delete a queue

To delete a queue, use deleteQueue:

-- | deleteQueue client queueName
deleteQueue client "test_queue"

Push Queues

Update Queue Information

To update the queue's push type and subscribers, use update:

update :: Client -> QueueName -> [Subscriber] -> String -> IO Response
update client "test_queue" [subscriber {url = "http://endpoint1.com"}, subscriber {url = "https://end.point.com/2"}] "unicast"

The last parameter is the broadcast type (either "unicast" or "multicast")

Add subscribers to a push queue

addSubscribers :: Client -> QueueName -> [Subscriber] -> IO IRonResponse
addSubscribers client test_queue [subscriber {url = "http://endpoint1.com"}, subscriber {url = "https://end.point.com/2"}])

Remove subscribers from a push queue

removeSubscribers :: Client -> QueueName -> [Subscriber]
main = removeSubscribers client "test_queue" [subscriber {url = "http://endpoint1.com"}, subscriber {url ="https://end.point.com/2"})

Get the push statuses of a message

getMessagePushStatuses :: Client -> QueueName -> ID -> IO SubscriberList
getMessagePushStatuses client "test_queue" "123456789abcdef"
{-
    subscriberList {
    subscribers = [Subscriber {retriesDelay = Just 60, retriesRemaining" = Just 2, statusCode = Just 200, status = Just "deleted", "url": "http://endpoint1.com", "id": "52.."}, ...]}
-}

Delete a pushed message

If you respond with a 202 status code, the pushed message will be reserved, not deleted, and should be manually deleted. You can get the message ID and subscriber ID from the push message's headers.

deleteMessagePushStatus :: Client -> QueueName -> MessageID -> [SuscriberID] -> IO IronResponse
main = deleteMessagePushStatus client "test_queue" "123456789abcdef" "987654321fedcba"

Pull queues

Add alerts to a queue

fixed_desc_alert = alert {type = "fixed", direction = "desc", trigger = 1000}
progressive_asc_alert = alert {type = "progressive", direction = "asc", trigger= 10000}
addAlerts :: Client -> QueueName -> [Alert] -> IO IronResponse
addAlerts client "test_queue" ([fixed_desc_alert, progressive_asc_alert])

Update alerts in a queue

progressive_asc_alert = alert {type = "progressive", direction = "asc", trigger = 5000, queue = "q"}
updateAlerts :: Client -> QueueName -> [Alert] -> IO IronResponse
updateAlerts client "test_queue" ([progressive_asc_alert])

Remove alerts from a queue

removeAlerts :: Client -> QueueName -> [AlertID] -> IO IronResponse
main = removeAlerts client "test_queue" (['5305d3b5a3e920763013c796', '513015d32b5a3e763013c796'])

Full Documentation

You can find more documentation here:

• http://iron.io
• http://dev.iron.io