Awesome Open Source
Awesome Open Source


battle tested.

Build Status

Octopoller is a micro gem for polling and retrying, perfect for making repeating requests.

Octopoller.poll(timeout: 15.seconds) do
    client.request_progress # ex. request a long running job's status
  rescue Error

# => { "status" => 200,  "body" => "" }


Octopoller was originally created for the purpose of polling GitHub's Source Imports API for a repo's import status. It is now the backbone of GitHub Classroom's import starter code process.


Add this line to your application's Gemfile:

gem 'octopoller'

And then execute:

$ bundle

Or install it yourself as:

$ gem install octopoller


Octopoller exposes a single function poll. Here is what the API looks like:

# Polls until success
# Re-runs when the block returns `:re_poll`
# wait      - The time delay in seconds between polls (default is 1 second)
#           - When given the argument `:exponentially` the action will be retried with exponetial backoff
# timeout   - The maximum number of seconds the poller will execute
# retries   - The maximum number of times the action will be retried
# yield     - A block that will execute, and if `:re_poll` is returned it will re-run
#           - Re-runs until something is returned or the timeout/retries is reached
# raise     - Raises an Octopoller::TimeoutError if the timeout is reached
# raise     - Raises an Octopoller::TooManyAttemptsError if the retries is reached
def poll(wait: 1.second, timeout: nil, retries: nil)

Octopoller has 3 use cases:

  • Poll something with a set timeout
  • Poll something with a set number of retries
  • Poll something with exponential backoff

Here's what using Octpoller is like for each of the use cases listed above:

  • Poll with a timeout:

    Octopoller.poll(timeout: 15.seconds) do
      puts ""
    # => ""
    # => ""
    # ... (for 15 seconds)
    # Timed out patiently (Octopoller::TimeOutError)
  • Poll with retries:

    Octopoller.poll(retries: 2) do
      puts ""
    # => ""
    # => ""
    # => ""
    # Tried maximum number of attempts (Octopoller::TooManyAttemptsError)
  • Poll with exponential backoff:

    start =
    Octopoller.poll(wait: :exponentially, retries: 4) do
      puts - start
    # => 0.5 seconds
    # => 1 second
    # => 2 seconds
    # => 4 seconds
    # => 8 seconds
    # Tried maximum number of attempts (Octopoller::TooManyAttemptsError)


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Octopoller projects codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
ruby (12,280)
ruby-gem (96)
retry (33)
polling (14)

Find Open Source By Browsing 7,000 Topics Across 59 Categories