Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 359 lines (232 sloc) 12.213 kB
e836246 @iced Better docs - intoduction and code.
iced authored
1 # Introduction
e8c43db @iced Basic README.
iced authored
2
24eb269 @treeder Show the steps at the top of the README.
treeder authored
3 To run your code in cloud you need to do three things:
4
5 - **Create code package**
6 - **Upload code package**
59a050a @iced Removing trailing spaces.
iced authored
7 - **Queue or schedule tasks** for execution
24eb269 @treeder Show the steps at the top of the README.
treeder authored
8
59a050a @iced Removing trailing spaces.
iced authored
9 While you can use [REST APIs](http://dev.iron.io/worker/reference/api) for that, it's easier to use an
24eb269 @treeder Show the steps at the top of the README.
treeder authored
10 IronWorker library created specifically for your language of choice, such as this gem, IronWorkerNG.
0145138 @iced Hash calculation and refactoring..
iced authored
11
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
12 # Preparing Your Environment
e8c43db @iced Basic README.
iced authored
13
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
14 You'll need to register at http://iron.io/ and get your credentials to use IronWorkerNG. Each account can have an unlimited number of projects, so take advantage of it by creating separate projects for development, testing and production. Each project is identified by a unique project ID and requires your access token before it will perform any action, like uploading or queuing workers.
fea0859 @iced As we accept only one worker per package, can merge it automaticaly.
iced authored
15
1df1567 @benmanns Reword and fix some typos in the README.
benmanns authored
16 Also, you'll need a Ruby 1.9 interpreter and the IronWorkerNG gem. Install it using following command.
e8c43db @iced Basic README.
iced authored
17
e836246 @iced Better docs - intoduction and code.
iced authored
18 ```sh
19 gem install iron_worker_ng
e8c43db @iced Basic README.
iced authored
20 ```
21
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
22 # Creating A Worker
e836246 @iced Better docs - intoduction and code.
iced authored
23
59a050a @iced Removing trailing spaces.
iced authored
24 Each IronWorkerNG Ruby worker is just Ruby code. It can be as simple or as complex as you want. For example,
364658b @treeder Update README.md
treeder authored
25 the following is an acceptable worker:
e8c43db @iced Basic README.
iced authored
26
27 ```ruby
364658b @treeder Update README.md
treeder authored
28 puts "Hello Worker!"
e836246 @iced Better docs - intoduction and code.
iced authored
29 puts "My task_id is #{@iron_worker_task_id}"
30 puts "I got '#{params}' parameters"
31 ```
32
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
33 All output to `STDOUT` will be logged and available for your review when your worker finishes execution.
e836246 @iced Better docs - intoduction and code.
iced authored
34
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
35 # Creating The Code Package
e8c43db @iced Basic README.
iced authored
36
364658b @treeder Update README.md
treeder authored
37 Before you can run use IronWorker, be sure you've [created a free account with Iron.io](http://www.iron.io)
59a050a @iced Removing trailing spaces.
iced authored
38 and [setup your Iron.io credentials on your system](http://dev.iron.io/articles/configuration/) (either in a json
39 file or using ENV variables). You only need to do that once for your machine. If you've done that, then you can continue.
364658b @treeder Update README.md
treeder authored
40
59a050a @iced Removing trailing spaces.
iced authored
41 Since our worker will be executed in the cloud, you'll need to bundle all the necessary gems,
364658b @treeder Update README.md
treeder authored
42 supplementary data, and other dependencies with it. `.worker` files make it easy to define your worker.
e8c43db @iced Basic README.
iced authored
43
e836246 @iced Better docs - intoduction and code.
iced authored
44 ```ruby
59a050a @iced Removing trailing spaces.
iced authored
45 # define the runtime language, this can be ruby, java, node, php, go, etc.
364658b @treeder Update README.md
treeder authored
46 runtime "ruby"
47 # exec is the file that will be executed:
48 exec "hello_worker.rb"
49 ```
50
51 You can read more about `.worker` files here: http://dev.iron.io/worker/reference/worker-files/
52
53 ## Uploading the Code Package
54
59a050a @iced Removing trailing spaces.
iced authored
55 If your .worker file is called `hello.worker`, then run:
364658b @treeder Update README.md
treeder authored
56
57 iron_worker upload hello
58
59 This will upload your worker with the name "hello" so you can reference it like that when queuing up tasks for it.
0145138 @iced Hash calculation and refactoring..
iced authored
60
364658b @treeder Update README.md
treeder authored
61 ## Queue Up a Task for your Worker
62
63 You can quicky queue up a task for your worker from the command line using:
64
65 iron_worker queue hello
66
67 Use the `-p` parameter to pass in a payload:
68
69 iron_worker queue hello -p "{\"hi\": \"world\"}"
70
71 Most commonly you'll be queuing up tasks from code though, so you can do this:
72
73 ```ruby
74 require "iron_worker_ng"
75 client = IronWorkerNG::Client.new
59a050a @iced Removing trailing spaces.
iced authored
76 100.times do
364658b @treeder Update README.md
treeder authored
77 client.tasks.create("hello", "foo"=>"bar")
78 end
e836246 @iced Better docs - intoduction and code.
iced authored
79 ```
f1f599b @treeder added debug info.
treeder authored
80 ### Debugging
81
82 To get a bunch of extra output to debug things, turn it on using:
83
84 IronCore::Logger.logger.level = ::Logger::DEBUG
85
e836246 @iced Better docs - intoduction and code.
iced authored
86
87 ## IronWorkerNG::Code::Ruby API
88
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
89 The IronWorkerNG::Code::Ruby class will help you package your code for upload, but to upload it to the cloud, you'll need to use the `IronWorkerNG::Client` class.
e836246 @iced Better docs - intoduction and code.
iced authored
90
d4e3410 @iced Free-form constructor for code which can automerge worker now and ver…
iced authored
91 ### initialize(*args)
e836246 @iced Better docs - intoduction and code.
iced authored
92
d4e3410 @iced Free-form constructor for code which can automerge worker now and ver…
iced authored
93 Create new code package with the specified args.
e836246 @iced Better docs - intoduction and code.
iced authored
94
95 ```ruby
49c8c80 @iced Renaming merge_worker -> merge_exec.
iced authored
96 code_with_name = IronWorkerNG::Code::Ruby.new(:exec => 'cool_worker.rb', :name => 'CoolWorker')
97 code_with_guessed_name = IronWorkerNG::Code::Ruby.new(:exec => 'cool_worker.rb')
98 code = IronWorkerNG::Code::Ruby.new # will need to use code.merge_exec later
e836246 @iced Better docs - intoduction and code.
iced authored
99 ```
100
101 ### name()
102
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
103 Return the code package's name.
e836246 @iced Better docs - intoduction and code.
iced authored
104
105 ```ruby
106 puts code.name
107 ```
108
d4e3410 @iced Free-form constructor for code which can automerge worker now and ver…
iced authored
109 ### name=(name)
110
111 Sets the code package's name.
112
113 ```ruby
114 code.name = 'CoolWorker'
115 ```
116
e836246 @iced Better docs - intoduction and code.
iced authored
117 ### hash_string()
118
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
119 Return the hash string for the code package. If you want to prevent uploading unchanged code packages, you can use it to check if any changes were made. It's very efficient, so it shouldn't cause any performance impact.
120
e836246 @iced Better docs - intoduction and code.
iced authored
121 ```
3d721a3 @iced Renaming Package to Code.
iced authored
122 puts code.hash_string
e836246 @iced Better docs - intoduction and code.
iced authored
123 ```
124
125 ### merge_file(path, dest = '')
e8c43db @iced Basic README.
iced authored
126
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
127 Merge the file located at `path` into the code package. If `dest` is set, it will be used as the path to a directory within the zip, into which the file will be merged. If the directory does not exist, it will be automatically created.
128
e836246 @iced Better docs - intoduction and code.
iced authored
129 ```ruby
130 code.merge_file '../config/database.yml' # will be in the same directory as worker
131 code.merge_file 'clients.csv', 'information/clients' # will be in information/clients subdirectory
e8c43db @iced Basic README.
iced authored
132 ```
4ef3e86 @iced CLI session in README
iced authored
133
e836246 @iced Better docs - intoduction and code.
iced authored
134 ### merge_dir(path, dest = '')
4ef3e86 @iced CLI session in README
iced authored
135
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
136 Recursively merge the directory located at path into the code package. If `dest` is set, it will be used as the path to a directory within the zip, into which the directory specified by `path` will be merged. If `dest` is set but does not exist, it will be automatically created.
e836246 @iced Better docs - intoduction and code.
iced authored
137
138 ```ruby
139 code.merge_dir '../config' # will be in the same directory as worker
140 code.merge_dir 'lib', 'utils' # will be in utils subdirectory, accessible as utils/lib
141 ```
142
49c8c80 @iced Renaming merge_worker -> merge_exec.
iced authored
143 ### merge_exec(path, name = nil)
e836246 @iced Better docs - intoduction and code.
iced authored
144
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
145 Merge the worker located at `path`. If `name` is omitted, a camel-cased version of the file name will be used. **You can have only one worker merged per code package.**
e836246 @iced Better docs - intoduction and code.
iced authored
146
147 ```ruby
49c8c80 @iced Renaming merge_worker -> merge_exec.
iced authored
148 code.merge_exec 'my_worker.rb' # name will be MyWorker
e836246 @iced Better docs - intoduction and code.
iced authored
149 ```
150
151 ### merge_gem(name, version = '>= 0')
152
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
153 Merge a gem with dependencies. Please note that gems which contains binary extensions will not be merged for now, as binary extensions are not supported at this time; we have [a set](http://dev.iron.io/worker/reference/environment/?lang=ruby#ruby_gems_installed) of the most common gems with binary extensions preinstalled for your use. You can use version constrains if you need a specific gem version.
e836246 @iced Better docs - intoduction and code.
iced authored
154
155 ```ruby
156 code.merge_gem 'activerecord'
157 code.merge_gem 'paperclip', '< 3.0.0,>= 2.1.0'
158 ```
159
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
160 ### merge_gemfile(path, *groups)
e836246 @iced Better docs - intoduction and code.
iced authored
161
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
162 Merge all gems from specified the groups in a Gemfile. Please note that this will not auto-require the gems when executing the worker.
e836246 @iced Better docs - intoduction and code.
iced authored
163
164 ```ruby
165 code.merge_gemfile '../Gemfile', 'common', 'worker' # merges gems from common and worker groups
4ef3e86 @iced CLI session in README
iced authored
166 ```
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
167
be85ea0 @treeder Split the upload and queue parts into two sections.
treeder authored
168 # Upload Your Worker
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
169
59a050a @iced Removing trailing spaces.
iced authored
170 When you have your code package, you are ready to upload and run it on the IronWorker cloud.
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
171
172 ```ruby
459daf4 @treeder Closes #18, split code upload from task create.
treeder authored
173 # Initialize the client
d2290eb @benmanns Add missing quote in README.
benmanns authored
174 client = IronWorkerNG::Client.new(:token => 'IRON_IO_TOKEN', :project_id => 'IRON_IO_PROJECT_ID')
459daf4 @treeder Closes #18, split code upload from task create.
treeder authored
175 # Upload the code
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
176 client.codes.create(code)
459daf4 @treeder Closes #18, split code upload from task create.
treeder authored
177 ```
178
179 **NOTE**: You only need to call `client.codes.create(code)` once for each time your code changes.
180
be85ea0 @treeder Split the upload and queue parts into two sections.
treeder authored
181 # Queue Up Tasks for Your Worker
182
59a050a @iced Removing trailing spaces.
iced authored
183 Now that the code is uploaded, we can create/queue up tasks. You can call this over and over
184 for as many tasks as you want.
459daf4 @treeder Closes #18, split code upload from task create.
treeder authored
185
186 ```ruby
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
187 client.tasks.create('MyWorker', {:client => 'Joe'})
188 ```
189
07cf332 @treeder Update README.md
treeder authored
190 # The Rest of the IronWorker API
191
192 ## IronWorker::Client
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
193
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
194 You can use the `IronWorkerNG::Client` class to upload code packages, queue tasks, create schedules, and more.
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
195
196 ### initialize(options = {})
197
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
198 Create a client object used for all your interactions with the IronWorker cloud.
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
199
200 ```ruby
201 client = IronWorkerNG::Client.new(:token => 'IRON_IO_TOKEN', :project_id => 'IRON_IO_PROJECT_ID')
202 ```
203
204 ### codes.list(options = {})
205
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
206 Return an array of information about uploaded code packages. Visit http://dev.iron.io/worker/reference/api/#list_code_packages for more information about the available options and the code package object format.
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
207
208 ```ruby
209 client.codes.list.each do |code|
210 puts code.inspect
211 end
212 ```
213
214 ### codes.get(code_id)
215
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
216 Return information about an uploaded code package with the specified ID. Visit http://dev.iron.io/worker/reference/api/#get_info_about_a_code_package for more information about the code package object format.
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
217
218 ```ruby
219 puts client.codes.get('1234567890').name
220 ```
221
222 ### codes.create(code)
223
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
224 Upload an `IronWorkerNG::Code::Ruby` object to the IronWorker cloud.
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
225
226 ```ruby
227 client.codes.create(code)
228 ```
229
230 ### codes.delete(code_id)
231
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
232 Delete the code package specified by `code_id` from the IronWorker cloud.
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
233
234 ```ruby
235 client.codes.delete('1234567890')
236 ```
237
238 ### codes.revisions(code_id, options = {})
239
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
240 Get an array of revision information for the code package specified by `code_id`. Visit http://dev.iron.io/worker/reference/api/#list_code_package_revisions for more information about the available options and the revision objects.
c58730a @iced Docs for Client#codes.*, Client constructor now uses hash, version bump.
iced authored
241
242 ```ruby
243 client.codes.revisions('1234567890').each do |revision|
244 puts revision.inspect
245 end
246 ```
c3e1546 @iced README for Client#codes.download.
iced authored
247
248 ### codes.download(code_id, options = {})
249
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
250 Download the code package specified by `code_id` and return it as an array of bytes. Visit http://dev.iron.io/worker/reference/api/#download_a_code_package for more information about the available options.
c3e1546 @iced README for Client#codes.download.
iced authored
251
252 ```ruby
253 data = client.codes.download('1234567890')
254 ```
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
255
256 ### tasks.list(options = {})
257
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
258 Retrieve an array of information about your workers' tasks. Visit http://dev.iron.io/worker/reference/api/#list_tasks for more information about the available options and the task object format.
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
259
260 ```ruby
261 client.tasks.list.each do |task|
262 puts task.inspect
263 end
264 ```
265
266 ### tasks.get(task_id)
267
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
268 Return information about the task specified by `task_id`. Visit http://dev.iron.io/worker/reference/api/#get_info_about_a_task for more information about the task object format.
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
269
270 ```ruby
271 puts client.tasks.get('1234567890').code_name
272 ```
273
274 ### tasks.create(code_name, params = {}, options = {})
275
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
276 Queue a new task for the code package specified by `code_name`, passing the `params` hash to it as a payload and returning a task object with only the `id` field filled. Visit http://dev.iron.io/worker/reference/api/#queue_a_task for more information about the available options.
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
277
278 ```ruby
279 task = client.tasks.create('MyWorker', {:client => 'Joe'}, {:delay => 180})
280 puts task.id
281 ```
282
283 ### tasks.cancel(task_id)
284
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
285 Cancel the task specified by `task_id`.
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
286
287 ```ruby
288 client.tasks.cancel('1234567890')
289 ```
290
291 ### tasks.cancel_all(code_id)
292
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
293 Cancel all tasks for the code package specified by `code_id`.
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
294
295 ```ruby
296 client.tasks.cancel_all('1234567890')
297 ```
298
299 ### tasks.log(task_id)
300
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
301 Retrieve the full task log for the task specified by `task_id`. Please note that log is available only after the task has completed execution. The log will include any output to `STDOUT`.
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
302
303 ```ruby
304 puts client.tasks.log('1234567890')
305 ```
306
307 ### tasks.set_progress(task_id, options = {})
308
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
309 Set the progress information for the task specified by `task_id`. This should be used from within workers to inform you about worker execution status, which you can retrieve with a `tasks.get` call. Visit http://dev.iron.io/worker/reference/api/#set_a_tasks_progress for more information about the available options.
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
310
311 ```ruby
312 client.tasks.set_progress('1234567890', {:msg => 'Still running...'})
313 ```
314
315 ### tasks.wait_for(task_id, options = {})
316
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
317 Wait (block) while the task specified by `task_id` executes. Options can contain a `:sleep` parameter used to modify the delay between API invocations; the default is 5 seconds. If a block is provided (as in the example below), it will be called after each API call with the task object as parameter.
a504aaf @iced Docs for Client#tasks.* completed.
iced authored
318
319 ```ruby
320 client.tasks.wait_for('1234567890') do |task|
321 puts task.msg
322 end
323 ```
9fab6a1 @iced Docs for Client#schedules.* completed.
iced authored
324
325 ### schedules.list(options = {})
326
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
327 Return an array of scheduled tasks. Visit http://dev.iron.io/worker/reference/api/#list_scheduled_tasks for more information about the available options and the scheduled task object format.
9fab6a1 @iced Docs for Client#schedules.* completed.
iced authored
328
329 ```ruby
330 client.schedules.list.each do |schedule|
331 puts schedule.inspect
332 end
333 ```
334
335 ### schedules.get(schedule_id)
336
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
337 Return information about the scheduled task specified by `schedule_id`. Visit http://dev.iron.io/worker/reference/api/#get_info_about_a_scheduled_task for more information about the scheduled task object format.
9fab6a1 @iced Docs for Client#schedules.* completed.
iced authored
338
339 ```ruby
340 puts client.schedules.get('1234567890').last_run_time
341 ```
342
343 ### schedules.create(code_name, params = {}, options = {})
344
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
345 Create a new scheduled task for the code package specified by `code_name`, passing the params hash to it as a data payload and returning a scheduled task object with only the `id` field filled. Visit http://dev.iron.io/worker/reference/api/#schedule_a_task for more information about the available options.
9fab6a1 @iced Docs for Client#schedules.* completed.
iced authored
346
347 ```ruby
348 schedule = client.schedules.create('MyWorker', {:client => 'Joe'}, {:start_at => Time.now + 3600})
349 puts schedule.id
350 ```
351
4ffc8df @benmanns Fix variable name in README.
benmanns authored
352 ### schedules.cancel(schedule_id)
9fab6a1 @iced Docs for Client#schedules.* completed.
iced authored
353
716e1e4 @paddyforan Updated readme docs.
paddyforan authored
354 Cancel the scheduled task specified by `schedule_id`.
9fab6a1 @iced Docs for Client#schedules.* completed.
iced authored
355
356 ```ruby
357 client.schedules.cancel('1234567890')
358 ```
Something went wrong with that request. Please try again.