Scheduler Service

A NestJS-based microservice that handles task scheduling through AWS EventBridge Scheduler, with automatic message delivery to SQS queues when schedules trigger.

Overview

This service provides a RESTful API for managing scheduled tasks using AWS EventBridge Scheduler. It allows you to:

• Create and manage schedule groups with dedicated SQS queues
• Create schedules with cron or rate expressions
• Automatically route messages to group-specific SQS queues when schedules trigger
• Update and delete existing schedules
• List schedules with pagination support
• Support multiple SQS queues with flexible group-to-queue mapping

Prerequisites

• Node.js 18+
• AWS Account with appropriate permissions
• AWS EventBridge Scheduler access
• Multiple SQS queues created (one per schedule group)
• IAM role for EventBridge to send messages to SQS

Environment Configuration

Create a .env file in the root directory:

# AWS Configuration
AWS_REGION=us-east-1
EVENTBRIDGE_ROLE_ARN=arn:aws:iam::123456789012:role/EventBridgeSchedulerRole

# AWS Credentials (choose one method)
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key

# SQS Queue Mappings (format: GROUP_NAME:QUEUE_URL,GROUP_NAME2:QUEUE_URL2)
SQS_QUEUE_MAPPINGS=notifications:https://sqs.us-east-1.amazonaws.com/123456789012/notifications-queue,reports:https://sqs.us-east-1.amazonaws.com/123456789012/reports-queue,tasks:https://sqs.us-east-1.amazonaws.com/123456789012/tasks-queue

# Application
PORT=3000

AWS Credential Configuration

The service supports multiple methods for AWS authentication:

Method 1: Environment Variables (Development/Testing)

Set credentials directly in your .env file:

AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key

Method 2: AWS Credentials File (Development)

Use AWS CLI profiles instead of environment variables:

AWS_PROFILE=your-profile-name

This uses credentials from ~/.aws/credentials:

[your-profile-name]
aws_access_key_id = your-access-key-id
aws_secret_access_key = your-secret-access-key

Method 3: IAM Roles (Recommended for Production)

When running on AWS infrastructure (EC2, ECS, Lambda), no additional configuration is needed. The service will automatically use the IAM role attached to the compute resource.

Method 4: EC2 Instance Metadata

When running on EC2 instances with attached IAM roles, credentials are automatically retrieved from the instance metadata service.

Installation

$ npm install

Running the application

# development
$ npm run start:dev

# production mode
$ npm run start:prod

Testing

# unit tests
$ npm run test

# test coverage
$ npm run test:cov

API Endpoints

Create Schedule

POST /groups/{groupName}/schedules

Example request:

{
  "name": "daily-report",
  "expression": "cron(0 9 * * ? *)",
  "payload": {
    "taskType": "generate-report",
    "reportId": "123"
  },
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z"
}

Get Schedule

GET /groups/{groupName}/schedules/{scheduleName}

Update Schedule

PATCH /groups/{groupName}/schedules/{scheduleName}

Delete Schedule

DELETE /groups/{groupName}/schedules/{scheduleName}

List Schedules

GET /groups/{groupName}/schedules?nextToken={token}

Delete Schedule Group

DELETE /groups/{groupName}

SQS Queue Mapping

Each schedule group can be mapped to a specific SQS queue. When a schedule triggers, the message will be sent to the queue associated with that group.

Configuration

Queue mappings are configured via the SQS_QUEUE_MAPPINGS environment variable:

SQS_QUEUE_MAPPINGS=group1:queue-url-1,group2:queue-url-2,group3:queue-url-3

Error Handling

• If a group has no specific queue mapping, schedule creation will fail with a 400 error

Examples

# Three groups with specific queues
SQS_QUEUE_MAPPINGS=notifications:https://sqs.us-east-1.amazonaws.com/123456789012/notifications-queue,reports:https://sqs.us-east-1.amazonaws.com/123456789012/reports-queue,tasks:https://sqs.us-east-1.amazonaws.com/123456789012/tasks-queue

Schedule Expression Formats

Rate Expressions

• rate(5 minutes) - Every 5 minutes
• rate(1 hour) - Every hour
• rate(1 day) - Every day

Cron Expressions

• cron(0 10 * * ? *) - Every day at 10:00 AM UTC
• cron(0 18 ? * MON-FRI *) - Every weekday at 6:00 PM UTC
• cron(0 8 1 * ? *) - First day of every month at 8:00 AM UTC

AWS IAM Requirements

The EventBridge role needs the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:SendMessage"
      ],
      "Resource": "arn:aws:sqs:*:*:*"
    }
  ]
}

The application needs these AWS permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "scheduler:CreateSchedule",
        "scheduler:UpdateSchedule",
        "scheduler:DeleteSchedule",
        "scheduler:GetSchedule",
        "scheduler:ListSchedules",
        "scheduler:CreateScheduleGroup",
        "scheduler:DeleteScheduleGroup",
        "iam:PassRole"
      ],
      "Resource": "*"
    }
  ]
}

Architecture

The service follows a clean architecture pattern:

• Controllers - Handle HTTP requests and responses
• Services - Contain business logic
• AWS Services - Handle AWS SDK interactions
• DTOs - Data validation and transformation

Error Handling

The service provides proper error responses:

• 400 - Bad Request (invalid parameters)
• 404 - Not Found (schedule or group doesn't exist)
• 409 - Conflict (schedule name already exists)
• 500 - Internal Server Error

License

This project is MIT licensed.