Skip to content

Message Service (Stack9-core v2.0 and above)

In Stack9 core version 2.0.0 a new service was created in order to allow integration with message queue services. This service is responsible to check which message queue service is configured in stack9 ('aws-sqs' or 'azure-queue-storage') and then add the message to the right service queue.

Related documentation:

Environment variables

MESSAGE_QUEUE_SERVICE enviroment variable should be configured with one of the expected message queue services

  • MESSAGE_QUEUE_SERVICE // 'aws-sqs' or 'azure-queue-storage'

Stack9-core

MessageService implements IMessageService and it is exported along to the other services to allow access by stack9-client instances, cron-jobs or custom api functions.

MessageService has a private variable prefix that's being used to differentiate between stack9 core handlers and custom client handlers. The possible values can be native or client. This value is defined by the child() function which initialise and return a new instance of MessageService with prefix value "client" when it is accessed by stack9-client instances, cron-jobs or custom api functions.

  • child(): MessageService is exported by the core among with other services, in case of being called by the stack9-core itself, this will be ignored and the prefix will be initialised in the class constructor with the default value native.

When MessageService is exported to be used out of the stack9-core, it will return a new instance of MessageService initialising the class with prefix value "client".

New instance of MessageService which the prefix will be initialised with "client"

const childMessageService = services.message.child();

  child(): IMessageService {
    return new MessageService('client');
  }

  • sendMessage(): When sendMessage() is called, it will try to find the queue ID passed as argument, concatenating the value "native" or "client" with the queue ID and then check if the queue is registered or not and then add the message to an array in memory until the transaction is committed.

  • dispatchMessages(): This function is called once the trasanction is commited, sending all messages in memory to the SQS service.

Ex:

const queue = `${this.prefix}-${message.queue}`;

If the queue is not found, then an error will be throwed and no message will be added to the queue.

throw new SystemError(`queue "${queue}" is not registered or invalid.`);

If no entityType or entityId or action is informed, an error will be throwed and no message will be added to the queue.

throw new SystemError('message must have at least one identifier field');

If all validations are executed without errors, a new message will be added to the queue.

Usage

Send Message

interface IMessageQueueMessage {
  queue: string; // REQUIRED: QUEUE identifier, must be the same configured in message-handler
  userId?: number; // OPTIONAL: Id of the user executing this action
  entityType?: string; // OPTIONAL: Entity name
  entityId?: number; // OPTIONAL: ID of the entity being processed
  action?: string; // OPTIONAL: workflow action
  operation?: string; // OPTIONAL: workflow operation
  body: string; // REQUIRED: Data to be passed to the queue, can be any JS object
}

await this.messageService.sendMessage(message: IMessageQueueMessage);

For more information about message queue service, see Message Queue Services ⇗