HATEOAS State Transitions — Modeling Resource State Machines with Links

// State machine definition for Threat resource
const threatStates = {
  new: {
    label: 'New',
    actions: [
      { rel: 'dt:analyze', method: 'POST', href: '/threats/{id}/analyze', title: 'Analyze Threat' },
      { rel: 'dt:ignore', method: 'POST', href: '/threats/{id}/ignore', title: 'Ignore Threat' },
    ],
    transitionsTo: ['analyzing', 'ignored'],
  },
  analyzing: {
    label: 'Analyzing',
    actions: [
      { rel: 'dt:cancel', method: 'POST', href: '/threats/{id}/cancel-analysis', title: 'Cancel Analysis' },
      { rel: 'dt:classify', method: 'POST', href: '/threats/{id}/classify', title: 'Classify Threat' },
    ],
    transitionsTo: ['new', 'identified'],
  },
  identified: {
    label: 'Identified',
    actions: [
      { rel: 'dt:quarantine', method: 'POST', href: '/threats/{id}/quarantine', title: 'Quarantine' },
      { rel: 'dt:remediate', method: 'POST', href: '/threats/{id}/remediate', title: 'Remediate' },
    ],
    transitionsTo: ['quarantined', 'remediated'],
  },
  quarantined: {
    label: 'Quarantined',
    actions: [
      { rel: 'dt:clean', method: 'POST', href: '/threats/{id}/clean', title: 'Clean Device' },
      { rel: 'dt:false-positive', method: 'POST', href: '/threats/{id}/false-positive', title: 'Mark False Positive' },
    ],
    transitionsTo: ['remediated', 'new'],
  },
  remediated: {
    label: 'Remediated',
    actions: [],
    transitionsTo: [],
  },
  ignored: {
    label: 'Ignored',
    actions: [],
    transitionsTo: [],
  },
};

function getActionsForState(threatId, state) {
  const stateDef = threatStates[state];
  if (!stateDef) return [];
  
  return stateDef.actions.map(action => ({
    ...action,
    href: action.href.replace('{id}', threatId),
  }));
}

// Validate transition
function canTransition(threat, targetState) {
  const stateDef = threatStates[threat.status];
  if (!stateDef) return false;
  return stateDef.transitionsTo.includes(targetState);
}

const express = require('express');
const app = express();

// Middleware to add state-dependent links
function addStateLinks(req, res, next) {
  const originalJson = res.json.bind(res);
  
  res.json = function(body) {
    if (body && body._links) {
      // Get state-dependent actions
      const state = body.status || 'new';
      const stateActions = getActionsForState(body.id, state);
      
      // Add state-dependent links
      for (const action of stateActions) {
        body._links[action.rel] = {
          href: action.href,
          title: action.title,
          method: action.method,
        };
      }
    }
    
    return originalJson(body);
  };
  
  next();
}

app.use(addStateLinks);

app.get('/threats/:id', (req, res) => {
  const threat = getThreat(req.params.id);
  
  res.json({
    ...threat,
    status: threat.status,
    _links: {
      self: { href: `/threats/${threat.id}` },
      collection: { href: '/threats' },
    },
  });
});

// Execute state transition
app.post('/threats/:id/:action', (req, res) => {
  const threat = getThreat(req.params.id);
  const action = req.params.action;
  
  // Map action to target state
  const actionStateMap = {
    analyze: 'analyzing',
    ignore: 'ignored',
    cancel: 'new',
    classify: 'identified',
    quarantine: 'quarantined',
    remediate: 'remediated',
    clean: 'remediated',
    'false-positive': 'new',
  };
  
  const targetState = actionStateMap[action];
  if (!targetState || !canTransition(threat, targetState)) {
    return res.status(422).json({
      error: `Cannot transition from ${threat.status} to ${targetState}`,
      _links: {
        self: { href: `/threats/${threat.id}` },
      },
    });
  }
  
  // Update state
  const updated = updateThreatState(threat.id, targetState);
  
  res.json({
    ...updated,
    _links: {
      self: { href: `/threats/${updated.id}` },
    },
  });
});

class StateMachineClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
  }
  
  async fetch(url) {
    const res = await fetch(`${this.baseUrl}${url}`);
    return res.json();
  }
  
  async getAvailableActions(threatId) {
    const threat = await this.fetch(`/threats/${threatId}`);
    
    console.log(`Threat: ${threat.name}`);
    console.log(`Current state: ${threat.status}`);
    
    // Available actions are in _links, filtered by state
    const actions = Object.entries(threat._links || {})
      .filter(([rel]) => rel.startsWith('dt:') && rel !== 'dt:scan' && rel !== 'dt:deep-scan')
      .map(([rel, link]) => ({
        rel,
        href: link.href,
        title: link.title,
      }));
    
    console.log('Available actions:');
    for (const action of actions) {
      console.log(`  [${action.rel}] ${action.title}`);
    }
    
    return { threat, actions };
  }
  
  async executeAction(threatId, rel) {
    const threat = await this.fetch(`/threats/${threatId}`);
    const action = threat._links[rel];
    
    if (!action) {
      throw new Error(`Action '${rel}' not available in current state`);
    }
    
    console.log(`Executing: ${action.title}`);
    
    const res = await fetch(`${this.baseUrl}${action.href}`, {
      method: action.method || 'POST',
      headers: { 'Content-Type': 'application/json' },
    });
    
    return res.json();
  }
  
  async walkThroughWorkflow(threatId) {
    // Navigate through the state machine step by step
    let currentState = 'new';
    const workflow = [
      'dt:analyze',
      'dt:classify',
      'dt:quarantine',
      'dt:clean',
    ];
    
    for (const action of workflow) {
      const { threat } = await this.getAvailableActions(threatId);
      console.log(`\n--- Step: ${action} ---`);
      
      const result = await this.executeAction(threatId, action);
      console.log(`New state: ${result.status}`);
      currentState = result.status;
    }
    
    console.log('\nWorkflow complete!');
  }
}

// Usage
const client = new StateMachineClient('https://api.dodatech.com');
await client.walkThroughWorkflow('threat-101');