Build a Production-Ready SMS Scheduler with Fastify, AWS, and Vonage

mkdir fastify-sms-scheduler
cd fastify-sms-scheduler

npm init -y

npm install fastify @fastify/env @aws-sdk/client-eventbridge @aws-sdk/client-sns @vonage/server-sdk dotenv

npm install --save-dev pino-pretty

// package.json
{
  // ... other configurations
  ""scripts"": {
    ""start"": ""node server.js"",
    ""dev"": ""node server.js | npx pino-pretty""
  }
  // ...
}

fastify-sms-scheduler/
├── node_modules/
├── routes/
│   ├── schedule.js         # Handles /schedule endpoint
│   └── webhook.js          # Handles /webhook/sns endpoint
├── .env                    # Environment variables (DO NOT COMMIT)
├── .gitignore
├── package.json
├── package-lock.json
└── server.js               # Main Fastify application setup

# .gitignore
node_modules
.env

# .env

# AWS Configuration
# Ensure AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) are configured
# via environment variables OR ~/.aws/credentials file.
AWS_REGION=us-east-1 # Replace with your desired AWS region
SNS_TOPIC_ARN=arn:aws:sns:us-east-1:123456789012:MySmsSchedulerTopic # Replace with your SNS Topic ARN (created later)
EVENTBRIDGE_ROLE_ARN=arn:aws:iam::123456789012:role/MyEventBridgeSnsRole # Replace with your EventBridge IAM Role ARN (created later)

# Vonage Configuration
VONAGE_API_KEY=YOUR_VONAGE_API_KEY
VONAGE_API_SECRET=YOUR_VONAGE_API_SECRET
VONAGE_FROM_NUMBER=+12015550123 # Replace with your purchased Vonage number (E.164 format)

# Server Configuration
HOST=0.0.0.0
PORT=3000
LOG_LEVEL=info
# For development, set this to your ngrok URL or public IP/domain
# For production, set this to your server's public domain/IP
PUBLIC_WEBHOOK_URL=https://your-publicly-accessible-url.com # IMPORTANT! Replace with your actual public URL

// server.js
'use strict';

const path = require('path');
const Fastify = require('fastify');
const fastifyEnv = require('@fastify/env');
const scheduleRoutes = require('./routes/schedule');
const webhookRoutes = require('./routes/webhook');

// --- Environment Variable Schema and Loading ---
// Defines required environment variables and their expected format/pattern
const envSchema = {
    type: 'object',
    required: [
        'AWS_REGION',
        'SNS_TOPIC_ARN',
        'EVENTBRIDGE_ROLE_ARN',
        'VONAGE_API_KEY',
        'VONAGE_API_SECRET',
        'VONAGE_FROM_NUMBER',
        'PUBLIC_WEBHOOK_URL',
    ],
    properties: {
        AWS_REGION: { type: 'string' },
        SNS_TOPIC_ARN: { type: 'string', pattern: '^arn:aws:sns:[^:]+:[^:]+:[^:]+' }, // Matches standard SNS ARN format
        EVENTBRIDGE_ROLE_ARN: { type: 'string', pattern: '^arn:aws:iam::[^:]+:role/.+' }, // Matches standard IAM Role ARN format
        VONAGE_API_KEY: { type: 'string' },
        VONAGE_API_SECRET: { type: 'string' },
        VONAGE_FROM_NUMBER: { type: 'string', pattern: '^\\+[1-9]\\d{1,14}' }, // E.164 format
        HOST: { type: 'string', default: '0.0.0.0' },
        PORT: { type: 'number', default: 3000 },
        LOG_LEVEL: { type: 'string', default: 'info' },
        PUBLIC_WEBHOOK_URL: { type: 'string', format: 'uri' }, // Ensures it's a valid URI
    },
};

const envOptions = {
    confKey: 'config', // Access environment variables via `fastify.config`
    schema: envSchema, // Validate environment variables against the schema
    dotenv: true,      // Load .env file if present
};

