esi

package
v0.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 19 Imported by: 0

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

View Source
const DefaultBaseURL = "https://esi.evetech.net"

DefaultBaseURL matches ESI_BASE in the TypeScript client.

View Source
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

View Source
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.

View Source
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

func KillmailPath(killmailID int64, hash string) string

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

func ParseExpires(header string) (int64, bool)

ParseExpires reads an HTTP Expires header into unix milliseconds, returning false when it is missing or unparseable.

func PathPrefix

func PathPrefix(rawURL string) string

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

func UserAgent

func UserAgent(cfg *config.Config) string

UserAgent identifies us to CCP, which their acceptable-use policy requires.

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 NewCache

func NewCache(client *redis.Client) *Cache

NewCache builds a cache over the shared Valkey.

func (*Cache) Get

func (c *Cache) Get(ctx context.Context, url string) *Entry

Get returns whatever is known about a URL, fresh or not. A stale entry is still returned so the caller can use its ETag.

func (*Cache) Set

func (c *Cache) Set(ctx context.Context, url string, entry *Entry)

Set stores a response in both tiers.

func (*Cache) Touch

func (c *Cache) Touch(ctx context.Context, url string, expires int64, etag string)

Touch extends an entry's life after ESI answered 304, keeping the body it already had.

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 New

func New(cfg *config.Config) *Client

New builds a fully coordinated client from configuration.

func NewForTest

func NewForTest(baseURL, userAgent string, coordination, cache *redis.Client) *Client

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

func (c *Coordination) AcquireSequential(ctx context.Context, group string) (string, error)

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

func (c *Coordination) TryClaim(ctx context.Context, url string) (string, error)

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"`
	Shares        int64  `json:"shares"`
	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.

func (*Entry) Fresh

func (e *Entry) Fresh(now time.Time) bool

Fresh reports whether the entry may be served without asking ESI.

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 FwWar

type FwWar struct {
	FactionID int32 `json:"faction_id"`
	AgainstID int32 `json:"against_id"`
}

FwWar is one faction pairing.

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

func ResolveGroup(rawURL string) Group

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

func (r *RateLimiter) Acquire(ctx context.Context, g Group, cost int) (time.Duration, error)

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

func (r *RateLimiter) ApplyRemaining(ctx context.Context, g Group, remaining int) error

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

func FetchAlliance(ctx context.Context, c *Client, id int32) (Response[Alliance], error)

FetchAlliance reads one alliance.

func FetchAllianceCorporations

func FetchAllianceCorporations(ctx context.Context, c *Client, id int32) (Response[[]int32], error)

FetchAllianceCorporations reads an alliance's member corporations.

func FetchAllianceList

func FetchAllianceList(ctx context.Context, c *Client) (Response[[]int32], error)

FetchAllianceList reads every alliance id in the game.

func FetchCharacter

func FetchCharacter(ctx context.Context, c *Client, id int32) (Response[Character], error)

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

func FetchCorporation(ctx context.Context, c *Client, id int32) (Response[Corporation], error)

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

func FetchFwLeaderboards(ctx context.Context, c *Client) (Response[FwLeaderboard], error)

FetchFwLeaderboards reads the faction leaderboard.

func FetchFwLeaderboardsCharacters

func FetchFwLeaderboardsCharacters(ctx context.Context, c *Client) (Response[FwLeaderboard], error)

FetchFwLeaderboardsCharacters reads the character leaderboard.

func FetchFwLeaderboardsCorporations

func FetchFwLeaderboardsCorporations(ctx context.Context, c *Client) (Response[FwLeaderboard], error)

FetchFwLeaderboardsCorporations reads the corporation leaderboard.

func FetchFwStats

func FetchFwStats(ctx context.Context, c *Client) (Response[[]FwStats], error)

FetchFwStats reads per-faction standings.

func FetchFwSystems

func FetchFwSystems(ctx context.Context, c *Client) (Response[[]FwSystem], error)

FetchFwSystems reads every contested system.

func FetchFwWars

func FetchFwWars(ctx context.Context, c *Client) (Response[[]FwWar], error)

FetchFwWars reads the faction pairings.

func FetchStatus

func FetchStatus(ctx context.Context, c *Client) (Response[Status], error)

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 FetchWar

func FetchWar(ctx context.Context, c *Client, id int32) (Response[War], error)

FetchWar reads one war.

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

func FetchWarList(ctx context.Context, c *Client, maxWarID int32) (Response[[]int32], error)

FetchWarList reads war ids, newest first. maxWarID pages backwards through history; zero starts at the most recent.

func Get

func Get[T any](ctx context.Context, c *Client, path string) (Response[T], error)

Get performs a cached, coordinated, rate-limited GET.

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

func Post[T any](ctx context.Context, c *Client, path string, body any) (Response[T], error)

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.

func (Response[T]) OK

func (r Response[T]) OK() bool

OK reports whether ESI supplied usable data. A conditional request returns 304 when the cached representation is still current; finishGet attaches that cached body, so callers must treat it as a successful response too.

func (Response[T]) Permanent

func (r Response[T]) Permanent() bool

Permanent reports whether retrying could ever produce a different answer. A 404 or 422 on a killmail means the id and hash do not go together; no amount of retrying will change that.

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.

type WarSide

type WarSide struct {
	AllianceID    int32   `json:"alliance_id"`
	CorporationID int32   `json:"corporation_id"`
	IskDestroyed  float64 `json:"isk_destroyed"`
	ShipsKilled   int32   `json:"ships_killed"`
}

WarSide is one belligerent.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL