• Stars
    star
    79
  • Rank 408,196 (Top 9 %)
  • Language
    Go
  • License
    MIT License
  • Created about 12 years ago
  • Updated over 6 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Iron.io API libraries

Iron.io Go Client Library

IronMQ

IronMQ is an elastic message queue for managing data and event flow within cloud applications and between systems.

The full API documentation is here and this client tries to stick to the API as much as possible so if you see an option in the API docs, you can use it in the methods below.

You can find Go docs here.

Getting Started

Get credentials

To start using iron_go, you need to sign up and get an oauth token.

  1. Go to http://iron.io/ and sign up.
  2. Create new project at http://hud.iron.io/dashboard
  3. Download the iron.json file from "Credentials" block of project

--

Configure

1. Reference the library:

import "github.com/iron-io/iron_go/mq"

2. Setup your Iron.io credentials

3. Create an IronMQ client object:

queue := mq.New("test_queue");

The Basics

Get Queues List

queues, err := mq.ListQueues(0, 100);
for _, element := range queues {
	fmt.Println(element.Name);
}

--

Get a Queue Object

You can have as many queues as you want, each with their own unique set of messages.

queue := mq.New("test_queue");

Now you can use it.

--

Post a Message on a Queue

Messages are placed on the queue in a FIFO arrangement. If a queue does not exist, it will be created upon the first posting of a message.

id, err := q.PushString("Hello, World!")

--

Retrieve Queue Information

info, err := q.Info()
fmt.Println(info.Name);

--

Get a Message off a Queue

msg, err := q.Get()
fmt.Printf("The message says: %q\n", msg.Body)

--

Delete a Message from a Queue

msg, _ := q.Get()
// perform some actions with a message here
msg.Delete()

Be sure to delete a message from the queue when you're done with it.

--

Queues

Retrieve Queue Information

info, err := q.Info()
fmt.Println(info.Name);
fmt.Println(info.Size);

QueueInfo struct consists of the following fields:

type QueueInfo struct {
	Id            string            `json:"id,omitempty"`
	Name          string            `json:"name,omitempty"`
	PushType      string            `json:"push_type,omitempty"`
	Reserved      int               `json:"reserved,omitempty"`
	RetriesDelay  int               `json:"retries,omitempty"`
	Retries       int               `json:"retries_delay,omitempty"`
	Size          int               `json:"size,omitempty"`
	Subscribers   []QueueSubscriber `json:"subscribers,omitempty"`
	TotalMessages int               `json:"total_messages,omitempty"`
	ErrorQueue    string            `json:"error_queue,omitempty"`
}

--

Delete a Message Queue

deleted, err := q.Delete()
if(deleted) { 
  fmt.Println("Successfully deleted")
} else {
  fmt.Println("Cannot delete, because of error: ", err)
}

--

Post Messages to a Queue

Single message:

id, err := q.PushString("Hello, World!")
// To control parameters like timeout and delay, construct your own message.
id, err := q.PushMessage(&mq.Message{Timeout: 60, Delay: 0, Body: "Hi there"})

Multiple messages:

You can also pass multiple messages in a single call.

ids, err := q.PushStrings("Message 1", "Message 2")

To control parameters like timeout and delay, construct your own message.

ids, err = q.PushMessages(
	&mq.Message{Timeout: 60, Delay: 0,  Body: "The first"},
	&mq.Message{Timeout: 60, Delay: 10, Body: "The second"},
	&mq.Message{Timeout: 60, Delay: 10, Body: "The third"},
	&mq.Message{Timeout: 60, Delay: 0,  Body: "The fifth"},
)

Parameters:

  • Timeout: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. Default is 60 seconds. Minimum is 30 seconds. Maximum is 86,400 seconds (24 hours).

  • Delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).

--

Get Messages from a Queue

msg, err := q.Get()
fmt.Printf("The message says: %q\n", msg.Body)

When you pop/get a message from the queue, it is no longer on the queue but it still exists within the system. You have to explicitly delete the message or else it will go back onto the queue after the timeout. The default timeout is 60 seconds. Minimal timeout is 30 seconds.

You also can get several messages at a time:

// get 5 messages
msgs, err := q.GetN(5)

And with timeout param:

messages, err := q.GetNWithTimeout(4, 600)

Touch a Message on a Queue

