Documentation
¶
Overview ¶
Package esi talks to CCP's EVE Swagger Interface.
Every call runs the same pipeline in-process — cache, pause check, error budget, singleflight, rate limit, sequential lock, HTTP — with Redis as the shared substrate, so a dozen workers behave as one client against ESI's per-application budget.
The thing to understand about ESI is that it polices two separate budgets. The rate limit is per endpoint family and is what the token bucket tracks. The *error* limit is global: exceed it and every endpoint returns 420 for a minute, whichever one you were abusing. That is why a 420 pauses the whole client rather than only the group that earned it.
Index ¶
- Constants
- Variables
- func KillmailPath(killmailID int64, hash string) string
- func ParseExpires(header string) (int64, bool)
- func PathPrefix(rawURL string) string
- func UserAgent(cfg *config.Config) string
- type Affiliation
- type Alliance
- type AllianceHistoryEntry
- type BucketState
- type Cache
- type Character
- type Client
- type Coordination
- func (c *Coordination) AcquireSequential(ctx context.Context, group string) (string, error)
- func (c *Coordination) ReleaseClaim(ctx context.Context, url, token string)
- func (c *Coordination) ReleaseSequential(ctx context.Context, group, token string)
- func (c *Coordination) TryClaim(ctx context.Context, url string) (string, error)
- func (c *Coordination) WaitForClaim(ctx context.Context, url string) bool
- type Corporation
- type CorporationHistoryEntry
- type Entry
- type FwLeaderboard
- type FwLeaderboardEntry
- type FwStats
- type FwSystem
- type FwWar
- type Group
- type RateLimiter
- func (r *RateLimiter) Acquire(ctx context.Context, g Group, cost int) (time.Duration, error)
- func (r *RateLimiter) ApplyHeaders(ctx context.Context, g Group, remaining int, resetAfter time.Duration) error
- func (r *RateLimiter) ApplyRemaining(ctx context.Context, g Group, remaining int) error
- func (r *RateLimiter) Peek(ctx context.Context, g Group) (BucketState, error)
- type Response
- func FetchAffiliations(ctx context.Context, c *Client, characterIDs []int32) (Response[[]Affiliation], error)
- func FetchAlliance(ctx context.Context, c *Client, id int32) (Response[Alliance], error)
- func FetchAllianceCorporations(ctx context.Context, c *Client, id int32) (Response[[]int32], error)
- func FetchAllianceList(ctx context.Context, c *Client) (Response[[]int32], error)
- func FetchCharacter(ctx context.Context, c *Client, id int32) (Response[Character], error)
- func FetchCharacterCorporationHistory(ctx context.Context, c *Client, id int32) (Response[[]CorporationHistoryEntry], error)
- func FetchCorporation(ctx context.Context, c *Client, id int32) (Response[Corporation], error)
- func FetchCorporationAllianceHistory(ctx context.Context, c *Client, id int32) (Response[[]AllianceHistoryEntry], error)
- func FetchFwLeaderboards(ctx context.Context, c *Client) (Response[FwLeaderboard], error)
- func FetchFwLeaderboardsCharacters(ctx context.Context, c *Client) (Response[FwLeaderboard], error)
- func FetchFwLeaderboardsCorporations(ctx context.Context, c *Client) (Response[FwLeaderboard], error)
- func FetchFwStats(ctx context.Context, c *Client) (Response[[]FwStats], error)
- func FetchFwSystems(ctx context.Context, c *Client) (Response[[]FwSystem], error)
- func FetchFwWars(ctx context.Context, c *Client) (Response[[]FwWar], error)
- func FetchStatus(ctx context.Context, c *Client) (Response[Status], error)
- func FetchWar(ctx context.Context, c *Client, id int32) (Response[War], error)
- func FetchWarKillmails(ctx context.Context, c *Client, warID int32, page int) (Response[[]WarKillmailRef], error)
- func FetchWarList(ctx context.Context, c *Client, maxWarID int32) (Response[[]int32], error)
- func Get[T any](ctx context.Context, c *Client, path string) (Response[T], error)
- func GetAllPages[T any](ctx context.Context, c *Client, path string, accessToken string) ([]T, Response[[]T], error)
- func GetAuthenticated[T any](ctx context.Context, c *Client, path, accessToken string) (Response[T], error)
- func Post[T any](ctx context.Context, c *Client, path string, body any) (Response[T], error)
- type Status
- type War
- type WarKillmailRef
- type WarSide
Constants ¶
const DefaultBaseURL = "https://esi.evetech.net"
DefaultBaseURL matches ESI_BASE in the TypeScript client.
const TokenCost = 2
TokenCost is what one request draws. Two rather than one, so that a group's nominal limit is reached at half the request count: headroom for the requests already in flight when a header snapshot was taken.
Variables ¶
var Groups = map[string]Group{ "status": { Name: "status", PathPrefix: "status", Limit: 600, Window: 900, HeaderAuthoritative: true, }, "characters": { Name: "characters", PathPrefix: "characters", Limit: 300, Window: 60, HeaderAuthoritative: true, }, "corporations": { Name: "corporations", PathPrefix: "corporations", Limit: 300, Window: 60, HeaderAuthoritative: true, }, "alliances": { Name: "alliances", PathPrefix: "alliances", Limit: 300, Window: 60, HeaderAuthoritative: true, }, "killmail": { Name: "killmail", PathPrefix: "killmails", Limit: 3600, Window: 900, HeaderAuthoritative: true, }, "characters-corporationhistory": { Name: "characters-corporationhistory", PathPrefix: "characters-corporationhistory", Limit: 60, Window: 60, Sequential: true, }, "corporations-alliancehistory": { Name: "corporations-alliancehistory", PathPrefix: "corporations-alliancehistory", Limit: 60, Window: 60, Sequential: true, }, "characters-affiliation": { Name: "characters-affiliation", PathPrefix: "characters-affiliation", Limit: 60, Window: 60, Sequential: true, }, "wars": { Name: "wars", PathPrefix: "wars", Limit: 60, Window: 60, Sequential: true, }, "fw": { Name: "fw", PathPrefix: "fw", Limit: 150, Window: 900, Sequential: true, }, }
Groups is the registry, keyed by name.
var Probation = Group{ Name: "probation", PathPrefix: "", Limit: 10, Window: 60, Sequential: true, }
Probation catches anything unrecognised: slow, serialised, header-distrusting.
An unknown endpoint is one whose limits nobody has measured, so it gets the treatment that cannot cause harm. Promoting it means adding a Groups entry after watching how it actually behaves under load.
Functions ¶
func KillmailPath ¶
KillmailPath builds the public killmail route.
The trailing slash is not decoration: ESI redirects without it, and a redirect on every killmail doubles the request count against the error limit.
func ParseExpires ¶
ParseExpires reads an HTTP Expires header into unix milliseconds, returning false when it is missing or unparseable.
func PathPrefix ¶
PathPrefix normalises an ESI path for classification: version segments, numeric IDs and hashes are dropped, and what remains is joined with dashes.
/latest/characters/12345/ → characters /latest/characters/12345/corporationhistory/ → characters-corporationhistory /latest/killmails/99/aabbcc.../ → killmails
Types ¶
type Affiliation ¶
type Affiliation struct {
CharacterID int32 `json:"character_id"`
CorporationID int32 `json:"corporation_id"`
AllianceID int32 `json:"alliance_id"`
FactionID int32 `json:"faction_id"`
}
Affiliation is one entry from the bulk affiliation lookup.
type Alliance ¶
type Alliance struct {
Name string `json:"name"`
Ticker string `json:"ticker"`
CreatorID int32 `json:"creator_id"`
CreatorCorporationID int32 `json:"creator_corporation_id"`
ExecutorCorporationID int32 `json:"executor_corporation_id"`
DateFounded string `json:"date_founded"`
FactionID int32 `json:"faction_id"`
}
Alliance is /alliances/{id}/.
type AllianceHistoryEntry ¶
type AllianceHistoryEntry struct {
RecordID int32 `json:"record_id"`
AllianceID int32 `json:"alliance_id"`
StartDate string `json:"start_date"`
IsDeleted bool `json:"is_deleted"`
}
AllianceHistoryEntry is one row of a corporation's alliance history.
AllianceID is zero for the stretches a corporation was in no alliance, which are real history rather than gaps.
type BucketState ¶
type BucketState struct {
Group string `json:"group"`
Remaining int `json:"remaining"`
Limit int `json:"limit"`
ResetAt time.Time `json:"reset_at"`
Seeded bool `json:"seeded"`
}
BucketState is a group's live budget, for diagnostics.
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is the two-tier response cache. Safe for concurrent use.
func (*Cache) Get ¶
Get returns whatever is known about a URL, fresh or not. A stale entry is still returned so the caller can use its ETag.
type Character ¶
type Character struct {
Name string `json:"name"`
Description string `json:"description"`
Birthday string `json:"birthday"`
Gender string `json:"gender"`
RaceID int32 `json:"race_id"`
BloodlineID int32 `json:"bloodline_id"`
SecurityStatus float64 `json:"security_status"`
Title string `json:"title"`
CorporationID int32 `json:"corporation_id"`
AllianceID int32 `json:"alliance_id"`
FactionID int32 `json:"faction_id"`
}
Character is /characters/{id}/.
type Client ¶
type Client struct {
BaseURL string
UserAgent string
HTTP *http.Client
// contains filtered or unexported fields
}
Client is the full ESI client. Safe for concurrent use.
func NewForTest ¶
NewForTest builds a client against dependencies the caller supplies.
Exported because the packages that sit on top of this one need a real pipeline — real bucket, real singleflight — pointed at a fake ESI, and the fields that would take are unexported. It does not adopt the Redis clients: Close leaves them open for whoever created them.
func (*Client) Close ¶
func (c *Client) Close()
Close releases the Redis connections the client opened.
func (*Client) Limiter ¶
func (c *Client) Limiter() *RateLimiter
Limiter exposes the rate limiter for diagnostics.
type Coordination ¶
type Coordination struct {
// contains filtered or unexported fields
}
Coordination provides the singleflight and sequential primitives.
func NewCoordination ¶
func NewCoordination(client *redis.Client) *Coordination
NewCoordination builds it over the coordination instance.
func (*Coordination) AcquireSequential ¶
AcquireSequential waits in line for a group's mutex. An empty token means the wait timed out.
func (*Coordination) ReleaseClaim ¶
func (c *Coordination) ReleaseClaim(ctx context.Context, url, token string)
ReleaseClaim gives up ownership. Failing to release is not worth surfacing: the TTL cleans up regardless, and the caller is usually already unwinding from a more interesting error.
func (*Coordination) ReleaseSequential ¶
func (c *Coordination) ReleaseSequential(ctx context.Context, group, token string)
ReleaseSequential hands the group's mutex to the next waiter.
func (*Coordination) TryClaim ¶
TryClaim attempts to become the one worker fetching url. An empty token means somebody else already is.
func (*Coordination) WaitForClaim ¶
func (c *Coordination) WaitForClaim(ctx context.Context, url string) bool
WaitForClaim blocks until the current holder finishes or its claim expires. A false return means the wait timed out; the caller should try the request itself rather than assume the cache was filled.
type Corporation ¶
type Corporation struct {
Name string `json:"name"`
Ticker string `json:"ticker"`
Description string `json:"description"`
DateFounded string `json:"date_founded"`
URL string `json:"url"`
CEOID int32 `json:"ceo_id"` // omitted for closed corporations on 2026-07-21+
CreatorID int32 `json:"creator_id"`
HomeStationID int32 `json:"home_station_id"`
AllianceID int32 `json:"alliance_id"`
MemberCount int32 `json:"member_count"`
WarEligible *bool `json:"war_eligible"`
State string `json:"state"`
Type string `json:"type"`
FriendlyFire string `json:"friendly_fire"`
// FactionID is the pre-2026-07-21 name; EnlistedFactionID replaced it.
FactionID int32 `json:"faction_id"`
EnlistedFactionID int32 `json:"enlisted_faction_id"`
// TaxRate is a fraction 0–1; TaxRates are percentages 0–100. Read them
// through TaxRateFraction rather than directly.
TaxRate *float64 `json:"tax_rate"`
TaxRates *struct {
ISK float64 `json:"isk"`
LoyaltyPoint float64 `json:"loyalty_point"`
} `json:"tax_rates"`
Palette map[string]any `json:"palette"`
}
Corporation is /corporations/{id}/.
The shape straddles a schema change CCP made on 2026-07-21, and both forms have to be understood because the compatibility date rolls forward on its own. Corporation() pins the newer one; the older fields stay decodable so a cached body written before the change still parses.
func (Corporation) Faction ¶
func (c Corporation) Faction() int32
Faction resolves whichever of the two faction fields is populated.
func (Corporation) LoyaltyPointTaxFraction ¶
func (c Corporation) LoyaltyPointTaxFraction() *float64
LoyaltyPointTaxFraction is nil before the 2026-07-21 shape, which had no such field — distinct from a corporation that taxes loyalty points at zero.
func (Corporation) TaxRateFraction ¶
func (c Corporation) TaxRateFraction() float64
TaxRateFraction normalises both spellings onto the 0–1 fraction the database stores. Mixing the two would show a 10% corporation as taxing 1000%.
type CorporationHistoryEntry ¶
type CorporationHistoryEntry struct {
RecordID int32 `json:"record_id"`
CorporationID int32 `json:"corporation_id"`
StartDate string `json:"start_date"`
IsDeleted bool `json:"is_deleted"`
}
CorporationHistoryEntry is one row of a character's corporation history.
type Entry ¶
type Entry struct {
Data json.RawMessage `json:"data"`
Status int `json:"status"`
Expires int64 `json:"expires"` // unix ms
ETag string `json:"etag,omitempty"`
}
Entry is one cached response.
type FwLeaderboard ¶
type FwLeaderboard struct {
Kills struct {
Yesterday []FwLeaderboardEntry `json:"yesterday"`
LastWeek []FwLeaderboardEntry `json:"last_week"`
ActiveTotal []FwLeaderboardEntry `json:"active_total"`
} `json:"kills"`
VictoryPoints struct {
Yesterday []FwLeaderboardEntry `json:"yesterday"`
LastWeek []FwLeaderboardEntry `json:"last_week"`
ActiveTotal []FwLeaderboardEntry `json:"active_total"`
} `json:"victory_points"`
}
FwLeaderboard is the kills/victory-points ranking triplet.
type FwLeaderboardEntry ¶
type FwLeaderboardEntry struct {
Amount int32 `json:"amount"`
FactionID int32 `json:"faction_id"`
CharacterID int32 `json:"character_id"`
CorporationID int32 `json:"corporation_id"`
}
FwLeaderboardEntry is one ranked row.
type FwStats ¶
type FwStats struct {
FactionID int32 `json:"faction_id"`
Pilots int32 `json:"pilots"`
SystemsControlled int32 `json:"systems_controlled"`
Kills struct {
Yesterday int32 `json:"yesterday"`
LastWeek int32 `json:"last_week"`
Total int32 `json:"total"`
} `json:"kills"`
VictoryPoints struct {
Yesterday int32 `json:"yesterday"`
LastWeek int32 `json:"last_week"`
Total int32 `json:"total"`
} `json:"victory_points"`
}
FwStats is one faction's standing.
type FwSystem ¶
type FwSystem struct {
SolarSystemID int32 `json:"solar_system_id"`
OwnerFactionID int32 `json:"owner_faction_id"`
OccupierFactionID int32 `json:"occupier_faction_id"`
Contested string `json:"contested"`
VictoryPoints int32 `json:"victory_points"`
VictoryPointsThreshold int32 `json:"victory_points_threshold"`
}
FwSystem is one contested system.
type Group ¶
type Group struct {
// Name keys the group's Redis state.
Name string
// PathPrefix is the normalised path this group claims.
PathPrefix string
// Limit and Window are the preset budget. They seed Redis on first use and
// remain the fallback whenever headers are absent.
Limit int
Window int // seconds
// HeaderAuthoritative marks a family where ESI reports its own accounting
// and learned values should overwrite the preset. False means ignore any
// headers and trust the preset.
HeaderAuthoritative bool
// Sequential forces one request at a time across the whole cluster. Some
// families return 420 under a concurrent burst even while the token bucket
// still has capacity, so pacing alone is not enough.
Sequential bool
}
Group is one endpoint family's budget and dispatch rules.
func ResolveGroup ¶
ResolveGroup classifies a URL or path into a group.
Longer prefixes are tried first, so `characters-corporationhistory` wins over `characters` — they have very different budgets and getting that backwards would burst an endpoint that 420s on contact.
type RateLimiter ¶
type RateLimiter struct {
// contains filtered or unexported fields
}
RateLimiter paces requests against a group's budget.
func NewRateLimiter ¶
func NewRateLimiter(client *redis.Client) *RateLimiter
NewRateLimiter builds a limiter over the coordination instance.
func (*RateLimiter) Acquire ¶
Acquire draws cost tokens, returning how long to wait when the bucket is dry. A zero duration means the caller may proceed.
func (*RateLimiter) ApplyHeaders ¶
func (r *RateLimiter) ApplyHeaders(ctx context.Context, g Group, remaining int, resetAfter time.Duration) error
ApplyHeaders merges what a response reported, for groups where ESI's own accounting is authoritative. A no-op for the hand-built groups: their headers do not exist, and pretending otherwise would overwrite a preset with noise.
func (*RateLimiter) ApplyRemaining ¶
ApplyRemaining updates only the counter, for responses that report remaining without a reset.
/killmails/{id}/{hash}/ does exactly that — group, limit, remaining and used, but no reset timestamp. Without this path the local bucket drains to zero with no feedback and then blocks every killmail until the window rolls over on its own.
func (*RateLimiter) Peek ¶
func (r *RateLimiter) Peek(ctx context.Context, g Group) (BucketState, error)
Peek reads a group's bucket without touching it. Seeded is false when the bucket has never been used, which reads as "full" rather than "empty".
type Response ¶
type Response[T any] struct { Data *T `json:"data"` Status int `json:"status"` Group string `json:"group,omitempty"` // RetryAfter is set on 420 and 429, in seconds. RetryAfter int `json:"retry_after,omitempty"` // Pages is the x-pages header, for endpoints that paginate. Pages int `json:"pages,omitempty"` // Cached reports that the body came from cache without touching ESI. Cached bool `json:"cached,omitempty"` }
Response is the outcome of a request.
Status 0 means the request never reached ESI — every retry was exhausted, or the pipeline gave up waiting. Callers must treat it as retryable rather than as a 4xx.
func FetchAffiliations ¶
func FetchAffiliations(ctx context.Context, c *Client, characterIDs []int32) (Response[[]Affiliation], error)
FetchAffiliations resolves many characters' corporation and alliance at once.
A POST because the id list would not fit in a URL, but a read: it is the cheapest way to notice that a thousand characters changed corp, at one request instead of a thousand.
func FetchAlliance ¶
FetchAlliance reads one alliance.
func FetchAllianceCorporations ¶
FetchAllianceCorporations reads an alliance's member corporations.
func FetchAllianceList ¶
FetchAllianceList reads every alliance id in the game.
func FetchCharacter ¶
FetchCharacter reads one character's public profile.
func FetchCharacterCorporationHistory ¶
func FetchCharacterCorporationHistory(ctx context.Context, c *Client, id int32) (Response[[]CorporationHistoryEntry], error)
FetchCharacterCorporationHistory reads every corporation a character has been in.
func FetchCorporation ¶
FetchCorporation reads one corporation.
The compatibility date is pinned per-request rather than left to the client's rolling header, because this endpoint's newer shape carries fields the older one does not — palette, tax_rates, state, type, friendly_fire — and the database has columns for them. Removable once the rolling date passes 2026-07-21 on its own.
func FetchCorporationAllianceHistory ¶
func FetchCorporationAllianceHistory(ctx context.Context, c *Client, id int32) (Response[[]AllianceHistoryEntry], error)
FetchCorporationAllianceHistory reads every alliance a corporation has been in.
func FetchFwLeaderboards ¶
FetchFwLeaderboards reads the faction leaderboard.
func FetchFwLeaderboardsCharacters ¶
FetchFwLeaderboardsCharacters reads the character leaderboard.
func FetchFwLeaderboardsCorporations ¶
func FetchFwLeaderboardsCorporations(ctx context.Context, c *Client) (Response[FwLeaderboard], error)
FetchFwLeaderboardsCorporations reads the corporation leaderboard.
func FetchFwStats ¶
FetchFwStats reads per-faction standings.
func FetchFwSystems ¶
FetchFwSystems reads every contested system.
func FetchFwWars ¶
FetchFwWars reads the faction pairings.
func FetchStatus ¶
FetchStatus reads the state of Tranquility.
It deliberately bypasses the ordinary ESI pause, cache, and limiter. This is the probe that decides whether those mechanisms should be paused, so making it obey their current state would prevent it from ever observing recovery.
func FetchWarKillmails ¶
func FetchWarKillmails(ctx context.Context, c *Client, warID int32, page int) (Response[[]WarKillmailRef], error)
FetchWarKillmails reads one page of a war's killmail references.
func FetchWarList ¶
FetchWarList reads war ids, newest first. maxWarID pages backwards through history; zero starts at the most recent.
func GetAllPages ¶
func GetAllPages[T any](ctx context.Context, c *Client, path string, accessToken string) ([]T, Response[[]T], error)
GetAllPages walks a paginated endpoint to the end and returns the whole list.
Partial results are returned alongside a failure rather than discarded: for a killmail backfill, nine pages of history is worth keeping even when the tenth times out, and the caller can retry from a bookmark.
func GetAuthenticated ¶
func GetAuthenticated[T any](ctx context.Context, c *Client, path, accessToken string) (Response[T], error)
GetAuthenticated performs a GET with a character's access token.
Authenticated responses are per-character and are neither cached nor deduplicated — two characters asking the same question get different answers, and a shared cache keyed by URL would hand one character another's data.
func Post ¶
Post performs a POST. Used by /characters/affiliation/, which is a read expressed as a write because the id list does not fit in a URL.
type Status ¶
type Status struct {
Players int32 `json:"players"`
ServerVersion string `json:"server_version"`
StartTime string `json:"start_time"`
Error string `json:"error"`
// VIP marks a restricted login window after a patch — the server is up but
// only staff can play, so no killmails will arrive.
VIP bool `json:"vip"`
}
Status is /status/, the state of Tranquility itself.
It is what tells a worker fleet whether there is any point running: during a downtime or an unplanned outage every other endpoint returns errors, and spending the global error budget discovering that repeatedly is how a deployment gets itself 420'd for the length of the outage.
type War ¶
type War struct {
ID int32 `json:"id"`
Declared string `json:"declared"`
Started string `json:"started"`
Finished string `json:"finished"`
Retracted string `json:"retracted"`
Mutual bool `json:"mutual"`
OpenForAllies bool `json:"open_for_allies"`
Aggressor WarSide `json:"aggressor"`
Defender WarSide `json:"defender"`
Allies []struct {
AllianceID int32 `json:"alliance_id"`
CorporationID int32 `json:"corporation_id"`
} `json:"allies"`
}
War is /wars/{id}/.
type WarKillmailRef ¶
type WarKillmailRef struct {
KillmailID int64 `json:"killmail_id"`
KillmailHash string `json:"killmail_hash"`
}
WarKillmailRef is an id/hash pair from a war's killmail list.