Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

14.0 KB
Raw Blame
//! Port definitions for github sync operations (webhooks and sync app).

use std::future::Future;

use macro_user_id::user_id::MacroUserIdStr;

use crate::domain::models::{
    AppJwt, EnrichedGithubPullRequest, GithubAppInstallationSource, GithubAuthenticatedUser,
    GithubError, GithubInstallationAccessToken, GithubKey, GithubPullRequestDetails,
    GithubRepository, GithubSetupAccessToken, GithubUserInstallation, MacroTaskId,
    PullRequestIndexPage, PullRequestIndexRequest, ResolvedTeamTaskReference, TeamTaskReference,
    ValidatedGithubWebhookEvent,
};

/// Repository for accessing github sync data from the database.
///
/// All methods perform database operations — SQL queries are written
/// directly in the outbound adapter implementation.
#[cfg_attr(test, mockall::automock(type Err = anyhow::Error;))]
pub trait GithubSyncRepo: Send + Sync + 'static {
    /// The error type returned by repository operations.
    type Err: Into<anyhow::Error> + Send + std::fmt::Debug;

    /// Provides a list of all task ids for a given github key
    fn get_task_ids(
        &self,
        github_key: GithubKey,
    ) -> impl Future<Output = Result<Vec<MacroTaskId>, Self::Err>> + Send;

    /// Upserts task ids for a given github key
    fn upsert_task_ids(
        &self,
        github_key: GithubKey,
        task_ids: &[MacroTaskId],
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;

    /// Filters out all pre-existing tasks for the github key
    /// Returns only new task ids
    fn filter_duplicate_tasks(
        &self,
        github_key: GithubKey,
        task_ids: &[MacroTaskId],
    ) -> impl Future<Output = Result<Vec<MacroTaskId>, Self::Err>> + Send;

    /// Resolves team-scoped task references for a GitHub App installation.
    ///
    /// Implementations should use the installation's team sources from
    /// `github_app_installation` (`source_type = 'team'`) and the referenced
    /// team slug/task number to find the backing Macro task document. Each
    /// match is returned with the team it resolved in; because team slugs are
    /// not unique, one reference may resolve in several of the installation's
    /// teams and callers must treat such references as ambiguous instead of
    /// linking every match.
    fn resolve_team_task_references(
        &self,
        installation_id: &str,
        references: &[TeamTaskReference],
    ) -> impl Future<Output = Result<Vec<ResolvedTeamTaskReference>, Self::Err>> + Send;

    /// Maps GitHub user IDs to the Macro user IDs linked to them via the `github_links` table.
    ///
    /// A GitHub user ID absent from the result has no link; a GitHub user ID may map to
    /// multiple Macro users because `github_links.github_user_id` is not unique (many Macro
    /// users may share one GitHub account).
    fn get_macro_ids_by_github_user_ids(
        &self,
        github_user_ids: &[String],
    ) -> impl Future<Output = Result<std::collections::HashMap<String, Vec<String>>, Self::Err>> + Send;

    /// Maps GitHub logins to the Macro user IDs linked to them via the `github_links` table.
    ///
    /// Logins are matched case-insensitively and returned lowercased. A login absent
    /// from the result has no link; a login may map to multiple Macro users because
    /// `github_links.github_username` is not unique.
    fn get_macro_ids_by_github_logins(
        &self,
        github_logins: &[String],
    ) -> impl Future<Output = Result<std::collections::HashMap<String, Vec<String>>, Self::Err>> + Send;

    /// Returns all team IDs the given macro user belongs to.
    fn get_user_team_ids(
        &self,
        macro_id: &str,
    ) -> impl Future<Output = Result<Vec<uuid::Uuid>, Self::Err>> + Send;

    /// Returns the Macro sources associated with a GitHub App installation.
    fn get_installation_sources(
        &self,
        installation_id: &str,
    ) -> impl Future<Output = Result<Vec<GithubAppInstallationSource>, Self::Err>> + Send;

    /// Returns the installations whose sources include the given Macro user or
    /// any of the given teams.
    ///
    /// The inverse of [`GithubSyncRepo::get_installation_sources`]: that
    /// answers "who installed this?", this answers "what did they install?".
    /// Ids are returned once each even when several of the user's sources
    /// point at the same installation.
    fn get_installation_ids_for_sources(
        &self,
        macro_id: &str,
        team_ids: &[uuid::Uuid],
    ) -> impl Future<Output = Result<Vec<String>, Self::Err>> + Send;

    /// Returns all Macro user IDs that belong to the given team.
    fn get_team_member_ids(
        &self,
        team_id: uuid::Uuid,
    ) -> impl Future<Output = Result<Vec<MacroUserIdStr<'static>>, Self::Err>> + Send;

    /// Upserts associations between a GitHub App installation and its sources.
    /// Ignores conflicts (idempotent).
    fn upsert_installation_sources(
        &self,
        installation_id: &str,
        sources: &[GithubAppInstallationSource],
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;

    /// Deletes all source associations for a GitHub App installation.
    /// Deleting an installation with no associations is a no-op (idempotent).
    fn delete_installation_sources(
        &self,
        installation_id: &str,
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;

    /// Records the Macro source a GitHub user asked to sync when requesting an
    /// org install that awaits admin approval. Replaces any earlier pending
    /// request by the same GitHub user (latest intent wins).
    fn upsert_installation_request(
        &self,
        github_user_id: &str,
        source: &GithubAppInstallationSource,
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;

    /// Returns the pending installation request source for a GitHub user, if any.
    fn get_installation_request(
        &self,
        github_user_id: &str,
    ) -> impl Future<Output = Result<Option<GithubAppInstallationSource>, Self::Err>> + Send;

    /// Deletes a GitHub user's pending installation request.
    /// Deleting a missing request is a no-op (idempotent).
    fn delete_installation_request(
        &self,
        github_user_id: &str,
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;
}

/// Client interface for making GitHub sync API calls.
///
/// Abstracts HTTP communication with GitHub's API so the service
/// layer does not need to manage its own HTTP client.
pub trait GithubSyncClient: Send + Sync + 'static {
    /// Exchanges a GitHub App setup callback code for a user access token.
    fn exchange_setup_code(
        &self,
        client_id: &str,
        client_secret: &str,
        code: &str,
    ) -> impl Future<Output = Result<GithubSetupAccessToken, GithubError>> + Send;

    /// Lists every GitHub App installation visible to a user access token.
    fn list_user_installations(
        &self,
        access_token: &str,
    ) -> impl Future<Output = Result<Vec<GithubUserInstallation>, GithubError>> + Send;

    /// Fetches the GitHub user behind a user access token.
    fn get_authenticated_user(
        &self,
        access_token: &str,
    ) -> impl Future<Output = Result<GithubAuthenticatedUser, GithubError>> + Send;

    /// Generates an installation access token for a given GitHub App installation.
    fn generate_installation_access_token(
        &self,
        jwt: &AppJwt,
        installation_id: u64,
    ) -> impl Future<Output = Result<GithubInstallationAccessToken, GithubError>> + Send;

    /// Finds which installation of our App covers a repository, if any.
    ///
    /// `None` means the App is not installed on it - which, from a caller
    /// acting for a user, is indistinguishable from a repository that does not
    /// exist, and deliberately so.
    fn get_repository_installation(
        &self,
        jwt: &AppJwt,
        owner: &str,
        repository: &str,
    ) -> impl Future<Output = Result<Option<u64>, GithubError>> + Send;

    /// Generates an installation access token cut down to one repository and a
    /// named set of permissions.
    ///
    /// An unscoped installation token reaches every repository in the
    /// installation with every permission it was granted; this is the narrow
    /// form, for callers acting on one repository's behalf. `permissions` are
    /// GitHub's own names and levels, e.g. `("contents", "write")`.
    fn generate_scoped_installation_access_token(
        &self,
        jwt: &AppJwt,
        installation_id: u64,
        repository: &str,
        permissions: &[(&str, &str)],
    ) -> impl Future<Output = Result<GithubInstallationAccessToken, GithubError>> + Send;

    /// Posts a comment on a GitHub pull request (via the issues API).
    fn create_pr_comment(
        &self,
        access_token: &str,
        owner: &str,
        repo: &str,
        pull_number: u64,
        body: &str,
    ) -> impl Future<Output = Result<(), GithubError>> + Send;

    /// Fetches enriched pull request details using a GitHub App installation token.
    fn get_pull_request_details(
        &self,
        access_token: &str,
        owner: &str,
        repo: &str,
        number: u64,
    ) -> impl Future<Output = Result<GithubPullRequestDetails, GithubError>> + Send;

    /// Lists open pull requests for repositories accessible to a GitHub App installation token.
    fn list_open_pull_requests(
        &self,
        access_token: &str,
    ) -> impl Future<Output = Result<Vec<EnrichedGithubPullRequest>, GithubError>> + Send;

    /// Branch names on one repository, as GitHub lists them.
    ///
    /// An empty repository has no branches and is an empty list, not an error.
    fn list_repository_branches(
        &self,
        access_token: &str,
        owner: &str,
        repository: &str,
    ) -> impl Future<Output = Result<Vec<String>, GithubError>> + Send;
}

/// Service interface for github sync operations (webhooks and sync app).
///
/// Handles webhook validation/processing and sync app installation token generation.
pub trait GithubSyncService: Send + Sync + 'static {
    /// Validates the incoming webhook event and returns back the `ValidatedGithubWebhookEvent`
    fn validate_webhook_event(
        &self,
        event_type: &str,
        signature: &str,
        body: &[u8],
    ) -> impl Future<Output = Result<ValidatedGithubWebhookEvent, GithubError>> + Send;

    /// Processes and incoming github webhook event
    fn process_webhook_event(
        &self,
        webhook_event: &ValidatedGithubWebhookEvent,
    ) -> impl Future<Output = Result<(), GithubError>> + Send;

    /// Begins an authenticated GitHub App installation setup flow.
    fn begin_installation_setup(
        &self,
        _macro_user_id: &MacroUserIdStr<'_>,
        _team_id: Option<uuid::Uuid>,
    ) -> impl Future<Output = Result<String, GithubError>> + Send {
        async {
            Err(GithubError::Internal(anyhow::anyhow!(
                "installation setup is unsupported"
            )))
        }
    }

    /// Completes an installation setup callback after verifying its state,
    /// that the completing GitHub account is linked to the state's Macro user,
    /// and (for install/update) that the account owns the installation.
    fn complete_installation_setup(
        &self,
        _state: &str,
        _code: Option<&str>,
        _installation_id: Option<u64>,
        _setup_action: &str,
    ) -> impl Future<Output = Result<(), GithubError>> + Send {
        async {
            Err(GithubError::Internal(anyhow::anyhow!(
                "installation setup is unsupported"
            )))
        }
    }

    /// Returns the raw installation URL for legacy inbound adapters.
    ///
    /// New installation flows must use [`GithubSyncService::begin_installation_setup`].
    fn get_github_sync_app_url(&self) -> &str;

    /// Generates an installation access token for the github sync app
    fn generate_installation_access_token(
        &self,
        installation_id: u64,
    ) -> impl Future<Output = Result<GithubInstallationAccessToken, GithubError>> + Send;
}

/// Publishes persisted PR mappings to users allowed to view their source.
pub trait GithubSyncRealtime: Send + Sync + 'static {
    /// Forward a saved entity; recipient selection belongs to the sync service.
    fn publish_pull_request(
        &self,
        recipients: &[MacroUserIdStr<'static>],
        entity: &foreign_entity::domain::models::ForeignEntity,
    ) -> impl Future<Output = Result<(), GithubError>> + Send;
}

/// Pages through every GitHub App installation Macro has recorded.
pub trait GithubInstallationLister: Send + Sync + 'static {
    /// The error type returned by repository operations.
    type Err: Into<anyhow::Error> + Send + std::fmt::Debug;

    /// Up to `limit` distinct installation ids that sort after `after`, in ascending order.
    fn list_installation_ids(
        &self,
        after: Option<&str>,
        limit: u32,
    ) -> impl Future<Output = Result<Vec<String>, Self::Err>> + Send;
}

/// Writes typed rows for pull requests stored before rows existed, one page of installations at
/// a time.
pub trait GithubPullRequestIndex: Send + Sync + 'static {
    /// Process the next page of installations and report what changed.
    fn index_pull_requests(
        &self,
        request: PullRequestIndexRequest,
    ) -> impl Future<Output = Result<PullRequestIndexPage, GithubError>> + Send;
}

/// Lists repository metadata for an installation the caller is authorized to access.
pub trait GithubRepositoryClient: Send + Sync + 'static {
    /// Fetch the installation's repositories using metadata-only access.
    fn repositories_for_installation(
        &self,
        jwt: &AppJwt,
        installation_id: u64,
    ) -> impl Future<Output = Result<Vec<GithubRepository>, GithubError>> + Send;
}

/// Publishes every verified delivery for other domains to act on.
///
/// Object-safe so read-only service instances can go without one.
pub trait GithubWebhookPublisher: Send + Sync + 'static {
    /// Await publication of one delivery.
    fn publish_received(
        &self,
        delivery: crate::domain::models::GithubWebhookReceived,
    ) -> std::pin::Pin<Box<dyn Future<Output = Result<(), GithubError>> + Send + '_>>;
}