Skip to main content

Managing Message Broker Topics

Message Broker Topics in Ductape define the channels through which your application publishes and subscribes to messages. Topics are essential for structuring event-driven communication between services, microservices, or external systems.

A topic is always associated with a specific message broker and environment. Its tag should follow the format: messageBrokerTag:topicTag (e.g., orders:new_order).

Creating a Topic​

To create a topic, use the create function from the messageBroker.topics interface. You must specify the broker, topic tag, and payload schema. For AWS SQS, you must also provide queue URLs for each environment.

const details = {
  name: "User Created Event",
  messageBrokerTag: "user-service",
  tag: "user-service:user_created",
  description: "Topic for user creation events.",
  queueUrl: [
    { env_slug: "prd", url: "https://sqs.us-east-1.amazonaws.com/123456789012/user-created-prd" },
    { env_slug: "dev", url: "https://sqs.us-east-1.amazonaws.com/123456789012/user-created-dev" },
  ],
  sample: {
    userId: "12345",
    createdAt: "2024-08-20T12:34:56Z"
  }
};

await ductape.app.messageBroker.topics.create(details);
FieldTypeRequiredDescription
namestringYesHuman-readable name for the topic.
messageBrokerTagstringYesTag of the associated message broker.
tagstringYesUnique topic identifier (brokerTag:topicTag).
descriptionstringNoDescription of the topic's purpose.
queueUrlarraySQS onlyArray of { env_slug, url } for each environment (SQS only).
sampleobjectYesExample payload for the topic.

Note: For SQS, queueUrl is required. For other brokers, omit this field.

Updating a Topic​

To update a topic, use the update function. You can change the description, queue URLs, or payload schema as needed.

const tag = "user-service:user_created";
const update = {
  description: "Updated description for the user creation event.",
  queueUrl: [
    { env_slug: "prd", url: "https://sqs.us-east-1.amazonaws.com/123456789012/user-created-prd-updated" },
  ],
};

await ductape.app.messageBroker.topics.update(tag, update);
Updatable FieldDescription
nameHuman-readable name for the topic.
messageBrokerTagTag of the associated message broker.
tagUnique topic identifier (brokerTag:topicTag).
descriptionDescription of the topic's purpose.
queueUrl (SQS)Array of { env_slug, url } for each environment (SQS only).
sampleExample payload for the topic.

Tip: Always use the brokerTag:topicTag format for topic tags to avoid conflicts.

Fetching Topics​

  • Fetch a single topic by tag: 
    const topic = ductape.app.messageBroker.topics.fetch("user-service:user_created");
  • Fetch all topics for a broker: 
    const topics = ductape.app.messageBroker.topics.fetchAll("user-service");

Best Practices​

  • Use descriptive names and tags for topics to clarify their purpose.
  • Keep payload schemas consistent and well-documented.
  • For SQS, ensure each environment has a unique queue URL.
  • Regularly review and update topic definitions as your integration needs evolve.
  • Use the same naming conventions for tags and slugs across your product.

See Also​