Skip to content

Record a sky camera around the clock, keep the footage on your own disk, and find what flew past.

15.1 KB
Raw Blame
import { ApplicationError } from '../../../shared/src/utils/errorSharedUtil';
import type { WorkshopDocument, Workflow, WorkshopNode } from '../models/workshopInferencemodel';
export function invalid(message: string): never {
  throw new ApplicationError('invalid_input', message);
}
export const record = (value: unknown): value is Record<string, unknown> =>
  !!value && typeof value === 'object' && !Array.isArray(value);
export const identifier = (value: unknown): value is string =>
  typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(value);
export const hash = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
const text = (v: unknown, n = 1000): v is string =>
  typeof v === 'string' && v.length <= n && !/[\u0000-\u001f]/.test(v);
const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
const time = (v: unknown): v is string => typeof v === 'string' && /^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/.test(v);
const minutes = (v: string) => Number(v.slice(0, 2)) * 60 + Number(v.slice(3, 5));
/** Recorded days that move with each run, in days from the run's UTC date. */
export const relativeDays: Record<string, number> = { 'run-day': 0, 'previous-day': -1 };
export const isRelativeDay = (day: unknown) => typeof day === 'string' && Object.hasOwn(relativeDays, day);
// ponytail: fixed margin for the relay to upload a window's last clips; raise it if uploads lag.
export const uploadGraceMinutes = 10;
// ponytail: fixed cadence; new-footage runs batch this many minutes of uploads.
export const arrivalMinutes = 15;
export const noMedia = 'The selected input has no available media.';
export function validateDocument(value: unknown): WorkshopDocument {
  if (
    !record(value) ||
    value.version !== 3 ||
    !Array.isArray(value.buckets) ||
    !Array.isArray(value.workflows) ||
    value.buckets.length > 500 ||
    value.workflows.length > 100
  )
    invalid('Invalid Workshop document.');
  const v = value as unknown as WorkshopDocument,
    bucketIds = new Set<string>(),
    names = new Set<string>();
  for (const b of v.buckets) {
    if (
      !record(b) ||
      !identifier(b.id) ||
      bucketIds.has(b.id) ||
      !text(b.name, 100) ||
      !b.name.trim() ||
      names.has(b.name.trim().toLowerCase()) ||
      !text(b.description, 300) ||
      !['raw', 'labeled'].includes(b.kind)
    )
      invalid('Invalid or duplicate bucket.');
    if (
      b.kind === 'raw'
        ? b.id !== 'camera-archive' || b.createdAt !== null
        : !text(b.createdAt) || !Number.isFinite(Date.parse(b.createdAt))
    )
      invalid('Invalid bucket provenance.');
    bucketIds.add(b.id);
    names.add(b.name.trim().toLowerCase());
  }
  if (!v.buckets.some(b => b.id === 'camera-archive' && b.kind === 'raw')) invalid('The camera archive is required.');
  const wfIds = new Set<string>();
  for (const w of v.workflows) {
    if (
      !record(w) ||
      !identifier(w.id) ||
      wfIds.has(w.id) ||
      !text(w.name, 100) ||
      !text(w.updatedAt) ||
      !Array.isArray(w.nodes) ||
      !Array.isArray(w.edges) ||
      w.nodes.length > 100 ||
      w.edges.length > 300
    )
      invalid('Invalid workflow.');
    wfIds.add(w.id);
    const ids = new Set<string>();
    for (const n of w.nodes) {
      if (
        !record(n) ||
        !identifier(n.id) ||
        ids.has(n.id) ||
        n.type !== 'workshop' ||
        !record(n.position) ||
        !finite(n.position.x) ||
        !finite(n.position.y) ||
        !record(n.data) ||
        !text(n.data.label)
      )
        invalid('Invalid workflow node.');
      ids.add(n.id);
      const d = n.data;
      switch (d.kind) {
        case 'input':
          if (!text(d.camera, 64) || (d.bucketId !== '' && !bucketIds.has(String(d.bucketId))))
            invalid('Invalid input bucket.');
          if (d.includeRejected !== undefined && typeof d.includeRejected !== 'boolean')
            invalid('includeRejected must be true or false.');
          break;
        case 'output':
          if (d.bucketId !== '' && !v.buckets.some(b => b.id === d.bucketId && b.kind === 'labeled'))
            invalid('Choose a labeled output bucket.');
          break;
        case 'footage':
          if (
            (!text(d.day, 10) && !isRelativeDay(d.day)) ||
            !text(d.from, 8) ||
            !text(d.until, 8) ||
            !finite(d.interval) ||
            d.interval < 1 ||
            d.interval > 3600 ||
            (d.pick !== undefined && !['first', 'change'].includes(String(d.pick)))
          )
            invalid('Invalid frame sampling.');
          break;
        case 'model':
          if (!text(d.modelKey, 150) || !finite(d.score) || d.score < 0 || d.score > 1)
            invalid('Invalid model settings.');
          break;
        case 'condition':
          validateCondition(d);
          break;
        case 'nothing':
          break;
        case 'schedule':
          if (
            !['time', 'arrival', 'workflow'].includes(String(d.trigger)) ||
            !Array.isArray(d.days) ||
            d.days.some(x => !Number.isInteger(x) || x < 0 || x > 6) ||
            !text(d.at, 5) ||
            !text(d.workflowId, 80) ||
            typeof d.onlyIf !== 'boolean'
          )
            invalid('Invalid schedule.');
          break;
        default:
          invalid('Unknown workflow step.');
      }
    }
    const edgeIds = new Set<string>();
    for (const e of w.edges) {
      if (
        !record(e) ||
        !identifier(e.id) ||
        edgeIds.has(e.id) ||
        !ids.has(e.source) ||
        !ids.has(e.target) ||
        !['out', 'yes', 'no'].includes(e.sourceHandle) ||
        e.targetHandle !== 'in'
      )
        invalid('Invalid connection.');
      edgeIds.add(e.id);
    }
  }
  // A workflow that starts after another must never lead back to itself.
  const follows = new Map<string, string[]>();
  for (const w of v.workflows)
    follows.set(
      w.id,
      w.nodes
        .filter(n => n.data.kind === 'schedule' && n.data.trigger === 'workflow')
        .map(n => String(n.data.workflowId)),
    );
  const settled = new Set<string>(),
    path = new Set<string>();
  const visit = (id: string) => {
    if (path.has(id)) invalid('Scheduled workflows cannot start each other in a loop.');
    if (settled.has(id)) return;
    path.add(id);
    (follows.get(id) ?? []).forEach(visit);
    path.delete(id);
    settled.add(id);
  };
  v.workflows.forEach(w => visit(w.id));
  return v;
}
function validateCondition(d: Record<string, unknown>, complete = false) {
  if (!['all', 'any'].includes(String(d.match)) || !Array.isArray(d.rules) || !d.rules.length || d.rules.length > 8)
    invalid('Choose 1–8 condition rules.');
  for (const r of d.rules as unknown[]) {
    if (!record(r) || !text(r.id, 150) || !r.id) invalid('Invalid condition rule.');
    if (r.kind === 'time' || r.kind === 'weekday') {
      if (!text(r.timeZone, 100)) invalid('Choose a time zone.');
      if (complete)
        try {
          new Intl.DateTimeFormat('en', { timeZone: r.timeZone as string });
        } catch {
          invalid('Unknown time zone.');
        }
      if (
        r.kind === 'time'
          ? complete
            ? !time(r.from) || !time(r.until) || r.from === r.until
            : !text(r.from, 8) || !text(r.until, 8)
          : !Array.isArray(r.days) ||
            (complete && !r.days.length) ||
            r.days.some(x => !Number.isInteger(x) || x < 0 || x > 6)
      )
        invalid('Invalid time condition.');
    } else {
      if (!text(r.className, 100)) invalid('Invalid class filter.');
      if (r.kind === 'class') {
        if (!['present', 'absent'].includes(String(r.operator))) invalid('Invalid class condition.');
      } else if (r.kind === 'confidence') {
        if (
          !['at-least', 'below'].includes(String(r.operator)) ||
          !finite(r.threshold) ||
          r.threshold < 0 ||
          r.threshold > 1
        )
          invalid('Invalid confidence condition.');
      } else if (r.kind === 'count') {
        if (
          !['at-least', 'equal', 'at-most'].includes(String(r.operator)) ||
          !Number.isInteger(r.count) ||
          Number(r.count) < 0 ||
          Number(r.count) > 10000
        )
          invalid('Invalid count condition.');
      } else if (r.kind === 'motion') {
        if (!motions.includes(String(r.operator))) invalid('Invalid motion condition.');
      } else invalid('Unsupported condition.');
    }
  }
}
const motions = ['moving', 'stationary', 'brief'];
/** Whether a workflow needs a processor that tracks objects: it keeps frames by change or routes on motion. */
export const usesTracking = (w: Workflow) =>
  w.nodes.some(
    n =>
      (n.data.kind === 'footage' && n.data.pick === 'change') ||
      (n.data.kind === 'condition' &&
        Array.isArray(n.data.rules) &&
        n.data.rules.some(r => record(r) && r.kind === 'motion')),
  );
