@mirante/alarms 0.4.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@mirante/alarms",
+  "version": "0.4.0",
+  "type": "module",
+  "private": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./runtime.proto": "./runtime.proto"
+  },
+  "scripts": {
+    "prepare": "node -e \"var fs=require('fs');var src='../../../proto/alarms/v1/alarms.proto';if(fs.existsSync(src))fs.copyFileSync(src,'runtime.proto')\"",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.13.4",
+    "@grpc/proto-loader": "^0.7.15"
+  }
+}

package/runtime.proto

@@ -0,0 +1,94 @@
+syntax = "proto3";
+
+package alarms.v1;
+
+option go_package = "github.com/g0ulartleo/mirante/proto/alarms/v1;alarmsv1";
+
+import "google/protobuf/struct.proto";
+
+service AlarmRuntime {
+  rpc ListAlarms(ListAlarmsRequest) returns (ListAlarmsResponse);
+  rpc GetAlarm(GetAlarmRequest) returns (GetAlarmResponse);
+  rpc RunAlarm(RunAlarmRequest) returns (RunAlarmResponse);
+  rpc Health(HealthRequest) returns (HealthResponse);
+}
+
+message HealthRequest {}
+
+message HealthResponse {
+  string status = 1;
+}
+
+message ListAlarmsRequest {}
+
+message ListAlarmsResponse {
+  repeated Alarm alarms = 1;
+}
+
+message GetAlarmRequest {
+  string alarm_id = 1;
+}
+
+message GetAlarmResponse {
+  Alarm alarm = 1;
+}
+
+message RunAlarmRequest {
+  string alarm_id = 1;
+}
+
+message RunAlarmResponse {
+  SignalStatus status = 1;
+  string message = 2;
+  RuntimeError error = 3;
+  repeated google.protobuf.Struct details = 4;
+}
+
+enum SignalStatus {
+  SIGNAL_STATUS_UNSPECIFIED = 0;
+  SIGNAL_STATUS_HEALTHY = 1;
+  SIGNAL_STATUS_UNHEALTHY = 2;
+  SIGNAL_STATUS_UNKNOWN = 3;
+  SIGNAL_STATUS_WARNING = 4;
+}
+
+enum RuntimeErrorCode {
+  RUNTIME_ERROR_CODE_UNSPECIFIED = 0;
+  RUNTIME_ERROR_CODE_UNSUPPORTED = 1;
+  RUNTIME_ERROR_CODE_RUNALARM_FAILED = 2;
+  RUNTIME_ERROR_CODE_INTERNAL = 3;
+}
+
+message RuntimeError {
+  RuntimeErrorCode code = 1;
+  string message = 2;
+}
+
+message Alarm {
+  string id = 1;
+  string name = 2;
+  string description = 3;
+  string how_to_fix = 4;
+  repeated string path = 5;
+  string cron = 6;
+  string interval = 7;
+  AlarmNotifications notifications = 8;
+}
+
+message AlarmNotifications {
+  map<string, NotificationChannels> channels = 1;
+}
+
+message NotificationChannels {
+  repeated SlackWebhookNotification slack_webhooks = 1;
+  repeated EmailNotification emails = 2;
+  bool notify_missing_signals = 3;
+}
+
+message SlackWebhookNotification {
+  string url = 1;
+}
+
+message EmailNotification {
+  repeated string to = 1;
+}

package/src/index.d.ts

