agentHeartbeat.js

Go to the documentation of this file.

/**
 * @file agentHeartbeat.js
 * @module routes/agentHeartbeat
 * @description Agent heartbeat endpoint for health monitoring and command queue polling.
 * Agents periodically call this endpoint to report status and retrieve pending commands.
 * @requires express
 * @author RMM-PSA Development Team
 * @copyright 2026 RMM-PSA Platform
 * @license Proprietary
 */
 
/**
 * @apiDefine AgentHeartbeat Agent Heartbeat
 * Agent health checks and command polling
 */
 
const express = require('express');
const router = express.Router();
 
// Dummy in-memory command queue for demo purposes
const agentCommands = {};
 
// Example: Add a command for an agent (in real use, this would be DB/Redis)
/**
 *
 * @param agent_uuid
 * @param command
 */
function addCommand(agent_uuid, command) {
  if (!agentCommands[agent_uuid]) agentCommands[agent_uuid] = [];
  agentCommands[agent_uuid].push(command);
}
 
// Example: Get and clear commands for agent
/**
 *
 * @param agent_uuid
 */
function getPendingCommandsForAgent(agent_uuid) {
  const cmds = agentCommands[agent_uuid] || [];
  agentCommands[agent_uuid] = [];
  return cmds;
}
 
/**
 * @api {post} /api/agent/heartbeat/:agent_uuid Agent heartbeat
 * @apiName AgentHeartbeat
 * @apiGroup AgentHeartbeat
 * @apiDescription Agent health check and command polling endpoint. Agents call periodically
 * to report online status and retrieve pending commands from in-memory queue.
 * Returns commands and clears queue for agent. TODO: Implement agent authentication.
 * @apiParam {string} agent_uuid Agent UUID from URL path
 * @apiSuccess {object[]} commands Array of pending commands for agent
 * @apiSuccess {string} commands.command_id Command ID
 * @apiSuccess {string} commands.type Command type (e.g., "run_script", "update")
 * @apiSuccess {object} commands.payload Command parameters
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/agent/heartbeat/abc-123-uuid \\\
 *     -H "Content-Type: application/json" \\\
 *     -d '{}'
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "commands": [
 *       {
 *         "command_id": "cmd-001",
 *         "type": "run_script",
 *         "payload": {
 *           "script_id": 42,
 *           "script_content": "Get-Service"
 *         }
 *       }
 *     ]
 *   }
 * @apiSuccessExample {json} No-Commands-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "commands": []
 *   }
 */
router.post('/heartbeat/:agent_uuid', async (req, res) => {
  const agent_uuid = req.params.agent_uuid;
  // TODO: Authenticate agent (JWT, etc.)
  // Get and clear pending commands
  const commands = getPendingCommandsForAgent(agent_uuid);
  res.json({ commands });
});
 
module.exports = router;