// --- Fastify Instance ---
const fastify = Fastify({
    logger: {
        level: process.env.LOG_LEVEL || 'info', // Set log level from env or default
        // Use pino-pretty only if NODE_ENV is not 'production' for readability
        // The 'dev' script handles piping to pino-pretty
        transport: process.env.NODE_ENV !== 'production'
            ? { target: 'pino-pretty' }
            : undefined,
    },
});

// --- Plugin Registration ---
fastify
    .register(fastifyEnv, envOptions) // Load and validate environment variables
    .after(err => { // Ensure env vars are loaded before proceeding
        if (err) {
            fastify.log.error('Environment variable validation failed:', err);
            process.exit(1);
        }
        fastify.log.info('Environment variables loaded successfully.');

        // Decorate Fastify instance with AWS/Vonage clients after config is loaded
        try {
            // AWS SDK Clients (v3 uses modular clients)
            const { EventBridgeClient } = require('@aws-sdk/client-eventbridge');
            const { SNSClient } = require('@aws-sdk/client-sns');
            // Initialize EventBridge client
            fastify.decorate('eventBridge', new EventBridgeClient({ region: fastify.config.AWS_REGION }));
            // Initialize SNS client (Needed for signature verification or future SNS actions)
            fastify.decorate('snsClient', new SNSClient({ region: fastify.config.AWS_REGION }));
            fastify.log.info('AWS SDK clients initialized.');

            // Vonage Client
            const { Vonage } = require('@vonage/server-sdk');
            const vonage = new Vonage({
                apiKey: fastify.config.VONAGE_API_KEY,
                apiSecret: fastify.config.VONAGE_API_SECRET,
            });
            fastify.decorate('vonage', vonage); // Make Vonage client available as fastify.vonage
            fastify.log.info('Vonage SDK client initialized.');

        } catch (sdkError) {
            fastify.log.error('Failed to initialize SDK clients:', sdkError);
            process.exit(1);
        }

        // Register Routes after plugins and decorators are ready
        fastify.register(scheduleRoutes, { prefix: '/schedule' }); // Routes defined in routes/schedule.js
        fastify.register(webhookRoutes, { prefix: '/webhook' });   // Routes defined in routes/webhook.js
        fastify.log.info('Routes registered.');
    });


// --- Health Check Route ---
// Basic endpoint to check if the server is running
fastify.get('/health', async (request, reply) => {
    return { status: 'ok', timestamp: new Date().toISOString() };
});


// --- Start Server ---
const start = async () => {
    try {
        // Wait for Fastify to be fully ready (plugins loaded, decorators applied)
        await fastify.ready();
        // Start listening for connections
        await fastify.listen({ port: fastify.config.PORT, host: fastify.config.HOST });
        fastify.log.info(`Server listening on port ${fastify.server.address().port}`);
        fastify.log.info(`Webhook base URL configured as: ${fastify.config.PUBLIC_WEBHOOK_URL}`);
        fastify.log.warn('Ensure the /webhook/sns endpoint is publicly accessible and matches the PUBLIC_WEBHOOK_URL for SNS notifications.');

    } catch (err) {
        fastify.log.error('Error starting server:', err);
        process.exit(1); // Exit if server fails to start
    }
};

start(); // Run the server start function

// routes/schedule.js
'use strict';

const { PutRuleCommand, PutTargetsCommand } = require('@aws-sdk/client-eventbridge');
const { randomUUID } = require('crypto'); // For unique rule names

// --- Request Body Schema for Validation ---
// Defines the expected structure and constraints for the POST request body
const scheduleBodySchema = {
    type: 'object',
    required: ['phoneNumber', 'message', 'sendAt'],
    properties: {
        phoneNumber: {
            type: 'string',
            description: 'Recipient phone number in E.164 format (e.g., +14155552671)',
            // Validates the phone number against the E.164 format pattern
            pattern: '^\\+[1-9]\\d{1,14}',
        },
        message: {
            type: 'string',
            description: 'The SMS message content',
            minLength: 1,          // Must not be empty
            maxLength: 1600,       // Vonage supports longer messages via concatenation
        },
        sendAt: {
            type: 'string',
            description: 'ISO 8601 timestamp for when to send the message (e.g., 2025-12-31T23:59:00Z). Must be in the future.',
            format: 'date-time',   // Validates ISO 8601 format
        },
    },
};

