@goodandready/dsh-cron 0.3.24 → 0.3.26

package/lib/routes/api.js

@@ -0,0 +1,178 @@
+import { handleTaskWebhookRoute } from './api-task-webhook.js';
+import { sendJson, rejectCrossOrigin, redactTaskSecrets } from '../http-utils.js';
+import {
+  handleTaskExport,
+  handleTaskImport,
+  applyImportPlan,
+} from './api-import-export.js';
+import { handleTelegramWebhook } from './api-webhook.js';
+import {
+  handleHeartbeatPing,
+  handleSchedulePreview,
+  handleDryRunTask,
+  handleScheduleTimeline,
+} from './api-helpers.js';
+import {
+  refuseConfigOwned,
+  handleTaskCollection,
+  createOrUpdateTask,
+  NOT_ALLOWED,
+  NOT_FOUND,
+} from './api-collection.js';
+import { handleTaskItem, deleteTask } from './api-item.js';
+import { handleItemPost } from './api-actions.js';
+
+export {
+  handleTaskExport,
+  handleTaskImport,
+  applyImportPlan,
+  handleTelegramWebhook,
+  handleHeartbeatPing,
+  handleSchedulePreview,
+  handleDryRunTask,
+  handleScheduleTimeline,
+  refuseConfigOwned,
+};
+
+/**
+ * Shared implementation for the /dsh-cron/tasks... and /dsh-cron/action...
+ * route families — the #66 alias is kept alive by the same code path instead
+ * of a duplicated handler.
+ *
+ * IMPORTANT: prefix routes must be registered WITHOUT a trailing slash —
+ * with one, the core degrades matching to exact-path equality and every
+ * deeper path unrouted (#96). Exported for unit tests.
+ */
+export function createCronApiHandler(store, scheduler, collection) {
+  const ctx = collection?.ctx;
+  return async function handleCronApi(req, res) {
+    try {
+      const apiToken = store?.getSettings?.()?.apiToken;
+      const authOptions = { apiToken, ctx };
+      const url = new URL(req.url, 'http://127.0.0.1');
+      const parts = url.pathname.split('/').filter(Boolean);
+      const scope = parts[1]; // 'tasks' | 'action' | 'heartbeat-ping'
+      const id = parts[2];
+      const action = parts[3];
+      const subAction = parts[4];
+
+      if (scope === 'telegram' && id === 'webhook') {
+        await handleTelegramWebhook({ store, scheduler, req, res });
+        return;
+      }
+      if (scope === 'webhook' && id) {
+        await handleTaskWebhookRoute({ store, scheduler, req, res, taskId: id });
+        return;
+      }
+
+      if ((scope === 'heartbeat' || scope === 'heartbeat-ping') && id) {
+        handleHeartbeatPing({ store, req, res, taskId: id, apiToken, ctx });
+        return;
+      }
+
+      if (scope === 'schedule' && id === 'preview') {
+        await handleSchedulePreview({ req, res, url, store, apiToken, ctx });
+        return;
+      }
+      if (scope === 'schedule' && id === 'timeline-24h') {
+        await handleScheduleTimeline({ req, res, url, store, scheduler, apiToken, ctx });
+        return;
+      }
+
+      if (!id) {
+        await handleTaskCollection({ store, scheduler, collection, req, res, url, scope, apiToken, ctx });
+        return;
+      }
+
+      if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
+
+      // Export/import are collection operations that live under /tasks/:id/…,
+      // so they are matched before the generic id handling below.
+      if (id === 'export') {
+        if (req.method !== 'GET') {
+          sendJson(res, 405, NOT_ALLOWED);
+          return;
+        }
+        handleTaskExport({ store, req, res });
+        return;
+      }
+      if (id === 'import') {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, NOT_ALLOWED);
+          return;
+        }
+        await handleTaskImport({ store, scheduler, req, res });
+        return;
+      }
+
+      await handleTaskItem({ store, scheduler, req, res, url, id, action, subAction, apiToken, ctx });
+    } catch (err) {
+      sendJson(res, err.statusCode || 500, { ok: false, error: err.message });
+    }
+  };
+}
+
+// --------------------------------------------------------- external surface
+
+/**
+ * Task operations for the token-guarded /dsh-cron/api/* prefix (#54). The shape
+ * is deliberately small — list, read, create or update, delete, manual run —
+ * and reuses the handlers above, so the confirmation gate for code-executing
+ * tasks and the config-owned refusals are the same code, not a second copy.
+ */
+export async function handleExternalTaskRequest({ store, scheduler, req, res, url, apiToken }) {
+  const parts = url.pathname.split('/').filter(Boolean); // dsh-cron, api, [tasks|heartbeat|schedule], :id?, :action?
+  if (parts[2] === 'webhook' && parts[3]) {
+    await handleTaskWebhookRoute({ store, scheduler, req, res, taskId: parts[3] });
+    return;
+  }
+  if (parts[2] === 'heartbeat' && parts[3]) {
+    handleHeartbeatPing({ store, req, res, taskId: parts[3], apiToken });
+    return;
+  }
+  if (parts[2] === 'schedule' && parts[3] === 'preview') {
+    await handleSchedulePreview({ req, res, url, store, apiToken });
+    return;
+  }
+  const id = parts[3];
+  const action = parts[4];
+  const subAction = parts[5];
+
+  if (!id) {
+    if (req.method === 'GET') {
+      const list = store
+        .list({ status: url.searchParams.get('status') || 'all', query: url.searchParams.get('query') || '' })
+        .map((task) => ({ ...redactTaskSecrets(task), running: scheduler.isRunning(task.id) }));
+      sendJson(res, 200, { ok: true, tasks: list });
+      return;
+    }
+    if (req.method === 'POST') {
+      await createOrUpdateTask({ store, scheduler, req, res, apiToken, ctx: undefined });
+      return;
+    }
+    sendJson(res, 405, NOT_ALLOWED);
+    return;
+  }
+
+  if (req.method === 'POST') {
+    const handled = await handleItemPost({ store, scheduler, req, res, url, id, action, subAction });
+    if (handled) return;
+  }
+  if (req.method === 'GET' && !action) {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return;
+    }
+    sendJson(res, 200, { ok: true, task: { ...redactTaskSecrets(task), running: scheduler.isRunning(id) } });
+    return;
+  }
+  if (req.method === 'DELETE' && !action) {
+    deleteTask({ store, scheduler, res, id });
+    return;
+  }
+  sendJson(res, 405, NOT_ALLOWED);
+}
+
+// webhook and helper endpoints moved to ./api-webhook.js and ./api-helpers.js
+

