We’re trending on ProductHunt!

If you like Ralley, please check us out over there...

πŸŽ‰

View

Docs

Hello πŸ‘‹

Ralley is a modern infinitely scaleable managed message queue (queue as a service), which requires no setup. Ralley works like any other queue, but instead of pushing jobs, you push requests.

Simply prefix a request with ralley.to/ and we'll queue and forward the request with the exact same method/body/headers/query.

No additional configuration for your endpoint, requests can be sent directly to your API as normal (sync) or via the ralley queue (async).

You can use Ralley to:

  • retry requests that error automatically or manually

  • schedule/cron requests at regular interval

  • delay requests for a given time (e.g. send a request after 30 mins)

It works great in combination with serverless platforms like Vercel (/Zeit). If you have any questions at all, feel free to contact us at calum@ralley.io.

Getting Started

It takes less than 5 minutes to get started with Ralley.

  1. Sign up to Ralley - it's free for the first 2,000 requests

  2. Obtain your API token

  3. Send a HTTPS request by prefixing it with ralley.to/ and adding your API token as a query parameter ?_token=<token>.

Try running the following command in your terminal/browser, and then visit the console to see logged request!

curl -X POST ralley.to/postman-echo/post?_token=<insert_your_api_token>

API Token

You will need to provide your API token with every request. You can obtain your API token from the console (once you've signed up).

You can provide the API token as a ?_token query parameter OR as a header X-Ralley-Token. You should keep this token secret at all times, and refresh it if it becomes compromised.

Queue

To a queue a request, simply prefix a request with ralley.to/ and we'll queue and forward the request with the exact same method/body/headers/query. In addition, to help with the processing of the queued request, we add the following additional headers:

  • X-Ralley-Start - this denotes the time the request started (this is particularly useful for scheduled requests)
  • X-Ralley-Id - this is the ID of the queued request job
ralley.to/your_url.com?_token=<insert_token>

Retry

You can automatically retry requests by adding the _retry query parameter or X-Ralley-Retry header.

ralley.to/your_url.com?_retry=3

By default, retries will be attempted at a fixed interval of 1 second. You can specify how retries should be attempted by adding one of the following backoff approaches:

  • immediate - runs the retry requests immediately after the initial request
  • exponential,<seconds> - exponentially increases the backoff by seconds^2. E.g. if set to 2, the first it would be 1 (1^2), 4 (2^2), 9 (3^2) seconds... and so on.
  • fixed,<seconds> - interval remains constant

For example:

ralley.to/your_url.com?_retry=3|immediate
ralley.to/your_url.com?_retry=3|fixed|1
ralley.to/your_url.com?_retry=3|exponential|1

With a retry of 3 a maximum of 4 calls will be made to your endpoint - 1 for the original request, and 3 retry requests.

Delay

You can delay a request (or if scheduled the start of the schedule) by providing the _delay parameter (or X-Ralley-Delay header) and a number of seconds to delay by. For example, you may want to send an e-mail 50 minutes after a new user signs up, or delete an accounts data after 30 days.

A _delay=600 would be a delay of 10 minutes.

ralley.to/your_url.com?_delay=600

Delay Until

Alternatively, you can specify _delay_until query parameter (or X-Ralley-Delay-Until header) to set the unix timestamp of the time to run the request.

ralley.to/your_url.com?_delay_until=1592998014

Schedule

You can schedule a request to repeat at a specified interval. There are two ways of creating a scheduled request - interval and CRON. Currently only one schedule is supported per request. When a scheduled request is sent to the URL you provide, the following additional request headers are added:

  • X-Ralley-Start - this allows you to ensure any time based logic is executed based on the correct interval

When you combine the delay (or delay until) with a schedule, then the schedule will not commence until the specified delay has passed. Subsequent scheduled requests will not have any delay applied and will be run at the given interval.

When you combine retry retry with a schedule, then the retry parameters will be passed to each subsequent scheduled request.

Interval

You can add an interval, which will run the request at every given interval using the _interval query parameter (or X-Ralley-Interval header). The interval must be provided in seconds. For example, 300 would be 5 minutes.

ralley.to/your_url.com?_interval=300

CRON

You can also create a schedule using the CRON syntax and the _cron query parameter (or X-Ralley-Cron header). For example, a CRON value of 5 14 * * * would result in a request being made every day at 2.05pm.

ralley.to/your_url.com?_cron=5|14|*|*|*
ralley.to/your_url.com?_cron=5 14 * * *

Either space () or pipe (|) can be used as the separator.

You can also provide a _timezone query parameter (or X-Ralley-Timezone header) in tz format for the CRON schedule. Your CRON schedule will then be applied in that timezone (this takes into account daylight saving clock changes, so when timezone is provided a non-standard interval may occur when the clocks change).

Tracing

You can add a trace ID to any request using _trace query parameter (or X-Ralley-Trace header), and that request will be linked as a child of the request with the trace ID you provided. This does not effect how your request will be queued, but simply helps connect the two items for discoverability in the Ralley console.

ralley.to/your_url.com?_trace=<id_obtained_from_another_request>

Environments

You often want to run your queue in a development or test environment. You can add a _env query parameter (or X-Ralley-Env header) to your requests to specify which environment the request is running in. This will then appear in the console, and can be used to filter requests.

Running in development

The easiest way to run Ralley in your development environment is to simply remove the ralley.to/ prefix based on an environment variable. Below is an example of how you might setup a utility function to handle this.

import axios from 'axios'

const { RALLEY_TOKEN, NODE_ENV } = process.env

export default function queue (url: string, data: any) {
  return axios(url, {
    method: 'POST',
    data,
    params: { 
      _token: RALLEY_TOKEN,
      _env: NODE_ENV,
    },
    baseURL: NODE_ENV === 'production' ? `https://ralley.to/` : '',
  })
}

This approach has the advantage that in development, errors are thrown directly which can lead to enhanced debugging πŸ™Œ.

Running in production

The easiest way to run Ralley in production is to expose the endpoint you want to call to the internet. Simply create a secret token which can then passed along with every request.

import express from 'express'

const { SECRET_TOKEN } = process.env

const app = express()

app.get('/my-service', (req) => {
  if (req.query.secret !== SECRET_TOKEN) {
    throw new Error('Not allowed!')
  }
  ...
})

You would then call this service with:

ralley.to/my-url.com/my-service?secret=s123&_token=<ralley_token>

Note: all Ralley parameters are stripped from the URL before being relayed, so you cannot check for presence of ?_token.

On premise (running Ralley behind your firewall)

Contact sales for running on-premise solution.

Bulk

The /bulk API allows you to send multiple request jobs to Ralley at once in a single transaction. Once the request is accepted, it's guaranteed that all your jobs will be added to Ralley.

Send a POST request to the ralley.to/bulk?_token=<your_token> API with a JSON body array of requests you'd like to send (and add Content-Type: "application/json" header).

Only the url property is required. If not provided, method will default to POST. If you provide an object/array as the body property, then a Content-Type header of application/json will be set automatically, otherwise Content-Type will be text/plain.

[{
  url: "anyurl.com",
  method: "POST",
  headers: {},
  params: {
    _delay: 3000,
  },
  body: 'Body of request', # string or json
}, {
  ...
}]

The response will be an array of IDs:

[{
  id: 1
}, {
  ...
}]

Requests

You can read the status of a job by using the /requests/<id> endpoint (you'll need to include your _token). The ID is returned in the response when you add a job to the queue.

Limits

The following limits are applied:

  • Maximum request size: Dependent on plan
  • Maximum redirects: 5
  • Maximum URL query parameters: 1000

FAQ

Why can't I access XYZ query parameter?

All Ralley query parameters (e.g. ?_token, ?_delay=300, etc) are stripped from the request when it is relayed to your endpoint. Therefore, you should not try to access these parameters. If you need access to them, simply duplicate them without the _ prefix and they will appear at your endpoint.

How can I prevent conflict with Ralley query parameters?

By default, Ralley query parameters (e.g. _delay, _cron, etc) are stripped from the request before it is forwarded to your endpoint. In the unlikely case that you need to use one of these parameters in your own code, you can specify the following header X-Ralley-No-Conflict to 1. In this mode, you should use the headers (e.g. X-Ralley-Delay, etc) to set the required Ralley parameters.

What if ralley.to is not allowed by our company firewall?

You can access our service using the alternative domain ralleyto.com. Simply replace ralley.to in the instructions above with this domain instead.

PrivacyTermsContactVersion: 1.0.170