@oneuptime/common 11.7.4 → 12.0.1

package/Types/Runbook/RunbookStep.ts

@@ -72,6 +72,84 @@ export interface AIStepConfig {
    * Response token cap. Defaults to 4096; clamped server-side.
    */
   maxTokens?: number;
+  /*
+   * Pin this step to a specific LLM provider. Optional — when unset the step
+   * uses the project's default provider (and, failing that, the global
+   * OneUptime provider), which is what every AI step did before this field
+   * existed.
+   *
+   * The id must name a provider the project owns or a global one; the server
+   * re-checks that on every run rather than trusting the stored config, since
+   * Runbook.steps is an unvalidated JSON column. A pinned provider that no
+   * longer resolves FAILS the step instead of quietly falling back to the
+   * default: an AI step runs unattended, and silently answering on a
+   * different model than the one a responder pinned is a change nobody would
+   * see. (Interactive chat, which has a human watching, does fall back.)
+   */
+  llmProviderId?: string;
+}
+
+/*
+ * Run a command on a host the Runner can reach over SSH.
+ *
+ * The point of a first-class step type — rather than "write `ssh host cmd` in
+ * a Bash step" — is that the credential is a managed, encrypted object with
+ * its own permissions instead of a private key sitting on the Runner's disk,
+ * and the command is a value we can validate rather than an opaque script.
+ */
+export interface SSHStepConfig {
+  /*
+   * ID of the RunbookCredential (type SSH) holding the host, user and key.
+   * The Runner resolves it at claim time; it is never stored on the step.
+   */
+  credentialId: string;
+  // The command to run on the remote host, verbatim.
+  command: string;
+  timeoutInMs?: number;
+  // ID of the Runner that opens the connection. Only it may claim the job.
+  agentId: string;
+  claimTimeoutInMs?: number;
+}
+
+/*
+ * The workload actions that cover almost every "turn it off and on again"
+ * remediation. Deliberately a closed set of verbs rather than free-form
+ * manifests: a runbook that can PATCH arbitrary Kubernetes objects is a
+ * cluster-admin shell, and the whole reason this exists is to make the common
+ * remediations safe rather than to add another way to run anything.
+ */
+export enum KubernetesAction {
+  // Rolling restart: stamps the pod template so the controller recreates pods.
+  RestartWorkload = "RestartWorkload",
+  // Set replica count — scale out under load, or to zero and back.
+  ScaleWorkload = "ScaleWorkload",
+}
+
+export enum KubernetesWorkloadKind {
+  Deployment = "Deployment",
+  StatefulSet = "StatefulSet",
+  DaemonSet = "DaemonSet",
+}
+
+export interface KubernetesStepConfig {
+  /*
+   * ID of the RunbookCredential (type Kubernetes) holding the API server URL,
+   * the service-account token and the CA certificate.
+   */
+  credentialId: string;
+  action: KubernetesAction;
+  workloadKind: KubernetesWorkloadKind;
+  namespace: string;
+  workloadName: string;
+  /*
+   * Target replica count. Required for ScaleWorkload and ignored otherwise.
+   * Zero is legitimate — draining a workload is a remediation.
+   */
+  replicas?: number;
+  timeoutInMs?: number;
+  // ID of the Runner that talks to the API server. Only it may claim the job.
+  agentId: string;
+  claimTimeoutInMs?: number;
 }
 
 export type RunbookStepConfig =
@@ -79,7 +157,9 @@ export type RunbookStepConfig =
   | JavaScriptStepConfig
   | HttpRequestStepConfig
   | BashStepConfig