@@ -0,0 +1,106 @@
+export const protoPath: string;
+
+export const SignalStatus: {
+  readonly UNSPECIFIED: 'SIGNAL_STATUS_UNSPECIFIED';
+  readonly HEALTHY: 'SIGNAL_STATUS_HEALTHY';
+  readonly UNHEALTHY: 'SIGNAL_STATUS_UNHEALTHY';
+  readonly UNKNOWN: 'SIGNAL_STATUS_UNKNOWN';
+  readonly WARNING: 'SIGNAL_STATUS_WARNING';
+};
+
+export const RuntimeErrorCode: {
+  readonly UNSPECIFIED: 'RUNTIME_ERROR_CODE_UNSPECIFIED';
+  readonly UNSUPPORTED: 'RUNTIME_ERROR_CODE_UNSUPPORTED';
+  readonly RUNALARM_FAILED: 'RUNTIME_ERROR_CODE_RUNALARM_FAILED';
+  readonly INTERNAL: 'RUNTIME_ERROR_CODE_INTERNAL';
+};
+
+export type SignalStatusValue = typeof SignalStatus[keyof typeof SignalStatus];
+export type RuntimeErrorCodeValue = typeof RuntimeErrorCode[keyof typeof RuntimeErrorCode];
+
+export interface Signal {
+  status: SignalStatusValue;
+  message: string;
+  details?: SignalDetail[];
+}
+
+export function healthy(message: string, options?: { details?: SignalDetail[] }): Signal;
+export function warning(message: string, options?: { details?: SignalDetail[] }): Signal;
+export function unhealthy(message: string, options?: { details?: SignalDetail[] }): Signal;
+export function unknown(message: string, options?: { details?: SignalDetail[] }): Signal;
+
+export interface AlarmDefinition {
+  id: string;
+  name?: string;
+  description: string;
+  howToFix?: string;
+  cron?: string;
+  interval?: string;
+  notifications?: {
+    critical?: {
+      slackWebhooks?: string[];
+      emails?: string[][];
+      notifyMissingSignals?: boolean;
+    };
+    warnings?: {
+      slackWebhooks?: string[];
+      emails?: string[][];
+      notifyMissingSignals?: boolean;
+    };
+  };
+  run(): Signal | Promise<Signal>;
+}
+
+export interface Alarm {
+  id: string;
+  name: string;
+  description: string;
+  howToFix?: string;
+  path?: string[];
+  cron?: string;
+  interval?: string;
+  notifications?: AlarmNotifications;
+}
+
+export interface AlarmNotifications {
+  channels: Record<string, NotificationChannels>;
+}
+
+export interface NotificationChannels {
+  slackWebhooks?: SlackWebhookNotification[];
+  emails?: EmailNotification[];
+  notifyMissingSignals?: boolean;
+}
+
+export interface SlackWebhookNotification {
+  url: string;
+}
+
+export interface EmailNotification {
+  to: string[];
+}
+
+export interface RunAlarmResponse {
+  status: SignalStatusValue;
+  message: string;
+  error?: RuntimeError;
+  details?: SignalDetail[];
+}
+
+export interface RuntimeError {
+  code: RuntimeErrorCodeValue;
+  message: string;
+}
+
+export type SignalDetail = Record<string, unknown>;
+
+export function loadAlarms(options: { alarmsDir: string }): Promise<AlarmDefinition[]>;
+export function createRuntimeService(alarms: AlarmDefinition[]): Record<string, unknown>;
+export function serveRuntime(options: {
+  alarmsDir: string;
+  addr?: string;
+  credentials?: object;
+  grpcOptions?: Record<string, number>;
+}): Promise<unknown>;
+export function toProtoAlarm(alarm: AlarmDefinition): Promise<Alarm>;
+export function normalizeDetails(details: SignalDetail[]): SignalDetail[];

package/src/index.js

