gonzalo_ticket_linear/

source.rs

//! A read-only [`TicketSource`] backed by the Linear GraphQL API.
//!
//! Authenticates with a Linear API key in the `Authorization` header. Phase 1
//! imports via `fetch_changed` (cursor-paginated `issues` query) and `get`.
//! HTTP-level behavior is exercised by the conformance suite's fixtures (#20);
//! the mapping is unit-tested in [`crate::mapping`].

use crate::mapping::{LinearIssue, issue_to_ticket};
use async_trait::async_trait;
use gonzalo_domain::{StateCategory, Ticket};
use gonzalo_ticket::{
    Capabilities, Cursor, Page, Result, SourceError, StateMapping, TicketSource, provider_error,
};
use serde::Deserialize;
use serde::de::DeserializeOwned;

/// The Linear workflow-state `type` a target [`StateCategory`] maps onto.
fn target_state_type(target: StateCategory) -> &'static str {
    match target {
        StateCategory::Triage => "triage",
        StateCategory::Backlog => "backlog",
        StateCategory::InProgress | StateCategory::Pending => "started",
        StateCategory::Done => "completed",
        StateCategory::Canceled => "canceled",
        // Open
        _ => "unstarted",
    }
}

#[derive(Debug, Deserialize)]
struct IssueTeamData {
    issue: Option<IssueTeam>,
}

#[derive(Debug, Deserialize)]
struct IssueTeam {
    team: Team,
}

#[derive(Debug, Deserialize)]
struct Team {
    states: StateNodes,
}

#[derive(Debug, Deserialize)]
struct StateNodes {
    nodes: Vec<WorkflowState>,
}

#[derive(Debug, Deserialize)]
struct WorkflowState {
    id: String,
    #[serde(rename = "type")]
    type_: String,
}

const ENDPOINT: &str = "https://api.linear.app/graphql";

/// The issue fields selected by both queries.
const ISSUE_FIELDS: &str = "id identifier title description priority \
    state { name type } assignee { displayName } creator { displayName } \
    labels { nodes { name } } team { key name } project { name }";

#[derive(Debug, Deserialize)]
struct GqlResponse<T> {
    #[serde(default = "Option::default")]
    data: Option<T>,
    #[serde(default)]
    errors: Vec<GqlError>,
}

#[derive(Debug, Deserialize)]
struct GqlError {
    message: String,
}

#[derive(Debug, Deserialize)]
struct IssuesData {
    issues: IssueConnection,
}

#[derive(Debug, Deserialize)]
struct IssueConnection {
    #[serde(rename = "pageInfo")]
    page_info: PageInfo,
    nodes: Vec<LinearIssue>,
}

#[derive(Debug, Deserialize)]
struct PageInfo {
    #[serde(rename = "hasNextPage")]
    has_next_page: bool,
    #[serde(rename = "endCursor")]
    end_cursor: Option<String>,
}

#[derive(Debug, Deserialize)]
struct IssueData {
    issue: Option<LinearIssue>,
}

/// The `{ success }` payload every Linear mutation returns.
#[derive(Debug, Deserialize)]
struct SuccessFlag {
    success: bool,
}

#[derive(Debug, Deserialize)]
struct IssueUpdateResp {
    #[serde(rename = "issueUpdate")]
    issue_update: SuccessFlag,
}

#[derive(Debug, Deserialize)]
struct CommentCreateResp {
    #[serde(rename = "commentCreate")]
    comment_create: SuccessFlag,
}

/// Linear returns HTTP 200 with `success: false` (and no `errors` array) for
/// writes it silently declines — an invalid `stateId`, insufficient
/// permissions, etc. Turn that into an error so a failed write never looks like
/// a successful one.
fn check_success(success: bool, op: &str) -> Result<()> {
    if success {
        Ok(())
    } else {
        Err(SourceError::Backend(format!(
            "linear {op} reported success: false"
        )))
    }
}

