beads/internal/linear/client.go
Kevin Glynn 50b0617405
fix(linear): arm rate-limit breaker after successful calls (#4778)
* fix(linear): arm rate-limit breaker after successful calls

Co-authored-by: Medhaug <Medhaug@users.noreply.github.com>

* fix(linear): expire rate limit breaker after reset

Agent-Signature: codex-gpt-5.6-sol-medium on behalf of matt wilkie

* fix(linear): parse reset header as epoch milliseconds

Agent-Signature: codex-gpt-5.6-sol-medium on behalf of matt wilkie

* fix(linear): require valid reset to arm breaker

Agent-Signature: codex-gpt-5.6-sol-medium on behalf of matt wilkie

* fix(linear): bound rate limit reset horizon

Agent-Signature: codex-gpt-5.6-sol-medium on behalf of matt wilkie

* test(linear): send valid reset header so breaker arms in reconcile mock

The breaker arming contract now requires a valid future
X-RateLimit-Requests-Reset alongside low remaining quota (48b0c6725).
The parent-reconcile mock only sent the remaining header, so the
breaker never armed and TestReconcileParents_AbortsOnRateLimit got no
abort error.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Medhaug <Medhaug@users.noreply.github.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-14 13:13:52 -07:00

1592 lines
41 KiB
Go

package linear
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"math/rand/v2"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"sync"
"time"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/types"
)
// projectsQuery is the GraphQL query for fetching projects.
const projectsQuery = `
query Projects($filter: ProjectFilter!, $first: Int!, $after: String) {
projects(
first: $first
after: $after
filter: $filter
) {
nodes {
id
name
description
slugId
url
state
progress
createdAt
updatedAt
completedAt
}
pageInfo {
hasNextPage
endCursor
}
}
}
`
// issuesQuery is the GraphQL query for fetching issues with all required fields.
// Used by both FetchIssues and FetchIssuesSince for consistency.
const issuesQuery = `
query Issues($filter: IssueFilter!, $first: Int!, $after: String) {
issues(
first: $first
after: $after
filter: $filter
) {
nodes {
id
identifier
title
description
url
priority
state {
id
name
type
}
assignee {
id
name
email
displayName
}
labels {
nodes {
id
name
}
}
parent {
id
identifier
}
projectMilestone {
id
name
description
progress
targetDate
}
relations {
nodes {
id
type
relatedIssue {
id
identifier
}
}
}
createdAt
updatedAt
completedAt
}
pageInfo {
hasNextPage
endCursor
}
}
}
`
type rateLimitState struct {
mu sync.RWMutex
remaining int
resetsAt time.Time
}
// maxRateLimitResetHorizon accommodates Linear's short quota windows and
// clock skew without allowing a nonsensical timestamp to block requests
// effectively forever.
const maxRateLimitResetHorizon = 24 * time.Hour
func newRateLimitState() *rateLimitState {
return &rateLimitState{remaining: -1}
}
// NewClient creates a new Linear client with the given API key and team ID.
func NewClient(apiKey, teamID string) *Client {
return &Client{
APIKey: apiKey,
TeamID: teamID,
Endpoint: DefaultAPIEndpoint,
AuthMode: AuthModeAPIKey,
HTTPClient: &http.Client{
Timeout: DefaultTimeout,
},
rateLimitState: newRateLimitState(),
}
}
// NewOAuthClient creates a new Linear client that authenticates via OAuth
// client_credentials flow instead of a static API key.
func NewOAuthClient(oauthConfig OAuthConfig, teamID string) *Client {
return &Client{
TeamID: teamID,
Endpoint: DefaultAPIEndpoint,
AuthMode: AuthModeOAuth,
TokenManager: NewOAuthTokenManager(oauthConfig),
HTTPClient: &http.Client{
Timeout: DefaultTimeout,
},
rateLimitState: newRateLimitState(),
}
}
// WithEndpoint returns a new client configured to use the specified endpoint.
// This is useful for testing with mock servers or connecting to self-hosted instances.
func (c *Client) WithEndpoint(endpoint string) *Client {
return &Client{
APIKey: c.APIKey,
TeamID: c.TeamID,
ProjectID: c.ProjectID,
Endpoint: endpoint,
HTTPClient: c.HTTPClient,
AuthMode: c.AuthMode,
TokenManager: c.TokenManager,
RateLimitFloor: c.RateLimitFloor,
rateLimitState: c.rateLimitState,
}
}
// WithHTTPClient returns a new client configured to use the specified HTTP client.
// This is useful for testing or customizing timeouts and transport settings.
func (c *Client) WithHTTPClient(httpClient *http.Client) *Client {
return &Client{
APIKey: c.APIKey,
TeamID: c.TeamID,
ProjectID: c.ProjectID,
Endpoint: c.Endpoint,
HTTPClient: httpClient,
AuthMode: c.AuthMode,
TokenManager: c.TokenManager,
RateLimitFloor: c.RateLimitFloor,
rateLimitState: c.rateLimitState,
}
}
// WithProjectID returns a new client configured to filter issues by the specified project.
// When set, FetchIssues and FetchIssuesSince will only return issues belonging to this project.
func (c *Client) WithProjectID(projectID string) *Client {
return &Client{
APIKey: c.APIKey,
TeamID: c.TeamID,
ProjectID: projectID,
Endpoint: c.Endpoint,
HTTPClient: c.HTTPClient,
AuthMode: c.AuthMode,
TokenManager: c.TokenManager,
RateLimitFloor: c.RateLimitFloor,
rateLimitState: c.rateLimitState,
}
}
// authHeader returns the Authorization header value for this client.
func (c *Client) authHeader() (string, error) {
switch c.AuthMode {
case AuthModeOAuth:
token, err := c.TokenManager.Token()
if err != nil {
return "", fmt.Errorf("failed to get OAuth token: %w", err)
}
return "Bearer " + token, nil
default:
return c.APIKey, nil
}
}
// WithRateLimitFloor returns a new client with the specified rate-limit circuit-breaker floor.
// When remaining API quota drops below this value, Execute returns ErrRateLimitExhausted.
func (c *Client) WithRateLimitFloor(floor int) *Client {
return &Client{
APIKey: c.APIKey,
TeamID: c.TeamID,
ProjectID: c.ProjectID,
Endpoint: c.Endpoint,
HTTPClient: c.HTTPClient,
AuthMode: c.AuthMode,
TokenManager: c.TokenManager,
RateLimitFloor: floor,
rateLimitState: c.rateLimitState,
}
}
func (c *Client) circuitBreakerError() *ErrRateLimitExhausted {
if c.rateLimitState == nil {
return nil
}
c.rateLimitState.mu.Lock()
defer c.rateLimitState.mu.Unlock()
if c.rateLimitState.remaining < 0 || c.rateLimitState.remaining >= c.rateLimitFloor() {
return nil
}
if !c.rateLimitState.resetsAt.IsZero() && !time.Now().Before(c.rateLimitState.resetsAt) {
c.rateLimitState.remaining = -1
c.rateLimitState.resetsAt = time.Time{}
return nil
}
return &ErrRateLimitExhausted{
Remaining: c.rateLimitState.remaining,
Floor: c.rateLimitFloor(),
ResetsAt: c.rateLimitState.resetsAt,
}
}
func (c *Client) recordRateLimitHeaders(info RateLimitInfo) {
if c.rateLimitState == nil || info.RequestsRemaining < 0 {
return
}
c.rateLimitState.mu.Lock()
defer c.rateLimitState.mu.Unlock()
now := time.Now()
if info.RequestsReset.IsZero() || !now.Before(info.RequestsReset) || info.RequestsReset.After(now.Add(maxRateLimitResetHorizon)) {
c.rateLimitState.remaining = -1
c.rateLimitState.resetsAt = time.Time{}
return
}
c.rateLimitState.remaining = info.RequestsRemaining
c.rateLimitState.resetsAt = info.RequestsReset
}
// rateLimitFloor returns the effective circuit-breaker floor, using the
// default when the client has no explicit override.
func (c *Client) rateLimitFloor() int {
if c.RateLimitFloor > 0 {
return c.RateLimitFloor
}
return DefaultRateLimitFloor
}
// parseRetryAfter parses the Retry-After header value, which may be an
// integer number of seconds or an HTTP-date. Returns zero duration if
// the header is absent or unparseable.
//
// The integer form ("120") is tried first. For the HTTP-date form,
// http.ParseTime is used, which covers RFC 1123, RFC 850, and ANSI C
// formats as required by RFC 9110 §10.2.3.
func parseRetryAfter(value string) time.Duration {
if value == "" {
return 0
}
if seconds, err := strconv.Atoi(value); err == nil && seconds > 0 {
return time.Duration(seconds) * time.Second
}
if t, err := http.ParseTime(value); err == nil {
if delay := time.Until(t); delay > 0 {
return delay
}
}
return 0
}
// parseRateLimitHeaders extracts rate-limit metadata from HTTP response headers.
func parseRateLimitHeaders(h http.Header) RateLimitInfo {
info := RateLimitInfo{RequestsRemaining: -1}
info.RetryAfter = parseRetryAfter(h.Get("Retry-After"))
if v := h.Get("X-RateLimit-Requests-Remaining"); v != "" {
if n, err := strconv.Atoi(v); err == nil {
info.RequestsRemaining = n
}
}
if v := h.Get("X-RateLimit-Requests-Reset"); v != "" {
if milliseconds, err := strconv.ParseInt(v, 10, 64); err == nil && milliseconds > 0 {
info.RequestsReset = time.UnixMilli(milliseconds).UTC()
}
}
return info
}
// Execute sends a GraphQL request to the Linear API.
// Handles rate limiting with server-hint-aware backoff: when a 429 response
// includes a Retry-After header, that delay is preferred over the computed
// exponential backoff. A circuit breaker returns ErrRateLimitExhausted when
// remaining quota drops below the configured floor (linear.rate_limit_floor).
// OAuth clients also invalidate and retry once on 401 responses.
func (c *Client) Execute(ctx context.Context, req *GraphQLRequest) (json.RawMessage, error) {
data, statusCode, err := c.executeOnce(ctx, req)
if err == nil {
return data, nil
}
// On 401 with OAuth, invalidate token and retry once.
if statusCode == http.StatusUnauthorized && c.AuthMode == AuthModeOAuth {
debug.Logf("oauth: received 401, invalidating token and retrying")
c.TokenManager.Invalidate()
data, _, retryErr := c.executeOnce(ctx, req)
if retryErr != nil {
return nil, retryErr
}
return data, nil
}
return nil, err
}
// executeOnce performs the actual HTTP request loop with rate-limit retries.
// Returns the response data, the last HTTP status code encountered, and any error.
func (c *Client) executeOnce(ctx context.Context, req *GraphQLRequest) (json.RawMessage, int, error) {
body, err := json.Marshal(req)
if err != nil {
return nil, 0, fmt.Errorf("failed to marshal request: %w", err)
}
var lastErr error
var lastStatus int
for attempt := 0; attempt <= MaxRetries; attempt++ {
if rlErr := c.circuitBreakerError(); rlErr != nil {
return nil, lastStatus, rlErr
}
httpReq, err := http.NewRequestWithContext(ctx, "POST", c.Endpoint, bytes.NewReader(body))
if err != nil {
return nil, 0, fmt.Errorf("failed to create request: %w", err)
}
httpReq.Header.Set("Content-Type", "application/json")
authValue, err := c.authHeader()
if err != nil {
return nil, 0, err
}
httpReq.Header.Set("Authorization", authValue)
resp, err := c.HTTPClient.Do(httpReq)
if err != nil {
lastErr = fmt.Errorf("request failed (attempt %d/%d): %w", attempt+1, MaxRetries+1, err)
continue
}
respBody, err := io.ReadAll(io.LimitReader(resp.Body, MaxResponseSize))
_ = resp.Body.Close() // Best effort: HTTP body close; connection may be reused regardless
if err != nil {
lastErr = fmt.Errorf("failed to read response (attempt %d/%d): %w", attempt+1, MaxRetries+1, err)
continue
}
lastStatus = resp.StatusCode
rl := parseRateLimitHeaders(resp.Header)
c.recordRateLimitHeaders(rl)
if resp.StatusCode == http.StatusTooManyRequests {
delay := rl.RetryAfter
if delay == 0 {
delay = RetryDelay * time.Duration(1<<attempt) // Exponential backoff
if half := int64(delay / 2); half > 0 {
delay += time.Duration(rand.Int64N(half)) //nolint:gosec // G404: jitter for retry backoff does not need crypto rand
}
} else if delay > MaxRetryAfterDelay {
fmt.Fprintf(os.Stderr, "linear: Retry-After %v exceeds cap %v; using cap\n", delay, MaxRetryAfterDelay)
delay = MaxRetryAfterDelay
}
lastErr = fmt.Errorf("rate limited (attempt %d/%d), retrying after %v", attempt+1, MaxRetries+1, delay)
select {
case <-ctx.Done():
return nil, lastStatus, ctx.Err()
case <-time.After(delay):
continue
}
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return nil, lastStatus, fmt.Errorf("API error: %s (status %d)", string(respBody), resp.StatusCode)
}
var gqlResp struct {
Data json.RawMessage `json:"data"`
Errors []GraphQLError `json:"errors,omitempty"`
}
if err := json.Unmarshal(respBody, &gqlResp); err != nil {
return nil, lastStatus, fmt.Errorf("failed to parse response: %w (body: %s)", err, string(respBody))
}
if len(gqlResp.Errors) > 0 {
errMsgs := make([]string, len(gqlResp.Errors))
for i, e := range gqlResp.Errors {
errMsgs[i] = e.Message
}
return nil, lastStatus, fmt.Errorf("GraphQL errors: %s", strings.Join(errMsgs, "; "))
}
return gqlResp.Data, lastStatus, nil
}
return nil, lastStatus, fmt.Errorf("max retries (%d) exceeded: %w", MaxRetries+1, lastErr)
}
// FetchIssues retrieves issues from Linear with optional filtering by state.
// state can be: "open" (unstarted/started), "closed" (completed/canceled), or "all".
// If ProjectID is set on the client, only issues from that project are returned.
func (c *Client) FetchIssues(ctx context.Context, state string) ([]Issue, error) {
var allIssues []Issue
var cursor string
filter := map[string]interface{}{
"team": map[string]interface{}{
"id": map[string]interface{}{
"eq": c.TeamID,
},
},
}
// Add project filter if configured
if c.ProjectID != "" {
filter["project"] = map[string]interface{}{
"id": map[string]interface{}{
"eq": c.ProjectID,
},
}
}
switch state {
case "open":
filter["state"] = map[string]interface{}{
"type": map[string]interface{}{
"in": []string{"backlog", "unstarted", "started"},
},
}
case "closed":
filter["state"] = map[string]interface{}{
"type": map[string]interface{}{
"in": []string{"completed", "canceled"},
},
}
}
page := 0
for {
select {
case <-ctx.Done():
return allIssues, ctx.Err()
default:
}
page++
if page > MaxPages {
return nil, fmt.Errorf("pagination limit exceeded: stopped after %d pages", MaxPages)
}
variables := map[string]interface{}{
"filter": filter,
"first": MaxPageSize,
}
if cursor != "" {
variables["after"] = cursor
}
req := &GraphQLRequest{
Query: issuesQuery,
Variables: variables,
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to fetch issues: %w", err)
}
var issuesResp IssuesResponse
if err := json.Unmarshal(data, &issuesResp); err != nil {
return nil, fmt.Errorf("failed to parse issues response: %w", err)
}
allIssues = append(allIssues, issuesResp.Issues.Nodes...)
if !issuesResp.Issues.PageInfo.HasNextPage {
break
}
cursor = issuesResp.Issues.PageInfo.EndCursor
}
return allIssues, nil
}
// FetchIssuesSince retrieves issues from Linear that have been updated since the given time.
// This enables incremental sync by only fetching issues modified after the last sync.
// The state parameter can be: "open", "closed", or "all".
// If ProjectID is set on the client, only issues from that project are returned.
func (c *Client) FetchIssuesSince(ctx context.Context, state string, since time.Time) ([]Issue, error) {
var allIssues []Issue
var cursor string
// Build the filter with team and updatedAt constraint.
// Linear uses ISO8601 format for date comparisons.
sinceStr := since.UTC().Format(time.RFC3339)
filter := map[string]interface{}{
"team": map[string]interface{}{
"id": map[string]interface{}{
"eq": c.TeamID,
},
},
"updatedAt": map[string]interface{}{
"gte": sinceStr,
},
}
// Add project filter if configured
if c.ProjectID != "" {
filter["project"] = map[string]interface{}{
"id": map[string]interface{}{
"eq": c.ProjectID,
},
}
}
// Add state filter if specified
switch state {
case "open":
filter["state"] = map[string]interface{}{
"type": map[string]interface{}{
"in": []string{"backlog", "unstarted", "started"},
},
}
case "closed":
filter["state"] = map[string]interface{}{
"type": map[string]interface{}{
"in": []string{"completed", "canceled"},
},
}
}
page := 0
for {
select {
case <-ctx.Done():
return allIssues, ctx.Err()
default:
}
page++
if page > MaxPages {
return nil, fmt.Errorf("pagination limit exceeded: stopped after %d pages", MaxPages)
}
variables := map[string]interface{}{
"filter": filter,
"first": MaxPageSize,
}
if cursor != "" {
variables["after"] = cursor
}
req := &GraphQLRequest{
Query: issuesQuery,
Variables: variables,
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to fetch issues since %s: %w", sinceStr, err)
}
var issuesResp IssuesResponse
if err := json.Unmarshal(data, &issuesResp); err != nil {
return nil, fmt.Errorf("failed to parse issues response: %w", err)
}
allIssues = append(allIssues, issuesResp.Issues.Nodes...)
if !issuesResp.Issues.PageInfo.HasNextPage {
break
}
cursor = issuesResp.Issues.PageInfo.EndCursor
}
return allIssues, nil
}
// GetTeamStates fetches the workflow states for the configured team.
func (c *Client) GetTeamStates(ctx context.Context) ([]State, error) {
query := `
query TeamStates($teamId: String!) {
team(id: $teamId) {
id
states {
nodes {
id
name
type
}
}
}
}
`
req := &GraphQLRequest{
Query: query,
Variables: map[string]interface{}{
"teamId": c.TeamID,
},
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to fetch team states: %w", err)
}
var teamResp TeamResponse
if err := json.Unmarshal(data, &teamResp); err != nil {
return nil, fmt.Errorf("failed to parse team states response: %w", err)
}
if teamResp.Team.States == nil {
return nil, fmt.Errorf("no states found for team")
}
return teamResp.Team.States.Nodes, nil
}
// GetTeamLabels returns all issue labels defined for the team (paginated).
func (c *Client) GetTeamLabels(ctx context.Context) ([]Label, error) {
const pageSize = 250
query := `
query TeamLabels($teamId: String!, $first: Int!, $after: String) {
team(id: $teamId) {
labels(first: $first, after: $after) {
nodes {
id
name
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
`
var all []Label
var after *string
for {
vars := map[string]interface{}{
"teamId": c.TeamID,
"first": pageSize,
"after": nil,
}
if after != nil {
vars["after"] = *after
}
req := &GraphQLRequest{
Query: query,
Variables: vars,
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to fetch team labels: %w", err)
}
var page struct {
Team struct {
Labels *struct {
Nodes []Label `json:"nodes"`
PageInfo struct {
HasNextPage bool `json:"hasNextPage"`
EndCursor string `json:"endCursor"`
} `json:"pageInfo"`
} `json:"labels"`
} `json:"team"`
}
if err := json.Unmarshal(data, &page); err != nil {
return nil, fmt.Errorf("failed to parse team labels response: %w", err)
}
if page.Team.Labels == nil {
return nil, fmt.Errorf("no labels connection found for team")
}
all = append(all, page.Team.Labels.Nodes...)
if !page.Team.Labels.PageInfo.HasNextPage {
break
}
if page.Team.Labels.PageInfo.EndCursor == "" {
break
}
cursor := page.Team.Labels.PageInfo.EndCursor
after = &cursor
}
return all, nil
}
// FindIssueByDescriptionContains searches for an issue whose description
// contains the given text. This powers idempotency dedup: we embed a
// deterministic marker in the description and search for it before creating.
// Returns nil (no error) when no match is found.
func (c *Client) FindIssueByDescriptionContains(ctx context.Context, text string) (*Issue, error) {
query := `
query FindByDescription($filter: IssueFilter!) {
issues(filter: $filter, first: 1) {
nodes {
id
identifier
title
description
url
priority
state {
id
name
type
}
createdAt
updatedAt
}
}
}
`
filter := map[string]interface{}{
"team": map[string]interface{}{
"id": map[string]interface{}{
"eq": c.TeamID,
},
},
"description": map[string]interface{}{
"contains": text,
},
}
req := &GraphQLRequest{
Query: query,
Variables: map[string]interface{}{
"filter": filter,
},
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to search issues by description: %w", err)
}
var issuesResp IssuesResponse
if err := json.Unmarshal(data, &issuesResp); err != nil {
return nil, fmt.Errorf("failed to parse description search response: %w", err)
}
if len(issuesResp.Issues.Nodes) > 0 {
return &issuesResp.Issues.Nodes[0], nil
}
return nil, nil
}
// issueCreateMutation is the GraphQL mutation for creating a Linear issue.
const issueCreateMutation = `
mutation CreateIssue($input: IssueCreateInput!) {
issueCreate(input: $input) {
success
issue {
id
identifier
title
description
url
priority
state {
id
name
type
}
createdAt
updatedAt
}
}
}
`
// buildIssueCreateInput constructs the GraphQL input map for an issueCreate mutation.
func (c *Client) buildIssueCreateInput(title, description string, priority int, stateID string, labelIDs []string) map[string]interface{} {
input := map[string]interface{}{
"teamId": c.TeamID,
"title": title,
"description": description,
}
if c.ProjectID != "" {
input["projectId"] = c.ProjectID
}
if priority > 0 {
input["priority"] = priority
}
if stateID != "" {
input["stateId"] = stateID
}
if len(labelIDs) > 0 {
input["labelIds"] = labelIDs
}
return input
}
// CreateIssue creates a new issue in Linear.
func (c *Client) CreateIssue(ctx context.Context, title, description string, priority int, stateID string, labelIDs []string) (*Issue, error) {
req := &GraphQLRequest{
Query: issueCreateMutation,
Variables: map[string]interface{}{"input": c.buildIssueCreateInput(title, description, priority, stateID, labelIDs)},
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to create issue: %w", err)
}
var createResp IssueCreateResponse
if err := json.Unmarshal(data, &createResp); err != nil {
return nil, fmt.Errorf("failed to parse create response: %w", err)
}
if !createResp.IssueCreate.Success {
return nil, fmt.Errorf("issue creation reported as unsuccessful")
}
return &createResp.IssueCreate.Issue, nil
}
// createIssueSingleAttempt executes the issueCreate mutation exactly once,
// without the retry loop used by Execute. This is intentional: retrying a
// mutation that may have already reached Linear risks creating a duplicate.
// The caller (CreateIssueIdempotent) handles retry safety by re-searching for
// the idempotency marker after any failure.
func (c *Client) createIssueSingleAttempt(ctx context.Context, title, description string, priority int, stateID string, labelIDs []string) (*Issue, error) {
req := &GraphQLRequest{
Query: issueCreateMutation,
Variables: map[string]interface{}{"input": c.buildIssueCreateInput(title, description, priority, stateID, labelIDs)},
}
body, err := json.Marshal(req)
if err != nil {
return nil, fmt.Errorf("failed to marshal request: %w", err)
}
httpReq, err := http.NewRequestWithContext(ctx, "POST", c.Endpoint, bytes.NewReader(body))
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
httpReq.Header.Set("Content-Type", "application/json")
authValue, err := c.authHeader()
if err != nil {
return nil, err
}
httpReq.Header.Set("Authorization", authValue)
resp, err := c.HTTPClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
respBody, err := io.ReadAll(io.LimitReader(resp.Body, MaxResponseSize))
_ = resp.Body.Close()
if err != nil {
return nil, fmt.Errorf("failed to read response: %w", err)
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return nil, fmt.Errorf("API error: %s (status %d)", string(respBody), resp.StatusCode)
}
var gqlResp struct {
Data json.RawMessage `json:"data"`
Errors []GraphQLError `json:"errors,omitempty"`
}
if err := json.Unmarshal(respBody, &gqlResp); err != nil {
return nil, fmt.Errorf("failed to parse response: %w (body: %s)", err, string(respBody))
}
if len(gqlResp.Errors) > 0 {
errMsgs := make([]string, len(gqlResp.Errors))
for i, e := range gqlResp.Errors {
errMsgs[i] = e.Message
}
return nil, fmt.Errorf("GraphQL errors: %s", strings.Join(errMsgs, "; "))
}
var createResp IssueCreateResponse
if err := json.Unmarshal(gqlResp.Data, &createResp); err != nil {
return nil, fmt.Errorf("failed to parse create response: %w", err)
}
if !createResp.IssueCreate.Success {
return nil, fmt.Errorf("issue creation reported as unsuccessful")
}
return &createResp.IssueCreate.Issue, nil
}
// CreateIssueIdempotent creates a new Linear issue with dedup protection.
// It embeds the given idempotency marker in the description and, before
// creating, queries Linear to see if an issue with that marker already exists.
// If a match is found (e.g., from a prior interrupted sync), the existing
// issue is returned without creating a duplicate.
//
// The create is performed as a single attempt (no internal retry) to avoid the
// following race: if issueCreate reaches Linear but the HTTP response is lost
// (network timeout, connection drop), a blind retry would create a second issue
// with the same marker. Instead, after any create failure, this function
// re-searches for the marker so that the caller can safely retry the entire
// CreateIssueIdempotent call and get a consistent result.
//
// Note: concurrent creates from multiple sources (e.g., two sync processes
// running simultaneously) cannot be made fully atomic without server-side
// uniqueness enforcement, which Linear does not provide. The dedup window is
// bounded by Linear's search-index propagation delay.
func (c *Client) CreateIssueIdempotent(ctx context.Context, title, description string, priority int, stateID string, labelIDs []string, marker string) (*Issue, bool, error) {
existing, err := c.FindIssueByDescriptionContains(ctx, marker)
if err != nil {
return nil, false, fmt.Errorf("idempotency check failed: %w", err)
}
if existing != nil {
return existing, true, nil
}
description = AppendIdempotencyMarker(description, marker)
issue, err := c.createIssueSingleAttempt(ctx, title, description, priority, stateID, labelIDs)
if err != nil {
// The mutation may have reached Linear despite the error. Re-check for
// the marker so callers retrying CreateIssueIdempotent get a consistent
// result rather than creating a duplicate.
if found, searchErr := c.FindIssueByDescriptionContains(ctx, marker); searchErr == nil && found != nil {
return found, true, nil
}
return nil, false, err
}
return issue, false, nil
}
// UpdateIssue updates an existing issue in Linear.
func (c *Client) UpdateIssue(ctx context.Context, issueID string, updates map[string]interface{}) (*Issue, error) {
query := `
mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {
issueUpdate(id: $id, input: $input) {
success
issue {
id
identifier
title
description
url
priority
state {
id
name
type
}
updatedAt
}
}
}
`
req := &GraphQLRequest{
Query: query,
Variables: map[string]interface{}{
"id": issueID,
"input": updates,
},
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to update issue: %w", err)
}
var updateResp IssueUpdateResponse
if err := json.Unmarshal(data, &updateResp); err != nil {
return nil, fmt.Errorf("failed to parse update response: %w", err)
}
if !updateResp.IssueUpdate.Success {
return nil, fmt.Errorf("issue update reported as unsuccessful")
}
return &updateResp.IssueUpdate.Issue, nil
}
// BatchCreateIssues creates multiple issues in Linear using the issueBatchCreate mutation.
// Inputs are chunked into groups of BatchSize (50).
//
// On ambiguous failure (API error or success=false), this method does NOT blindly
// retry the full chunk—Linear may have partially applied the mutation. Instead it
// searches for each issue's idempotency marker (embedded in the description) to
// discover which issues were actually created, and returns an error for the rest.
func (c *Client) BatchCreateIssues(ctx context.Context, inputs []IssueCreateInput) ([]Issue, error) {
if len(inputs) == 0 {
return nil, nil
}
query := `
mutation BatchCreateIssues($input: IssueBatchCreateInput!) {
issueBatchCreate(input: $input) {
success
issues {
id
identifier
title
url
priority
state {
id
name
type
}
createdAt
updatedAt
}
}
}
`
var allIssues []Issue
for start := 0; start < len(inputs); start += BatchSize {
end := start + BatchSize
if end > len(inputs) {
end = len(inputs)
}
chunk := inputs[start:end]
req := &GraphQLRequest{
Query: query,
Variables: map[string]interface{}{
"input": map[string]interface{}{
"issues": chunk,
},
},
}
data, err := c.Execute(ctx, req)
if err != nil {
found, recoverErr := c.recoverAfterAmbiguousBatch(ctx, chunk)
if recoverErr != nil {
return allIssues, fmt.Errorf("batch create failed and recovery search also failed: %w (batch error: %v)", recoverErr, err)
}
allIssues = append(allIssues, found...)
if len(found) < len(chunk) {
return allIssues, fmt.Errorf("batch create failed; %d of %d issues unconfirmed (batch error: %v)", len(chunk)-len(found), len(chunk), err)
}
continue
}
var batchResp IssueBatchCreateResponse
if err := json.Unmarshal(data, &batchResp); err != nil {
return allIssues, fmt.Errorf("failed to parse batch create response: %w", err)
}
if !batchResp.IssueBatchCreate.Success {
found, recoverErr := c.recoverAfterAmbiguousBatch(ctx, chunk)
if recoverErr != nil {
return allIssues, fmt.Errorf("batch create unsuccessful and recovery search also failed: %w", recoverErr)
}
allIssues = append(allIssues, found...)
if len(found) < len(chunk) {
return allIssues, fmt.Errorf("batch create unsuccessful; %d of %d issues unconfirmed", len(chunk)-len(found), len(chunk))
}
continue
}
allIssues = append(allIssues, batchResp.IssueBatchCreate.Issues...)
}
return allIssues, nil
}
// recoverAfterAmbiguousBatch searches Linear for each issue in a failed batch
// chunk to determine which were actually created. It looks for the idempotency
// marker (<!-- bd-idempotency: ... -->) embedded in each input's description.
// Returns only the issues confirmed to exist in Linear.
func (c *Client) recoverAfterAmbiguousBatch(ctx context.Context, chunk []IssueCreateInput) ([]Issue, error) {
var found []Issue
for _, input := range chunk {
marker := extractIdempotencyMarker(input.Description)
if marker == "" {
continue
}
existing, err := c.FindIssueByDescriptionContains(ctx, marker)
if err != nil {
return found, fmt.Errorf("recovery search failed for %q: %w", input.Title, err)
}
if existing != nil {
found = append(found, *existing)
}
}
return found, nil
}
// extractIdempotencyMarker extracts the bd-idempotency HTML comment from a
// description string. Returns "" if no marker is found.
func extractIdempotencyMarker(description string) string {
idx := strings.Index(description, idempotencyPrefix)
if idx < 0 {
return ""
}
end := strings.Index(description[idx:], idempotencySuffix)
if end < 0 {
return ""
}
return description[idx : idx+end+len(idempotencySuffix)]
}
// BatchUpdateIssues updates multiple issues in Linear using the issueBatchUpdate mutation.
// This applies the SAME update to all specified issue IDs per call. IDs are chunked
// into groups of BatchSize (50). If a batch call fails, it falls back to per-issue
// UpdateIssue for that chunk.
func (c *Client) BatchUpdateIssues(ctx context.Context, ids []string, updates map[string]interface{}) ([]Issue, error) {
if len(ids) == 0 {
return nil, nil
}
query := `
mutation BatchUpdateIssues($ids: [UUID!]!, $input: IssueUpdateInput!) {
issueBatchUpdate(ids: $ids, input: $input) {
success
issues {
id
identifier
title
url
priority
state {
id
name
type
}
updatedAt
}
}
}
`
var allIssues []Issue
for start := 0; start < len(ids); start += BatchSize {
end := start + BatchSize
if end > len(ids) {
end = len(ids)
}
chunk := ids[start:end]
req := &GraphQLRequest{
Query: query,
Variables: map[string]interface{}{
"ids": chunk,
"input": updates,
},
}
data, err := c.Execute(ctx, req)
if err != nil {
for _, id := range chunk {
issue, updateErr := c.UpdateIssue(ctx, id, updates)
if updateErr != nil {
return allIssues, fmt.Errorf("batch update failed, single-issue fallback also failed for %s: %w (batch error: %v)", id, updateErr, err)
}
allIssues = append(allIssues, *issue)
}
continue
}
var batchResp IssueBatchUpdateResponse
if err := json.Unmarshal(data, &batchResp); err != nil {
return allIssues, fmt.Errorf("failed to parse batch update response: %w", err)
}
if !batchResp.IssueBatchUpdate.Success {
for _, id := range chunk {
issue, updateErr := c.UpdateIssue(ctx, id, updates)
if updateErr != nil {
return allIssues, fmt.Errorf("batch update unsuccessful, single-issue fallback also failed for %s: %w", id, updateErr)
}
allIssues = append(allIssues, *issue)
}
continue
}
allIssues = append(allIssues, batchResp.IssueBatchUpdate.Issues...)
}
return allIssues, nil
}
// FetchIssueByIdentifier retrieves a single issue from Linear by its identifier (e.g., "TEAM-123").
// Returns nil if the issue is not found.
func (c *Client) FetchIssueByIdentifier(ctx context.Context, identifier string) (*Issue, error) {
query := `
query IssueByIdentifier($filter: IssueFilter!) {
issues(filter: $filter, first: 1) {
nodes {
id
identifier
title
description
url
priority
state {
id
name
type
}
assignee {
id
name
email
displayName
}
labels {
nodes {
id
name
}
}
parent {
id
identifier
}
projectMilestone {
id
name
description
progress
targetDate
}
createdAt
updatedAt
completedAt
}
}
}
`
// Build filter to search by identifier number and team prefix
// Linear identifiers look like "TEAM-123", we filter by number
// and validate the full identifier in the results
variables := map[string]interface{}{
"filter": map[string]interface{}{
"team": map[string]interface{}{
"id": map[string]interface{}{
"eq": c.TeamID,
},
},
},
}
// Extract the issue number from identifier (e.g., "123" from "TEAM-123")
parts := strings.Split(identifier, "-")
if len(parts) >= 2 {
if number, err := strconv.Atoi(parts[len(parts)-1]); err == nil {
// Add number filter for more precise matching
variables["filter"].(map[string]interface{})["number"] = map[string]interface{}{
"eq": number,
}
}
}
req := &GraphQLRequest{
Query: query,
Variables: variables,
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to fetch issue by identifier: %w", err)
}
var issuesResp IssuesResponse
if err := json.Unmarshal(data, &issuesResp); err != nil {
return nil, fmt.Errorf("failed to parse issues response: %w", err)
}
// Find the exact match by identifier (in case of partial matches)
for _, issue := range issuesResp.Issues.Nodes {
if issue.Identifier == identifier {
return &issue, nil
}
}
return nil, nil // Issue not found
}
// BuildStateCache fetches and caches team states.
func BuildStateCache(ctx context.Context, client *Client) (*StateCache, error) {
states, err := client.GetTeamStates(ctx)
if err != nil {
return nil, err
}
cache := &StateCache{
States: states,
StatesByID: make(map[string]State),
}
for _, s := range states {
cache.StatesByID[s.ID] = s
if cache.OpenStateID == "" && (s.Type == "unstarted" || s.Type == "backlog") {
cache.OpenStateID = s.ID
}
}
return cache, nil
}
// FindStateForBeadsStatus returns the best Linear state ID for a Beads status.
func (sc *StateCache) FindStateForBeadsStatus(status types.Status) string {
targetType := StatusToLinearStateType(status)
for _, s := range sc.States {
if s.Type == targetType {
return s.ID
}
}
if len(sc.States) > 0 {
return sc.States[0].ID
}
return ""
}
// ExtractLinearIdentifier extracts the Linear issue identifier (e.g., "TEAM-123") from a Linear URL.
func ExtractLinearIdentifier(url string) string {
// Linear URLs look like: https://linear.app/team/issue/TEAM-123/title
// We want to extract "TEAM-123"
parts := strings.Split(url, "/")
for i, part := range parts {
if part == "issue" && i+1 < len(parts) {
return parts[i+1]
}
}
return ""
}
// CanonicalizeLinearExternalRef returns a stable Linear issue URL without the slug.
// Example: https://linear.app/team/issue/TEAM-123/title -> https://linear.app/team/issue/TEAM-123
// Returns ok=false if the URL isn't a recognizable Linear issue URL.
func CanonicalizeLinearExternalRef(externalRef string) (canonical string, ok bool) {
if externalRef == "" || !IsLinearExternalRef(externalRef) {
return "", false
}
parsed, err := url.Parse(externalRef)
if err != nil || parsed.Scheme == "" || parsed.Host == "" {
return "", false
}
segments := strings.Split(parsed.Path, "/")
for i, segment := range segments {
if segment == "issue" && i+1 < len(segments) && segments[i+1] != "" {
path := "/" + strings.Join(segments[1:i+2], "/")
return fmt.Sprintf("%s://%s%s", parsed.Scheme, parsed.Host, path), true
}
}
return "", false
}
// IsLinearExternalRef checks if an external_ref URL is a Linear issue URL.
func IsLinearExternalRef(externalRef string) bool {
return strings.Contains(externalRef, "linear.app/") && strings.Contains(externalRef, "/issue/")
}
// FetchTeams retrieves all teams accessible with the current API key.
// This is useful for discovering the team ID needed for configuration.
func (c *Client) FetchTeams(ctx context.Context) ([]Team, error) {
query := `
query {
teams {
nodes {
id
name
key
}
}
}
`
req := &GraphQLRequest{
Query: query,
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to fetch teams: %w", err)
}
var teamsResp TeamsResponse
if err := json.Unmarshal(data, &teamsResp); err != nil {
return nil, fmt.Errorf("failed to parse teams response: %w", err)
}
return teamsResp.Teams.Nodes, nil
}
// FetchProjects retrieves projects from Linear with optional filtering by state.
// state can be: "planned", "started", "paused", "completed", "canceled", or "all"/"".
func (c *Client) FetchProjects(ctx context.Context, state string) ([]Project, error) {
var allProjects []Project
var cursor string
filter := map[string]interface{}{
"team": map[string]interface{}{
"id": map[string]interface{}{
"eq": c.TeamID,
},
},
}
if state != "all" && state != "" {
filter["state"] = map[string]interface{}{
"eq": state,
}
}
for {
variables := map[string]interface{}{
"filter": filter,
"first": MaxPageSize,
}
if cursor != "" {
variables["after"] = cursor
}
req := &GraphQLRequest{
Query: projectsQuery,
Variables: variables,
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to fetch projects: %w", err)
}
var projectsResp ProjectsResponse
if err := json.Unmarshal(data, &projectsResp); err != nil {
return nil, fmt.Errorf("failed to parse projects response: %w", err)
}
allProjects = append(allProjects, projectsResp.Projects.Nodes...)
if !projectsResp.Projects.PageInfo.HasNextPage {
break
}
cursor = projectsResp.Projects.PageInfo.EndCursor
}
return allProjects, nil
}
// CreateProject creates a new project in Linear.
func (c *Client) CreateProject(ctx context.Context, name, description, state string) (*Project, error) {
query := `
mutation CreateProject($input: ProjectCreateInput!) {
projectCreate(input: $input) {
success
project {
id
name
description
slugId
url
state
progress
createdAt
updatedAt
}
}
}
`
input := map[string]interface{}{
"teamIds": []string{c.TeamID},
"name": name,
"description": description,
}
if state != "" {
input["state"] = state
}
req := &GraphQLRequest{
Query: query,
Variables: map[string]interface{}{
"input": input,
},
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to create project: %w", err)
}
var createResp ProjectCreateResponse
if err := json.Unmarshal(data, &createResp); err != nil {
return nil, fmt.Errorf("failed to parse create project response: %w", err)
}
if !createResp.ProjectCreate.Success {
return nil, fmt.Errorf("project creation reported as unsuccessful")
}
return &createResp.ProjectCreate.Project, nil
}
// UpdateProject updates an existing project in Linear.
func (c *Client) UpdateProject(ctx context.Context, projectID string, updates map[string]interface{}) (*Project, error) {
query := `
mutation UpdateProject($id: String!, $input: ProjectUpdateInput!) {
projectUpdate(id: $id, input: $input) {
success
project {
id
name
description
slugId
url
state
progress
updatedAt
}
}
}
`
req := &GraphQLRequest{
Query: query,
Variables: map[string]interface{}{
"id": projectID,
"input": updates,
},
}
data, err := c.Execute(ctx, req)
if err != nil {
return nil, fmt.Errorf("failed to update project: %w", err)
}
var updateResp ProjectUpdateResponse
if err := json.Unmarshal(data, &updateResp); err != nil {
return nil, fmt.Errorf("failed to parse update project response: %w", err)
}
if !updateResp.ProjectUpdate.Success {
return nil, fmt.Errorf("project update reported as unsuccessful")
}
return &updateResp.ProjectUpdate.Project, nil
}