campaign

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: 13 Imported by: 0

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

View Source
const (
	StatusPending  = 0
	StatusActive   = 1
	StatusArchived = 2
)

Campaign lifecycle states, stored as smallints.

View Source
const (
	EntityCharacter   = 0
	EntityCorporation = 1
	EntityAlliance    = 2
)

Entity types on a side.

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

View Source
const (
	ReferenceMatched   = 0
	ReferenceUnmatched = 1
	ReferenceLate      = 2
	ReferenceInvalid   = 3
)

Reference statuses.

View Source
const (
	PrizePoolFunding   = 0
	PrizePoolReady     = 1
	PrizePoolPaid      = 2
	PrizePoolCancelled = 3
)

Prize pool lifecycle, stored as smallints.

View Source
const EveKillCorporationID = 98779905

EveKillCorporationID is the only corporation whose donations fund campaigns.

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

View Source
const PendingJournalLimit = 5000

PendingJournalLimit bounds one sweep.

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

View Source
var ErrPaused = errors.New("campaign processing is paused")

ErrPaused means a campaign has been deliberately taken out of processing.

Functions

func CalculatePayouts

func CalculatePayouts(fundedTotal float64, percentages []float64) []int64

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

func Finalize(ctx context.Context, pool *pgxpool.Pool, campaignID string) (bool, error)

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

func IsAreaCampaign(entities []Entity, loc Location) bool

IsAreaCampaign reports a campaign defined by place rather than by participants.

func Load

func Load(ctx context.Context, pool *pgxpool.Pool, id string) (*Campaign, []Entity, error)

Load reads a campaign and its sides.

func ParseFundingReason

func ParseFundingReason(reason string) (string, bool)

ParseFundingReason extracts the campaign id from a donation reason.

func PopulatedSideCount

func PopulatedSideCount(entities []Entity) int

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

func (c Campaign) EffectiveEnd(now time.Time) time.Time

EffectiveEnd is the campaign's end, or now for an open-ended one.

func (Campaign) Finished

func (c Campaign) Finished(now time.Time) bool

Finished reports whether the campaign's end plus its grace has passed.

func (Campaign) GracePeriod

func (c Campaign) GracePeriod() time.Duration

GracePeriod is how long after the end this campaign stays open for a final compute. Longer when money depends on the result.

type Entity

type Entity struct {
	ID         int64
	SideIndex  int16
	EntityType int16
	EntityID   int32
}

Entity is one participant on a side.

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.

func (Location) HasFilter

func (l Location) HasFilter() bool

HasFilter reports whether the location narrows anything.

type Result

type Result struct {
	CampaignID string    `json:"campaign_id"`
	Killmails  int64     `json:"killmails"`
	Sides      int       `json:"sides"`
	Through    time.Time `json:"processed_through"`
}

Result reports one recompute.

func Process

func Process(ctx context.Context, pool *pgxpool.Pool, campaignID string) (*Result, error)

Process recomputes one campaign's statistics.

type SideTotals

type SideTotals struct {
	SideIndex    int16   `json:"side_index"`
	Kills        int64   `json:"kills"`
	Losses       int64   `json:"losses"`
	IskDestroyed float64 `json:"isk_destroyed"`
	IskLost      float64 `json:"isk_lost"`
}

SideTotals is one side's aggregate.

Jump to

Keyboard shortcuts

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