/// Imports issues from a Linear workspace.
pub struct LinearSource {
    client: reqwest::Client,
    endpoint: reqwest::Url,
    api_key: String,
    mapping: Option<StateMapping>,
}

impl LinearSource {
    /// Connect with a Linear API key (sent verbatim in the `Authorization`
    /// header, per Linear's personal-API-key scheme).
    pub fn new(api_key: impl Into<String>) -> Result<Self> {
        Self::with_endpoint(ENDPOINT, api_key)
    }

    /// Connect against a custom GraphQL endpoint (e.g. a test server).
    pub fn with_endpoint(endpoint: &str, api_key: impl Into<String>) -> Result<Self> {
        let client = reqwest::Client::builder()
            .user_agent("gonzalo-ticket-linear")
            .build()
            .map_err(be)?;
        Ok(Self {
            client,
            endpoint: reqwest::Url::parse(endpoint).map_err(be)?,
            api_key: api_key.into(),
            mapping: None,
        })
    }

    /// Apply a per-connection [`StateMapping`] for state-name → category
    /// overrides (falls back to Linear's state `type`).
    #[must_use]
    pub fn with_mapping(mut self, mapping: StateMapping) -> Self {
        self.mapping = Some(mapping);
        self
    }

    async fn query<T: DeserializeOwned>(
        &self,
        query: &str,
        variables: serde_json::Value,
    ) -> Result<T> {
        let body = serde_json::json!({ "query": query, "variables": variables });
        let resp = self
            .client
            .post(self.endpoint.clone())
            .header(reqwest::header::AUTHORIZATION, &self.api_key)
            .json(&body)
            .send()
            .await
            .map_err(be)?
            .check_status()
            .await?;
        let gql: GqlResponse<T> = resp.json().await.map_err(be)?;
        if !gql.errors.is_empty() {
            let msg = gql
                .errors
                .iter()
                .map(|e| e.message.as_str())
                .collect::<Vec<_>>()
                .join("; ");
            return Err(SourceError::Backend(format!("linear graphql: {msg}")));
        }
        gql.data
            .ok_or_else(|| SourceError::Backend("linear graphql: empty data".into()))
    }
}

#[async_trait]
impl TicketSource for LinearSource {
    fn capabilities(&self) -> Capabilities {
        Capabilities {
            push: true,
            comments: true,
            ..Capabilities::default()
        }
    }

    async fn fetch_changed(&self, cursor: &Cursor) -> Result<Page> {
        let query = format!(
            "query($after: String) {{ issues(first: 100, after: $after) {{ \
             pageInfo {{ hasNextPage endCursor }} nodes {{ {ISSUE_FIELDS} }} }} }}"
        );
        let data: IssuesData = self
            .query(&query, serde_json::json!({ "after": cursor.0 }))
            .await?;
        let tickets = data
            .issues
            .nodes
            .iter()
            .map(|i| issue_to_ticket(i, self.mapping.as_ref()))
            .collect();
        let next = if data.issues.page_info.has_next_page {
            Cursor(data.issues.page_info.end_cursor)
        } else {
            Cursor::default()
        };
        Ok(Page { tickets, next })
    }

    async fn get(&self, uid: &str) -> Result<Ticket> {
        let query = format!("query($id: String!) {{ issue(id: $id) {{ {ISSUE_FIELDS} }} }}");
        let data: IssueData = self.query(&query, serde_json::json!({ "id": uid })).await?;
        let issue = data
            .issue
            .ok_or_else(|| SourceError::Backend(format!("no linear issue {uid}")))?;
        Ok(issue_to_ticket(&issue, self.mapping.as_ref()))
    }