Touching a reserved message extends its timeout by the duration specified when the message was created, which is 60 seconds by default.

msg, _ := q.Get()
err := msg.Touch()

There is another way to touch a message without getting it:

err := q.TouchMessage("5987586196292186572")

--

Release Message

msg, _ := q.Get()
delay  := 30
err := msg.release(delay)

Or another way to release a message without creation of message object:

delay := 30
err := q.ReleaseMessage("5987586196292186572", delay)

Optional parameters:

  • delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).

--

Delete a Message from a Queue

msg, _ := q.Get()
// perform some actions with a message here
err := msg.Delete()

Or

err := q.DeleteMessage("5987586196292186572")

Be sure to delete a message from the queue when you're done with it.

--

Peek Messages from a Queue

Peeking at a queue returns the next messages on the queue, but it does not reserve them.

message, err := q.Peek()

There is a way to get several messages not reserving them:

messages, err := q.PeekN(50)
for _, m := range messages {
  fmt.Println(m.Body)
}

And with timeout param:

messages, err := q.PeekNWithTimeout(4, 600)

--

Clear a Queue

err := q.Clear()

Add an Alert to a Queue

Check out our Blog Post on Queue Alerts.

Alerts have now been incorporated into IronMQ. This feature lets developers control actions based on the activity within a queue. With alerts, actions can be triggered when the number of messages in a queue reach a certain threshold. These actions can include things like auto-scaling, failure detection, load-monitoring, and system health.

You may add up to 5 alerts per queue.

Required parameters:

  • type: required - "fixed" or "progressive". In case of alert's type set to "fixed", alert will be triggered when queue size pass value set by trigger parameter. When type set to "progressive", alert will be triggered when queue size pass any of values, calculated by trigger * N where N >= 1. For example, if trigger set to 10, alert will be triggered at queue sizes 10, 20, 30, etc.
  • direction: required - "asc" or "desc". Set direction in which queue size must be changed when pass trigger value. If direction set to "asc" queue size must growing to trigger alert. When direction is "desc" queue size must decreasing to trigger alert.
  • trigger: required. It will be used to calculate actual values of queue size when alert must be triggered. See type field description. Trigger must be integer value greater than 0.
  • queue: required. Name of queue which will be used to post alert messages.
err := q.AddAlerts(
  &mq.Alert{Queue: "new_milestone_queue", Trigger: 10, Direction: "asc",  Type: "progressive"},
  &mq.Alert{Queue: "low_level_queue",     Trigger: 5,  Direction: "desc", Type: "fixed" })

Update alerts in a queue

err := q.AddAlerts(
  &mq.Alert{Queue: "milestone_queue", Trigger: 100, Direction: "asc",  Type: "progressive"})

Remove alerts from a queue

You can delete an alert from a queue by id:

err := q.RemoveAlert("532fdf593663ed6afa06ed16")

Or delete several alerts by ids:

err := q.RemoveAlerts("532f59663ed6afed16483052", "559663ed6af6483399b3400a")

Also you can delete all alerts

err := q.RemoveAllAlerts()

Please, remember, that passing zero of alerts while update process will lead to deleating of all previously added alerts.

q.AddAlerts(
  &mq.Alert{Queue: "alert1", Trigger: 10, Direction: "asc", Type: "progressive"},
  &mq.Alert{Queue: "alert2", Trigger: 5,  Direction: "desc", Type: "fixed" })
info, _ := q.Info() // 2

q.UpdateAlerts()
info, _ = q.Info()  // 0

--

Push Queues

IronMQ push queues allow you to setup a queue that will push to an endpoint, rather than having to poll the endpoint. Here's the announcement for an overview.

Update a Message Queue

queueInfo := mq.QueueInfo{
	//...
} 
info, err := q.Update(queueInfo);

QueueInfo struct consists of following fields:

type QueueInfo struct {
	PushType      string            `json:"push_type,omitempty"`
	RetriesDelay  int               `json:"retries,omitempty"`
	Retries       int               `json:"retries_delay,omitempty"`
	Subscribers   []QueueSubscriber `json:"subscribers,omitempty"`
	// and some other fields not related to push queues
}

