A Ruby client for the QStash service from Upstash.

QStash is an HTTP-based messaging and scheduling solution, designed for serverless and edge computing environments, guaranteeing at-least-once delivery.

If you're coming from a Rails background, you'll be familiar with ActiveJob, Sidekiq, and/or DelayedJob for background job processing. QStash can run background jobs which may/may not be a use case if you're using Ruby in a serverless environment but it's also much more than that. It can:

• Schedule messages to be delivered at a later time.
• Serve as a FIFO message queue.
• Serve as a push based fanout exchange (think RabbitMQ).

• QStash
  • Contents
  • Getting Started
  • Messages
  • Events
  • Signing Keys
  • Dead Letter Queue
  • URL Groups
  • Development
  • Contributing
  • License

Add this line to your application's Gemfile:

gem 'qstash'

Setup your thread safe configuration:

QStash.configure do |q|
  q.token = "your-qstash-token"
  q.url = "https://qstash.upstash.io"
end

or you can set the following ENV variables at runtime:

QSTASH_TOKEN=your-qstash-token
QSTASH_URL=https://qstash.upstash.io

To publish a message to a queue:

QStash::Message.publish(destination: "https://example.com/api/message-receiver", body: "Hello, World!")

From Upstash's docs:

Destination can either be a topic name or id that you configured in the Upstash console, a valid url where the message gets sent to, or a valid QStash API name like api/llm. If the destination is a URL, make sure the URL is prefixed with a valid protocol (http:// or https://)

You can also pass in headers. We help format Upstash's headers for you if you pass them in:

- "Upstash-Method",
- "Upstash-Timeout",
- "Upstash-Retries",
- "Upstash-Callback",
- "Upstash-Failure-Callback",
- "Upstash-Forward-*
- "Upstash-Delay",
- "Upstash-Not-Before",
- "Upstash-Deduplication-Id",
- "Upstash-Content-Based-Deduplication"

QStash::Message.publish(
  destination: "https://example.com/api/message-receiver",
  body: "Hello, World!",
  headers: { upstash_retries: 2 }
)

To enqueue a message to a queue:

QStash::Message.enqueue(
  queue_name: "my-queue",
  destination: "https://example.com/api/message-receiver",
  body: "Hello, World!"
)

To batch publish messages:

QStash::Message.batch_publish(messages: [
  {
    destination: "https://example.com/api/message-receiver",
    body: "Hello, World!"
  },
  {
    destination: "https://example.com/api/message-receiver",
    body: "Hello, World Again!",
    headers: { upstash_retries: 2 }
  }
])

To get a message from a queue:

QStash::Message.get("1234") # 1234 is the message id

To cancel a message from a queue:

QStash::Message.cancel("1234") # 1234 is the message id

To bulk cancel messages from a queue:

QStash::Message.cancel(["1234", "5678"])

To list all events:

QStash::Event.list

You can pass in any filters available from the Upstash docs.

QStash::Event.list(filters: {
  queueName: "my-queue",
  fromDate: Time.now - 1.day,
  toDate: Time.now
})

To get your current signing keys:

QStash::SigningKeys.get

To rotate signing keys:

QStash::SigningKeys.rotate

To get dead letter messages:

QStash::DLQ.get("1234") # 1234 is the dlq id of the message

To list dead letter messages:

QStash::DLQ.list

To list dead letter messages with filters:

QStash::DLQ.list(filters: {
  queueName: "my-queue", 
  fromDate: Time.now - 1.day, 
  toDate: Time.now 
})

To delete dead letter messages:

QStash::DLQ.delete("1234") # 1234 is the dlq id of the message

To delete multiple dead letter messages:

QStash::DLQ.delete(["1234", "5678"])

To list all url groups:

QStash::URLGroup.list

To add endpoints to a url group:

QStash::URLGroup.add_endpoints("my-url-group", endpoints: [{url: "https://example.com/api/message-receiver"}])

Note that this will create the url group if it doesn't already exist.

To delete endpoints from a url group:

QStash::URLGroup.delete_endpoints("my-url-group", endpoints: [{url: "https://example.com/api/message-receiver"}])

To delete a url group:

QStash::URLGroup.delete("my-url-group")

To get a url group:

QStash::URLGroup.get("my-url-group")

After checking out the repo, run bin/setup to install dependencies. Then, run rake test 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 run tests across all gem supported ruby versions (requires Docker):

bin/dev-test

To run lint across all gem supported ruby versions (requires Docker):

bin/dev-lint

Bug reports and pull requests are welcome on GitHub at https://github.com/dvmonroe/qstash-ruby.

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