@oneuptime/common 14.0.10 → 14.0.12

package/UI/Components/Workflow/WorkflowRunExport.ts

@@ -0,0 +1,435 @@
+/*
+ * A workflow run as a file someone can keep, attach to a ticket or send on.
+ *
+ * Two files, for two jobs:
+ *
+ *   - The log, as plain text (.txt): the Full Log tab's lines, exactly as the
+ *     runner printed them, under a short heading that says which workflow and
+ *     which run they belong to, how it ended and when. A log that has been
+ *     passed along twice still says what it is.
+ *   - The whole run, as JSON (.json): the same heading as data, every step the
+ *     Steps tab shows with what it received and returned, and the log as a
+ *     list of lines, for reading in an editor or feeding to a script.
+ *
+ * Both are built from what the dashboard already holds - the run it read
+ * through the API - and nothing else. That is what keeps them safe to hand
+ * on: the runner redacts secret variables and sensitive values before a run
+ * is ever stored, so the log and the steps arrive redacted, and the only
+ * other fields written here are the run's own id, status and times and its
+ * workflow's id and name. A user can download exactly what they could read.
+ *
+ * This module only builds names and text; it touches no browser API, so it
+ * is tested as plain functions. DownloadWorkflowRun saves the result.
+ */
+
+import WorkflowStatus, {
+  getWorkflowStatusLabel,
+} from "../../../Types/Workflow/WorkflowStatus";
+import {
+  WorkflowStepTrace,
+  parseTrace,
+} from "../../../Types/Workflow/StepTrace";
+import { JSONObject, JSONValue } from "../../../Types/JSON";
+import WorkflowLog from "../../../Models/DatabaseModels/WorkflowLog";
+
+export type WorkflowRunDate = Date | string | null | undefined;
+
+/** Which run a log belongs to: what names the file and heads it. */
+export interface WorkflowRunDetails {
+  /** The run's id, which is its WorkflowLog row's id. */
+  runId?: string | null | undefined;
+  workflowId?: string | null | undefined;
+  workflowName?: string | null | undefined;
+  status?: WorkflowStatus | string | null | undefined;
+  /**
+   * When the trigger fired and the run was queued: the row's createdAt, which
+   * the run lists call Scheduled At.
+   */
+  scheduledAt?: WorkflowRunDate;
+  startedAt?: WorkflowRunDate;
+  completedAt?: WorkflowRunDate;
+}
+
+/** A run, with everything a download writes. */
+export interface WorkflowRunExport extends WorkflowRunDetails {
+  logs: string;
+  stepTrace: WorkflowStepTrace;
+}
+
+export enum WorkflowRunExportFormat {
+  // The log as plain text.
+  Log = "Log",
+  // The whole run - steps included - as JSON.
+  JSON = "JSON",
+}
+
+export interface WorkflowRunExportFile {
+  fileName: string;
+  content: string;
+  mimeType: string;
+}
+
+export const WORKFLOW_RUN_LOG_EXTENSION: string = "txt";
+export const WORKFLOW_RUN_JSON_EXTENSION: string = "json";
+
+export const WORKFLOW_RUN_LOG_MIME_TYPE: string = "text/plain;charset=utf-8";
+export const WORKFLOW_RUN_JSON_MIME_TYPE: string =
+  "application/json;charset=utf-8";
+
+/*
+ * The workflow's name is cut to this many characters in a file name. Each one
+ * can take three bytes in UTF-8 (a Japanese or Chinese name), and most file
+ * systems stop at 255 bytes, which the run id and the time also need room in.
+ */
+export const WORKFLOW_RUN_FILE_NAME_MAX_NAME_LENGTH: number = 50;
+
+// A name with nothing left once it is made safe for a file name.
+export const WORKFLOW_RUN_FILE_NAME_FALLBACK: string = "workflow";
+
+// Under the heading of a run that printed nothing.
+export const WORKFLOW_RUN_EMPTY_LOG_LINE: string =
+  "This run did not log anything.";
+
+export type ToDateFunction = (value: WorkflowRunDate) => Date | null;
+
+/*
+ * A run's time as a real date, or null. Models carry Date objects, a step
+ * trace carries ISO strings, and an old or partial row can carry nothing at
+ * all - or something that is not a date, which is treated as nothing rather
+ * than printed as "Invalid Date".
+ */
+export const toRunDate: ToDateFunction = (
+  value: WorkflowRunDate,
+): Date | null => {
+  if (!value) {
+    return null;
+  }
+
+  const date: Date = value instanceof Date ? value : new Date(value);
+
+  return isNaN(date.getTime()) ? null : date;
+};
+
+type ToIsoStringFunction = (value: WorkflowRunDate) => string | null;
+
+const toIsoString: ToIsoStringFunction = (
+  value: WorkflowRunDate,
+): string | null => {
+  const date: Date | null = toRunDate(value);
+
+  return date ? date.toISOString() : null;
+};
+
+type CleanTextFunction = (value: string | null | undefined) => string | null;
+
+const cleanText: CleanTextFunction = (
+  value: string | null | undefined,
+): string | null => {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed: string = value.trim();
+
+  return trimmed ? trimmed : null;
+};
+
+export type GetWorkflowNameForFileNameFunction = (
+  workflowName: string | null | undefined,
+) => string;
+
+/*
+ * The workflow's name as the start of a file name: lower case, with every run
+ * of spaces, punctuation and characters a file system refuses (/ \ : * ? " < >
+ * |) turned into one dash. Letters and digits of every script stay, so a
+ * workflow called "Nächtlicher Abgleich" or "夜間同期" keeps its name.
+ */
+export const getWorkflowNameForFileName: GetWorkflowNameForFileNameFunction = (
+  workflowName: string | null | undefined,
+): string => {
+  const slug: string = (workflowName || "")
+    .normalize("NFC")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{M}\p{N}_]+/gu, "-")
+    .replace(/^-+|-+$/g, "");
+
+  /*
+   * Cut by characters, not by UTF-16 units, so a letter outside the Basic
+   * Multilingual Plane is never split in half.
+   */
+  const shortened: string = Array.from(slug)
+    .slice(0, WORKFLOW_RUN_FILE_NAME_MAX_NAME_LENGTH)
+    .join("")
+    .replace(/-+$/g, "");
+
+  return shortened || WORKFLOW_RUN_FILE_NAME_FALLBACK;
+};
+
+export type GetRunTimeForFileNameFunction = (
+  run: WorkflowRunDetails,
+) => string | null;
+
+/*
+ * When the run happened, as a file name can hold it: the time it started, or
+ * the time it was queued when it never started, in UTC, with dashes where an
+ * ISO time has colons (which Windows does not allow) - 2026-09-30T10-00-01.
+ * The same shape every other OneUptime download stamps its file with.
+ */
+export const getRunTimeForFileName: GetRunTimeForFileNameFunction = (
+  run: WorkflowRunDetails,
+): string | null => {
+  const date: Date | null =
+    toRunDate(run.startedAt) || toRunDate(run.scheduledAt);
+
+  if (!date) {
+    return null;
+  }
+
+  return date.toISOString().slice(0, 19).replace(/:/g, "-");
+};
+
+type GetRunIdForFileNameFunction = (
+  runId: string | null | undefined,
+) => string | null;
+
+// An id is letters, digits and dashes; anything else is not one to trust.
+const getRunIdForFileName: GetRunIdForFileNameFunction = (
+  runId: string | null | undefined,
+): string | null => {
+  const id: string = (cleanText(runId) || "").replace(/[^A-Za-z0-9-]+/g, "");
+
+  return id || null;
+};
+
+export type GetWorkflowRunFileNameFunction = (
+  run: WorkflowRunDetails,
+  format: WorkflowRunExportFormat,
+) => string;
+
+/**
+ * What a downloaded run is called: the workflow, the run and when it ran, so
+ * a folder of them sorts by workflow and then by time, and two runs never
+ * share a name - nightly-sync-run-0193c0de-…-2026-09-30T10-00-01.txt.
+ */
+export const getWorkflowRunFileName: GetWorkflowRunFileNameFunction = (
+  run: WorkflowRunDetails,
+  format: WorkflowRunExportFormat,
+): string => {
+  const parts: Array<string> = [
+    getWorkflowNameForFileName(run.workflowName),
+    "run",
+  ];
+
+  const runId: string | null = getRunIdForFileName(run.runId);
+
+  if (runId) {
+    parts.push(runId);
+  }
+
+  const time: string | null = getRunTimeForFileName(run);
+
+  if (time) {
+    parts.push(time);
+  }
+
+  const extension: string =
+    format === WorkflowRunExportFormat.JSON
+      ? WORKFLOW_RUN_JSON_EXTENSION
+      : WORKFLOW_RUN_LOG_EXTENSION;
+
+  return `${parts.join("-")}.${extension}`;
+};
+
+export type HasWorkflowRunContentFunction = (
+  run: Pick<WorkflowRunExport, "logs" | "stepTrace">,
+) => boolean;
+
+/** There is something to copy or download: a log, or at least one step. */
+export const hasWorkflowRunContent: HasWorkflowRunContentFunction = (
+  run: Pick<WorkflowRunExport, "logs" | "stepTrace">,
+): boolean => {
+  if (typeof run.logs === "string" && run.logs.length > 0) {
+    return true;
+  }
+
+  const steps: unknown = run.stepTrace?.steps;
+
+  // A hole in the list is not a step, as the Steps tab counts them.
+  return (
+    Array.isArray(steps) &&
+    steps.some((step: unknown): boolean => {
+      return Boolean(step) && typeof step === "object";
+    })
+  );
+};
+
+export type GetWorkflowRunHeadingLinesFunction = (
+  run: WorkflowRunDetails,
+) => Array<string>;
+
+/*
+ * The heading above a downloaded log, one fact to a line. A fact the
+ * dashboard does not have - a run that has not finished has no Completed at -
+ * is left out rather than written as a blank.
+ */
+export const getWorkflowRunHeadingLines: GetWorkflowRunHeadingLinesFunction = (
+  run: WorkflowRunDetails,
+): Array<string> => {
+  const lines: Array<string> = [];
+
+  type AddLineFunction = (label: string, value: string | null) => void;
+
+  const addLine: AddLineFunction = (
+    label: string,
+    value: string | null,
+  ): void => {
+    if (value) {
+      lines.push(`${label}: ${value}`);
+    }
+  };
+
+  addLine("Workflow", cleanText(run.workflowName));
+  addLine("Workflow ID", cleanText(run.workflowId));
+  addLine("Run ID", cleanText(run.runId));
+  addLine("Status", run.status ? getWorkflowStatusLabel(run.status) : null);
+  addLine("Scheduled at", toIsoString(run.scheduledAt));
+  addLine("Started at", toIsoString(run.startedAt));
+  addLine("Completed at", toIsoString(run.completedAt));
+
+  return lines;
+};
+
+export type BuildWorkflowRunLogTextFunction = (
+  run: WorkflowRunExport,
+) => string;
+
+/**
+ * The .txt: the heading, a blank line, then the log exactly as it was
+ * printed - not re-wrapped, not cut short however long it is - ending with a
+ * newline, as a text file should.
+ */
+export const buildWorkflowRunLogText: BuildWorkflowRunLogTextFunction = (
+  run: WorkflowRunExport,
+): string => {
+  const heading: Array<string> = getWorkflowRunHeadingLines(run);
+  const logs: string = typeof run.logs === "string" ? run.logs : "";
+  const body: string = logs.length > 0 ? logs : WORKFLOW_RUN_EMPTY_LOG_LINE;
+
+  const text: string =
+    heading.length > 0 ? `${heading.join("\n")}\n\n${body}` : body;
+
+  return text.endsWith("\n") ? text : `${text}\n`;
+};
+
+export type GetLogLinesFunction = (logs: string) => Array<string>;
+
+/*
+ * The log as its lines. Splitting on "\n" and joining them back with it gives
+ * the log back exactly, so nothing is lost; an empty log has no lines rather
+ * than one empty one.
+ */
+export const getLogLines: GetLogLinesFunction = (
+  logs: string,
+): Array<string> => {
+  if (typeof logs !== "string" || logs.length === 0) {
+    return [];
+  }
+
+  return logs.split("\n");
+};
+
+export type GetWorkflowRunJsonFunction = (run: WorkflowRunExport) => JSONObject;
+
+/**
+ * The .json, as an object:
+ *
+ *   workflow   - its id and name
+ *   run        - its id, status (as the API stores it: "Success", not the
+ *                list's "Executed"), and when it was scheduled, started and
+ *                completed, as ISO times or null
+ *   stepTrace  - the steps, in the same shape the API returns a run's
+ *                stepTrace in (see Types/Workflow/StepTrace)
+ *   log        - the full log, one string per line
+ */
+export const getWorkflowRunJson: GetWorkflowRunJsonFunction = (
+  run: WorkflowRunExport,
+): JSONObject => {
+  return {
+    workflow: {
+      id: cleanText(run.workflowId),
+      name: cleanText(run.workflowName),
+    },
+    run: {
+      id: cleanText(run.runId),
+      status: cleanText(run.status),
+      scheduledAt: toIsoString(run.scheduledAt),
+      startedAt: toIsoString(run.startedAt),
+      completedAt: toIsoString(run.completedAt),
+    },
+    stepTrace: (run.stepTrace || { steps: [] }) as unknown as JSONObject,
+    log: getLogLines(run.logs),
+  };
+};
+
+export type BuildWorkflowRunJsonTextFunction = (
+  run: WorkflowRunExport,
+) => string;
+
+export const buildWorkflowRunJsonText: BuildWorkflowRunJsonTextFunction = (
+  run: WorkflowRunExport,
+): string => {
+  return `${JSON.stringify(getWorkflowRunJson(run), null, 2)}\n`;
+};
+
+export type GetWorkflowRunExportFileFunction = (
+  run: WorkflowRunExport,
+  format: WorkflowRunExportFormat,
+) => WorkflowRunExportFile;
+
+export const getWorkflowRunExportFile: GetWorkflowRunExportFileFunction = (
+  run: WorkflowRunExport,
+  format: WorkflowRunExportFormat,
+): WorkflowRunExportFile => {
+  if (format === WorkflowRunExportFormat.JSON) {
+    return {
+      fileName: getWorkflowRunFileName(run, format),
+      content: buildWorkflowRunJsonText(run),
+      mimeType: WORKFLOW_RUN_JSON_MIME_TYPE,
+    };
+  }
+
+  return {
+    fileName: getWorkflowRunFileName(run, WorkflowRunExportFormat.Log),
+    content: buildWorkflowRunLogText(run),
+    mimeType: WORKFLOW_RUN_LOG_MIME_TYPE,
+  };
+};
+
+export type GetWorkflowRunExportFromWorkflowLogFunction = (
+  log: WorkflowLog,
+) => WorkflowRunExport;
+
+/**
+ * A row of the run lists, as a run to download. Reads only the columns the
+ * lists already ask the API for - the run's id, status and times, its
+ * workflow, its log and its steps - so a row downloads exactly what the user
+ * was allowed to read.
+ */
+export const getWorkflowRunExportFromWorkflowLog: GetWorkflowRunExportFromWorkflowLogFunction =
+  (log: WorkflowLog): WorkflowRunExport => {
+    const workflowId: string | null =
+      log.workflowId?.toString() ||
+      (log.workflow?._id ? String(log.workflow._id) : null);
+
+    return {
+      runId: log._id ? String(log._id) : null,
+      workflowId: workflowId,
+      workflowName: log.workflow?.name || null,
+      status: log.workflowStatus || null,
+      scheduledAt: log.createdAt || null,
+      startedAt: log.startedAt || null,
+      completedAt: log.completedAt || null,
+      logs: typeof log.logs === "string" ? log.logs : "",
+      stepTrace: parseTrace((log.stepTrace as JSONValue) || null),
+    };
+  };

