Skip to main content

Queues - Publish

Overview​

Publishing to a queue submits background work for asynchronous processing.

In RelayX, queues are explicit resources. You must initialize a queue before you can publish jobs to it. Publishing does not implicitly create or infer queues. This makes queue usage predictable and prevents accidental job delivery to the wrong queue.

Publishing is fire-and-forget. A successful publish only confirms that the job was accepted by the RelayX backend. It does not mean the job has run or completed.

How This Works​

Publishing a job follows a strict sequence:

  1. Create a RelayX client with API credentials.
  2. Initialize the client.
  3. Establish a network connection.
  4. Initialize the target queue.
  5. Publish jobs through the queue handle.

When publish() is called on a queue:

  • The SDK validates the job payload.
  • If the client is connected, the job is sent to the RelayX backend.
  • The job becomes available to subscribed workers.

If the client is disconnected or reconnecting, the publish call returns false. A true return value only confirms backend acceptance, not execution.

API Usage​

Client Initialization and Connection​

import { Realtime } from "relayx-webjs";

const client = new Realtime({
  api_key: process.env.RELAYX_API_KEY,
  secret: process.env.RELAYX_API_SECRET,
});

await client.init();
await client.connect();

The client must be initialized and connected before any queue operations.

Initializing a Queue​

Before publishing, explicitly initialize the queue.

const workerQueue = await client.initQueue("<QUEUE_ID>");
  • <QUEUE_ID> uniquely identifies the queue.
  • The queue ID is found in the worker queue section of the developer console.

All publish and subscribe operations are performed through this queue instance.

Publishing a Job​

const success = await workerQueue.publish("email-jobs", {
  userId: "12345",
  template: "welcome-email",
});

if (!success) {
  console.error("Job was not published");
}

Parameters​

  • topic (string, required)
    Logical identifier for the job type.

  • payload (object, required)
    Job data. RelayX treats this as opaque data. Validation is application-defined.

Return Value​

  • true — job was accepted by the backend.
  • false — job was not sent, usually because:
    • The client is disconnected or reconnecting.
    • The connection has been closed.

A return value of true does not indicate job execution.

Failure & Edge Cases​

Network Failures​

If the connection drops:

  • publish() may return false.
  • The job is not guaranteed to be persisted.
  • Retry after reconnection if the job is important.

Invalid Input​

publish() throws an error if:

  • The topic name is invalid.
  • The topic is a system-reserved topic.
  • The client doesn't have permissions to publish to the specified topic. More information here
  • Publish attempt is made when allowed message quota (hard limit with no extra messages) has exceeded.

These errors must be caught by the application.

Process Crashes​

  • If the process crashes after publish() returns true, the job remains queued.
  • If it crashes before a successful return, the job may be lost.

Common Mistakes​

Skipping Queue Initialization​

Calling publish() without first calling initQueue() will fail. Queue initialization is mandatory.

Assuming Publish Waits for Processing​

Publishing does not wait for a worker to run the job. It only confirms backend acceptance.

Assuming Exactly-Once Execution​

Jobs are delivered at least once. Workers must be idempotent.

Notes & Limitations​

  • An active connection is required to publish.
  • Publishing does not depend on worker availability.
  • RelayX does not support delayed or scheduled jobs.


Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️