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 ¶
- Variables
- func Auth(prefix string) error
- func AuthFromStatus(status int, prefix string) error
- func Do(ctx context.Context, cfg Config, method, path string, payload []byte, ...) (int, []byte, error)
- func DoRaw(ctx context.Context, cfg Config, method, path string, payload []byte, ...) (int, []byte, error)
- func Snippet(b []byte) string
- type AuthError
- type Config
- type Meter
- type RejectedCredential
- type Usage
Constants ¶
This section is empty.
Variables ¶
var ErrAuth = errors.New("credential rejected")
ErrAuth is the shared identity for a rejected Atlassian credential (HTTP 401 or 403). Client packages keep named wrappers (jira.ErrAuth, confluence.ErrAuth) so existing errors.Is call sites keep compiling; those wrappers unwrap to this sentinel.
DoRaw never returns this: a completed HTTP response is status+body. JSON call helpers use Do, which classifies 401/403 here so a new client inherits the identity by using the transport.
Functions ¶
func Auth ¶ added in v0.14.1
Auth returns a rejected-credential error named by prefix (Config.ErrPrefix: "jira", "confluence", …).
func AuthFromStatus ¶ added in v0.14.1
AuthFromStatus returns Auth(prefix) for 401/403, nil otherwise.
func Do ¶ added in v0.14.1
func Do(ctx context.Context, cfg Config, method, path string, payload []byte, hasBody, mutating bool) (int, []byte, error)
Do is DoRaw plus 401/403 classification. JSON call helpers use this so a new client inherits rejected-credential identity. Raw keeps DoRaw: a completed response is never an error there.
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. JSON call helpers use Do, which classifies 401/403 as ErrAuth; Raw stays here.
Types ¶
type AuthError ¶ added in v0.14.1
type AuthError struct {
Prefix string
}
AuthError names which connector's credential died. Error() is "<prefix>: credential rejected" so last_error distinguishes sources. Unwrap returns ErrAuth so errors.Is(err, ErrAuth) is true for every client.
func (AuthError) RejectedCredential ¶ added in v0.14.1
func (e AuthError) RejectedCredential()
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 RejectedCredential ¶ added in v0.14.1
type RejectedCredential interface {
RejectedCredential()
}
RejectedCredential is the marker Watch keys on. A source that is not built on this package can still implement the method; Do-produced errors implement it too.
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