Documentation
¶
Overview ¶
Package wars fetches and stores war declarations.
A war is a small, slow-changing record with one awkward property: it stays interesting after it ends. Killmails reference war ids indefinitely, so a war finished in 2013 still has to resolve to a name and two belligerents.
Three things therefore drive what gets refetched: wars ESI has that we do not, wars still running (or only just finished, since the final tallies land after the finish), and wars referenced by stored killmails whose metadata was never imported — which historical killmail backfills leave behind routinely.
Index ¶
- Constants
- Variables
- func AggregateAllInTx(ctx context.Context, tx pgx.Tx) error
- func AggregateKillmail(ctx context.Context, tx pgx.Tx, killmailID int64) (bool, error)
- func MissingKillmails(ctx context.Context, pool *pgxpool.Pool, client *esi.Client, warID int32) ([]killmail.Ref, error)
- func Refresh(ctx context.Context, pool *pgxpool.Pool, client *esi.Client, warID int32) (*esi.War, error)
- func StoreAllies(ctx context.Context, pool *pgxpool.Pool, warID int32, w esi.War) (int64, error)
- type Attacker
- type Contribution
- type Discover
- type Membership
- type RebuildResult
- type Summary
- type Victim
Constants ¶
const ( SideCombined int16 = 0 SideAggressor int16 = 1 SideDefender int16 = 2 )
Sides of a war. COMBINED is the war's own total, tracked alongside the two sides so a war page does not have to add them up — and because a kill by someone on neither side still happened in the war.
const ( CategoryKilled int16 = 0 CategoryKilledBy int16 = 1 )
Interaction categories.
const ( TargetCharacter int16 = 0 TargetCorporation int16 = 1 TargetAlliance int16 = 2 )
Target types.
const ( LockNamespace = 20_260_721 LockKey = 1 )
Advisory lock coordinating incremental writers against a full rebuild.
Live writers take it shared; the rebuild takes it exclusive. Without that, a rebuild that swaps the table contents could lose a kill ingested while it was computing — the increment would land on rows about to be replaced.
const MissingRepairBatch = 100
MissingRepairBatch bounds how many orphaned war references are repaired per run. Historical backfills can leave tens of thousands; taking a hundred an hour clears the backlog steadily without ever competing with live work.
Variables ¶
var ErrWarUnknown = errors.New("war not found")
ErrWarUnknown means the killmail names a war we have no row for.
Functions ¶
func AggregateAllInTx ¶
AggregateAllInTx runs the set-based aggregation straight into war_interactions, inside a transaction the caller controls.
Exists for the agreement test, which has to compute both answers inside one transaction it will roll back — so it can use neither Rebuild's own transaction nor its exclusive lock. Sharing the SQL is the whole point: a test that reimplemented the aggregation would be testing itself.
func AggregateKillmail ¶
AggregateKillmail folds one killmail into war_interactions.
Returns false when the war itself is missing. The war list has historical gaps, and a killmail that names a war we have never imported is not a failure — it is work that has to wait for the war. Reporting that as "not done" leaves the effect pending so the repair path replays it once the war row exists, rather than marking it complete over a war that was never read.
func MissingKillmails ¶
func MissingKillmails(ctx context.Context, pool *pgxpool.Pool, client *esi.Client, warID int32) ([]killmail.Ref, error)
MissingKillmails walks a war's killmail list and returns the ones that still need war processing.
ESI pages these, and a long war has thousands. The page loop stops on the first empty page rather than trusting a total, because ESI does not report one for this endpoint.
func Refresh ¶
func Refresh(ctx context.Context, pool *pgxpool.Pool, client *esi.Client, warID int32) (*esi.War, error)
Refresh stores one war and returns what ESI said about it.
The decoded war comes back so the caller can record its allies without fetching it a second time. A nil war with a nil error means ESI does not recognise the id — see below.
func StoreAllies ¶
StoreAllies records the third parties who joined a war.
Insert-only: allies are appended to a war and never removed. war_allies has only a serial primary key, so ON CONFLICT cannot deduplicate the logical (war, alliance, corporation) identity; guard it explicitly instead.
Types ¶
type Contribution ¶
Contribution is one row to increment.
func Contributions ¶
func Contributions(v Victim, attackers []Attacker, m Membership) []Contribution
Contributions produces the distinct interactions one killmail establishes.
One per fact, not one per attacker. Forty attackers from one alliance produce a single aggressor-killed-victim contribution, so the count stays "ships destroyed" and the ISK stays "ISK destroyed" — which is what the war page claims they are. Counting per attacker would report forty kills for one dead ship and multiply the ISK by forty.
That collapsing happens structurally rather than by filtering: the attacker sides are gathered into a set before anything is emitted, and every add below uses a distinct (side, category, target type) combination. The seen map is a guard against a future edit breaking that, not a working part of it — as written, it never fires.
type Discover ¶
type Discover struct {
// New are wars ESI lists that are not stored.
New []int32
// Active are stored wars that have not finished, or finished recently
// enough that the final tallies may still be moving.
Active []int32
// Missing are wars referenced by stored killmails but never imported.
Missing []int32
}
Discover reports which wars need fetching.
type Membership ¶
type Membership struct {
AggressorAllianceID int32
AggressorCorporationID int32
DefenderAllianceIDs map[int32]bool
DefenderCorporationIDs map[int32]bool
}
Membership is who is on which side of a war.
Defenders are sets because a war accumulates allies; aggressors are single ids because EVE allows exactly one.
func LoadMembership ¶
LoadMembership reads a war's sides, including accumulated allies.
func (Membership) Side ¶
func (m Membership) Side(corporationID, allianceID int32) (int16, bool)
Side reports which side of the war an entity is on, or false for neither.
Neither is a normal answer, not an error: third parties shoot into wars all the time, and a neutral who lands a kill belongs to the war's combined total without belonging to a side.
type RebuildResult ¶
RebuildResult reports what a rebuild produced.
func Rebuild ¶
Rebuild replaces war_interactions for a scope, atomically.
Everything happens in one repeatable-read transaction holding the exclusive advisory lock, which is what makes it safe to run against a live killboard: incremental writers take the same lock shared, so none of them can slip an increment into a table that is about to be replaced.
The replacement is built in a temporary table and validated before anything in production is touched. A unique index on the logical key is that validation — if the aggregation somehow produced two rows for one key, the index creation aborts the transaction while the real table is still intact.
Pass warID 0 to rebuild every war.
type Summary ¶
type Summary struct {
Killmails int64
KillmailISK float64
Rows int64
Wars int64
CombinedCorpKills int64
CombinedCorpISK float64
}
Summary describes what a scope currently holds.