relay

package
v0.2.12 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package relay publishes events for the WebSocket server.

Events go out over Redis pub/sub on channels prefixed `ws:`, which is what the relay process subscribes to. That indirection is what lets the workers stay stateless: no worker holds a socket, and any number of them can publish to a relay that may be restarted, scaled or redeployed independently.

Publishing is deliberately fire-and-forget. A killmail that was parsed, valued and stored has done the work that matters; failing the job because a notification did not go out would retry the whole thing and store nothing new. The event is lost, the data is not, and the site catches up on next load.

Index

Constants

View Source
const (
	ChannelKillmail = "killmails"
	ChannelKilllist = "killlist"
	ChannelFeed     = "feed"
	ChannelStatus   = "status"

	// Plural, matching the relay's endpoints (/comments, /announcements). The
	// mismatch with the singular queue names above is the existing convention,
	// not a typo — the queue is named for the event, the channel for the page.
	ChannelComments      = "comments"
	ChannelAnnouncements = "announcements"
)

Channels currently in use. Named here rather than at each call site so the set is greppable, and because these strings are a contract with a separate process — changing one silently stops delivering to it.

View Source
const ChannelPrefix = "ws:"

ChannelPrefix is what the relay process subscribes to.

Variables

This section is empty.

Functions

func RoutingKeys

func RoutingKeys(p *killmail.Parsed, systemSecurity float64, hasSecurity bool) []string

RoutingKeys builds the keys a parsed killmail publishes under.

systemSecurity is separate because it is not on the killmail row — it comes from the static-data cache — and hasSecurity distinguishes "security 0.0", which is a real nullsec value, from "we do not know the system".

Types

type EntityNames

type EntityNames struct {
	Characters   map[int32]string
	Corporations map[int32]string
	Alliances    map[int32]string
}

EntityNames holds the names a killlist row needs.

func LookupNames

func LookupNames(ctx context.Context, pool *pgxpool.Pool, characters, corporations, alliances []int32) (EntityNames, error)

LookupNames reads the names for the entities a killmail row references.

One query per kind regardless of attacker count. Only the victim and the final blow appear on a killlist row, so this is at most six ids — but the query shape is the same either way and this keeps the call site simple.

type Event

type Event struct {
	RoutingKeys []string `json:"routing_keys"`
	Data        any      `json:"data"`
}

Event is one published message.

RoutingKeys let a subscriber filter without the relay understanding the payload: a client subscribed to `victim.98000001` receives only the kills carrying that key. The relay matches keys and forwards; it never inspects Data.

type FeedNotice

type FeedNotice struct {
	Seq         int64    `json:"seq"`
	KillmailID  int64    `json:"killmail_id"`
	RoutingKeys []string `json:"routing_keys"`
}

FeedNotice is the payload published on the feed channel.

Flat rather than wrapped in an Event, because this channel predates the routing-key envelope and its subscribers parse it at the top level.

type KilllistEvent

type KilllistEvent struct {
	Event    string      `json:"event"`
	Killmail KilllistRow `json:"killmail"`
}

KilllistEvent is what the killlist channel carries.

type KilllistRow