// --- Route Plugin ---
async function scheduleRoutes(fastify, options) {

    // Define the POST /schedule endpoint with schema validation
    fastify.post('/', { schema: { body: scheduleBodySchema } }, async (request, reply) => {
        const { phoneNumber, message, sendAt } = request.body;
        // Access decorated clients (eventBridge), config, and logger from Fastify instance
        const { eventBridge, config, log } = fastify;

        const scheduleTimestamp = new Date(sendAt);
        const now = new Date();

        // --- Input Validation ---
        // Check if the requested send time is in the future
        if (scheduleTimestamp <= now) {
            log.warn({ body: request.body }, 'Scheduled time is not in the future');
            return reply.code(400).send({ error: 'Scheduled time must be in the future.' });
        }

        // EventBridge rule names must be unique and < 64 chars
        // Generate a unique name using a prefix and UUID
        const ruleName = `sms-schedule-${randomUUID()}`;

        // EventBridge schedule expression for a specific time (one-time trigger)
        // Format: at(YYYY-MM-DDTHH:MM:SS) - Requires UTC time
        const scheduleExpression = `at(${scheduleTimestamp.toISOString().substring(0, 19)})`;

        // Payload to send to the SNS topic when the schedule triggers
        const snsInputPayload = JSON.stringify({
            phoneNumber: phoneNumber,
            message: message,
            // Include metadata for potential tracking/debugging in the webhook
            scheduledRuleName: ruleName,
            originalSendAt: sendAt,
        });

        log.info({ ruleName, scheduleExpression, phoneNumber }, 'Attempting to create EventBridge rule');

        try {
            // --- Create EventBridge Rule ---
            // Define parameters for the PutRule API call
            const putRuleParams = {
                Name: ruleName,                          // Unique rule name
                ScheduleExpression: scheduleExpression,  // Specific time trigger
                State: 'ENABLED',                        // Ensure the rule is active
                Description: `One-time schedule to send SMS to ${phoneNumber}`,
                // EventBridge automatically deletes one-time schedule rules ('at()' expression)
                // after they run, so no explicit deletion logic is needed here.
            };
            const ruleCommand = new PutRuleCommand(putRuleParams);
            // Send the command to AWS EventBridge
            const ruleResponse = await eventBridge.send(ruleCommand);
            log.info({ ruleName, ruleArn: ruleResponse.RuleArn }, 'EventBridge rule created successfully');

            // --- Set Target for the Rule (SNS Topic) ---
            // Define parameters to link the rule to our SNS topic
            const putTargetsParams = {
                Rule: ruleName, // The rule we just created
                Targets: [
                    {
                        Id: `target-${ruleName}`,              // Unique target ID for this rule
                        Arn: config.SNS_TOPIC_ARN,           // Target is our SNS Topic ARN from config
                        Input: snsInputPayload,                // Pass the SMS details as input to the target
                        RoleArn: config.EVENTBRIDGE_ROLE_ARN, // Role allowing EventBridge to publish to SNS
                    },
                ],
            };
            const targetCommand = new PutTargetsCommand(putTargetsParams);
            // Send the command to link the target
            await eventBridge.send(targetCommand);
            log.info({ ruleName, targetId: `target-${ruleName}` }, 'EventBridge target set successfully');

            // --- Respond to Client ---
            // Send a 202 Accepted response: the request is accepted, and the SMS is scheduled
            reply.code(202).send({
                message: 'SMS scheduled successfully.',
                ruleName: ruleName, // Optionally return the rule name for reference
                scheduledTime: scheduleTimestamp.toISOString(),
            });

        } catch (error) {
            log.error({ err: error, ruleName }, 'Error creating EventBridge rule or target');

            // Basic error handling for AWS SDK errors
            // Consider more specific error handling (e.g., check AWS error codes)
            // Potential enhancement: Attempt cleanup (delete rule) if target setting fails,
            // though EventBridge might handle partially created resources.
            reply.code(500).send({ error: 'Failed to schedule SMS due to an internal error.' });
        }
    });
}

