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 API

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.

  • /requests [GET] - list requests all requests. Filters can be provided - e.g. ?filters={ field: "value" }

  • /requests/<id> [GET] - get a single request log

  • /requests/<id>/inactive [PATCH] - pause a request, only allowed if job is in pending or active state

  • /requests/<id>/active [PATCH] - unpause a request, only allowed if job is in inactive

  • /requests/<id>/request.body [GET] - read the request body

  • /requests/<id>/response.body [GET] - read the response to the proxied request

CLI

The Ralley CLI helps you to view requests, manage your account and includes a dev server.

Install

Install using NPM:

npm install -g @ralley/cli

Install using script:

curl -fsSL get.ralley.io -o get-ralley.sh
sh get-ralley.sh

You should update Ralley by running the same command.

Usage

Usage: ralley <command> [options]

Commands:
  ralley workspaces   Manage workspaces
  ralley queue <url>  Send a queued request to a service
  ralley requests     Manage requests
  ralley config       Configure CLI
  ralley login        Login to Ralley
  ralley logout       Logout (and delete user config)
  ralley signup       Sign up to Ralley
  ralley dev          Start dev environment

Options:
  --version, -v    Show version number                                 [boolean]
  --token, -t      Authentication token
  --workspace, -w  Workspace to target
  --endpoint, -e   Queue server endpoint
  --dev            Send requests to dev server
  --silent, -s     Silent mode (no stdout)
  --debug          Debug mode (more stdout)
  --json           Format response as JSON (only valid for list commands)
  -h               Show help

For additional usage commands use -h on sub-commands. E.g. ralley workspaces -h.

Dev Server (ralley dev)

A local dev server that can be used during development. It implements the same API as the ralley.to. By default it runs on http://localhost:4747 - you can specify an alternative port using -p.

To start a dev server use:

ralley dev

And to queue a request use:

curl http://localhost:4747/myurl.com?_delay=10

The queue and requests commands support a --dev flag which can be used to target your dev server instead of the Ralley production servers. E.g. To list requests on your dev server use ralley requests --dev

You can specify a workspace ID (and optional token) when creating the dev server, this allows you to start multiple servers without causing conflicts.

ralley dev -w name:token123

Differences to production

There are some minor differences to the production server:

  • If token is not provided using ralley dev -w name:token, then _token is not required. In production, _token param is always required.

  • Only the the following endpoints are supported. These endpoints work in the same way as the Ralley API, unless otherwise specified:

    • Queue [ANY] - http://localhost:4747/<url> (incl all headers/query parameters)
    • Bulk [POST] - http://localhost:4747/bulk
    • List requests [GET] - http://localhost:4747/requests. Only exact match filters are supported (e.g. /requests?filters={duration: 0.1}).
    • Get a single request [GET] - http://localhost:4747/requests/<id>
    • Pause request [PATCH] - http://localhost:4747/requests/<id>/inactive
    • Unpause request [PATCH] - http://localhost:4747/requests/<id>/active
    • Get request body [GET] - http://localhost:4747/requests/<id>/request.body
    • Get response body [GET] - http://localhost:4747/requests/<id>/response.body
  • In addition, you can reset/remove completed requests by calling /requests/reset [POST]. If you wish to remove ALL requests (including pending and active requests), then append ?hard=1. This can be useful for automated testing.

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.1.12