Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
12.2 KB
Raw Blame
/**
 * Scheduling handler — DB-backed schedule registration.
 *
 * Fase 5 (serene-sauteeing-jellyfish.md) replaced K8s CronJobs with a
 * Postgres-backed worker living inside `control-api`. The WRC's job is now
 * limited to keeping `workflow_schedules` in sync with the recipe's
 * `spec.scheduling` — it never emits a CronJob, Pod, or HTTP trigger.
 *
 * Responsibilities:
 *   1. On reconcile with `spec.scheduling` present → UPSERT a row into
 *      `workflow_schedules` keyed on (recipe_namespace, recipe_name).
 *   2. On reconcile WITHOUT scheduling → DELETE the row (idempotent).
 *   3. On recipe delete → DELETE the row (idempotent).
 *
 * Invariants:
 *   • `next_fire_at` is only reset when `cron_expression` or `timezone`
 *     changed, OR when re-enabling after `suspend` (the stored value is
 *     likely stale after a long suspend window). Otherwise we preserve
 *     whatever the worker has already advanced it to.
 *   • `enabled = NOT suspend` so the worker's `enabled = TRUE` filter keeps
 *     suspended schedules dormant without deleting the row.
 *   • `concurrency_policy` mirrors `concurrencyPolicy` (default `Forbid`, the
 *     CRD default; unknown values also map to `Forbid`). The control-api
 *     worker enforces Forbid; Replace is not implemented and behaves as Allow.
 *   • All UPDATEs explicitly set `updated_at = now()` — the codebase does not
 *     use auto-update triggers (see control-api db.ts convention).
 */
import { CronExpressionParser } from 'cron-parser'
import type { Pool } from 'pg'
import type { SchedulingSpec } from './types'

export const WORKFLOW_TEAM_ID_LABEL = 'clerum.io/workflow-team-id'
export const MAX_TTL_SECONDS_AFTER_FINISHED = 30 * 24 * 60 * 60

/** Mirrors the CRD enum on `schedule.concurrencyPolicy` and the DB CHECK. */
export type ScheduleConcurrencyPolicy = 'Forbid' | 'Replace' | 'Allow'
export const DEFAULT_SCHEDULE_CONCURRENCY_POLICY: ScheduleConcurrencyPolicy = 'Forbid'
const SCHEDULE_CONCURRENCY_POLICIES: ReadonlySet<string> = new Set(['Forbid', 'Replace', 'Allow'])

/** Omitted or unknown values resolve to the CRD default, `Forbid`. */
export function resolveScheduleConcurrencyPolicy(value: unknown): ScheduleConcurrencyPolicy {
  return typeof value === 'string' && SCHEDULE_CONCURRENCY_POLICIES.has(value)
    ? (value as ScheduleConcurrencyPolicy)
    : DEFAULT_SCHEDULE_CONCURRENCY_POLICY
}

/** Actor types that may trigger a run. Mirrors the check constraint on `workflow_runs.actor_type`. */
export type TriggerAllowedActor = 'user' | 'autonomous' | 'scheduled'

export interface SchedulingRecipe {
  metadata: { name: string; namespace: string; uid: string; labels?: Record<string, string> }
  spec: {
    scheduling?: SchedulingSpec
    /**
     * Optional actor allow-list mirrored from `spec.triggers.onDemand.allowedActors`.
     * Denormalized into `workflow_schedules.allowed_actors` so the DB-backed
     * schedule worker can gate scheduled fires consistently with the on-demand
     * admin endpoint — otherwise a recipe with `allowedActors: ['user']` would
     * silently keep firing on schedule while blocking the same-authority API
     * path, which is the bug this field closes (Phase 7 review finding).
     *
     * `undefined` / `null` = no allow-list (any actor may fire).
     */
    allowedActors?: TriggerAllowedActor[] | null
    /**
     * Optional retention configuration mirrored from `spec.runRetention`.
     * The schedule worker stamps these values onto each `workflow_runs` row
     * so active-run timeout and post-finish archive windows follow the recipe
     * contract.
     */
    runRetention?: {
      maxRunDurationSeconds?: number | null
      ttlSecondsAfterFinished?: number | null
    } | null
  }
}

export type SchedulingAction =
  | 'created'
  | 'updated'
  | 'suspended'
  | 'resumed'
  | 'skipped'
  | 'deleted'

/** Public result shape — `batchApi.*Action` wording preserved for log parity. */
export interface SchedulingResult {
  action: SchedulingAction
}