    async fn set_state(&self, uid: &str, target: StateCategory) -> Result<()> {
        // Linear states are workspace-defined; resolve a state of the issue's
        // team whose `type` matches the target, then update the issue to it.
        let states_query =
            "query($id: String!) { issue(id: $id) { team { states { nodes { id type } } } } }";
        let data: IssueTeamData = self
            .query(states_query, serde_json::json!({ "id": uid }))
            .await?;
        let team = data
            .issue
            .ok_or_else(|| SourceError::Backend(format!("no linear issue {uid}")))?
            .team;
        let want = target_state_type(target);
        let state = team
            .states
            .nodes
            .iter()
            .find(|s| s.type_ == want)
            .ok_or_else(|| {
                SourceError::Backend(format!("team has no workflow state of type '{want}'"))
            })?;

        let mutation = "mutation($id: String!, $sid: String!) { issueUpdate(id: $id, input: { stateId: $sid }) { success } }";
        let resp: IssueUpdateResp = self
            .query(mutation, serde_json::json!({ "id": uid, "sid": state.id }))
            .await?;
        check_success(resp.issue_update.success, "issueUpdate")
    }

    async fn comment(&self, uid: &str, body: &str) -> Result<()> {
        let mutation = "mutation($id: String!, $body: String!) { commentCreate(input: { issueId: $id, body: $body }) { success } }";
        let resp: CommentCreateResp = self
            .query(mutation, serde_json::json!({ "id": uid, "body": body }))
            .await?;
        check_success(resp.comment_create.success, "commentCreate")
    }
}

fn be<E: std::fmt::Display>(e: E) -> SourceError {
    SourceError::Backend(e.to_string())
}

/// Fail with the provider's own message instead of reqwest's generic one.
///
/// reqwest's `error_for_status()` discards the response body, which is exactly
/// where a ticket provider puts the reason — expired token, missing scope,
/// malformed query, rate-limit window. Swapping it for `check_status()` keeps
/// the reason (#240). The message format is shared via
/// [`provider_error`](gonzalo_ticket::provider_error) so the connectors cannot
/// drift apart.
trait CheckStatus: Sized {
    async fn check_status(self) -> Result<Self>;
}

impl CheckStatus for reqwest::Response {
    async fn check_status(self) -> Result<Self> {
        let status = self.status();
        if status.is_success() {
            return Ok(self);
        }
        // Read the body only on the failure path; the caller decodes success.
        let body = self.text().await.unwrap_or_default();
        Err(provider_error(status.as_u16(), &body))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn endpoint_and_write_capabilities() {
        let src = LinearSource::new("lin_api_xxx").unwrap();
        assert!(src.capabilities().push);
        assert!(src.capabilities().comments);
        assert_eq!(src.endpoint.as_str(), "https://api.linear.app/graphql");
    }

    #[test]
    fn parses_graphql_errors_envelope() {
        // Round-trips the error envelope shape the connector surfaces.
        let resp: GqlResponse<IssuesData> =
            serde_json::from_str(r#"{"errors":[{"message":"bad"}]}"#).unwrap();
        assert!(resp.data.is_none());
        assert_eq!(resp.errors[0].message, "bad");
    }

    #[test]
    fn issue_update_success_false_is_deserialized() {
        // Linear returns HTTP 200 with success:false and no `errors` array.
        let resp: GqlResponse<IssueUpdateResp> =
            serde_json::from_str(r#"{"data":{"issueUpdate":{"success":false}}}"#).unwrap();
        assert!(!resp.data.unwrap().issue_update.success);
    }

    #[test]
    fn comment_create_success_is_deserialized() {
        let resp: GqlResponse<CommentCreateResp> =
            serde_json::from_str(r#"{"data":{"commentCreate":{"success":true}}}"#).unwrap();
        assert!(resp.data.unwrap().comment_create.success);
    }

    #[test]
    fn check_success_maps_false_to_backend_error() {
        let err = check_success(false, "issueUpdate").unwrap_err();
        match err {
            SourceError::Backend(msg) => {
                assert!(msg.contains("issueUpdate"), "message was: {msg}");
                assert!(msg.contains("success: false"), "message was: {msg}");
            }
            other => panic!("expected Backend error, got {other:?}"),
        }
    }

    #[test]
    fn check_success_passes_true() {
        assert!(check_success(true, "commentCreate").is_ok());
    }
}