type KilllistRow struct {
	KillmailID   int64  `json:"killmail_id"`
	KillmailHash string `json:"killmail_hash"`

	// KillmailTime is the wire shape — an ISO string, not a timestamp — because
	// this is what the browser receives.
	KillmailTime string `json:"killmail_time"`

	// These four are nullable in the schema but the REST resolver defaults them
	// rather than forwarding null, so a live row and a refetched one agree on a
	// kill with no value or no attacker count recorded.
	TotalValue    float64 `json:"total_value"`
	AttackerCount int32   `json:"attacker_count"`
	IsNPC         bool    `json:"is_npc"`
	IsSolo        bool    `json:"is_solo"`

	ShipTypeID     *int32  `json:"ship_type_id"`
	ShipName       *string `json:"ship_name"`
	ShipGroupName  *string `json:"ship_group_name"`
	ShipMarketPath *string `json:"ship_market_path"`
	MetaGroupID    *int32  `json:"meta_group_id"`

	VictimCharacterID     *int32  `json:"victim_character_id"`
	VictimCharacterName   *string `json:"victim_character_name"`
	VictimCorporationID   *int32  `json:"victim_corporation_id"`
	VictimCorporationName *string `json:"victim_corporation_name"`
	VictimAllianceID      *int32  `json:"victim_alliance_id"`
	VictimAllianceName    *string `json:"victim_alliance_name"`
	VictimFactionID       *int32  `json:"victim_faction_id"`

	FinalBlowCharacterID     *int32  `json:"final_blow_character_id"`
	FinalBlowCharacterName   *string `json:"final_blow_character_name"`
	FinalBlowCorporationID   *int32  `json:"final_blow_corporation_id"`
	FinalBlowCorporationName *string `json:"final_blow_corporation_name"`
	FinalBlowAllianceID      *int32  `json:"final_blow_alliance_id"`
	FinalBlowAllianceName    *string `json:"final_blow_alliance_name"`
	FinalBlowShipTypeID      *int32  `json:"final_blow_ship_type_id"`
	FinalBlowShipName        *string `json:"final_blow_ship_name"`

	SolarSystemID       int32    `json:"solar_system_id"`
	SolarSystemName     *string  `json:"solar_system_name"`
	SolarSystemSecurity *float64 `json:"solar_system_security"`
	RegionID            *int32   `json:"region_id"`
	RegionName          *string  `json:"region_name"`
}

KilllistRow is the flattened killmail summary the killlist UI renders.