-  | AIStepConfig;
+  | AIStepConfig
+  | SSHStepConfig
+  | KubernetesStepConfig;
 
 export interface RunbookStep {
   id: string;

package/Types/Runbook/RunbookStepType.ts

@@ -4,6 +4,32 @@ enum RunbookStepType {
   HttpRequest = "HttpRequest",
   Bash = "Bash",
   AI = "AI",
+  SSH = "SSH",
+  Kubernetes = "Kubernetes",
 }
 
 export default RunbookStepType;
+
+/*
+ * Step types that execute on a Runner rather than on the OneUptime Worker,
+ * because they act on the customer's own infrastructure. Everything listed
+ * here carries an agentId on its config and goes through the RunnerJob
+ * claim path.
+ *
+ * This list is the ENFORCEMENT point — RunnerJobService refuses to
+ * enqueue a job for any type not in it, so a Runner can never be handed work
+ * it has no executor for. The Worker's own dispatch is a per-type switch
+ * rather than a list check (each type needs different arguments), so adding a
+ * type here without adding it there means the step fails with "unknown step
+ * type" rather than being silently mis-run.
+ */
+export const RUNNER_EXECUTED_STEP_TYPES: Array<RunbookStepType> = [
+  RunbookStepType.JavaScript,
+  RunbookStepType.Bash,
+  RunbookStepType.SSH,
+  RunbookStepType.Kubernetes,
+];
+
+export function isRunnerExecutedStepType(type: RunbookStepType): boolean {
+  return RUNNER_EXECUTED_STEP_TYPES.includes(type);
+}

package/Types/Runbook/RunnerJobOrigin.ts

@@ -0,0 +1,20 @@
+/*
+ * Where a RunnerJob came from — the discriminator that decides which Runner
+ * capability gates its claim.
+ *
+ * Runbook:       a step of a runbook execution (the original job source).
+ *                Claimable only by Runners with canRunRunbooks.
+ * AiRemediation: an ad-hoc command composed by an AI remediation run (either
+ *                auto-executed under an operator allowlist or human-approved
+ *                as part of a command plan). Claimable only by Runners with
+ *                canRunAiCommands.
+ *
+ * Rows created before this enum existed were backfilled to Runbook by the
+ * AddAiCommandRemediation migration, so the column is NOT NULL.
+ */
+enum RunnerJobOrigin {
+  Runbook = "Runbook",
+  AiRemediation = "AiRemediation",
+}
+
+export default RunnerJobOrigin;

package/Types/Runbook/{RunbookAgentJobStatus.ts → RunnerJobStatus.ts}

@@ -1,4 +1,4 @@
-enum RunbookAgentJobStatus {
+enum RunnerJobStatus {
   // Inserted by the Worker. No agent has claimed it yet.
   Pending = "Pending",
   // An agent has atomically claimed the job and is preparing to execute it.
@@ -18,4 +18,4 @@ enum RunbookAgentJobStatus {
   Cancelled = "Cancelled",
 }
 
-export default RunbookAgentJobStatus;
+export default RunnerJobStatus;

package/Types/Runner/RunnerLiveStatus.ts

@@ -0,0 +1,114 @@
+import OneUptimeDate from "../Date";
+
+/*
+ * How recently a Runner must have heartbeated to count as online. Matches the
+ * window AIAgentService.isAgentAlive uses, and comfortably clears the Runner's
+ * 60s heartbeat interval.
+ *
+ * This lives in Types, not in RunnerService, because the dashboard has to
+ * answer the same question the server does. RunnerService imports it from
+ * here so the two cannot drift: a server that hands out work to Runners it
+ * considers alive, next to a dashboard that calls those same Runners
+ * disconnected, is worse than either answer on its own.
+ */
+export const RUNNER_ALIVE_WINDOW_IN_MINUTES: number = 5;
+
+/*
+ * What a Runner's heartbeat actually says about it right now.
+ *
+ * Deliberately NOT the same thing as the persisted RunnerConnectionStatus
+ * column. That column is written exactly twice — Disconnected when the row is
+ * created, Connected on the first heartbeat — and nothing ever writes it back,
+ * so a Runner that ran once last March still reads "connected" today. Every
+ * server-side liveness check already ignores it and compares lastAlive against
+ * the window above; this enum lets the dashboard tell the user the same truth.
+ */
+export enum RunnerLiveStatus {
+  /* Heartbeated within the window: it is polling for work right now. */
+  Connected = "connected",
+
+  /*
+   * Heartbeated at some point, but not recently enough. The container is
+   * stopped, wedged, or cannot reach OneUptime.
+   */
+  Disconnected = "disconnected",
+
+  /*
+   * Never heartbeated at all. The row exists because someone created it in the
+   * dashboard, but the Docker command has not been run yet. This is a setup
+   * step the user still owes us, not a failure, and the UI must not dress it up
+   * as one.
+   */
+  NeverConnected = "never-connected",
+}
+
+/*
+ * lastAlive arrives as a Date from a hydrated model and as an ISO string from
+ * a raw API payload, so both are accepted. Anything falsy — null from Postgres,
+ * undefined from a select that never asked for the column — means "no heartbeat
+ * has ever been recorded".
+ */
+export type GetRunnerLiveStatusFunction = (
+  lastAlive: Date | string | null | undefined,
+) => RunnerLiveStatus;
+
+export const getRunnerLiveStatus: GetRunnerLiveStatusFunction = (
+  lastAlive: Date | string | null | undefined,
+): RunnerLiveStatus => {
+  if (!lastAlive) {
+    return RunnerLiveStatus.NeverConnected;
+  }
+
+  const lastAliveDate: Date = OneUptimeDate.fromString(lastAlive);
+
+  /*
+   * An unparseable value is not evidence of life. Returning Disconnected keeps
+   * a malformed timestamp from being reported as a healthy Runner.
+   */
+  if (isNaN(lastAliveDate.getTime())) {
+    return RunnerLiveStatus.Disconnected;
+  }
+
+  const windowStart: Date = OneUptimeDate.getSomeMinutesAgo(
+    RUNNER_ALIVE_WINDOW_IN_MINUTES,
+  );
+
+  if (OneUptimeDate.isAfter(lastAliveDate, windowStart)) {
+    return RunnerLiveStatus.Connected;
+  }
+
+  return RunnerLiveStatus.Disconnected;
+};
+
+/*
+ * The English label for each state, which is also its i18next lookup key.
+ *
+ * "Connected" and "Disconnected" already had translations in all sixteen
+ * Dashboard locale files before any of this — the probe pages have used them
+ * for years — so routing every Runner status label through these three
+ * constants is what lets the new state reuse them instead of inventing a
+ * parallel set that would have to be translated again.
+ *
+ * It lives here rather than in the component because two very different
+ * surfaces need the same words: the status bubble, and the plain-string
+ * option label in the runbook step editor's Runner picker.
+ */
+export type GetRunnerLiveStatusLabelFunction = (
+  status: RunnerLiveStatus,
+) => string;
+
+export const getRunnerLiveStatusLabel: GetRunnerLiveStatusLabelFunction = (
+  status: RunnerLiveStatus,
+): string => {
+  if (status === RunnerLiveStatus.Connected) {
+    return "Connected";
+  }
+
+  if (status === RunnerLiveStatus.NeverConnected) {
+    return "Never connected";
+  }
+
+  return "Disconnected";
+};
+
+export default RunnerLiveStatus;

package/Types/StatusPage/StatusPageReport.ts

@@ -0,0 +1,99 @@
+/*
+ * The shape of the scheduled "Uptime Report" email for a status page.
+ *
+ * A status page organises its resources into a tree of groups (Corporate Unit ->
+ * Region -> Market -> Unit), and every level of that tree shows a rolled up
+ * availability on the live page. Recipients of this email frequently have no
+ * login, so the report has to carry the same hierarchy - a flat list of monitor
+ * names says nothing about which region or unit a monitor belongs to.
+ *
+ * Three views of the same numbers are exposed, because the built-in email
+ * template and customer authored templates need different things:
+ *
+ *   - `resources`  - every resource, flat. The original shape, kept so templates
+ *                    written before groups existed keep rendering. Each row now
+ *                    also carries the group it belongs to.
+ *   - `groups`     - the nested tree, for templates that can recurse.
+ *   - `rows`       - the tree flattened into render order with a `depth` on each
+ *                    row. Email HTML cannot recurse comfortably, so the built-in
+ *                    template walks this.
+ */
+
+export interface StatusPageReportItem {
+  resourceName: string;
+  totalIncidentCount: number;
+  uptimePercent: number;
+  uptimePercentAsString: string;
+  downtimeInHoursAndMinutes: string;
+  /*
+   * The group this resource is attached to directly. Empty string when the
+   * resource is not in any group (it renders above the groups on the live page).
+   */
+  groupName: string;
+  /*
+   * Every group from the top of the tree down to this resource's own group,
+   * joined with " / " - e.g. "Region 001 / Market 001 / Unit 0660". Empty string
+   * when the resource is not in any group.
+   */
+  groupPath: string;
+}
+
+/*
+ * Numbers rolled up over a group and everything nested under it - the same set
+ * of resources the live status page rolls a group's uptime over.
+ */
+export interface StatusPageReportGroupMetrics {
+  uptimePercent: number;
+  uptimePercentAsString: string;
+  downtimeInHoursAndMinutes: string;
+  totalIncidentCount: number;
+}
+
+export interface StatusPageReportGroup extends StatusPageReportGroupMetrics {
+  groupName: string;
+  // Ancestors and this group joined with " / ".
+  groupPath: string;
+  // 0 for a top level group, 1 for its children, and so on.
+  depth: number;
+  // Resources in this group AND in every group nested under it.
+  totalResources: number;
+  // Resources attached to this group directly, in status page order.
+  resources: Array<StatusPageReportItem>;
+  subGroups: Array<StatusPageReportGroup>;
+}
+
+/*
+ * One line of the report, in the order the live status page renders it:
+ * ungrouped resources first, then each group followed by its own resources and
+ * then its sub groups.
+ */
+export interface StatusPageReportRow {
+  isGroup: boolean;
+  name: string;
+  depth: number;
+  // Precomputed so an email template does not have to do arithmetic in Handlebars.
+  indentInPixels: number;
+  uptimePercentAsString: string;
+  downtimeInHoursAndMinutes: string;
+  totalIncidentCount: number;
+  /*
+   * Only meaningful on a group row: how many resources the group rolls up.
+   * Always 0 on a resource row.
+   */
+  totalResources: number;
+}
+
+export interface StatusPageReport {
+  reportDates: string; // start date and end date in string. e.g. "01 July 2021 - 14 July 2021"
+  totalResources: number;
+  totalIncidents: number;
+  averageUptimePercent: string;
+  totalDowntimeInHoursAndMinutes: string;
+  resources: Array<StatusPageReportItem>;
+  groups: Array<StatusPageReportGroup>;
+  // Resources that are not in any group, in status page order.
+  ungroupedResources: Array<StatusPageReportItem>;
+  rows: Array<StatusPageReportRow>;
+  // Whether this status page organises its resources into groups at all.
+  hasGroups: boolean;
+}

package/Types/Telemetry/TelemetryRetentionConfig.ts

@@ -29,9 +29,26 @@ export default interface TelemetryRetentionConfig {
   profiles?: {
     default?: number | null;
   };
+  /*
+   * Session replay does NOT go through resolveTelemetryRetentionInDays
+   * below. That function puts service.retainTelemetryDataForDays above the
+   * project pillar default, so an application configured for 90-day trace
+   * retention would silently inherit 90-day replay retention, and an
+   * unconfigured one would get 15 days rather than replay's 7. Replay is
+   * resolved by Common/Server/Utils/SessionReplay/SessionReplayRetention.ts,
+   * which reads only this pillar and then clamps to the allowed set.
+   */
+  sessionReplay?: {
+    default?: number | null;
+  };
 }
 
-export type TelemetryPillar = "logs" | "traces" | "metrics" | "profiles";
+export type TelemetryPillar =
+  | "logs"
+  | "traces"
+  | "metrics"
+  | "profiles"
+  | "sessionReplay";
 
 export const HARDCODED_DEFAULT_TELEMETRY_RETENTION_IN_DAYS: number = 15;
 

package/Types/Text.ts

@@ -63,6 +63,39 @@ export default class Text {
     return result.toLowerCase();
   }
 
+  /*
+   * Space out a PascalCase identifier for display: "MaskAllText" becomes
+   * "Mask All Text".
+   *
+   * Casing is preserved rather than lowercased, so acronyms survive
+   * ("OIDCProvider" -> "OIDC Provider" and not "Oidc Provider"). Text that
+   * is already spaced is returned unchanged, which makes this safe to
+   * apply to an enum whose values are a mix of both.
+   *
+   * LIMITATION, and the reason callers must opt in rather than getting
+   * this for free: a case boundary inside a single word is
+   * indistinguishable from a word boundary, so proper nouns and
+   * initialisms that embed one come out wrong - "GitHub" -> "Git Hub",
+   * "NodeJS" -> "Node JS", "IPv4Address" -> "I Pv4 Address". Do not use
+   * this on values that are product names, identifiers, or anything else
+   * that is not simply English words concatenated.
+   */
+  public static fromPascalCaseToReadable(text: string): string {
+    if (!text) {
+      return text;
+    }
+
+    return (
+      text
+        // "maskAll" / "v2Recorder" -> "mask All" / "v2 Recorder"
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        // "OIDCProvider" -> "OIDC Provider"; the run keeps its own casing.
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .replace(/\s+/g, " ")
+        .trim()
+    );
+  }
+
   public static getFirstWord(text: string): string {
     if (!text || text.length === 0) {
       return text;