The tulip.pkg.mqueue module exports the mqueue package. It implements a message queue with at-least-once delivery.


  • tulip.pkg.database


  • allowed_queues: array of string = if set, only those queues will be allowed.
  • default_max_age: integer|nil = if set, use as default max age for the messages (default: 30).
  • default_max_attempts: integer|nil = if set, use as default maximum number of attempts to process a message (default: 1).

#API Extensions

Registering this package provides the following method and field extensions.

#v, err = App:mqueue(t[, conn[, msg]])

Enqueues a message, or dequeues a batch of messages to process.

  • t: table = a table with the following fields:
    • t.max_attempts: number|nil = maximum number of attempts (enqueue only)
    • t.max_age: number|nil = number of seconds to process message (enqueue only)
    • t.queue: string = queue name
    • t.max_receive: number|nil = maximum number of messages to receive, when the call is a dequeue operation. Defaults to 1.
  • conn: connection|nil = optional database connection to use
  • msg: table|nil = if provided, enqueues that message. It gets encoded as JSON.


  • v: bool|array of tables|nil = if msg is provided, returns a boolean that indicates if the message was enqueued, otherwise returns an array of tables representing the messages to process. Each table has an id and a payload fields and a :done(conn) method. Is nil on error.
  • err: Error|nil = error message if v is nil
#res, err = Message:done(conn)

Marks the message as done so it isn't processed anymore. Note that if the max age of the message was expired, the message would still be pending again after the call.


  • conn: connection = the database connection to use


  • res: userdata = the database result
  • err: Error|nil = error message if res is nil
#Message.raw_payload: string

The JSON payload as a string, as stored in the DB.

#Message.payload_err: string

The JSON decoding error, if any.

#Message.payload: table

The payload as a Lua table, JSON-decoded.

#Message.id: number

The id of the message.

#Message.attempts: number

The number of attempts done so far (not including the current one).

#Message.max_attempts: number

The maximum number of attempts for this message.

#Message.max_age: number

The max age of this message (time allocated for processing).

#Message.first_created: epoch

The timestamp when the message was first created, as epoch value.

Back to index

About this wiki

commit 3ebfbd288b8e5c95fdf8ce2027a0e94cfa1c8976
Author: Martin Angers <martin.n.angers@gmail.com>
Date:   2021-02-25T14:07:12-05:00

Update to reflect Request:validate_body
Clone this wiki
https://git.sr.ht/~mna/tulip-wiki (read-only)
git@git.sr.ht:~mna/tulip-wiki (read/write)