Documentation
¶
Overview ¶
Package apidocs is a shared fetcher for the GitLab API reference docs (the doc/api/<area>.md files in the gitlab-org/gitlab monorepo) used as a source of truth alongside the client-go SDK by the audit utilities.
Docs are cached on disk in a single shared, gitignored directory (.cache/gitlab-api-docs/ under the repo root). A cached doc is reused while it is younger than MaxAge (7 days by default); older or missing docs are re-downloaded. Callers can force a full refresh or pin to offline (cached only). Downloads are polite: a server Retry-After is honored, otherwise exponential backoff with jitter is used, and successful fetches are spaced so a full sweep does not trip GitLab's raw rate limiter.
Index ¶
Constants ¶
const ( // DefaultBaseURL is the raw GitLab API reference doc root. Each area maps to // <DefaultBaseURL><area>.md. DefaultBaseURL = "https://gitlab.com/gitlab-org/gitlab/-/raw/master/doc/api/" // DefaultUserDocBaseURL is the raw doc root one level above the API // reference. Some endpoint families carry their only licensing-tier badge on // a user-facing page (e.g. merge request dependencies), so tier auditors need // to fetch pages relative to doc/ as well as doc/api/. DefaultUserDocBaseURL = "https://gitlab.com/gitlab-org/gitlab/-/raw/master/doc/" // DefaultMaxAge is how long a cached doc is considered fresh before a // re-download is attempted. DefaultMaxAge = 7 * 24 * time.Hour )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Fetcher ¶
type Fetcher struct {
// contains filtered or unexported fields
}
Fetcher downloads and caches GitLab API reference docs. The zero value is not usable; construct one with New so defaults are applied.
func (*Fetcher) Fetch ¶
Fetch returns the markdown for one doc area (e.g. "branches"). It serves a cached copy when present and fresh (younger than MaxAge) unless Refresh is set; otherwise it downloads, caches, and returns the doc. In Offline mode it returns the cached copy at any age and never downloads. The context cancels an in-flight download and aborts the retry backoff.
type Options ¶
type Options struct {
// Refresh forces a re-download even when the cached copy is still fresh.
Refresh bool
// Offline never hits the network: cached docs are returned regardless of
// age, and a cache miss is an error.
Offline bool
// Strict disables the stale-cache fallback: when a download fails (e.g. an
// upstream 404/410 removal), the error is returned instead of serving an
// older cached copy. Authoritative callers such as -validate-docs set this
// so a deleted doc is not masked by a previously cached body.
Strict bool
// MaxAge overrides the freshness window; 0 uses DefaultMaxAge.
MaxAge time.Duration
// BaseURL overrides the doc root (used by tests); empty uses DefaultBaseURL.
BaseURL string
// CacheDir overrides the on-disk cache location; empty uses the shared
// CacheDir(repoRoot). Useful for tests and callers that want an isolated cache.
CacheDir string
// Client overrides the HTTP client; nil uses a 30s-timeout default.
Client *http.Client
}
Options configures a Fetcher.
Source Files