wars

package
v0.2.4 Latest Latest
Warning

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

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

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

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

View Source
const (
	CategoryKilled   int16 = 0
	CategoryKilledBy int16 = 1
)

Interaction categories.

View Source
const (
	TargetCharacter   int16 = 0
	TargetCorporation int16 = 1
	TargetAlliance    int16 = 2
)

Target types.

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

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

View Source
var ErrWarUnknown = errors.New("war not found")

ErrWarUnknown means the killmail names a war we have no row for.

Functions

func AggregateAllInTx

func AggregateAllInTx(ctx context.Context, tx pgx.Tx) error

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

func AggregateKillmail(ctx context.Context, tx pgx.Tx, killmailID int64) (bool, error)

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

func StoreAllies(ctx context.Context, pool *pgxpool.Pool, warID int32, w esi.War) (int64, error)

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 Attacker

type Attacker struct {
	CharacterID   int32
	CorporationID int32
	AllianceID    int32
	FinalBlow     bool
}

Attacker is one attacker row, reduced to what the aggregation reads.

type Contribution

type Contribution struct {
	Side       int16
	Category   int16
	TargetType int16
	TargetID   int32
}

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.

func Find

func Find(ctx context.Context, pool *pgxpool.Pool, client *esi.Client) (Discover, error)

Find works out what to fetch.

func (Discover) Total

func (d Discover) Total() int

Total is how many fetches the discovery implies.

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

func LoadMembership(ctx context.Context, tx pgx.Tx, warID int32) (Membership, error)

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

type RebuildResult struct {
	Rows int64
	Wars int64
}

RebuildResult reports what a rebuild produced.

func Rebuild

func Rebuild(ctx context.Context, pool *pgxpool.Pool, warID int32) (RebuildResult, error)

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.

func Summarize

func Summarize(ctx context.Context, pool *pgxpool.Pool, warID int32) (Summary, error)

Summarize reports the current state of a scope, for the preview.

The combined corporation figures are the ones to read: they are one row per war per victim corporation, so they are directly comparable to the killmail count above them. If those two disagree, the table has drifted.

type Victim

type Victim struct {
	CharacterID   int32
	CorporationID int32
	AllianceID    int32
}

Victim is the loss side of a killmail.

Jump to

Keyboard shortcuts

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