Skip to main content

Messaging – Publish

Overview​

The publish API allows your NodeJS application to send messages to a specific RelayX topic.

Publishing is the primary way data enters the RelayX messaging system. When a message is published to a topic, it is immediately routed to all active subscribers of that topic. This mechanism is used to broadcast events, state changes, telemetry, or notifications across different parts of a system.

The publish operation is intentionally simple. It does not wait for subscribers to process the message and does not coordinate delivery across consumers. Once a message is accepted by the RelayX backend, delivery is handled asynchronously.

This page explains how publishing works in the NodeJS SDK, what the publish call does at runtime, and how to handle edge cases such as reconnects and failures.

How This Works​

When you call publish(topic, message):

  1. The SDK validates the topic name locally.
  2. The message payload is serialized.
  3. If the client is connected, the message is sent immediately to the RelayX backend.
  4. If the client is reconnecting, the message is placed into an offline buffer.
  5. Once accepted by the backend, the message is delivered to all matching subscribers.

Publishing is fire-and-forget. The SDK does not wait for subscribers, acknowledgements, or downstream processing.

RelayX provides at-least-once delivery semantics. Messages may be delivered more than once to subscribers if failures occur during handling, but messages are never silently dropped once accepted by the backend.

API Usage​

publish(topic, message)​

Publishes a message to the given topic.

Required Parameters​

  • topic (string)

    • The topic to publish to. The topic must follow RelayX topic naming rules and must not be a reserved system topic.
    • More information here

  • message (any)
    The message payload. Supported types include:

    • JSON objects
    • Strings
    • Numbers

The SDK does not enforce a schema. Producers and consumers must agree on payload structure.

Return Value​

publish(topic, message) returns a boolean:

  • true
    The message was has been sent.

  • false
    One of the following occurred:

    • The client is reconnecting and the message was stored offline.
    • The connection is closed.

A false return value does not mean the message is lost.

Code Example​

// JSON Message
const success = await client.publish("orders.created", {
    orderId: "12345",
    amount: 250,
    currency: "USD",
});

// String Message
const success = await client.publish("orders.created", "Order #123 created!");

// Number Message
const success = await client.publish("orders.created", 123);

if (!success) {
    console.log("Message queued for resend or client disconnected from Relay Network");
}

Failure & Edge Cases​

Invalid Topics​

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.

Reconnecting State​

If the client is reconnecting:

  • publish() returns false.
  • The message is stored in an offline buffer.
  • The buffer is retained for up to 2 minutes.

When the client reconnects successfully, buffered messages are automatically republished.

If reconnection fails and the connection closes permanently, buffered messages are discarded.

Message Limits​

Publishing may fail if message limits are exceeded. This is for plans with a message limit and no extra messages available.

In this case, publish() throws an error indicating the limit has been reached.

Process Crashes​

If the NodeJS process crashes:

  • In-memory buffered messages are lost.
  • No resend occurs after restart.

Applications that require durability must persist messages externally.

Message Republish Confirmation​

To receive confirmation that buffered messages were resent after reconnect:

  • Subscribe to the MESSAGE_RESEND system topic.
  • The SDK emits an array of JSON objects describing republished messages.
import { MESSAGE_RESEND } from "relayx-js"

client.on(MESSAGE_RESEND, (data) => {
    console.log(data)
})

Strcuture of the data sent to the callback,

[
    {
        "topic": "<String, topic which the message was sent to>",
        "message": "<JsonObject | String | Number => Your Message>",
        "resent": "<Boolean, if message was republished or not>"
    }
]

This mechanism is optional and intended for observability.

Common Mistakes​

Assuming publish Waits for Delivery​

publish() does not wait for subscribers or acknowledgements.

Publishing to Wildcard Topics​

Publishing to wildcard topics does not throw an error, but subscribers matching the pattern will not receive the message.

Ignoring false Return Values​

A false return value indicates offline buffering.

Notes & Limitations​

  • Publishing is non-blocking.
  • Offline buffering is in-memory and time-limited.
  • Message ordering is enforced per topic by the backend.
  • The SDK does not retry publishes after permanent disconnection.


Need Help?

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