@oneuptime/common 12.0.34 → 13.0.1

package/Server/Utils/CodeRepository/GitHub/GitHubAgentTaskTrigger.ts

@@ -0,0 +1,341 @@
+import ObjectID from "../../../../Types/ObjectID";
+import AIRunType from "../../../../Types/AI/AIRunType";
+import AIRunStatus, {
+  AIRunStatusHelper,
+} from "../../../../Types/AI/AIRunStatus";
+import CodeFixTaskType, {
+  CodeFixTaskTypeHelper,
+} from "../../../../Types/AI/CodeFixTaskType";
+import CodeFixTaskContext, {
+  getGitHubConversationNumber,
+  getGitHubTaskContext,
+  GitHubTaskContext,
+} from "../../../../Types/AI/CodeFixTaskContext";
+import GitHubCommandType from "../../../../Types/CodeRepository/GitHubCommand";
+import { LIMIT_PER_PROJECT } from "../../../../Types/Database/LimitMax";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import OneUptimeDate from "../../../../Types/Date";
+import AIRun from "../../../../Models/DatabaseModels/AIRun";
+import AIRunService from "../../../Services/AIRunService";
+import FixRunBudget from "../../AI/CodeFix/FixRunBudget";
+import QueryHelper from "../../../Types/Database/QueryHelper";
+import CaptureSpan from "../../Telemetry/CaptureSpan";
+
+/*
+ * Turns a GitHub command that has ALREADY been verified — signed webhook,
+ * repository bound to the project, commenter holds write access — into a
+ * queued CodeFix AIRun the agent worker can claim.
+ *
+ * The sibling of SubjectCodeFixRun for conversations instead of incidents. It
+ * enforces the same two things every enqueue path must: the project's daily
+ * fix-run budget, and at most one live run per piece of work. What is
+ * different is the dedupe key. An incident dedupes on its subject row; a
+ * GitHub command has no row, so the key is (repository, issue-or-pull-request,
+ * command) — which is exactly the granularity a user expects: asking for a
+ * review while a revision is running is two different requests, asking for the
+ * same review twice is one.
+ */
+export default class GitHubAgentTaskTrigger {
+  // Which recipe carries out each command. Conversational commands have none.
+  public static getTaskTypeForCommand(
+    commandType: GitHubCommandType,
+  ): CodeFixTaskType | null {
+    switch (commandType) {
+      case GitHubCommandType.Implement:
+        return CodeFixTaskType.GitHubIssueFix;
+      case GitHubCommandType.Revise:
+        return CodeFixTaskType.GitHubPullRequestRevision;
+      case GitHubCommandType.Review:
+        return CodeFixTaskType.GitHubPullRequestReview;
+      default:
+        return null;
+    }
+  }
+
+  /*
+   * The live run, if any, for this exact piece of work.
+   *
+   * The conversation number lives inside the JSON taskContext, which the query
+   * layer cannot filter on — so this reads the project's non-terminal GitHub
+   * runs (bounded and short-lived: they exist only between a comment and its
+   * pull request) and matches in memory. The same honest trade
+   * SubjectCodeFixRun makes for its per-trace and per-service guards.
+   */
+  @CaptureSpan()
+  public static async findNonTerminalRunForConversation(data: {
+    projectId: ObjectID;
+    codeRepositoryId: ObjectID;
+    conversationNumber: number;
+    taskType: CodeFixTaskType;
+  }): Promise<AIRun | null> {
+    const activeRuns: Array<AIRun> = await AIRunService.findBy({
+      query: {
+        projectId: data.projectId,
+        runType: AIRunType.CodeFix,
+        codeFixTaskType: data.taskType,
+        status: QueryHelper.notIn(AIRunStatusHelper.terminalStatuses()),
+      },
+      select: { _id: true, taskContext: true },
+      limit: LIMIT_PER_PROJECT,
+      skip: 0,
+      props: { isRoot: true },
+    });
+
+    return (
+      activeRuns.find((run: AIRun): boolean => {
+        const github: GitHubTaskContext | null = getGitHubTaskContext(
+          run.taskContext,
+        );
+
+        if (!github) {
+          return false;
+        }
+
+        return (
+          github.codeRepositoryId === data.codeRepositoryId.toString() &&
+          getGitHubConversationNumber(github) === data.conversationNumber
+        );
+      }) || null
+    );
+  }
+
+  /*
+   * Every live run for one conversation, whatever the recipe — what "@oneuptime
+   * cancel" acts on. A user cancelling a thread means "stop whatever you are
+   * doing here", not "stop the one recipe I happen to name".
+   */
+  @CaptureSpan()
+  public static async findNonTerminalRunsForConversation(data: {
+    projectId: ObjectID;
+    codeRepositoryId: ObjectID;
+    conversationNumber: number;
+  }): Promise<Array<AIRun>> {
+    const activeRuns: Array<AIRun> = await AIRunService.findBy({
+      query: {
+        projectId: data.projectId,
+        runType: AIRunType.CodeFix,
+        codeFixTaskType: QueryHelper.any(
+          CodeFixTaskTypeHelper.getGitHubTaskTypes(),
+        ),
+        status: QueryHelper.notIn(AIRunStatusHelper.terminalStatuses()),
+      },
+      select: { _id: true, taskContext: true, status: true },
+      limit: LIMIT_PER_PROJECT,
+      skip: 0,
+      props: { isRoot: true },
+    });
+
+    return activeRuns.filter((run: AIRun): boolean => {
+      const github: GitHubTaskContext | null = getGitHubTaskContext(
+        run.taskContext,
+      );
+
+      if (!github) {
+        return false;
+      }
+
+      return (
+        github.codeRepositoryId === data.codeRepositoryId.toString() &&
+        getGitHubConversationNumber(github) === data.conversationNumber
+      );
+    });
+  }
+
+  /*
+   * Record the durable intent as a Queued CodeFix AIRun.
+   *
+   * Created as root: AIRun rows are server-written only (empty create ACL).
+   * The caller must already have established that this command is allowed —
+   * that the webhook signature verified, that the installation is bound to
+   * the project, and that the commenter can write to the repository.
+   *
+   * Throws BadDataException when a run for this work is already live or when
+   * the project is over its daily fix-run budget. The webhook handler turns
+   * both into a plain-English reply in the thread rather than a silent drop:
+   * a command that produces no visible response reads as a broken integration.
+   */
+  @CaptureSpan()
+  public static async enqueueGitHubCodeFixRun(data: {
+    projectId: ObjectID;
+    taskType: CodeFixTaskType;
+    github: GitHubTaskContext;
+  }): Promise<AIRun> {
+    if (!CodeFixTaskTypeHelper.isGitHubTaskType(data.taskType)) {
+      throw new BadDataException(
+        `${data.taskType} is not a GitHub-triggered task type.`,
+      );
+    }
+
+    const github: GitHubTaskContext | null = getGitHubTaskContext({
+      github: data.github,
+    } as CodeFixTaskContext);
+
+    if (!github) {
+      throw new BadDataException(
+        "A GitHub run needs a repository and exactly one issue or pull request.",
+      );
+    }
+
+    GitHubAgentTaskTrigger.assertTaskTypeMatchesContext(data.taskType, github);
+
+    const conversationNumber: number = getGitHubConversationNumber(github);
+
+    const existingRun: AIRun | null =
+      await GitHubAgentTaskTrigger.findNonTerminalRunForConversation({
+        projectId: data.projectId,
+        codeRepositoryId: new ObjectID(github.codeRepositoryId),
+        conversationNumber: conversationNumber,
+        taskType: data.taskType,
+      });
+
+    if (existingRun) {
+      throw new BadDataException(
+        "I am already working on this — I will comment here when I am done.",
+      );
+    }
+
+    await FixRunBudget.assertWithinBudget(data.projectId, {});
+
+    const run: AIRun = new AIRun();
+    run.projectId = data.projectId;
+    run.runType = AIRunType.CodeFix;
+    run.codeFixTaskType = data.taskType;
+    run.status = AIRunStatus.Queued;
+    run.taskContext = { github: github };
+
+    return AIRunService.create({
+      data: run,
+      props: { isRoot: true },
+    });
+  }
+
+  /*
+   * A queued run must be EXECUTABLE by the recipe it names.
+   *
+   * getGitHubTaskContext proves the context is well formed; it does not prove
+   * it matches the recipe. A revision with an issue-only context, or one with
+   * no head branch pinned, passes every other check and is then claimed by a
+   * worker that has nothing to push to — a run that was accepted, told the
+   * user "on it", and could never have succeeded. Catch it at the boundary,
+   * where the message can still be honest about what went wrong.
+   */
+  private static assertTaskTypeMatchesContext(
+    taskType: CodeFixTaskType,
+    github: GitHubTaskContext,
+  ): void {
+    if (taskType === CodeFixTaskType.GitHubIssueFix) {
+      if (github.issueNumber === undefined) {
+        throw new BadDataException(
+          "A GitHub issue task needs an issue to work on.",
+        );
+      }
+
+      return;
+    }
+
+    if (github.pullRequestNumber === undefined) {
+      throw new BadDataException(
+        "A GitHub pull request task needs a pull request to work on.",
+      );
+    }
+
+    /*
+     * Only a revision needs a branch. A review of a pull request from a fork
+     * deliberately has none — it works from the base branch plus the diff.
+     */
+    if (
+      taskType === CodeFixTaskType.GitHubPullRequestRevision &&
+      !github.pullRequestHeadRefName
+    ) {
+      throw new BadDataException(
+        "I cannot revise this pull request because its branch is not in this repository — it may come from a fork.",
+      );
+    }
+  }
+
+  /*
+   * Record the app's acknowledgement comment on the run, so a later status
+   * change edits that comment instead of posting another one.
+   *
+   * Written after the INSERT rather than as part of it because the comment
+   * cannot exist before the run does — the comment links to the run's page.
+   * A failure here is not worth failing the run over: the worst case is one
+   * extra comment when the run finishes.
+   *
+   * The stored context is re-read and merged rather than overwritten from the
+   * caller's in-memory copy. TypeORM replaces a jsonb column wholesale, so
+   * writing the caller's object would clobber anything another writer put
+   * there in between — a narrow window, but a lost update on a column the
+   * outcome sweeper also touches.
+   */
+  @CaptureSpan()
+  public static async recordAcknowledgementComment(data: {
+    aiRunId: ObjectID;
+    github: GitHubTaskContext;
+    acknowledgementCommentId: number;
+  }): Promise<void> {
+    const run: AIRun | null = await AIRunService.findOneById({
+      id: data.aiRunId,
+      select: { _id: true, taskContext: true },
+      props: { isRoot: true },
+    });
+
+    const storedContext: CodeFixTaskContext = run?.taskContext || {};
+
+    await AIRunService.updateOneById({
+      id: data.aiRunId,
+      data: {
+        taskContext: {
+          ...storedContext,
+          github: {
+            ...data.github,
+            ...(storedContext.github || {}),
+            acknowledgementCommentId: data.acknowledgementCommentId,
+          },
+        },
+      } as never,
+      props: { isRoot: true },
+    });
+  }
+
+  /*
+   * Cancel every live run for a conversation.
+   *
+   * A Queued run is cancelled outright — no worker holds it. A Running one is
+   * also marked Cancelled: the worker cannot be reached mid-run, but the CAS
+   * transitions on the reporting endpoints mean its late Completed/Error
+   * report simply loses the race and does not resurrect the run. The user gets
+   * the honest answer either way, which is why the count is returned.
+   */
+  @CaptureSpan()
+  public static async cancelRunsForConversation(data: {
+    projectId: ObjectID;
+    codeRepositoryId: ObjectID;
+    conversationNumber: number;
+  }): Promise<number> {
+    const runs: Array<AIRun> =
+      await GitHubAgentTaskTrigger.findNonTerminalRunsForConversation(data);
+
+    let cancelledCount: number = 0;
+
+    for (const run of runs) {
+      if (!run.id || !run.status) {
+        continue;
+      }
+
+      const transitioned: number = await AIRunService.attemptStatusTransition({
+        aiRunId: run.id,
+        fromStatus: run.status,
+        set: {
+          status: AIRunStatus.Cancelled,
+          completedAt: OneUptimeDate.getCurrentDate(),
+          errorMessage: "Cancelled from GitHub.",
+        },
+      });
+
+      cancelledCount += transitioned;
+    }
+
+    return cancelledCount;
+  }
+}