Two independent producers emit this shape and they must stay identical: the REST resolver behind the /api/killlist/* endpoints, and the live event this package publishes and the client prepends to page one. They have drifted before — the relay payload was once missing ship_market_path, so a live row rendered without its ship link until you reloaded the page, and missing meta_group_id, so the client had to download a separate set of ship type ids just to evaluate the tech-level filter.

Every field is therefore a pointer or has an explicit zero default matching what the REST resolver applies. The nullable ones are pointers because the client distinguishes absent from zero: a kill with no recorded attacker count is not a kill with zero attackers.

func BuildKilllistRow

func BuildKilllistRow(p *killmail.Parsed, cache *eve.Cache, paths eve.MarketPaths, names EntityNames) KilllistRow

BuildKilllistRow flattens a parsed killmail into the wire shape.

type KillmailAttacker

type KillmailAttacker struct {
	CharacterID    int32   `json:"character_id"`
	CorporationID  int32   `json:"corporation_id"`
	AllianceID     int32   `json:"alliance_id"`
	FactionID      int32   `json:"faction_id"`
	ShipTypeID     int32   `json:"ship_type_id"`
	WeaponTypeID   int32   `json:"weapon_type_id"`
	DamageDone     int32   `json:"damage_done"`
	FinalBlow      bool    `json:"final_blow"`
	SecurityStatus float64 `json:"security_status"`

	CharacterName   *string `json:"character_name"`
	CorporationName *string `json:"corporation_name"`
	AllianceName    *string `json:"alliance_name"`
	ShipTypeName    *string `json:"ship_type_name"`
	ShipGroupID     *int32  `json:"ship_group_id"`
	ShipGroupName   *string `json:"ship_group_name"`
	WeaponTypeName  *string `json:"weapon_type_name"`
}

type KillmailEvent

type KillmailEvent struct {
	Event        string `json:"event"`
	KillmailID   int64  `json:"killmail_id"`
	KillmailHash string `json:"killmail_hash"`
	KillmailTime string `json:"killmail_time"`

	SolarSystemID       int32    `json:"solar_system_id"`
	SolarSystemName     *string  `json:"solar_system_name"`
	SolarSystemSecurity *float64 `json:"solar_system_security"`
	ConstellationID     *int32   `json:"constellation_id"`
	ConstellationName   *string  `json:"constellation_name"`
	RegionID            *int32   `json:"region_id"`
	RegionName          *string  `json:"region_name"`

	TotalValue     float64 `json:"total_value"`
	FittedValue    float64 `json:"fitted_value"`
	DroppedValue   float64 `json:"dropped_value"`
	DestroyedValue float64 `json:"destroyed_value"`
	Points         int32   `json:"points"`
	IsSolo         bool    `json:"is_solo"`
	IsNPC          bool    `json:"is_npc"`
	WarID          int32   `json:"war_id"`

	Victim    KillmailVictim     `json:"victim"`
	Attackers []KillmailAttacker `json:"attackers"`
}

KillmailEvent is the full hydrated event consumed by the /killmails relay channel. Keep this distinct from KilllistEvent: the latter is a compact, flattened row for list pages, while this mirrors the ESI-shaped detail payload emitted by the TypeScript worker.

func BuildKillmailEvent

func BuildKillmailEvent(
	p *killmail.Parsed,
	cache *eve.Cache,
	names EntityNames,
	price func(int32) float64,
) KillmailEvent

BuildKillmailEvent hydrates the stored rows with the same cache, name, and price information as backend/src/queues/killmails/queue.ts.

type KillmailItem

type KillmailItem struct {
	ItemTypeID        int32   `json:"item_type_id"`
	Flag              int32   `json:"flag"`
	QuantityDropped   int64   `json:"quantity_dropped"`
	QuantityDestroyed int64   `json:"quantity_destroyed"`
	Singleton         int16   `json:"singleton"`
	ItemTypeName      *string `json:"item_type_name"`
	ItemGroupID       *int32  `json:"item_group_id"`
	ItemGroupName     *string `json:"item_group_name"`
	ItemCategoryID    *int32  `json:"item_category_id"`
	Value             float64 `json:"value"`
}

type KillmailVictim

type KillmailVictim struct {
	CharacterID   int32 `json:"character_id"`
	CorporationID int32 `json:"corporation_id"`
	AllianceID    int32 `json:"alliance_id"`
	FactionID     int32 `json:"faction_id"`
	ShipTypeID    int32 `json:"ship_type_id"`
	DamageTaken   int32 `json:"damage_taken"`

	CharacterName   *string `json:"character_name"`
	CorporationName *string `json:"corporation_name"`
	AllianceName    *string `json:"alliance_name"`
	ShipTypeName    *string `json:"ship_type_name"`
	ShipGroupID     *int32  `json:"ship_group_id"`
	ShipGroupName   *string `json:"ship_group_name"`

	Position *killmail.ESIPosition `json:"position,omitempty"`
	Items    []KillmailItem        `json:"items"`
}

type Publisher

type Publisher struct {
	Redis *redis.Client

	// OnError is called when a publish fails, for logging. Optional — the
	// failure is never returned, because no caller should act on it.
	OnError func(channel string, err error)
}

Publisher sends events to the relay.

func (*Publisher) Publish

func (p *Publisher) Publish(ctx context.Context, channel string, routingKeys []string, data any)

Publish sends one event.

Never returns an error. See the package comment: the caller has already done the work that matters, and there is no useful action to take when a notification does not go out.

func (*Publisher) PublishRaw

func (p *Publisher) PublishRaw(ctx context.Context, channel string, payload any)

PublishRaw sends a pre-shaped payload that is not wrapped in an Event.

The feed channel predates the routing-key envelope and carries its own shape — `{seq, killmail_id, routing_keys}` at the top level rather than nested under `data`. Subscribers parse it that way, so it cannot be normalised without changing them.

func (*Publisher) PublishToFeed

func (p *Publisher) PublishToFeed(ctx context.Context, pool *pgxpool.Pool, killmailID int64, routingKeys []string) error

PublishToFeed appends a killmail to the feed and notifies subscribers.

The insert is what matters and its failure is returned; the notification is best-effort, because a client that misses it recovers on its next poll from the sequence number it already holds. This intentionally avoids the TypeScript failure mode where a Redis outage retries a successful insert and appends duplicate feed rows.

Jump to

Keyboard shortcuts

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