/**
 * Reconcile `workflow_schedules` for a single recipe. Idempotent — safe to
 * call on every WRC reconcile tick.
 *
 * Returns a small summary describing the mutation that occurred so the caller
 * can emit the historical `log.info(\`Scheduling: ${action}\`)` line.
 */
export async function reconcileScheduling(
  pool: Pool,
  recipe: SchedulingRecipe
): Promise<SchedulingResult> {
  const sched = recipe.spec.scheduling
  const ns = recipe.metadata.namespace
  const name = recipe.metadata.name

  // No scheduling requested → ensure no row lingers. Idempotent DELETE.
  if (!sched) {
    const deleted = await pool.query(
      `DELETE FROM workflow_schedules
        WHERE recipe_namespace = $1 AND recipe_name = $2`,
      [ns, name]
    )
    return { action: (deleted.rowCount ?? 0) > 0 ? 'deleted' : 'skipped' }
  }

  const timezone = sched.timezone ?? 'UTC'
  const wantSuspend = sched.suspend ?? false
  const enabled = !wantSuspend
  const teamId = requiredScheduleTeamId(recipe.metadata.labels, `${ns}/${name}`)
  // `undefined` (CRD field absent) → SQL NULL (no restriction). An explicit
  // empty array is also normalized to NULL: an operator writing `[]` almost
  // certainly meant "no gating", not "deny every actor" (matches the
  // getOnDemandAllowedActors() semantics in control-api/routes/admin/workflows).
  const allowedActors =
    Array.isArray(recipe.spec.allowedActors) && recipe.spec.allowedActors.length > 0
      ? JSON.stringify(recipe.spec.allowedActors)
      : null
  const maxDurationSeconds =
    typeof recipe.spec.runRetention?.maxRunDurationSeconds === 'number' &&
    Number.isInteger(recipe.spec.runRetention.maxRunDurationSeconds) &&
    recipe.spec.runRetention.maxRunDurationSeconds > 0
      ? recipe.spec.runRetention.maxRunDurationSeconds
      : null
  const ttlSecondsAfterFinished = resolveTtlSecondsAfterFinished(
    recipe.spec.runRetention?.ttlSecondsAfterFinished ?? null
  )
  const concurrencyPolicy = resolveScheduleConcurrencyPolicy(sched.concurrencyPolicy)

  // Fetch current row so we can emit semantic actions (created/updated/…) and
  // decide whether to reset next_fire_at. One SELECT + one UPSERT per tick.
  const existing = await pool.query<{
    cron_expression: string
    timezone: string
    enabled: boolean
    team_id: string | null
    allowed_actors: TriggerAllowedActor[] | null
    max_duration_seconds: number | null
    ttl_seconds_after_finished: number | null
    concurrency_policy: string | null
  }>(
    `SELECT cron_expression, timezone, enabled, team_id::text AS team_id,
            allowed_actors, max_duration_seconds, ttl_seconds_after_finished,
            concurrency_policy
       FROM workflow_schedules
      WHERE recipe_namespace = $1 AND recipe_name = $2`,
    [ns, name]
  )

  const initialNextFire = computeNextFire(sched.cron, timezone, new Date())
  const prev = existing.rows[0]

  if (!prev) {
    await pool.query(
      `INSERT INTO workflow_schedules
         (recipe_namespace, recipe_name, team_id, cron_expression, timezone,
          next_fire_at, enabled, allowed_actors, max_duration_seconds,
          ttl_seconds_after_finished, concurrency_policy, created_at, updated_at)
       VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9, $10, $11, now(), now())`,
      [
        ns,
        name,
        teamId,
        sched.cron,
        timezone,
        initialNextFire,
        enabled,
        allowedActors,
        maxDurationSeconds,
        ttlSecondsAfterFinished,
        concurrencyPolicy,
      ]
    )
    return { action: 'created' }
  }

  const cronChanged = prev.cron_expression !== sched.cron || prev.timezone !== timezone
  const resuming = prev.enabled === false && enabled === true
  const suspending = prev.enabled === true && enabled === false
  const teamChanged = prev.team_id !== teamId
  const actorsChanged = !sameActorList(prev.allowed_actors, recipe.spec.allowedActors ?? null)
  const durationChanged = prev.max_duration_seconds !== maxDurationSeconds
  const ttlChanged = prev.ttl_seconds_after_finished !== ttlSecondsAfterFinished
  const policyChanged = prev.concurrency_policy !== concurrencyPolicy

  // Reset next_fire_at only when the schedule itself shifted or we're waking
  // a suspended schedule — the worker's advancement of next_fire_at is the
  // authoritative value while the schedule is live and unchanged.
  if (cronChanged || resuming) {
    await pool.query(
      `UPDATE workflow_schedules
         SET cron_expression = $1,
             timezone = $2,
             enabled = $3,
             next_fire_at = $4,
             team_id = $5,
             allowed_actors = $6::jsonb,
             max_duration_seconds = $7,
             ttl_seconds_after_finished = $8,
             concurrency_policy = $9,
             updated_at = now()
       WHERE recipe_namespace = $10 AND recipe_name = $11`,
      [
        sched.cron,
        timezone,
        enabled,
        initialNextFire,
        teamId,
        allowedActors,
        maxDurationSeconds,
        ttlSecondsAfterFinished,
        concurrencyPolicy,
        ns,
        name,
      ]
    )
  } else if (
    suspending ||
    prev.enabled !== enabled ||
    teamChanged ||
    actorsChanged ||
    durationChanged ||
    ttlChanged ||
    policyChanged
  ) {
    await pool.query(
      `UPDATE workflow_schedules
         SET enabled = $1,
             team_id = $2,
             allowed_actors = $3::jsonb,
             max_duration_seconds = $4,
             ttl_seconds_after_finished = $5,
             concurrency_policy = $6,
             updated_at = now()
       WHERE recipe_namespace = $7 AND recipe_name = $8`,
      [
        enabled,
        teamId,
        allowedActors,
        maxDurationSeconds,
        ttlSecondsAfterFinished,
        concurrencyPolicy,
        ns,
        name,
      ]
    )
  } else {
    return { action: 'skipped' }
  }

  if (suspending) return { action: 'suspended' }
  if (resuming) return { action: 'resumed' }
  return { action: 'updated' }
}