module.exports = scheduleRoutes;

// routes/webhook.js
'use strict';

const https = require('https'); // Standard Node.js module for HTTPS requests
const { Buffer } = require('buffer'); // Potentially needed for signature verification

// --- Helper function to perform HTTPS GET requests ---
// Used to confirm the SNS subscription by visiting the SubscribeURL
function httpsGet(url) {
    return new Promise((resolve, reject) => {
        https.get(url, (res) => {
            let data = '';
            res.on('data', (chunk) => { data += chunk; });
            res.on('end', () => {
                // Resolve on success status codes
                if (res.statusCode >= 200 && res.statusCode < 300) {
                    resolve({ statusCode: res.statusCode, data: data });
                } else {
                    reject(new Error(`HTTPS GET failed for ${url} with status ${res.statusCode}`));
                }
            });
        }).on('error', (err) => {
            // Reject on network errors
            reject(err);
        });
    });
}


// --- Route Plugin ---
async function webhookRoutes(fastify, options) {
    const { vonage, config, log, snsClient } = fastify; // Access decorated clients, config, logger, and snsClient

    fastify.post('/sns', {
        // Configure Fastify to provide the raw request body
        // This is needed because SNS sends a raw JSON string, and
        // signature verification (if implemented) requires the raw bytes.
        config: {
            rawBody: true
        }
    }, async (request, reply) => {
        // Get the SNS message type header (e.g., 'SubscriptionConfirmation', 'Notification')
        const messageType = request.headers['x-amz-sns-message-type'];
        let snsMessage;

        // --- Log raw headers and body for debugging ---
        log.debug({ headers: request.headers, rawBody: request.rawBody?.toString() }, 'Received SNS webhook request');


        // --- Parse SNS Message Body ---
        try {
            // SNS sends the message as a raw JSON string in the request body
            if (!request.rawBody) {
                 throw new Error('Request body is missing');
            }
            // Parse the raw body string into a JavaScript object
            snsMessage = JSON.parse(request.rawBody.toString());
            log.info({ messageType, messageId: snsMessage.MessageId || 'N/A' }, 'Parsed SNS message');
        } catch (parseError) {
            log.error({ err: parseError, rawBody: request.rawBody?.toString() }, 'Failed to parse SNS message JSON');
            return reply.code(400).send({ error: 'Invalid SNS message format' });
        }

        // --- Handle Subscription Confirmation ---
        if (messageType === 'SubscriptionConfirmation') {
            log.info({ subscribeURL: snsMessage.SubscribeURL }, 'Received SNS Subscription Confirmation request');
            try {
                // IMPORTANT SECURITY CHECK: Validate the SubscribeURL origin before fetching
                const subscribeUrl = new URL(snsMessage.SubscribeURL);
                // Ensure it's HTTPS and an expected AWS domain to prevent SSRF attacks
                if (subscribeUrl.protocol !== 'https:' || !subscribeUrl.hostname.endsWith('.amazonaws.com')) {
                    log.error({ subscribeURL: snsMessage.SubscribeURL }, 'Invalid SubscribeURL domain or protocol');
                    return reply.code(400).send({ error: 'Invalid subscription URL' });
                }

                // Call the SubscribeURL provided by AWS to confirm the subscription
                log.info(`Attempting to confirm subscription by visiting: ${snsMessage.SubscribeURL}`);
                const confirmationResponse = await httpsGet(snsMessage.SubscribeURL);
                log.info({ url: snsMessage.SubscribeURL, statusCode: confirmationResponse.statusCode }, 'Successfully confirmed SNS subscription');
                // Respond with 200 OK to SNS to indicate successful confirmation
                return reply.code(200).send({ message: 'Subscription confirmed' });

            } catch (confirmError) {
                log.error({ err: confirmError, subscribeURL: snsMessage.SubscribeURL }, 'Failed to confirm SNS subscription via SubscribeURL');
                return reply.code(500).send({ error: 'Failed to confirm subscription' });
            }
        }

        // --- Handle Notification ---
        else if (messageType === 'Notification') {
            log.info({ messageId: snsMessage.MessageId, subject: snsMessage.Subject }, 'Received SNS Notification');

            try {
                // --- [PRODUCTION CRITICAL] Verify SNS Message Signature ---
                // This step is crucial to ensure the message is authentic (from AWS SNS) and unaltered.
                // Implementation involves:
                // 1. Getting the message fields in the correct order.
                // 2. Fetching the AWS SNS public signing certificate from snsMessage.SigningCertURL (with validation).
                // 3. Verifying the signature (snsMessage.Signature) using the certificate and message data.
                // See AWS Docs: https://docs.aws.amazon.com/sns/latest/dg/sns-verify-signature-of-message.html
                // Example libraries: 'sns-validator', or manual implementation using Node 'crypto'.
                /*
                const { MessageVerifier } = require('aws-sns-message-validator'); // Example using a library
                const verifier = new MessageVerifier();
                try {
                    await verifier.validate(snsMessage); // Throws error if invalid
                    log.info({ messageId: snsMessage.MessageId }, 'SNS message signature verified successfully.');
                } catch (verificationError) {
                    log.warn({ messageId: snsMessage.MessageId, err: verificationError }, 'Invalid SNS message signature');
                    return reply.code(403).send({ error: 'Invalid signature or verification failed' });
                }
                */
                // --- Signature Verification Logic Placeholder End ---


                // --- Parse the inner message payload ---
                // The actual data sent by EventBridge is nested within the 'Message' field of the SNS notification
                const payload = JSON.parse(snsMessage.Message);
                const { phoneNumber, message, scheduledRuleName } = payload; // Extract details

                // Validate required fields in the payload
                if (!phoneNumber || !message) {
                     log.error({ payload, messageId: snsMessage.MessageId }, 'Missing phoneNumber or message in SNS notification payload');
                     return reply.code(400).send({ error: 'Invalid notification payload content' });
                }

                log.info({ phoneNumber, scheduledRuleName, messageId: snsMessage.MessageId }, 'Processing scheduled SMS via Vonage');

                // --- Send SMS using Vonage ---
                // Use the decorated Vonage client (fastify.vonage)
                await vonage.sms.send({
                    to: phoneNumber,                // Recipient number from payload
                    from: config.VONAGE_FROM_NUMBER, // Sender number from config
                    text: message,                  // Message content from payload
                });

                log.info({ phoneNumber, scheduledRuleName, messageId: snsMessage.MessageId }, 'SMS sent successfully via Vonage.');

                // Respond 200 OK to SNS to acknowledge receipt and processing
                return reply.code(200).send({ message: 'Notification processed and SMS sent' });

            } catch (processError) {
                log.error({ err: processError, messageId: snsMessage.MessageId }, 'Error processing SNS notification or sending SMS');
                // Respond with 500 to indicate failure; SNS may retry based on its policy
                return reply.code(500).send({ error: 'Failed to process notification' });
            }
        }

        // --- Handle Unknown Message Type ---
        else {
            log.warn({ messageType, messageId: snsMessage.MessageId || 'N/A' }, 'Received unknown SNS message type');
            // Respond politely but indicate it wasn't processed as expected
            return reply.code(400).send({ error: `Unsupported message type: ${messageType}` });
        }
    });
}

module.exports = webhookRoutes;