Documentation
¶
Overview ¶
Package atlhttp is the shared HTTP transport for Atlassian Cloud clients (Jira, Confluence): retries, backoff, path safety, and optional usage meters.
The token lives only in the Authorization header. It is never put in an error, a log line or a URL (constitution article 8), which is why DoRaw reports the method and path but never the request itself.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DoRaw ¶
func DoRaw(ctx context.Context, cfg Config, method, path string, payload []byte, hasBody, mutating bool) (int, []byte, error)
DoRaw is the single HTTP path for JSON call helpers and Raw: retries, backoff, and optional usage. Path must be site-relative (leading "/"); absolute URLs and scheme-relative paths are rejected so the Authorization header never leaves the configured site. mutating selects the write retry policy (429/503 only).
A completed HTTP response always returns err == nil with the status and body (including non-2xx). err is reserved for transport failures and bad paths.
Types ¶
type Config ¶
type Config struct {
// Base is the site (or wiki) origin with no trailing slash.
Base string
// Auth is the full Authorization header value (e.g. "Basic …").
Auth string
// HTTP is the client used for each attempt; nil is a programming error.
HTTP *http.Client
// Retries is the total number of attempts per request; Backoff is the first
// wait, doubling per attempt and capped at 30 s.
Retries int
Backoff time.Duration
// ErrPrefix labels resolve errors ("jira" → "jira: bad site URL").
ErrPrefix string
// Usage, when non-nil, records every attempt that left the process.
Usage *Meter
}
Config is the per-request transport configuration. Callers pass live client fields so tests can mutate HTTP/Retries/Backoff after construction.
type Meter ¶
type Meter struct {
// contains filtered or unexported fields
}
Meter holds atomic counters shared by concurrent DoRaw goroutines. A Client is used from up to 4 concurrent sync workers (contracts/sync.md).
func (*Meter) Take ¶
Take returns the current counters and zeroes the numeric fields so a flusher can accumulate into daily totals without double-counting.
LastThrottledAt is a timestamp, not a counter: it is included in the snapshot but is NOT cleared. The in-process "last 429" stays visible until the process exits or a later 429 overwrites it.
type Usage ¶
type Usage struct {
Requests int64
Throttled int64 // 429 responses
ServerErrors int64 // 5xx responses, excluding 429
Retries int64 // attempts re-sent after a wait
WaitMS int64 // milliseconds actually spent in wait()
LastThrottledAt time.Time // UTC; zero if never throttled
}
Usage is a point-in-time snapshot of outbound Atlassian HTTP traffic. Counters are process-local until a caller persists them (see store.api_usage).
Requests counts every HTTP attempt, including retries: that is the unit that draws from the site's rate budget. This is our own call volume, not the remaining point pool — the site does not expose that.
Source Files