The following parameters are all related to Push Queues:

  • push_type: Either multicast to push to all subscribers or unicast to push to one and only one subscriber. Default is multicast.
  • retries: How many times to retry on failure. Default is 3. Maximum is 100.
  • retries_delay: Delay between each retry in seconds. Default is 60.
  • subscribers: An array of QueueSubscriber This set of subscribers will replace the existing subscribers. To add or remove subscribers, see the add subscribers endpoint or the remove subscribers endpoint.

QueueSubscriber has the following structure:

type QueueSubscriber struct {
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers,omitempty"`
}

--

Set Subscribers on a Queue

Subscribers can be any HTTP endpoint. push_type is one of:

  • multicast: will push to all endpoints/subscribers
  • unicast: will push to one and only one endpoint/subscriber
err := q.AddSubscribers(
	"http://mysterious-brook-1807.herokuapp.com/ironmq_push_3", 
	"http://mysterious-brook-1807.herokuapp.com/ironmq_push_4")

--

Get Message Push Status

After pushing a message:

subscribers, err := message.Subscribers()

Returns an array of subscribers with status.

--

Revert Queue Back to Pull Queue

If you want to revert you queue just update push_type to 'pull'.

q.Update(mq.QueueInfo{
	PushType: "pull",	
});

--

Further Links


Β© 2011 - 2014 Iron.io Inc. All Rights Reserved.

More Repositories

1

functions

IronFunctions - the serverless microservices platform by
Go
3,182
star
2

dockers

Uber tiny Docker images for all the things.
HTML
1,591
star
3

dockerworker

The new IronWorker workflow examples. Test locally, then upload and start queuing jobs!
Scala
233
star
4

functions-ui

User interface for IronFunctions - http://github.com/iron-io/functions
Vue
95
star
5

iron_mq_php

PHP client for IronMQ.
PHP
89
star
6

lambda

All Iron.io open source AWS Lambda code.
Go
69
star
7

iron_worker_ruby_ng

Next Gen Ruby gem for IronWorker
Ruby
58
star
8

iron_worker_php

PHP client for IronWorker
PHP
56
star
9

iron_mq_node

CoffeeScript
51
star
10

laraworker

Easily add IronWorker to Laravel Applications
PHP
45
star
11

iron_mq_java

Java library for IronMQ.
Java
44
star
12

iron_worker_python

Python client for IronWorker
Python
42
star
13

iron_worker_ruby

Official IronWorker gem.
Ruby
39
star
14

iron_mq_ruby

Ruby library for IronMQ.
Ruby
35
star
15

ironcli

Command line tool for the Iron.io platform.
Go
35
star
16

iron_mq_python

Python client for IronMQ.
Python
35
star
17

docs

Iron.io Dev Center documentation.
CSS
30
star
18

iron_celery

IronMQ broker and IronCache results store for Python's Celery project.
Python
30
star
19

iron_worker_rails_example

Rails Application Demonstrating IronWorker Usage
Ruby
26
star
20

iron_worker_node

CoffeeScript
25
star
21

rest

HTTP/REST client wrapper that provides a standard interface for making http requests using different http clients.
Ruby
23
star
22

iron_core_php

PHP
19
star
23

iron_dotnet

C#
18
star
24

picasso

Project Picasso (Functions-as-a-Service) for OpenStack
17
star
25

heroku_sinatra_example

This is an example Sinatra application ready to run on Heroku using IronWorker and IronMQ Add Ons.
Ruby
17
star
26

iron_go3

Go lib for IronMQ v3.
Go
15
star
27

iron_cache_php

PHP
15
star
28

iron_cache_ruby

Ruby client for IronCache
Ruby
14
star
29

runner

Go
11
star
30

iron_worker_java

Java
9
star
31

iron_cache_python

Python
9
star
32

functions_js

JavaScript library for IronFunctions.
JavaScript
9
star
33

ironcasts-series-1

All code examples used in IronWorker 101 in IronCast Episode 1 to Episode 4
Ruby
8
star
34

slackbots

A repository of Slack bots that run on IronWorker
Ruby
8
star
35

abt

ABT - Always Be Testing - A ruby gem that uses IronWorker to continously run tests.
Ruby
8
star
36

functions_go

Go library for IronFunctions.
Go
7
star
37

golog

Simple logging helper for Go.
Go
7
star
38

iron_mq_go

DEPRECATED! Use https://github.com/iron-io/iron_go
Go
7
star
39