@@ -0,0 +1,255 @@
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const protoPath = path.join(packageRoot, 'runtime.proto');
+
+export const SignalStatus = Object.freeze({
+  UNSPECIFIED: 'SIGNAL_STATUS_UNSPECIFIED',
+  HEALTHY: 'SIGNAL_STATUS_HEALTHY',
+  UNHEALTHY: 'SIGNAL_STATUS_UNHEALTHY',
+  UNKNOWN: 'SIGNAL_STATUS_UNKNOWN',
+  WARNING: 'SIGNAL_STATUS_WARNING',
+});
+
+export const RuntimeErrorCode = Object.freeze({
+  UNSPECIFIED: 'RUNTIME_ERROR_CODE_UNSPECIFIED',
+  UNSUPPORTED: 'RUNTIME_ERROR_CODE_UNSUPPORTED',
+  RUNALARM_FAILED: 'RUNTIME_ERROR_CODE_RUNALARM_FAILED',
+  INTERNAL: 'RUNTIME_ERROR_CODE_INTERNAL',
+});
+
+export function healthy(message, options = {}) {
+  return {
+    status: SignalStatus.HEALTHY,
+    message: String(message ?? ''),
+    details: normalizeDetails(options.details ?? []),
+  };
+}
+
+export function warning(message, options = {}) {
+  return {
+    status: SignalStatus.WARNING,
+    message: String(message ?? ''),
+    details: normalizeDetails(options.details ?? []),
+  };
+}
+
+export function unhealthy(message, options = {}) {
+  return {
+    status: SignalStatus.UNHEALTHY,
+    message: String(message ?? ''),
+    details: normalizeDetails(options.details ?? []),
+  };
+}
+
+export function unknown(message, options = {}) {
+  return {
+    status: SignalStatus.UNKNOWN,
+    message: String(message ?? ''),
+    details: normalizeDetails(options.details ?? []),
+  };
+}
+
+export async function loadAlarms({ alarmsDir }) {
+  if (!alarmsDir) {
+    throw new Error('alarmsDir is required');
+  }
+  if (!fs.existsSync(alarmsDir)) {
+    return [];
+  }
+
+  const alarms = [];
+  const seen = new Set();
+
+  async function walk(dir, relPath) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath, [...relPath, entry.name]);
+      } else if (entry.isFile() && /\.(js|mjs|ts)$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+        const moduleURL = pathToFileURL(fullPath).href;
+        const mod = await import(moduleURL);
+        for (const value of Object.values(mod)) {
+          if (typeof value !== 'object' || value === null) continue;
+          if (typeof value.id !== 'string') continue;
+          if (typeof value.run !== 'function') continue;
+          if (!value.cron && !value.interval) continue;
+
+          validateAlarm(value);
+          if (seen.has(value.id)) {
+            throw new Error(`duplicate alarm id ${JSON.stringify(value.id)}`);
+          }
+          seen.add(value.id);
+          value.path = relPath;
+          alarms.push(value);
+        }
+      }
+    }
+  }
+
+  await walk(alarmsDir, []);
+  return alarms;
+}
+
+export function createRuntimeService(alarms) {
+  const byID = new Map(alarms.map((alarm) => [alarm.id, alarm]));
+  return {
+    ListAlarms: async (call, callback) => {
+      try {
+        callback(null, { alarms: await Promise.all(alarms.map(toProtoAlarm)) });
+      } catch (error) {
+        callback(error);
+      }
+    },
+    GetAlarm: async (call, callback) => {
+      try {
+        const alarmID = call.request?.alarmId;
+        const alarm = byID.get(alarmID);
+        if (!alarm) {
+          callback({ code: 5, message: `alarm ${JSON.stringify(alarmID)} not found` });
+          return;
+        }
+        callback(null, { alarm: await toProtoAlarm(alarm) });
+      } catch (error) {
+        callback(error);
+      }
+    },
+    RunAlarm: async (call, callback) => {
+      const alarmID = call.request?.alarmId;
+      const alarm = byID.get(alarmID);
+      if (!alarm) {
+        callback(null, errorResponse(
+          RuntimeErrorCode.UNSUPPORTED,
+          `alarm ${JSON.stringify(alarmID)} not found`,
+        ));
+        return;
+      }
+
+      try {
+        const signal = await alarm.run();
+        if (!signal || signal.status == null) {
+          callback(null, errorResponse(
+            RuntimeErrorCode.RUNALARM_FAILED,
+            `alarm ${JSON.stringify(alarmID)} did not return a valid signal`,
+          ));
+          return;
+        }
+        callback(null, signal);
+      } catch (error) {
+        callback(null, errorResponse(
+          RuntimeErrorCode.RUNALARM_FAILED,
+          `run failed: ${error.message}`,
+        ));
+      }
+    },
+    Health: async (_call, callback) => {
+      callback(null, { status: 'SERVING' });
+    },
+  };
+}
+
+export async function serveRuntime({ alarmsDir, addr = '127.0.0.1:50051', credentials, grpcOptions = {} }) {
+  const grpc = require('@grpc/grpc-js');
+  const protoLoader = require('@grpc/proto-loader');
+  const packageDefinition = protoLoader.loadSync(protoPath, {
+    longs: String,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+  });
+  const proto = grpc.loadPackageDefinition(packageDefinition).alarmruntime.v1;
+  const alarms = await loadAlarms({ alarmsDir });
+  const server = new grpc.Server(grpcOptions);
+  server.addService(proto.AlarmRuntime.service, createRuntimeService(alarms));
+  const creds = credentials ?? grpc.ServerCredentials.createInsecure();
+  await new Promise((resolve, reject) => {
+    server.bindAsync(addr, creds, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+  return server;
+}
+
+const KNOWN_SEVERITIES = new Set(['critical', 'warnings']);
+
+export async function toProtoAlarm(alarm) {
+  validateAlarm(alarm);
+  const raw = alarm.notifications ?? {};
+  const channels = {};
+  for (const [severity, ch] of Object.entries(raw)) {
+    if (!KNOWN_SEVERITIES.has(severity)) {
+      console.warn(`unknown notification severity ${JSON.stringify(severity)}, skipping`);
+      continue;
+    }
+    channels[severity] = {
+      slackWebhooks: (ch.slackWebhooks ?? []).filter(Boolean).map((url) => ({ url })),
+      emails: (ch.emails ?? []).map((to) => ({ to: normalizeArray(to).filter(Boolean) })),
+      notifyMissingSignals: Boolean(ch.notifyMissingSignals),
+    };
+  }
+  return {
+    id: alarm.id,
+    name: alarm.name || '',
+    description: alarm.description,
+    howToFix: alarm.howToFix || '',
+    path: alarm.path ?? [],
+    cron: alarm.cron || '',
+    interval: alarm.interval || '',
+    notifications: { channels },
+  };
+}
+
+export function normalizeDetails(details) {
+  return normalizeArray(details).map((detail) => {
+    if (!detail || typeof detail !== 'object' || Array.isArray(detail)) {
+      throw new Error('detail must be a plain object');
+    }
+    return detail;
+  });
+}
+
+function validateAlarm(alarm) {
+  if (typeof alarm.id !== 'string' || !alarm.id) {
+    throw new Error('alarm id is required');
+  }
+  if (!alarm.description) {
+    throw new Error(`alarm ${JSON.stringify(alarm.id)} description is required`);
+  }
+  if (!alarm.cron && !alarm.interval) {
+    throw new Error(`alarm ${JSON.stringify(alarm.id)} cron or interval is required`);
+  }
+  if (alarm.cron && alarm.interval) {
+    throw new Error(`alarm ${JSON.stringify(alarm.id)} cron and interval cannot both be set`);
+  }
+  if (typeof alarm.run !== 'function') {
+    throw new Error(`alarm ${JSON.stringify(alarm.id)} must have a run method`);
+  }
+}
+
+function errorResponse(code, message) {
+  return {
+    status: SignalStatus.UNKNOWN,
+    message,
+    error: { code, message },
+  };
+}
+
+function normalizeArray(value) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}

package/test/index.test.js

@@ -0,0 +1,162 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import { protoPath, RuntimeErrorCode, SignalStatus, loadAlarms } from '../src/index.js';
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'alarms-test-'));
+
+function writeAlarm(dir, relFile, alarmObj) {
+  const name = relFile.replace(/\.ts$/, '.mjs');
+  const fullPath = path.join(dir, name);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  const { run, ...props } = alarmObj;
+  const propsJson = JSON.stringify(props, null, 2);
+  const jsCode = `export const alarm = Object.assign(${propsJson}, { run: ${run} });\n`;
+  fs.writeFileSync(fullPath, jsCode);
+}
+
+describe('mirante-alarms-js', () => {
+  it('exports a runtime proto path', () => {
+    assert.equal(fs.existsSync(protoPath), true);
+    assert.match(fs.readFileSync(protoPath, 'utf8'), /service AlarmRuntime/);
+  });
+
+  it('exports shared enum constants', () => {
+    assert.equal(SignalStatus.WARNING, 'SIGNAL_STATUS_WARNING');
+    assert.equal(RuntimeErrorCode.UNSUPPORTED, 'RUNTIME_ERROR_CODE_UNSUPPORTED');
+  });
+});
+
+describe('loadAlarms', () => {
+  let dir;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(tmpDir, 'load-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns empty array when dir does not exist', async () => {
+    const alarms = await loadAlarms({ alarmsDir: '/nonexistent/path' });
+    assert.deepEqual(alarms, []);
+  });
+
+  it('loads alarms from root of alarmsDir', async () => {
+    writeAlarm(dir, 'check-http.ts', {
+      id: 'check-http',
+      description: 'Checks HTTP',
+      interval: '1m',
+      run: 'function(){}',
+    });
+
+    const alarms = await loadAlarms({ alarmsDir: dir });
+    assert.equal(alarms.length, 1);
+    assert.deepEqual(alarms[0].path, []);
+  });
+
+  it('derives path from single subdirectory', async () => {
+    writeAlarm(dir, 'db/connection-pool.ts', {
+      id: 'db-conn-pool',
+      description: 'Checks connection pool',
+      interval: '1m',
+      run: 'function(){}',
+    });
+
+    const alarms = await loadAlarms({ alarmsDir: dir });
+    assert.equal(alarms.length, 1);
+    assert.deepEqual(alarms[0].path, ['db']);
+  });
+
+  it('derives path from nested subdirectories', async () => {
+    writeAlarm(dir, 'aws/production/ec2/cpu.ts', {
+      id: 'aws-prod-ec2-cpu',
+      description: 'Checks CPU',
+      interval: '1m',
+      run: 'function(){}',
+    });
+
+    const alarms = await loadAlarms({ alarmsDir: dir });
+    assert.equal(alarms.length, 1);
+    assert.deepEqual(alarms[0].path, ['aws', 'production', 'ec2']);
+  });
+
+  it('loads alarms from multiple directories and assigns correct paths', async () => {
+    writeAlarm(dir, 'root-alarm.ts', {
+      id: 'root-alarm',
+      description: 'Root level',
+      interval: '1m',
+      run: 'function(){}',
+    });
+    writeAlarm(dir, 'db/mysql/connections.ts', {
+      id: 'mysql-conns',
+      description: 'MySQL connections',
+      interval: '1m',
+      run: 'function(){}',
+    });
+    writeAlarm(dir, 'db/redis/memory.ts', {
+      id: 'redis-mem',
+      description: 'Redis memory',
+      interval: '1m',
+      run: 'function(){}',
+    });
+    writeAlarm(dir, 'infra/dns.ts', {
+      id: 'dns-check',
+      description: 'DNS check',
+      interval: '1m',
+      run: 'function(){}',
+    });
+
+    const alarms = await loadAlarms({ alarmsDir: dir });
+    assert.equal(alarms.length, 4);
+
+    const byId = Object.fromEntries(alarms.map(a => [a.id, a]));
+    assert.deepEqual(byId['root-alarm'].path, []);
+    assert.deepEqual(byId['mysql-conns'].path, ['db', 'mysql']);
+    assert.deepEqual(byId['redis-mem'].path, ['db', 'redis']);
+    assert.deepEqual(byId['dns-check'].path, ['infra']);
+  });
+
+  it('overrides alarm path if alarm defines one', async () => {
+    writeAlarm(dir, 'custom-path.ts', {
+      id: 'custom-path',
+      description: 'Has path but should be overridden',
+      interval: '1m',
+      run: 'function(){}',
+    });
+
+    const alarms = await loadAlarms({ alarmsDir: dir });
+    assert.equal(alarms.length, 1);
+    assert.deepEqual(alarms[0].path, []);
+  });
+
+  it('fails on duplicate alarm ids across directories', async () => {
+    writeAlarm(dir, 'dup-a.ts', {
+      id: 'dup',
+      description: 'Duplicate A',
+      interval: '1m',
+      run: 'function(){}',
+    });
+    writeAlarm(dir, 'dup-b.ts', {
+      id: 'dup',
+      description: 'Duplicate B',
+      interval: '1m',
+      run: 'function(){}',
+    });
+
+    await assert.rejects(
+      () => loadAlarms({ alarmsDir: dir }),
+      /duplicate alarm id/,
+    );
+  });
+
+  it('throws if alarmsDir is not provided', async () => {
+    await assert.rejects(
+      () => loadAlarms({}),
+      /alarmsDir is required/,
+    );
+  });
+});