Documentation
¶
Overview ¶
Package atlhttp is the shared HTTP transport for Atlassian Cloud clients (Jira, Confluence): path safety, Authorization host pinning, and the Do/DoRaw loop. Retryable statuses, backoff plus Retry-After, the error snippet, the 64 MiB body cap, and Usage/Meter live in httppolicy so a non-Atlassian connector can share that policy without importing this package.
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 = httppolicy.Meter
Meter holds atomic counters shared by concurrent DoRaw goroutines.
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 = httppolicy.Usage
Usage is the host-neutral HTTP usage snapshot. The struct lives in httppolicy so Linear reports the same type without importing this package (path joining / Authorization host pinning stay here).
Callers (jira.Usage, confluence.Usage, sync.usageTaker, store.api_usage) keep using this name.
Source Files