iron_core_ruby

Ruby
7
star
40

iron_mq_clojure

Clojure client for IronMQ
Clojure
7
star
41

iron_cache_rails

Rails cache store and session store using IronCache by www.iron.io
Ruby
7
star
42

heroku-iron-celery-demo

A demo of running Celery on Heroku. Downloads an RSS feed and parses the items. http://iron-celery-demo.herokuapp.com
JavaScript
7
star
43

workers

Ruby
6
star
44

iron_core_python

Python
6
star
45

iron_core_node

CoffeeScript
6
star
46

ironmq-openshift-quickstart

Shell
5
star
47

ironcasts-series-1-samplecode

Ruby
5
star
48

gosqs

SQS interface for Go
Go
5
star
49

issues

For Iron.io services issue tracking. Public facing issue tracking for behind the scenes issues.
5
star
50

rackspace-django-demo

Python
5
star
51

lambda-vs-ironworker

Examples of using Lambda and IronWorker to do the same thing.
JavaScript
4
star
52

functions_ruby

Ruby library for IronFunctions.
Ruby
4
star
53

newrelic_platform

Ruby library for the new New Relic Platform - http://newrelic.com/platform
Ruby
4
star
54

image_processor

PHP
4
star
55

glock

Boom
Go
4
star
56

rails-nginx-unicorn

A dead simple base image for dockerizing Rails apps using unicorn/foreman/nginx
Nginx
4
star
57

iron_cache_dotnet

C#
3
star
58

microcontainers

Reference site for Microcontainers.
3
star
59

koders

A Ruby app using Sinatra and IronWorker to pull top Stackoverflow users then finds the languages they use on Github to get the top languages for the top SO users.
JavaScript
3
star
60

iron_combine

Ruby
3
star
61

iron-worker-examples

Top uses of IW with examples
HTML
3
star
62

gridiron

Python
2
star
63

heroku_iron_boomi_salesforce

Heroku -> Iron.io -> Boomi -> Salesforce Integration Demo
JavaScript
2
star
64

python-picassoclient

OpenStack SDK & CLI plugin for Picasso (Functions-as-a-Service)
2
star
65

splunk-ironmq-mi

Python
2
star
66

simple_worker_redirect

Redirects SimpleWorker to IronWorker
Ruby
2
star
67

logspout-statsd

A statsd adapter for logspout.
Go
2
star
68

worker_ruby

Ruby sdk for Titan.
Ruby
2
star
69

iron_cache_node

CoffeeScript
1
star
70

newrelic_parse_plugin

A New Relic Platform agent for Parse.
Ruby
1
star
71

maven

For hosting our java jars for Maven central.
Shell
1
star
72

worker_go

Go library for Titan.
Go
1
star
73

gobson_temp

Go
1
star
74

fn-go

A library for handling Go Language functions input and output
Go
1
star
75

monger

Go
1
star
76

ironmq-openshift-cartridge

Ruby
1
star
77

r-lang-worker-example

Hello world for R on IronWorker
R
1
star
78

iron_twilio_insanity

Iron.io and Twilio present: Beachbody Insanity Reminder
Ruby
1
star
79

codegen

JavaScript
1
star
80

sfbeta

Ruby
1
star
81

iron_mq_rust

βš™οΈ Rust client for IronMQ
Rust
1
star
82

iron_mq_groovy

Groovy client for IronMQ
Groovy
1
star
83

worker_js

JavaScript
1
star
84

platform_performance

PHP
1
star
85

function-fork-me

An example function to fork and modify.
JavaScript
1
star
86

newrelic_ironmq_plugin

A New Relic Platform agent for IronMQ.
Ruby
1
star
87

iron_core_java

1
star
88

iron_consumer

Ruby
1
star
89

php_example_app

A PHP application that uses Iron.io services.
PHP
1
star
90

build_worker

Standard build worker for doing remote builds on IronWorker.
Ruby
1
star
91

newrelic_airbrake_plugin

A New Relic Platform agent for Airbrake.
Ruby
1
star
92

buckets

Go
1
star
93

ironfunctions-murano

Murano application package for IronFunctions on OpenStack
1
star
94

newrelic_saas_agent

Template for easily creating NewRelic Platform agents for SaaS services. No servers required.
Ruby
1
star