package/Server/Utils/CodeRepository/GitHub/GitHubCommandAuthorizer.ts

@@ -0,0 +1,274 @@
+import logger from "../../Logger";
+import CodeRepositoryType from "../../../../Types/CodeRepository/CodeRepositoryType";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import CodeRepository from "../../../../Models/DatabaseModels/CodeRepository";
+import ObjectID from "../../../../Types/ObjectID";
+import Project from "../../../../Models/DatabaseModels/Project";
+import CodeRepositoryService from "../../../Services/CodeRepositoryService";
+import ProjectService from "../../../Services/ProjectService";
+import GitHubInstallationBinding from "./GitHubInstallationBinding";
+import GitHubConversation, {
+  GitHubRepositoryPermission,
+} from "./GitHubConversation";
+import CaptureSpan from "../../Telemetry/CaptureSpan";
+
+/*
+ * Whether a GitHub command may run, and — just as important — whether the app
+ * should say anything about it.
+ *
+ * The threat this exists for: a connected repository's issue tracker is open
+ * to anyone with a GitHub account, and a mention costs nothing to write. So
+ * every command arrives as a request from an untrusted party, and there are
+ * two distinct failure modes to keep apart.
+ *
+ *   - A command the app cannot carry out (feature switched off, repository not
+ *     connected) is answered, because the person asking is a collaborator who
+ *     would otherwise think the integration is broken.
+ *
+ *   - A command from someone WITHOUT write access is not answered in the
+ *     thread at all. Replying would make the app a comment-poster that any
+ *     GitHub account can drive: one mention, one guaranteed comment, repeat.
+ *     It gets a single reaction on the offending comment instead — visible to
+ *     the author, idempotent, and useless as an amplifier.
+ */
+
+export enum GitHubAuthorizationOutcome {
+  // The command may proceed.
+  Allowed = "Allowed",
+  /*
+   * Not a command from a human this app should ever answer: a bot, or a
+   * repository this OneUptime instance has no connection to. Silence.
+   */
+  Ignore = "Ignore",
+  /*
+   * A real person without write access to the repository. React, do not
+   * reply — see the note above.
+   */
+  InsufficientPermission = "InsufficientPermission",
+  /*
+   * A collaborator asked, but the repository has GitHub commands switched
+   * off. Reply, so they know where the switch is.
+   */
+  CommandsDisabled = "CommandsDisabled",
+}
+
+export interface GitHubAuthorizationResult {
+  outcome: GitHubAuthorizationOutcome;
+  codeRepository?: CodeRepository | undefined;
+  /*
+   * The OneUptime project the app is acting for. Named in the acknowledgement
+   * comment: a repository can be connected to more than one project, and a
+   * team should never have to guess whose AI budget a command just spent.
+   */
+  projectName?: string | undefined;
+  // Filled for the outcomes that are answered in the thread.
+  reason?: string | undefined;
+}
+
+/*
+ * How many connected-repository rows to consider for one webhook. The same
+ * repository can be imported by several projects, and the app acts for exactly
+ * one of them — the oldest bound connection. This bounds the query; hitting it
+ * is logged rather than silently truncated.
+ */
+const MAX_CONNECTED_REPOSITORY_CANDIDATES: number = 10;
+
+export default class GitHubCommandAuthorizer {
+  /*
+   * The CodeRepository row a webhook's repository belongs to.
+   *
+   * Matched on organization + name + installation, then re-derived from the
+   * project: the row's installation ID is a value stored on a record, and the
+   * question "may this installation act for this project?" is only ever
+   * answered by GitHubInstallationBinding, never by the row itself. Same rule
+   * the repository-token endpoint applies before it mints a token.
+   *
+   * More than one project may have imported the same repository. Acting for
+   * all of them would mean one comment producing several pull requests, so the
+   * OLDEST connection wins — deterministic, and stable across redeliveries of
+   * the same webhook.
+   */
+  @CaptureSpan()
+  public static async resolveConnectedRepository(data: {
+    organizationName: string;
+    repositoryName: string;
+    installationId: string;
+  }): Promise<CodeRepository | null> {
+    const candidates: Array<CodeRepository> =
+      await CodeRepositoryService.findBy({
+        query: {
+          organizationName: data.organizationName,
+          repositoryName: data.repositoryName,
+          repositoryHostedAt: CodeRepositoryType.GitHub,
+          gitHubAppInstallationId: data.installationId,
+        },
+        select: {
+          _id: true,
+          projectId: true,
+          organizationName: true,
+          repositoryName: true,
+          mainBranchName: true,
+          gitHubAppInstallationId: true,
+          isGitHubCommandsEnabled: true,
+          gitHubTriggerLabel: true,
+        },
+        sort: { createdAt: SortOrder.Ascending },
+        limit: MAX_CONNECTED_REPOSITORY_CANDIDATES,
+        skip: 0,
+        props: { isRoot: true },
+      });
+
+    /*
+     * At the cap, a legitimate connection past the tenth is invisible — and
+     * would otherwise be indistinguishable from "not connected at all". Say so
+     * once, so an operator chasing a silently ignored command has something to
+     * find.
+     */
+    if (candidates.length === MAX_CONNECTED_REPOSITORY_CANDIDATES) {
+      logger.warn(
+        `${data.organizationName}/${data.repositoryName} matched the maximum of ${MAX_CONNECTED_REPOSITORY_CANDIDATES} connected repository rows for installation ${data.installationId}; any connection beyond that is not being considered.`,
+      );
+    }
+
+    for (const candidate of candidates) {
+      if (!candidate.projectId || !candidate.gitHubAppInstallationId) {
+        continue;
+      }
+
+      const isBound: boolean =
+        await GitHubInstallationBinding.isInstallationBoundToProject({
+          projectId: candidate.projectId,
+          installationId: candidate.gitHubAppInstallationId,
+        });
+
+      if (!isBound) {
+        logger.warn(
+          `Ignoring a GitHub command for ${data.organizationName}/${data.repositoryName}: installation ${data.installationId} is not bound to project ${candidate.projectId.toString()}.`,
+        );
+        continue;
+      }
+
+      if (candidates.length > 1) {
+        logger.info(
+          `${data.organizationName}/${data.repositoryName} is connected to ${candidates.length} OneUptime projects; acting for the oldest connection (project ${candidate.projectId.toString()}).`,
+        );
+      }
+
+      return candidate;
+    }
+
+    return null;
+  }
+
+  /*
+   * Whether this repository answers GitHub commands at all.
+   *
+   * A null column means enabled. The switch was added after the repositories
+   * were, and defaulting existing rows to "off" would mean the feature does
+   * nothing anywhere until every repository is visited by hand. Nothing
+   * happens until somebody deliberately types the mention regardless, so the
+   * safe default is also the useful one.
+   */
+  public static areCommandsEnabled(codeRepository: CodeRepository): boolean {
+    return codeRepository.isGitHubCommandsEnabled !== false;
+  }
+
+  @CaptureSpan()
+  public static async authorize(data: {
+    organizationName: string;
+    repositoryName: string;
+    installationId: string;
+    senderLogin: string;
+    // GitHub's own "is this a bot" signal from the webhook's sender object.
+    senderType: string | undefined;
+  }): Promise<GitHubAuthorizationResult> {
+    if (
+      !data.senderLogin ||
+      data.senderType?.toLowerCase() === "bot" ||
+      GitHubConversation.isBotLogin(data.senderLogin)
+    ) {
+      /*
+       * The loop guard. The app's own comments arrive here as webhooks, and so
+       * do every other bot's — neither is a human asking for work.
+       */
+      return { outcome: GitHubAuthorizationOutcome.Ignore };
+    }
+
+    const codeRepository: CodeRepository | null =
+      await GitHubCommandAuthorizer.resolveConnectedRepository({
+        organizationName: data.organizationName,
+        repositoryName: data.repositoryName,
+        installationId: data.installationId,
+      });
+
+    if (!codeRepository) {
+      /*
+       * The app is installed on a repository this instance has not connected
+       * to a project. It has no project to bill, no budget to check and no
+       * agent to run — and no standing to comment in someone's repository.
+       */
+      return { outcome: GitHubAuthorizationOutcome.Ignore };
+    }
+
+    if (!GitHubCommandAuthorizer.areCommandsEnabled(codeRepository)) {
+      return {
+        outcome: GitHubAuthorizationOutcome.CommandsDisabled,
+        codeRepository: codeRepository,
+        reason:
+          "GitHub commands are switched off for this repository. A project admin can turn them back on in OneUptime under Code Repositories → this repository → Settings.",
+      };
+    }
+
+    const permission: GitHubRepositoryPermission =
+      await GitHubConversation.getUserRepositoryPermission({
+        installationId: data.installationId,
+        organizationName: data.organizationName,
+        repositoryName: data.repositoryName,
+        username: data.senderLogin,
+      });
+
+    if (!GitHubConversation.canCommandApp(permission)) {
+      logger.info(
+        `Refusing a GitHub command from ${data.senderLogin} on ${data.organizationName}/${data.repositoryName}: repository permission is "${permission}".`,
+      );
+
+      return {
+        outcome: GitHubAuthorizationOutcome.InsufficientPermission,
+        codeRepository: codeRepository,
+      };
+    }
+
+    return {
+      outcome: GitHubAuthorizationOutcome.Allowed,
+      codeRepository: codeRepository,
+      projectName: await GitHubCommandAuthorizer.getProjectName(
+        codeRepository.projectId,
+      ),
+    };
+  }
+
+  /*
+   * The project's display name, for attribution in the thread. Never fails the
+   * command: a name is a nicety, and losing it is not a reason to refuse work.
+   */
+  private static async getProjectName(
+    projectId: ObjectID | undefined,
+  ): Promise<string | undefined> {
+    if (!projectId) {
+      return undefined;
+    }
+
+    try {
+      const project: Project | null = await ProjectService.findOneById({
+        id: projectId,
+        select: { _id: true, name: true },
+        props: { isRoot: true },
+      });
+
+      return project?.name || undefined;
+    } catch (error) {
+      logger.debug(`Could not read the project name for attribution: ${error}`);
+      return undefined;
+    }
+  }
+}