package/UI/Components/Workflow/WorkflowRunExportActions.tsx

@@ -0,0 +1,242 @@
+/*
+ * Copy log and Download, in the header of a workflow run's modal.
+ *
+ * Copy log puts the Full Log tab's text on the clipboard, for pasting into a
+ * chat or a ticket. Download offers the two files a run can be saved as: the
+ * log, as plain text, and the whole run - each step's inputs and outputs too -
+ * as JSON. Both work from either tab, and from a run that is still going,
+ * which then saves what it has logged so far.
+ *
+ * They are drawn like the step dialog's "How to use", the other control a
+ * workflow dialog keeps in its header: quiet, label beside the icon, and only
+ * the icon on a phone, where the header has no room for words (the label
+ * stays for screen readers). Neither is the thing the modal is for - it only
+ * shows a run, and its one way out is Close - so neither looks like an action
+ * button.
+ */
+
+import Icon from "../Icon/Icon";
+import MoreMenu from "../MoreMenu/MoreMenu";
+import MoreMenuItem from "../MoreMenu/MoreMenuItem";
+import Clipboard from "../../Utils/Clipboard";
+import useTranslateValue from "../../Utils/Translation";
+import {
+  WorkflowRunExportText,
+  downloadWorkflowRun,
+} from "./DownloadWorkflowRun";
+import {
+  WorkflowRunExport,
+  WorkflowRunExportFormat,
+} from "./WorkflowRunExport";
+import IconProp from "../../../Types/Icon/IconProp";
+import React, {
+  FunctionComponent,
+  ReactElement,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+export interface ComponentProps {
+  run: WorkflowRunExport;
+}
+
+// How long "Copied!" or "Copy failed" stays on the button.
+export const COPY_FEEDBACK_DURATION_MS: number = 2000;
+
+enum CopyState {
+  Idle = "Idle",
+  Copied = "Copied",
+  Failed = "Failed",
+}
+
+// Drawn like the step dialog's header button (ComponentSettingsModal).
+const BUTTON_CLASS_NAME: string =
+  "inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-sm font-medium text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-700 focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500";
+
+// The words beside an icon, which a phone leaves to screen readers.
+const LABEL_CLASS_NAME: string = "max-sm:sr-only";
+
+const WorkflowRunExportActions: FunctionComponent<ComponentProps> = (
+  props: ComponentProps,
+): ReactElement => {
+  const { translateString } = useTranslateValue();
+
+  const translate: (text: string) => string = (text: string): string => {
+    return translateString(text) || text;
+  };
+
+  const [copyState, setCopyState] = useState<CopyState>(CopyState.Idle);
+  const [downloadError, setDownloadError] = useState<string | null>(null);
+
+  const copyFeedbackTimer: React.MutableRefObject<ReturnType<
+    typeof setTimeout
+  > | null> = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (copyFeedbackTimer.current) {
+        clearTimeout(copyFeedbackTimer.current);
+      }
+    };
+  }, []);
+
+  type ShowCopyStateFunction = (state: CopyState) => void;
+
+  const showCopyState: ShowCopyStateFunction = (state: CopyState): void => {
+    if (copyFeedbackTimer.current) {
+      clearTimeout(copyFeedbackTimer.current);
+    }
+
+    setCopyState(state);
+
+    copyFeedbackTimer.current = setTimeout(() => {
+      copyFeedbackTimer.current = null;
+      setCopyState(CopyState.Idle);
+    }, COPY_FEEDBACK_DURATION_MS);
+  };
+
+  const copyLog: () => Promise<void> = async (): Promise<void> => {
+    // A refused or missing clipboard resolves false: "Copied!" would lie.
+    const hasCopied: boolean = await Clipboard.copyToClipboard(props.run.logs);
+
+    showCopyState(hasCopied ? CopyState.Copied : CopyState.Failed);
+  };
+
+  type DownloadFunction = (format: WorkflowRunExportFormat) => void;
+
+  const download: DownloadFunction = (
+    format: WorkflowRunExportFormat,
+  ): void => {
+    setDownloadError(null);
+
+    try {
+      downloadWorkflowRun(props.run, format);
+    } catch {
+      setDownloadError(translate(WorkflowRunExportText.downloadFailed));
+    }
+  };
+
+  const hasLog: boolean = props.run.logs.length > 0;
+
+  const copyLabel: string =
+    copyState === CopyState.Copied
+      ? WorkflowRunExportText.copied
+      : copyState === CopyState.Failed
+        ? WorkflowRunExportText.copyFailed
+        : WorkflowRunExportText.copyLog;
+
+  const copyIcon: IconProp =
+    copyState === CopyState.Copied
+      ? IconProp.Check
+      : copyState === CopyState.Failed
+        ? IconProp.Alert
+        : IconProp.Copy;
+
+  const copyIconClassName: string =
+    copyState === CopyState.Copied
+      ? "h-4 w-4 text-emerald-600"
+      : copyState === CopyState.Failed
+        ? "h-4 w-4 text-red-600"
+        : "h-4 w-4";
+
+  /*
+   * Said once, to a screen reader, when a copy lands or fails: a changed
+   * button label is not reliably announced while the button has focus.
+   */
+  const copyAnnouncement: string =
+    copyState === CopyState.Copied
+      ? translate(WorkflowRunExportText.copied)
+      : copyState === CopyState.Failed
+        ? translate(WorkflowRunExportText.copyFailedMessage)
+        : "";
+
+  return (
+    <div
+      className="flex flex-col items-end gap-1"
+      data-testid="workflow-run-export-actions"
+    >
+      <div className="flex items-center gap-1">
+        {/*
+         * Copy only when there is a log to copy. A run that recorded steps
+         * but printed nothing still has its steps to download.
+         */}
+        {hasLog ? (
+          <button
+            type="button"
+            className={BUTTON_CLASS_NAME}
+            data-testid="workflow-run-copy-log"
+            onClick={() => {
+              void copyLog();
+            }}
+          >
+            <Icon icon={copyIcon} className={copyIconClassName} />
+            <span className={LABEL_CLASS_NAME}>{translate(copyLabel)}</span>
+          </button>
+        ) : (
+          <></>
+        )}
+
+        {/*
+         * Portalled: drawn inside the dialog, the menu would be cut off by its
+         * scrolling body under a short Steps tab. MoreMenu keeps the keyboard,
+         * and a click that only closes the menu, from reaching the modal.
+         */}
+        <MoreMenu
+          text={translate(WorkflowRunExportText.download)}
+          isMenuPortaled={true}
+          elementToBeShownInsteadOfButton={
+            <button
+              type="button"
+              className={BUTTON_CLASS_NAME}
+              data-testid="workflow-run-download"
+            >
+              <Icon icon={IconProp.Download} className="h-4 w-4" />
+              <span className={LABEL_CLASS_NAME}>
+                {translate(WorkflowRunExportText.download)}
+              </span>
+              <Icon icon={IconProp.ChevronDown} className="h-3.5 w-3.5" />
+            </button>
+          }
+        >
+          {[
+            <MoreMenuItem
+              key="log"
+              text={translate(WorkflowRunExportText.downloadLog)}
+              icon={IconProp.TextFile}
+              onClick={() => {
+                download(WorkflowRunExportFormat.Log);
+              }}
+            />,
+            <MoreMenuItem
+              key="json"
+              text={translate(WorkflowRunExportText.downloadJson)}
+              icon={IconProp.Code}
+              onClick={() => {
+                download(WorkflowRunExportFormat.JSON);
+              }}
+            />,
+          ]}
+        </MoreMenu>
+      </div>
+
+      <span className="sr-only" role="status" aria-live="polite">
+        {copyAnnouncement}
+      </span>
+
+      {downloadError ? (
+        <p
+          className="max-w-[14rem] text-right text-xs text-red-600"
+          role="alert"
+          data-testid="workflow-run-download-error"
+        >
+          {downloadError}
+        </p>
+      ) : (
+        <></>
+      )}
+    </div>
+  );
+};
+
+export default WorkflowRunExportActions;