package/lib/routes/external-api.js

@@ -0,0 +1,74 @@
+/**
+ * External REST surface under /dsh-cron/api/* (#54, ADR-0001).
+ *
+ * Everything a browser panel needs stays on the local, cross-origin-protected
+ * routes; this prefix exists for CI and host-side automation, so it is the only
+ * surface guarded by a bearer token. The token lives in the plugin settings as
+ * a masked value: an unconfigured token disables the surface (503) instead of
+ * leaving it open, and a wrong token is answered with 401.
+ *
+ * The operations themselves are shared with the panel routes (lib/api.js), so
+ * the confirmation gate for code-executing tasks and the config-owned refusals
+ * apply here exactly as they do over HTTP from the UI.
+ */
+
+import { timingSafeEqual } from 'node:crypto';
+import { sendJson } from '../http-utils.js';
+import { handleExternalTaskRequest } from './api.js';
+
+/** Settings key that holds the bearer token. */
+export const API_TOKEN_SETTING_KEY = 'apiToken';
+
+/** Route prefix owned by this surface. */
+export const EXTERNAL_API_PREFIX = '/dsh-cron/api';
+
+/**
+ * Constant-time token comparison. Length is compared first because
+ * timingSafeEqual throws on buffers of different sizes; a length mismatch is
+ * not a secret worth hiding for a fixed-length token.
+ */
+export function tokenMatches(expected, provided) {
+  if (!expected || !provided) return false;
+  const a = Buffer.from(String(expected), 'utf8');
+  const b = Buffer.from(String(provided), 'utf8');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/** Bearer token of a request, or an empty string when there is none. */
+export function readBearerToken(req) {
+  const header = String((req.headers && req.headers.authorization) || '');
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Guard the external prefix, then hand the request to the shared task
+ * operations. `getToken` is read per request so a settings change applies
+ * without a restart.
+ */
+export function createExternalApiHandler({ store, scheduler, getToken }) {
+  return async function handleExternalApi(req, res) {
+    const expected = typeof getToken === 'function' ? getToken() : '';
+    if (!expected) {
+      sendJson(res, 503, {
+        ok: false,
+        error: 'External API is disabled: set the "' + API_TOKEN_SETTING_KEY + '" setting to enable it',
+      });
+      return;
+    }
+    if (!tokenMatches(expected, readBearerToken(req))) {
+      sendJson(res, 401, { ok: false, error: 'Unauthorized' });
+      return;
+    }
+    const url = new URL(req.url, 'http://127.0.0.1');
+    // `url` must be inside the try: a malformed body (an unparseable schedule,
+    // for example) surfaces as a thrown error from the shared handlers, and an
+    // unhandled rejection here would answer nothing at all.
+    try {
+      await handleExternalTaskRequest({ store, scheduler, req, res, url, apiToken: expected });
+    } catch (err) {
+      sendJson(res, (err && err.statusCode) || 500, { ok: false, error: (err && err.message) || String(err) });
+    }
+  };
+}

package/lib/routes/index.js

@@ -0,0 +1,11 @@
+export * from './api-collection.js';
+export * from './api-item.js';
+export * from './api-actions.js';
+export * from './api-import-export.js';
+export * from './api-task-webhook.js';
+export * from './api-webhook.js';
+export * from './api-helpers.js';
+export * from './metrics.js';
+export * from './external-api.js';
+export * from './routes.js';
+export * from './api.js';

package/lib/routes/metrics.js

@@ -0,0 +1,125 @@
+import { rejectCrossOrigin } from '../http-utils.js';
+/**
+ * Prometheus exposition of the scheduler (#53).
+ *
+ * The renderer is hand-rolled on purpose: the profile has no prom-client and
+ * adding a production dependency for a handful of counters is not justified.
+ * Only counts, statuses and durations are exported — never prompts, run output
+ * or task configuration, so the endpoint can be scraped without leaking work
+ * content.
+ */
+
+export const METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+
+/** Run statuses the scheduler can finish with. */
+export const RUN_STATUSES = ['success', 'error', 'timeout', 'skipped', 'missed'];
+
+const NL = String.fromCharCode(10);
+const BACKSLASH = String.fromCharCode(92);
+const QUOTE = String.fromCharCode(34);
+
+/** Escape a label value for the Prometheus text format. */
+export function escapeLabel(value) {
+  return String(value)
+    .split(BACKSLASH).join(BACKSLASH + BACKSLASH)
+    .split(QUOTE).join(BACKSLASH + QUOTE)
+    .split(NL).join(BACKSLASH + 'n');
+}
+
+function sample(name, labels, value) {
+  const rendered = Object.keys(labels)
+    .map((key) => key + '=' + QUOTE + escapeLabel(labels[key]) + QUOTE)
+    .join(',');
+  return name + (rendered ? '{' + rendered + '}' : '') + ' ' + value;
+}
+
+/**
+ * Render the current scheduler state as Prometheus text exposition.
+ * Pure function over plain data so it is testable without a store.
+ */
+export function renderMetrics({ tasks = [], stats = {}, runCounters = {}, scheduler } = {}) {
+  const lines = [];
+  const byStatus = {};
+  for (const task of tasks) {
+    const status = task.status || 'unknown';
+    byStatus[status] = (byStatus[status] || 0) + 1;
+  }
+
+  lines.push('# HELP dsh_cron_tasks_total Scheduled tasks by status.');
+  // A gauge despite the name: this is a snapshot of how many tasks are in each
+  // state, not a monotonically growing total.
+  lines.push('# TYPE dsh_cron_tasks_total gauge');
+  for (const status of Object.keys(byStatus).sort()) {
+    lines.push(sample('dsh_cron_tasks_total', { status }, byStatus[status]));
+  }
+
+  lines.push('# HELP dsh_cron_task_last_duration_seconds Duration of the last finished run of a task.');
+  lines.push('# TYPE dsh_cron_task_last_duration_seconds gauge');
+  for (const task of tasks) {
+    // lastRunAt marks a finished run: a task that never ran still carries
+    // lastDurationMs = 0, and exporting that would show instant runs in
+    // monitoring.
+    if (!Number.isFinite(task.lastDurationMs) || !task.lastRunAt) continue;
+    lines.push(sample('dsh_cron_task_last_duration_seconds', { task: task.id }, task.lastDurationMs / 1000));
+  }
+
+  lines.push('# HELP dsh_cron_runs_total Finished runs since the plugin started, by status.');
+  lines.push('# TYPE dsh_cron_runs_total counter');
+  for (const status of RUN_STATUSES) {
+    lines.push(sample('dsh_cron_runs_total', { status }, Number(runCounters[status]) || 0));
+  }
+
+  lines.push('# HELP dsh_cron_run_records Run records currently kept in memory.');
+  lines.push('# TYPE dsh_cron_run_records gauge');
+  lines.push('dsh_cron_run_records ' + (Number(stats.totalRuns) || 0));
+
+  if (scheduler && typeof scheduler.runningCount === 'function') {
+    lines.push('# HELP dsh_cron_concurrent_running Number of currently executing tasks.');
+    lines.push('# TYPE dsh_cron_concurrent_running gauge');
+    lines.push('dsh_cron_concurrent_running ' + (Number(scheduler.runningCount()) || 0));
+  }
+
+  lines.push('# HELP dsh_cron_task_tokens_total Cumulative tokens consumed by task.');
+  lines.push('# TYPE dsh_cron_task_tokens_total counter');
+  for (const task of tasks) {
+    if (Number(task.totalTokens) > 0) {
+      lines.push(sample('dsh_cron_task_tokens_total', { task: task.id }, task.totalTokens));
+    }
+  }
+
+  lines.push('# HELP dsh_cron_task_cost_usd_total Estimated cumulative LLM cost in USD.');
+  lines.push('# TYPE dsh_cron_task_cost_usd_total counter');
+  for (const task of tasks) {
+    if (Number(task.totalCostUsd) > 0) {
+      lines.push(sample('dsh_cron_task_cost_usd_total', { task: task.id }, task.totalCostUsd));
+    }
+  }
+
+  return lines.join(NL) + NL;
+}
+
+/**
+ * GET /dsh-cron/metrics — read-only. A scraper is a plain local client, so no
+ * cross-origin check applies, and nothing sensitive is exposed.
+ */
+export function createMetricsHandler({ store, scheduler }) {
+  return function handleMetrics(req, res) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Method not allowed' + NL);
+      return;
+    }
+    const settings = store && typeof store.getSettings === 'function' ? store.getSettings() : {};
+    const apiToken = settings.apiToken;
+    if (rejectCrossOrigin(req, res, { apiToken })) return;
+
+    const body = renderMetrics({
+      tasks: store.list({ status: 'all' }),
+      stats: store.getAggregatedStats(),
+      runCounters: typeof scheduler.getRunCounters === 'function' ? scheduler.getRunCounters() : {},
+      scheduler,
+    });
+    res.writeHead(200, { 'Content-Type': METRICS_CONTENT_TYPE, 'Cache-Control': 'no-store' });
+    res.end(req.method === 'HEAD' ? undefined : body);
+  };
+}