/** Server execution validation: drafts can be disconnected; submitted runs cannot. */
export function executionGraph(w: Workflow) {
  const inputs = w.nodes.filter(n => n.data.kind === 'input'),
    outputs = w.nodes.filter(n => n.data.kind === 'output');
  if (inputs.length !== 1 || !outputs.length) invalid('Connect one input bucket and at least one output bucket.');
  if ([...inputs, ...outputs].some(n => !n.data.bucketId))
    invalid('Choose a replacement for each missing input or output bucket before running.');
  if (outputs.some(n => n.data.bucketId === inputs[0].data.bucketId))
    invalid('A run cannot write into its input bucket.');
  const map = new Map(w.nodes.map(n => [n.id, n]));
  const schedules = w.nodes.filter(n => n.data.kind === 'schedule');
  if (schedules.length > 1) invalid('Use one schedule per workflow.');
  for (const s of schedules)
    if (
      w.edges.some(e => e.target === s.id) ||
      w.edges.filter(e => e.source === s.id).length !== 1 ||
      !w.edges.some(e => e.source === s.id && e.sourceHandle === 'out' && e.target === inputs[0].id)
    )
      invalid('Connect the schedule to the input bucket.');
  const visited = new Set<string>(),
    active = new Set<string>();
  function walk(n: WorkshopNode, kind: 'video' | 'frames' | 'labels', hasModel = false) {
    if (active.has(n.id)) invalid('Workflow connections contain a cycle.');
    active.add(n.id);
    visited.add(n.id);
    const d = n.data;
    if (d.kind === 'condition') validateCondition(d, true);
    if (d.kind === 'footage') {
      if (kind !== 'video') invalid('Frame sampling requires video.');
      kind = 'frames';
    }
    if (d.kind === 'model') {
      if (kind === 'video') invalid('Add frame sampling before a model.');
      kind = 'labels';
      hasModel = true;
    }
    if (
      d.kind === 'condition' &&
      (d.rules as Record<string, unknown>[]).some(r =>
        ['class', 'confidence', 'count', 'motion'].includes(String(r.kind)),
      ) &&
      kind !== 'labels'
    )
      invalid('Prediction conditions need an upstream model.');
    if (d.kind === 'output' && (kind !== 'labels' || !hasModel))
      invalid('Every output path needs a model in this run. Add a model before the output bucket.');
    const edges = w.edges.filter(e => e.source === n.id),
      incoming = w.edges.filter(e => e.target === n.id);
    if (
      d.kind === 'input'
        ? incoming.length !== schedules.length
        : d.kind === 'output' || d.kind === 'nothing'
          ? incoming.length < 1
          : incoming.length !== 1
    )
      invalid('Each processing step needs exactly one incoming connection.');
    const required =
      d.kind === 'output' || d.kind === 'nothing' ? [] : d.kind === 'condition' ? ['yes', 'no'] : ['out'];
    if (edges.length !== required.length || required.some(h => edges.filter(e => e.sourceHandle === h).length !== 1))
      invalid('Connect every output port.');
    for (const e of edges) walk(map.get(e.target)!, kind, hasModel);
    active.delete(n.id);
  }
  // An output may receive both mutually exclusive branches. Its incoming count is checked separately below.
  const raw = inputs[0].data.bucketId === 'camera-archive';
  walk(inputs[0], raw ? 'video' : 'labels');
  if (visited.size + schedules.length !== w.nodes.length) invalid('Connect or remove unused steps before running.');
  const footage = w.nodes.filter(n => n.data.kind === 'footage');
  if (raw ? footage.length !== 1 : footage.length !== 0)
    invalid('Raw inputs need one frame sampling step. Labeled inputs already contain images.');
  const schedule = schedules[0];
  if (schedule) validateSchedule(schedule.data, footage[0]?.data);
  return { input: inputs[0], outputs, footage: footage[0], schedule };
}
function validateSchedule(d: Record<string, unknown>, footage?: Record<string, unknown>) {
  if (footage?.day && !isRelativeDay(footage.day))
    invalid(
      'A scheduled workflow would process the same recorded day every time. Choose Day of each run or Day before each run in the footage filter.',
    );
  if (d.trigger === 'time') {
    if (!(d.days as number[]).length || !time(d.at)) invalid('Choose the days and UTC time for this schedule.');
    if (
      footage?.day === 'run-day' &&
      time(footage.until) &&
      minutes(d.at) < minutes(footage.until) + uploadGraceMinutes
    ) {
      const earliest = minutes(footage.until) + uploadGraceMinutes;
      invalid(
        earliest >= 1440
          ? 'This window ends too late in the day to finish uploading before midnight UTC. Use Day before each run.'
          : `Schedule at ${String(Math.floor(earliest / 60)).padStart(2, '0')}:${String(earliest % 60).padStart(2, '0')} UTC or later so the whole window has been recorded and uploaded.`,
      );
    }
  }
  if (d.trigger === 'arrival' && footage) {
    // Each run takes the window of the day it runs on, so uploads for a window must land before the day's last check.
    if (footage.day !== 'run-day')
      invalid(
        'When new footage arrives takes recordings as they upload. Choose Day of each run in the footage filter.',
      );
    const latest = 1440 - arrivalMinutes - uploadGraceMinutes;
    if (time(footage.until) && minutes(footage.until) > latest)
      invalid(
        `End the window by ${String(Math.floor(latest / 60)).padStart(2, '0')}:${String(latest % 60).padStart(2, '0')} UTC so its last clips upload before the day's final new-footage check.`,
      );
  }
  if (d.trigger === 'workflow' && !identifier(d.workflowId)) invalid('Choose the workflow this one follows.');
}
export function resolveDay(day: unknown, now: Date) {
  return isRelativeDay(day) ? new Date(+now + relativeDays[day as string] * 86400000).toISOString().slice(0, 10) : day;
}
export function samplingWindow(raw: Record<string, unknown>, now = new Date()) {
  const data: Record<string, unknown> = { ...raw, day: resolveDay(raw.day, now) };
  if (!text(data.day, 10) || !/^\d{4}-\d{2}-\d{2}$/.test(data.day) || !time(data.from) || !time(data.until))
    invalid('Choose a recorded date and time range.');
  const from = new Date(`${data.day}T${data.from}Z`),
    until = new Date(`${data.day}T${data.until}Z`);
  if (
    !Number.isFinite(+from) ||
    !Number.isFinite(+until) ||
    from >= until ||
    from.toISOString().slice(0, 10) !== data.day
  )
    invalid('Invalid recorded window.');
  return { from: from.toISOString(), until: until.toISOString() };
}