Documentation
¶
Overview ¶
Package campaign computes the aggregate view of a user-defined conflict.
A campaign is a saved query: some entities, optionally a location, and a time window. Its statistics are recomputed from the killmails rather than incremented, which is what lets a campaign be edited after the fact — change a side and the numbers follow.
Recomputation is expensive, so almost everything here exists to avoid doing it. The gate check answers "has anything happened since last time?" with a few index probes, and an idle campaign therefore costs nearly nothing however often the sweep runs. Getting that wrong does not produce wrong numbers; it produces an hourly job that recomputes hundreds of dormant campaigns.
Index ¶
- Constants
- Variables
- func CalculatePayouts(fundedTotal float64, percentages []float64) []int64
- func Finalize(ctx context.Context, pool *pgxpool.Pool, campaignID string) (bool, error)
- func HasNewKills(ctx context.Context, pool *pgxpool.Pool, c *Campaign, entities []Entity) (bool, error)
- func IsAreaCampaign(entities []Entity, loc Location) bool
- func Load(ctx context.Context, pool *pgxpool.Pool, id string) (*Campaign, []Entity, error)
- func ParseFundingReason(reason string) (string, bool)
- func PopulatedSideCount(entities []Entity) int
- func ProcessJournalEntries(ctx context.Context, pool *pgxpool.Pool, entries []JournalEntry) (int, error)
- type Campaign
- type Entity
- type JournalEntry
- type Location
- type Result
- type SideTotals
Constants ¶
const ( StatusPending = 0 StatusActive = 1 StatusArchived = 2 )
Campaign lifecycle states, stored as smallints.
const ( EntityCharacter = 0 EntityCorporation = 1 EntityAlliance = 2 )
Entity types on a side.
const ( // EndGraceHours is how long after a campaign's end it stays eligible for // one last catch-up compute. Killmails arrive late, so finalising the // instant the clock passes would freeze a campaign missing its final kills. EndGraceHours = 1 // PrizeEndGraceHours is the longer window for a campaign with a prize // pool. Money is being settled from these numbers, so they get a full day // for stragglers before anything is paid. PrizeEndGraceHours = 24 // InactivityArchiveDays retires an open-ended campaign that has seen no // matching kill. Area campaigns are exempt — a quiet region is still a // region, and its campaign is a standing watch rather than a dead one. InactivityArchiveDays = 30 )
Timing policy.
const ( ReferenceMatched = 0 ReferenceUnmatched = 1 ReferenceLate = 2 ReferenceInvalid = 3 )
Reference statuses.
const ( PrizePoolFunding = 0 PrizePoolReady = 1 PrizePoolPaid = 2 PrizePoolCancelled = 3 )
Prize pool lifecycle, stored as smallints.
const EveKillCorporationID = 98779905
EveKillCorporationID is the only corporation whose donations fund campaigns.
const IDBoundSlack = 2 * 24 * time.Hour
IDBoundSlack widens the killmail-id range derived from a time bound.
Killmail ids correlate with time but are not strictly ordered by it — mails are backfilled and arrive late — so converting a timestamp to an id range needs slack on both sides or genuine kills fall outside it.
const PendingJournalLimit = 5000
PendingJournalLimit bounds one sweep.
const ProcessingTimeout = 10 * time.Minute
ProcessingTimeout bounds one recompute at the database.
A campaign scoped too broadly would otherwise hold a connection for minutes. Failing is the right outcome — it tells the owner their campaign is too broad, where a slow success just makes the sweep unreliable for everyone.
Variables ¶
var ErrPaused = errors.New("campaign processing is paused")
ErrPaused means a campaign has been deliberately taken out of processing.
Functions ¶
func CalculatePayouts ¶
CalculatePayouts divides a pool between ranks by weight.
Everything is whole ISK — the game has no fractions — which is what makes the first place a special case. Flooring every share loses the remainder, so the shares below first are floored and first takes what is left. The alternative, distributing the remainder proportionally, produces a pool that does not add up to what was funded, and a prize pool that does not add up is a support ticket.
func Finalize ¶
Finalize freezes the standings and writes the payouts.
Returns false when there was nothing to settle — no pool, or one already settled. That is the ordinary outcome of the sweep re-examining a campaign it has already finished with, not an error.
The pool row is locked for the whole transaction. Two workers reaching a campaign at the same moment would otherwise both read status Funding and both write payouts, and the second would overwrite the first with the same numbers — harmless today, and exactly the kind of thing that stops being harmless the moment a payout step is added between them.
func HasNewKills ¶
func HasNewKills(ctx context.Context, pool *pgxpool.Pool, c *Campaign, entities []Entity) (bool, error)
HasNewKills reports whether anything matching the campaign has happened since it was last computed.
This is the gate that makes an hourly sweep over hundreds of campaigns affordable: a handful of index probes that stop at the first match, rather than the full recompute. It is deliberately allowed to be optimistic — a false positive costs one wasted recompute, while a false negative would leave a campaign silently stale.
func IsAreaCampaign ¶
IsAreaCampaign reports a campaign defined by place rather than by participants.
func ParseFundingReason ¶
ParseFundingReason extracts the campaign id from a donation reason.
func PopulatedSideCount ¶
PopulatedSideCount counts the sides that actually hold entities. A declared-but-empty side can never kill or lose anything, so it does not make a campaign contested.
func ProcessJournalEntries ¶
func ProcessJournalEntries(ctx context.Context, pool *pgxpool.Pool, entries []JournalEntry) (int, error)
ProcessJournalEntries classifies donations and credits the ones that qualify.
Each entry is its own transaction. One malformed reason must not roll back the twenty good donations processed alongside it, and the journal entry's identity is the idempotency key — the reference row's primary key is (corporation, division, journal id), so a second pass over the same entry inserts nothing and credits nothing.
Types ¶
type Campaign ¶
type Campaign struct {
ID string
StartTime time.Time
EndTime *time.Time
ProcessedThrough *time.Time
LastActivityAt *time.Time
CreatedAt time.Time
Status int16
Location Location
HasPrizePool bool
ProcessingPaused bool
}
Campaign is the stored definition.
func (Campaign) EffectiveEnd ¶
EffectiveEnd is the campaign's end, or now for an open-ended one.
func (Campaign) GracePeriod ¶
GracePeriod is how long after the end this campaign stays open for a final compute. Longer when money depends on the result.
type JournalEntry ¶
type JournalEntry struct {
CorporationID int32
Division int16
JournalID int64
Date time.Time
RefType string
Amount float64
Reason string
}
JournalEntry is one wallet journal row being considered as funding.
func PendingJournalEntries ¶
func PendingJournalEntries(ctx context.Context, pool *pgxpool.Pool, corporationID int32, limit int) ([]JournalEntry, error)
PendingJournalEntries finds campaign donations not yet classified.
Bounded because it also serves as the catch-up for entries imported before this existed: without a limit the first run over that backlog would be one enormous query.
type Location ¶
type Location struct {
SystemIDs []int32 `json:"systemIds,omitempty"`
ConstellationIDs []int32 `json:"constellationIds,omitempty"`
RegionIDs []int32 `json:"regionIds,omitempty"`
}
Location narrows a campaign to part of space.