/**
 * Delete the schedule row for a recipe. Called from the reconciler's delete
 * path — matches the semantics of the old `batchApi.deleteNamespacedCronJob`.
 * Idempotent.
 */
export async function deleteScheduling(
  pool: Pool,
  recipeNamespace: string,
  recipeName: string
): Promise<void> {
  await pool.query(
    `DELETE FROM workflow_schedules
      WHERE recipe_namespace = $1 AND recipe_name = $2`,
    [recipeNamespace, recipeName]
  )
}

/**
 * Compute the next fire time after `from`. Exported for tests — the
 * control-api worker owns the advancement loop, but the reconciler must seed
 * `next_fire_at` on INSERT with a real cron-aware value (otherwise a weekly
 * job would fire immediately on creation).
 */
export function computeNextFire(cronExpression: string, timezone: string, from: Date): Date {
  const interval = CronExpressionParser.parse(cronExpression, {
    currentDate: from,
    tz: timezone || 'UTC',
  })
  return interval.next().toDate()
}

/**
 * Order-insensitive equality on two optional actor allow-lists. An empty list
 * is normalized to null (see `allowedActors` handling above) so we only compare
 * null vs null, null vs non-empty, or two non-empty sets.
 */
function sameActorList(a: TriggerAllowedActor[] | null, b: TriggerAllowedActor[] | null): boolean {
  const normA = Array.isArray(a) && a.length > 0 ? [...a].sort() : null
  const normB = Array.isArray(b) && b.length > 0 ? [...b].sort() : null
  if (normA === null && normB === null) return true
  if (normA === null || normB === null) return false
  if (normA.length !== normB.length) return false
  return normA.every((v, i) => v === normB[i])
}

function resolveTtlSecondsAfterFinished(value: number | null | undefined): number {
  if (value === undefined || value === null) return MAX_TTL_SECONDS_AFTER_FINISHED
  if (Number.isInteger(value) && value >= 0 && value <= MAX_TTL_SECONDS_AFTER_FINISHED) {
    return value
  }
  return MAX_TTL_SECONDS_AFTER_FINISHED
}

function requiredScheduleTeamId(
  labels: Record<string, string> | undefined,
  recipeRef: string
): string {
  const teamId = labels?.[WORKFLOW_TEAM_ID_LABEL]?.trim() ?? ''
  if (!teamId) {
    throw new Error(`${recipeRef} scheduled WorkflowRecipe requires ${WORKFLOW_TEAM_ID_LABEL}`)
  }
  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(teamId)) {
    throw new Error(`${recipeRef} has invalid ${WORKFLOW_TEAM_ID_LABEL}`)
  }
  return teamId
}