Feature: Message Retries
Relevant source files
The following files were used as context for generating this wiki page:
MessageJS is designed with production-ready features, including message retries, to enhance the reliability of message delivery. The retry mechanism is a key component for handling transient network failures or temporary unavailability of third-party provider APIs.
This feature is approached from two perspectives: client-side retries handled by the SDK, and a more robust server-side retry architecture. The data model is designed to support tracking message status, which is fundamental for any retry logic.
Sources: README.md:16, QUICK_START.md:100
Client-Side SDK Retries
The MessageJS client SDK is documented to include a retry mechanism configurable during initialization. This allows the client application to automatically retry sending a message if the initial API call to the MessageJS backend fails.
Sources: API_REFERENCE.md:465-469
Configuration
According to the API reference, the number of retries can be configured using the retries option within the messagejs.init() method.
| Option | Type | Description | Default |
|---|---|---|---|
retries | number | Number of retry attempts | 1 |
Sources: API_REFERENCE.md:465-469
The following code snippet from the documentation illustrates how to configure this option:
import messagejs from 'messagejs-client';
messagejs.init('<api_key_placeholder>', 'proj_xyz789', {
endpoint: 'https://api.messagejs.pro', // optional
timeout: 10000, // optional, default 10s
retries: 1 // optional, default 1
});
Sources: API_REFERENCE.md:465-469
Note: While the API_REFERENCE.md specifies the retries option, the current implementation in packages/client/src/index.ts does not include this parameter in the MessageJSConfig interface or the init method logic. This indicates the feature is documented but not yet implemented in the client SDK source code.
Sources: packages/client/src/index.ts:15-23, packages/client/src/index.ts:71-81
Documented Flow
The diagram below illustrates the documented behavior of the client-side retry logic. If the fetch call to the MessageJS API fails (e.g., network error or a non-2xx response), the SDK would attempt to resend the request based on the retries configuration.
This diagram represents the flow described in the documentation, which may differ from the current implementation.
Sources: API_REFERENCE.md:465-485, packages/client/src/index.ts:93-118
Server-Side Retry Architecture (Planned)
The core backend is architected to handle message processing asynchronously, which is the foundation for a robust server-side retry system. The messageController outlines a plan to use a job queue for processing and sending messages, allowing for retries without blocking the initial API response.
Sources: packages/core/src/api/controllers/messageController.ts:35-45
High-Level Flow
When the API receives a sendMessage request, it is designed to perform initial validation, create a MessageLog entry with a QUEUED status, and then push a job to a message queue (e.g., BullMQ) for background processing. This ensures the client receives a fast response, confirming the message has been accepted.
This diagram shows the planned asynchronous message processing flow.
Retry Logic within Worker
The background worker would contain the core retry logic. If a message fails to send via the third-party connector, instead of immediately marking it as FAILED, the worker would re-queue the job, potentially with an exponential backoff delay. Only after exhausting all retry attempts would the message status be permanently set to FAILED.
This diagram details the planned retry process inside the background worker.
Data Model for Retry Support
The Prisma data model is designed to support message retries by tracking the lifecycle of each message. The MessageLog table and its associated MessageStatus enum are central to this.
Sources: packages/core/prisma/schema.prisma, packages/core/src/types/dataModels.ts
MessageLog Schema
The MessageLog model contains fields essential for managing and tracking retries.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the message log entry. |
status | MessageStatus | The current state of the message (QUEUED, SENT, FAILED, etc.). |
error | String? | Stores the error message if the status is FAILED. |
externalMessageId | String? | The ID from the third-party provider, received upon successful sending. |
timestamp | DateTime | The creation timestamp of the log entry. |
Sources: packages/core/prisma/schema.prisma:79-87
MessageStatus Enum
The MessageStatus enum defines the possible states of a message, which dictates whether a retry is necessary. A message in the FAILED state might be a candidate for a retry attempt.
This diagram shows the relationship between the MessageLog model and the MessageStatus enum that governs its state.
Sources: packages/core/prisma/schema.prisma:25-30, packages/core/src/types/dataModels.ts:60-66
Summary
The message retry feature in MessageJS is a core design principle for ensuring reliable message delivery. The system is architected with provisions for both client-side and server-side retries. While the client-side retry mechanism is documented, its implementation in the source code is not yet complete. The server-side retry logic is planned as part of an asynchronous, queue-based architecture, and the underlying database schema is already in place to support the tracking of message statuses and errors, which is essential for this functionality.