events

package
v0.3.18 Latest Latest
Warning

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

Go to latest
Published: Nov 22, 2026 License: GPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package events provides Ether's typed domain event envelope, schema registry, non-blocking in-process event bus, durable outbox migration, and test recorder.

Publishers emit events synchronously with Bus.Publish; delivery never blocks callers (slow subscribers drop with atomic counters). Flows, notifications, plugin outboxes and cluster bridges subscribe asynchronously.

Index

Constants

View Source
const (
	// SourceBuiltin identifies events emitted by Ether itself.
	SourceBuiltin = "ether"
	// OwnerBuiltin identifies built-in schemas in Registry.
	OwnerBuiltin = "builtin"
	// PluginPrefix namespaces plugin-contributed event types ("plugin:<pluginId>/<key>").
	PluginPrefix = "plugin:"
	// RedactedValue masks Secret fields in persisted traces and API responses.
	RedactedValue = "[redacted]"
)
View Source
const (
	EventAuthLoginSucceeded             = "auth.login.succeeded"
	EventAuthLoginFailed                = "auth.login.failed"
	EventAuthGrantRevoked               = "auth.grant.revoked"
	EventAuthDeviceRegistered           = "auth.device.registered"
	EventAuthDeviceQuickConnectApproved = "auth.device.quickconnect_approved"
	EventAuthSessionNewIP               = "auth.session.new_ip"
	EventAuthTokenExpired               = "auth.token.expired"
	EventAuthRateLimited                = "auth.rate.limited"
	EventAuthCertificateRenewed         = "auth.certificate.renewed"
)
View Source
const (
	EventCacheBudgetFull        = "cache.budget.full"
	EventCacheBudgetRecovered   = "cache.budget.recovered"
	EventCacheEvictionSpike     = "cache.eviction.spike"
	EventCachePrefetchCompleted = "cache.prefetch.completed"
	EventCachePrefetchFailed    = "cache.prefetch.failed"
)

Canonical cache event type names.

View Source
const (
	EventClusterNodeJoined          = "cluster.node.joined"
	EventClusterNodeLost            = "cluster.node.lost"
	EventClusterNodeDraining        = "cluster.node.draining"
	EventClusterLeaderElected       = "cluster.leader.elected"
	EventClusterDatabaseUnavailable = "cluster.database.unavailable"
	EventClusterDatabaseRecovered   = "cluster.database.recovered"
)
View Source
const (
	EventFlowsRunFailed        = "flows.run.failed"
	EventFlowsFlowAutoDisabled = "flows.flow.auto_disabled"
	EventFlowsBusDropped       = "flows.bus.dropped"
	EventFlowsDigestScheduled  = "flows.digest.scheduled"
)
View Source
const (
	EventIndexerRequestFailed    = "indexer.request.failed"
	EventIndexerServiceOutage    = "indexer.service.outage"
	EventIndexerServiceRecovered = "indexer.service.recovered"
	EventIndexerBudgetWarning    = "indexer.budget.warning"
	EventIndexerBudgetExhausted  = "indexer.budget.exhausted"
	EventIndexerRateLimited      = "indexer.rate.limited"
)

Canonical indexer event type names.

View Source
const (
	EventLibraryTitleAdded        = "library.title.added"
	EventLibraryBatchAdded        = "library.batch.added"
	EventLibraryTitleAvailable    = "library.title.available"
	EventLibraryTitleUnavailable  = "library.title.unavailable"
	EventLibraryEpisodeAired      = "library.episode.aired"
	EventLibrarySyncStarted       = "library.sync.started"
	EventLibrarySyncCompleted     = "library.sync.completed"
	EventLibrarySyncFailed        = "library.sync.failed"
	EventLibraryCollectionRebuilt = "library.collection.rebuilt"
	EventLibraryWatchlistSynced   = "library.watchlist.synced"
	EventLibraryMetadataFailed    = "library.metadata.failed"
)
View Source
const (
	EventLiveTVChannelTuned         = "livetv.channel.tuned"
	EventLiveTVChannelStopped       = "livetv.channel.stopped"
	EventLiveTVInputStalled         = "livetv.input.stalled"
	EventLiveTVInputRecovered       = "livetv.input.recovered"
	EventLiveTVInputLost            = "livetv.input.lost"
	EventLiveTVSourceFailover       = "livetv.source.failover"
	EventLiveTVSourceDegraded       = "livetv.source.degraded"
	EventLiveTVSourceCooldown       = "livetv.source.cooldown"
	EventLiveTVProviderAuthFailed   = "livetv.provider.auth_failed"
	EventLiveTVProviderLimitReached = "livetv.provider.limit_reached"
	EventLiveTVGuideRefreshed       = "livetv.guide.refreshed"
	EventLiveTVGuideFailed          = "livetv.guide.failed"
)

Canonical Live TV event type names.

View Source
const (
	EventPlaybackSessionStarted       = "playback.session.started"
	EventPlaybackSessionPaused        = "playback.session.paused"
	EventPlaybackSessionResumed       = "playback.session.resumed"
	EventPlaybackSessionStopped       = "playback.session.stopped"
	EventPlaybackSessionCompleted     = "playback.session.completed"
	EventPlaybackSessionFailed        = "playback.session.failed"
	EventPlaybackSessionTerminated    = "playback.session.terminated"
	EventPlaybackSourceFailover       = "playback.source.failover"
	EventPlaybackStreamStalled        = "playback.stream.stalled"
	EventPlaybackStreamDecision       = "playback.stream.decision"
	EventPlaybackStreamQualityChanged = "playback.stream.quality_changed"
	EventPlaybackStreamSeeked         = "playback.stream.seeked"
	EventPlaybackMarkerEntered        = "playback.marker.entered"
	EventPlaybackMarkerExited         = "playback.marker.exited"
	EventPlaybackConcurrencyExceeded  = "playback.concurrency.exceeded"
	EventPlaybackAdmissionDenied      = "playback.admission.denied"
	EventPlaybackTranscodeFallback    = "playback.transcode.fallback"
)

Canonical playback event type names.

View Source
const (
	EventPluginPackageInstalled = "plugin.package.installed"
	EventPluginPackageUpdated   = "plugin.package.updated"
	EventPluginPackageRemoved   = "plugin.package.removed"
	EventPluginStateEnabled     = "plugin.state.enabled"
	EventPluginStateDisabled    = "plugin.state.disabled"
	EventPluginHealthDegraded   = "plugin.health.degraded"
	EventPluginHealthRecovered  = "plugin.health.recovered"
	EventPluginQuotaExceeded    = "plugin.quota.exceeded"
	EventPluginJobFailed        = "plugin.job.failed"
)
View Source
const (
	EventProviderServiceOutage        = "provider.service.outage"
	EventProviderServiceRecovered     = "provider.service.recovered"
	EventProviderAuthRejected         = "provider.auth.rejected"
	EventProviderQuotaWarning         = "provider.quota.warning"
	EventProviderQuotaExhausted       = "provider.quota.exhausted"
	EventProviderDebridCached         = "provider.debrid.cached"
	EventProviderDebridFailed         = "provider.debrid.failed"
	EventProviderConnectionsSaturated = "provider.connections.saturated"
)

Canonical provider (Usenet & debrid) event type names.

View Source
const (
	EventResolverSearchCompleted    = "resolver.search.completed"
	EventResolverSearchEmpty        = "resolver.search.empty"
	EventResolverReleaseSelected    = "resolver.release.selected"
	EventResolverReleaseBlocklisted = "resolver.release.blocklisted"
	EventResolverPinCreated         = "resolver.pin.created"
	EventResolverPinRemoved         = "resolver.pin.removed"
	EventResolverPinUnhealthy       = "resolver.pin.unhealthy"
	EventResolverPinRejected        = "resolver.pin.rejected"
)

Canonical resolver event type names.

View Source
const (
	EventSystemServerStarted       = "system.server.started"
	EventSystemServerStopping      = "system.server.stopping"
	EventSystemServerCrashed       = "system.server.crashed"
	EventSystemHealthChanged       = "system.health.changed"
	EventSystemReachabilityChanged = "system.reachability.changed"
	EventSystemUpdateAvailable     = "system.update.available"
	EventSystemUpdateInstalled     = "system.update.installed"
	EventSystemUpdateRolledBack    = "system.update.rolled_back"
	EventSystemBackupCompleted     = "system.backup.completed"
	EventSystemBackupFailed        = "system.backup.failed"
	EventSystemDiskLow             = "system.disk.low"
)
View Source
const (
	EventVaultRecordStored   = "vault.record.stored"
	EventVaultRecordDead     = "vault.record.dead"
	EventVaultPayloadMissing = "vault.payload.missing"
	EventVaultPackCompacted  = "vault.pack.compacted"
	EventVaultQuotaWarning   = "vault.quota.warning"
)

Canonical vault event type names.

View Source
const (
	EventViewerAccountJoined      = "viewer.account.joined"
	EventViewerAccountDeactivated = "viewer.account.deactivated"
	EventViewerAccountMerged      = "viewer.account.merged"
	EventViewerAccessChanged      = "viewer.access.changed"
	EventViewerSafetyUpdated      = "viewer.safety.updated"
	EventViewerInviteCreated      = "viewer.invite.created"
	EventViewerInviteAccepted     = "viewer.invite.accepted"
	EventViewerWatchScrobbled     = "viewer.watch.scrobbled"
	EventViewerRatingSubmitted    = "viewer.rating.submitted"
)
View Source
const DefaultSubscriberBuffer = 256

DefaultSubscriberBuffer is the bounded channel capacity given to subscribers that do not specify a custom buffer size.

Variables

View Source
var ErrDuplicateSchema = errors.New("events: schema already registered")

ErrDuplicateSchema is returned when registering an event type that already exists.

View Source
var ErrInvalidEventType = errors.New("events: invalid event type")

ErrInvalidEventType is returned when an event type fails naming validation.

Functions

func DecodePayload

func DecodePayload[T any](ev Envelope) (T, error)

DecodePayload unmarshals ev.Payload into T.

func DomainOf

func DomainOf(eventType string) string

DomainOf extracts the domain portion of an event type ("playback" for "playback.session.started", or "plugin:<pluginId>" for plugin events).

func IsPluginType

func IsPluginType(eventType string) bool

IsPluginType reports whether eventType belongs to a plugin.

func MatchPattern

func MatchPattern(pattern, eventType string) bool

MatchPattern reports whether eventType matches a subscription pattern. Supported patterns:

  • "*" matches every event type.
  • "domain.*" or "domain.noun.*" matches any event starting with that prefix.
  • "plugin:<id>/*" matches any event published by that plugin.
  • "domain." or "plugin:<id>/" matches any event with that literal prefix.
  • Any other pattern matches exact equality.

func NewID

func NewID() string

NewID generates a random event ID ("evt_<16 hex>").

func NewTestBus

func NewTestBus(t TestTB, opts ...BusOptions) (*Bus, *Recorder)

NewTestBus constructs a Bus wired to a Recorder subscribed to all events (including dry-run events) and automatically cleans up when t finishes.

func ParsePluginEventType

func ParsePluginEventType(eventType string) (pluginID, key string, ok bool)

ParsePluginEventType splits "plugin:<pluginId>/<key>" and validates both halves.

func PluginEventType

func PluginEventType(pluginID, key string) string

PluginEventType formats a plugin-namespaced event type.

func RegisterAuthSchemas

func RegisterAuthSchemas(r *Registry)

RegisterAuthSchemas registers all auth domain event schemas on r.

func RegisterBuiltins

func RegisterBuiltins(r *Registry)

RegisterBuiltins registers every compiled-in Ether event schema on r. Calling RegisterBuiltins more than once on the same registry is safe.

func RegisterCacheSchemas

func RegisterCacheSchemas(r *Registry)

RegisterCacheSchemas registers all built-in cache event schemas.

func RegisterClusterSchemas

func RegisterClusterSchemas(r *Registry)

RegisterClusterSchemas registers all cluster domain event schemas on r.

func RegisterFlowsSchemas

func RegisterFlowsSchemas(r *Registry)

RegisterFlowsSchemas registers all flows meta-domain event schemas on r.

func RegisterIndexerSchemas

func RegisterIndexerSchemas(r *Registry)

RegisterIndexerSchemas registers all built-in indexer event schemas.

func RegisterLibrarySchemas

func RegisterLibrarySchemas(r *Registry)

RegisterLibrarySchemas registers all library domain event schemas on r.

func RegisterLiveTVSchemas

func RegisterLiveTVSchemas(r *Registry)

RegisterLiveTVSchemas registers all built-in Live TV event schemas.

func RegisterPlaybackSchemas

func RegisterPlaybackSchemas(r *Registry)

RegisterPlaybackSchemas registers all built-in playback event schemas.

func RegisterPluginSchemas

func RegisterPluginSchemas(r *Registry)

RegisterPluginSchemas registers all plugin domain event schemas on r.

func RegisterProviderSchemas

func RegisterProviderSchemas(r *Registry)

RegisterProviderSchemas registers all built-in provider event schemas.

func RegisterResolverSchemas

func RegisterResolverSchemas(r *Registry)

RegisterResolverSchemas registers all built-in resolver event schemas.

func RegisterStruct

func RegisterStruct[T any](r *Registry, meta EventSchema) error

RegisterStruct reflects payload struct type T (reading `json` and `event` tags), merges any explicit meta.Fields overrides, and registers the resulting schema.

func RegisterSystemSchemas

func RegisterSystemSchemas(r *Registry)

RegisterSystemSchemas registers all system domain event schemas on r.

func RegisterVaultSchemas

func RegisterVaultSchemas(r *Registry)

RegisterVaultSchemas registers all built-in vault event schemas.

func RegisterViewerSchemas

func RegisterViewerSchemas(r *Registry)

RegisterViewerSchemas registers all viewer domain event schemas on r.

func ValidateType

func ValidateType(eventType string) error

ValidateType checks that eventType follows either built-in "domain.noun.verb" or plugin "plugin:<pluginId>/<key>" naming rules.

Types

type AuthCertificateRenewedPayload

type AuthCertificateRenewedPayload struct {
	Domains   []string  `json:"domains" event:"label=Domains;desc=DNS names covered by the renewed TLS certificate;example=*.1-2-3-4.abc.plex.direct"`
	Issuer    string    `json:"issuer,omitempty" event:"label=Issuer;desc=Certificate authority or subject issuer;example=R11"`
	ExpiresAt time.Time `` /* 132-byte string literal not displayed */
}

type AuthDeviceQuickConnectApprovedPayload

type AuthDeviceQuickConnectApprovedPayload struct {
	ViewerID   int64  `json:"viewerId" event:"label=Viewer ID;desc=Viewer who approved the Quick Connect pairing;example=7"`
	DeviceName string `json:"deviceName,omitempty" event:"label=Device Name;desc=Paired device name;example=Living Room TV"`
	Platform   string `json:"platform,omitempty" event:"label=Platform;desc=Paired device platform or surface;example=jellyfin"`
}

type AuthDeviceRegisteredPayload

type AuthDeviceRegisteredPayload struct {
	DeviceID             string `json:"deviceId" event:"label=Device ID;desc=Assigned Ether device identifier;example=dev_14"`
	ClientIdentifier     string `` /* 132-byte string literal not displayed */
	Name                 string `json:"name,omitempty" event:"label=Device Name;desc=Human-readable device name;example=Living Room Apple TV"`
	Platform             string `json:"platform,omitempty" event:"label=Platform;desc=Client operating system or platform;example=tvOS"`
	ViewerID             int64  `json:"viewerId,omitempty" event:"label=Viewer ID;desc=Viewer associated with the device;example=7"`
	Username             string `json:"username,omitempty" event:"label=Username;desc=Username associated with the device;pii;example=alex"`
	RemoteIP             string `json:"remoteIP,omitempty" event:"label=Remote IP;desc=Network address seen during registration;pii;example=192.168.1.44"`
	IsFirstSeenForViewer bool   `` /* 142-byte string literal not displayed */
}

type AuthGrantRevokedPayload

type AuthGrantRevokedPayload struct {
	ViewerID  int64  `json:"viewerId" event:"label=Viewer ID;desc=Viewer whose grant or session was revoked;example=7"`
	GrantKind string `json:"grantKind" event:"label=Grant Kind;desc=Scope of revoked credential;example=device"`
	Reason    string `json:"reason,omitempty" event:"label=Reason;desc=Reason for revocation;example=sign_out"`
	Actor     string `json:"actor,omitempty" event:"label=Actor;desc=Actor or subsystem that revoked the grant;example=owner"`
}

type AuthLoginFailedPayload

type AuthLoginFailedPayload struct {
	Username string `json:"username,omitempty" event:"label=Username;desc=Attempted username if provided;pii;example=alex"`
	Method   string `json:"method" event:"label=Method;desc=Authentication method attempted;example=password"`
	Reason   string `json:"reason" event:"label=Reason;desc=Failure classification;example=invalid_credentials"`
	Client   string `json:"client,omitempty" event:"label=Client;desc=Client application name;example=Ether browser"`
	Platform string `json:"platform,omitempty" event:"label=Platform;desc=Client platform;example=Web"`
	RemoteIP string `json:"remoteIP,omitempty" event:"label=Remote IP;desc=Client network address;pii;example=203.0.113.42"`
}

type AuthLoginSucceededPayload

type AuthLoginSucceededPayload struct {
	ViewerID int64  `json:"viewerId" event:"label=Viewer ID;desc=Authenticated viewer account ID;example=1"`
	Username string `json:"username" event:"label=Username;desc=Authenticated viewer username;pii;example=alex"`
	Method   string `json:"method" event:"label=Method;desc=Authentication method used;example=password"`
	Client   string `json:"client,omitempty" event:"label=Client;desc=Client application name;example=Vela"`
	Platform string `json:"platform,omitempty" event:"label=Platform;desc=Client operating system or platform;example=tvOS"`
	RemoteIP string `json:"remoteIP,omitempty" event:"label=Remote IP;desc=Client network address;pii;example=203.0.113.42"`
}

type AuthRateLimitedPayload

type AuthRateLimitedPayload struct {
	Scope     string `json:"scope" event:"label=Scope;desc=Authentication endpoint or surface that tripped rate limiting;example=login"`
	RemoteIP  string `json:"remoteIP" event:"label=Remote IP;desc=Client IP or network prefix that exceeded the limit;pii;example=203.0.113.99"`
	Attempts  int    `json:"attempts" event:"label=Attempts;desc=Number of attempts observed in the current window;example=21"`
	WindowSec int    `json:"windowSec" event:"label=Window;desc=Rate-limit sliding window duration in seconds;unit=s;example=300"`
}

type AuthSessionNewIPPayload

type AuthSessionNewIPPayload struct {
	ViewerID          int64    `json:"viewerId" event:"label=Viewer ID;desc=Viewer connecting from an unfamiliar IP;example=7"`
	Username          string   `json:"username" event:"label=Username;desc=Viewer display name or username;pii;example=alex"`
	RemoteIP          string   `json:"remoteIP" event:"label=Remote IP;desc=New network address observed;pii;example=198.51.100.24"`
	PreviousIPs       []string `` /* 139-byte string literal not displayed */
	Location          string   `json:"location" event:"label=Location;desc=Whether the new IP is on the local network or WAN;enum=lan|wan;example=wan"`
	Country           string   `json:"country,omitempty" event:"label=Country;desc=GeoIP country if available;example=US"`
	City              string   `json:"city,omitempty" event:"label=City;desc=GeoIP city if available;example=Seattle"`
	ASN               string   `json:"asn,omitempty" event:"label=ASN;desc=Autonomous system number if available;example=AS7922"`
	Org               string   `json:"org,omitempty" event:"label=Organization;desc=Network operator name if available;example=Example ISP"`
	Client            string   `json:"client,omitempty" event:"label=Client;desc=Client application name;example=Plex for iOS"`
	Platform          string   `json:"platform,omitempty" event:"label=Platform;desc=Client platform;example=iOS"`
	SessionID         string   `json:"sessionId,omitempty" event:"label=Session ID;desc=Playback or auth session identifier;example=sess_01"`
	DistinctActiveIPs int      `` /* 128-byte string literal not displayed */
}

type AuthTokenExpiredPayload

type AuthTokenExpiredPayload struct {
	Provider  string `json:"provider" event:"label=Provider;desc=External service whose token expired or was revoked;example=trakt"`
	Scope     string `json:"scope,omitempty" event:"label=Scope;desc=Integration scope affected by the expired token;example=watch_sync"`
	AccountID string `json:"accountId,omitempty" event:"label=Account ID;desc=Provider account identifier if known;example=trakt:7"`
	ViewerID  int64  `json:"viewerId,omitempty" event:"label=Viewer ID;desc=Viewer owning the expired token;example=7"`
	Username  string `json:"username,omitempty" event:"label=Username;desc=Username owning the expired token;pii;example=alex"`
	Error     string `json:"error" event:"label=Error;desc=Rejection or expiration error reported by the provider;example=refresh token revoked"`
}

type Bus

type Bus struct {
	// contains filtered or unexported fields
}

Bus is Ether's non-blocking in-process event bus. Publishers never block on slow consumers; full subscriber buffers drop the event and increment counters.

func NewBus

func NewBus(opts BusOptions) *Bus

NewBus creates an in-process event bus.

func (*Bus) Close

func (b *Bus) Close()

Close closes the bus and all active subscriber channels. It is idempotent.

func (*Bus) Publish

func (b *Bus) Publish(ev Envelope)

Publish dispatches ev to every matching subscriber without ever blocking. Missing ID, OccurredAt, Node, Source, Version and Payload fields are defaulted.

func (*Bus) PublishTyped

func (b *Bus) PublishTyped(eventType string, payload any, opts ...EnvelopeOption) error

PublishTyped marshals payload into an Envelope and publishes it non-blockingly.

func (*Bus) Stats

func (b *Bus) Stats() BusStats

Stats snapshots bus publish/drop counts and every active subscriber's state.

func (*Bus) Subscribe

func (b *Bus) Subscribe(opts SubscriptionOptions) *Subscription

Subscribe attaches a bounded subscriber matching opts.Patterns. Call Unsubscribe when done (or Close the bus) to release resources.

func (*Bus) SubscribeFunc

func (b *Bus) SubscribeFunc(ctx context.Context, opts SubscriptionOptions, fn func(context.Context, Envelope)) *Subscription

SubscribeFunc subscribes and invokes fn sequentially in a background goroutine until ctx is cancelled, Unsubscribe is called, or the bus closes. Panics in fn are recovered and logged so one subscriber cannot crash the process.

type BusOptions

type BusOptions struct {
	// NodeID stamps envelopes whose Node is empty.
	NodeID string
	// DefaultBuffer sets the default subscriber channel capacity (256 when <= 0).
	DefaultBuffer int
	// Now supplies the clock for missing OccurredAt timestamps (defaults to time.Now).
	Now func() time.Time
	// Logger receives rate-limited overload drop warnings (defaults to slog.Default()).
	Logger *slog.Logger
	// Registry, when provided, fills in default schema Version when Envelope.Version == 0.
	Registry *Registry
	// OnDrop is invoked (synchronously, must not block) whenever a subscriber
	// buffer overflows and an event is dropped.
	OnDrop func(subscriber string, ev Envelope)
}

BusOptions configures an in-process Bus.

type BusStats

type BusStats struct {
	Published   uint64            `json:"published"`
	Dropped     uint64            `json:"dropped"`
	Subscribers []SubscriberStats `json:"subscribers"`
}

BusStats summarizes total bus traffic and every active subscriber.

type CacheBudgetFullPayload

type CacheBudgetFullPayload struct {
	CacheKind   string  `json:"cacheKind" event:"label=Cache kind;example=segment"`
	UsedBytes   int64   `json:"usedBytes" event:"label=Used bytes;unit=bytes;example=53687091200"`
	BudgetBytes int64   `json:"budgetBytes" event:"label=Budget bytes;unit=bytes;example=53687091200"`
	PercentUsed float64 `json:"percentUsed" event:"label=Percent used;unit=%;example=100"`
}

CacheBudgetFullPayload is emitted when cache usage reaches or exceeds its configured budget.

type CacheBudgetRecoveredPayload

type CacheBudgetRecoveredPayload struct {
	CacheKind   string  `json:"cacheKind" event:"label=Cache kind;example=segment"`
	UsedBytes   int64   `json:"usedBytes" event:"label=Used bytes;unit=bytes;example=45097156608"`
	BudgetBytes int64   `json:"budgetBytes" event:"label=Budget bytes;unit=bytes;example=53687091200"`
	PercentUsed float64 `json:"percentUsed" event:"label=Percent used;unit=%;example=84"`
}

CacheBudgetRecoveredPayload is emitted when cache usage falls back below the full threshold.

type CacheEvictionSpikePayload

type CacheEvictionSpikePayload struct {
	CacheKind      string `json:"cacheKind" event:"label=Cache kind;example=segment"`
	EvictedBytes   int64  `json:"evictedBytes" event:"label=Evicted bytes;unit=bytes;example=2147483648"`
	EvictedEntries int    `json:"evictedEntries" event:"label=Evicted entries;example=512"`
	WindowSec      int    `json:"windowSec" event:"label=Window duration;unit=s;example=60"`
}

CacheEvictionSpikePayload is emitted when cache eviction volume spikes over a short window.

type CachePrefetchCompletedPayload

type CachePrefetchCompletedPayload struct {
	TitleKey    string `json:"titleKey,omitempty" event:"label=Title key;example=episode:12345"`
	TitleName   string `json:"titleName,omitempty" event:"label=Title name;example=Severance S01E02"`
	Kind        string `json:"kind" event:"label=Prefetch kind;example=next_episode"`
	BytesWarmed int64  `json:"bytesWarmed,omitempty" event:"label=Bytes warmed;unit=bytes;example=67108864"`
	DurationMS  int64  `json:"durationMs" event:"label=Prefetch duration;duration_ms;unit=ms;example=2350"`
}

CachePrefetchCompletedPayload is emitted when a prefetch job finishes warming data.

type CachePrefetchFailedPayload

type CachePrefetchFailedPayload struct {
	TitleKey  string `json:"titleKey,omitempty" event:"label=Title key;example=episode:12345"`
	TitleName string `json:"titleName,omitempty" event:"label=Title name;example=Severance S01E02"`
	Kind      string `json:"kind" event:"label=Prefetch kind;example=next_episode"`
	Error     string `json:"error" event:"label=Error message;example=indexer budget exhausted"`
}

CachePrefetchFailedPayload is emitted when a prefetch job fails.

type ClusterDatabaseRecoveredPayload

type ClusterDatabaseRecoveredPayload struct {
	Dialect          string `json:"dialect" event:"label=Dialect;desc=Database backend dialect;example=postgres"`
	OutageDurationMS int64  `` /* 146-byte string literal not displayed */
	ReplayedWrites   int64  `json:"replayedWrites" event:"label=Replayed Writes;desc=Count of held writes flushed on recovery;example=14"`
}

type ClusterDatabaseUnavailablePayload

type ClusterDatabaseUnavailablePayload struct {
	Dialect string `json:"dialect" event:"label=Dialect;desc=Database backend dialect;example=postgres"`
	Error   string `json:"error" event:"label=Error;desc=Last database connectivity error;example=connection refused"`
}

type ClusterLeaderElectedPayload

type ClusterLeaderElectedPayload struct {
	LeaderNodeID     string `json:"leaderNodeId" event:"label=Leader Node ID;desc=Node identifier of the newly elected leader;example=node-a"`
	LeaderName       string `json:"leaderName" event:"label=Leader Name;desc=Display name of the newly elected leader;example=media-1"`
	Epoch            int64  `json:"epoch" event:"label=Epoch;desc=Monotonic leadership term number;example=12"`
	PreviousLeaderID string `` /* 131-byte string literal not displayed */
}

type ClusterNodeDrainingPayload

type ClusterNodeDrainingPayload struct {
	NodeID         string `json:"nodeId" event:"label=Node ID;desc=Unique identifier of the draining node;example=node-a"`
	NodeName       string `json:"nodeName" event:"label=Node Name;desc=Display name of the draining node;example=media-1"`
	Reason         string `json:"reason" event:"label=Reason;desc=Reason the node entered drain mode;example=rolling_update"`
	ActiveSessions int    `json:"activeSessions" event:"label=Active Sessions;desc=Number of playback sessions still active on the node;example=3"`
}

type ClusterNodeJoinedPayload

type ClusterNodeJoinedPayload struct {
	NodeID      string   `json:"nodeId" event:"label=Node ID;desc=Unique cluster node identifier;example=node-b"`
	NodeName    string   `json:"nodeName" event:"label=Node Name;desc=Display name of the joining node;example=media-2"`
	Version     string   `json:"version,omitempty" event:"label=Version;desc=Ether version running on the node;example=0.3.17"`
	Roles       []string `json:"roles,omitempty" event:"label=Roles;desc=Roles advertised by the node;example=server,worker"`
	MemberCount int      `json:"memberCount" event:"label=Member Count;desc=Live cluster members after the join;example=2"`
}

type ClusterNodeLostPayload

type ClusterNodeLostPayload struct {
	NodeID      string   `json:"nodeId" event:"label=Node ID;desc=Unique identifier of the lost node;example=node-b"`
	NodeName    string   `json:"nodeName" event:"label=Node Name;desc=Display name of the lost node;example=media-2"`
	LastSeenMS  int64    `` /* 139-byte string literal not displayed */
	Roles       []string `json:"roles,omitempty" event:"label=Roles;desc=Roles held by the lost node;example=worker"`
	MemberCount int      `json:"memberCount" event:"label=Member Count;desc=Remaining live cluster members;example=1"`
}

type Correlation

type Correlation struct {
	// Key overrides the derived correlation key when explicitly set.
	Key       string `json:"key,omitempty"`
	SessionID string `json:"sessionId,omitempty"`
	PlayID    string `json:"playId,omitempty"`
	TitleID   string `json:"titleId,omitempty"`
	ViewerID  int64  `json:"viewerId,omitempty"`
	ChannelID string `json:"channelId,omitempty"`
	SourceID  string `json:"sourceId,omitempty"`
	PluginID  string `json:"pluginId,omitempty"`
	DeviceID  string `json:"deviceId,omitempty"`
	LibraryID string `json:"libraryId,omitempty"`
}

Correlation links related events across playback, Live TV, viewers, libraries and plugins so flows can order runs and match wait_event nodes accurately.

func (Correlation) EffectiveKey

func (c Correlation) EffectiveKey(fallbackNode, fallbackID string) string

EffectiveKey returns the stable correlation key used for per-key ordering and wait_event matching.

func (Correlation) ToMap

func (c Correlation) ToMap() map[string]any

ToMap returns correlation fields as a plain map for condition evaluation and template rendering.

type EnumOption

type EnumOption struct {
	Value string `json:"value"`
	Label string `json:"label,omitempty"`
}

EnumOption describes one allowed value of a FieldEnum field.

type Envelope

type Envelope struct {
	ID          string          `json:"id"`
	Type        string          `json:"type"`
	Version     int             `json:"version"`
	OccurredAt  time.Time       `json:"occurredAt"`
	Node        string          `json:"node,omitempty"`
	Source      string          `json:"source,omitempty"`
	Correlation Correlation     `json:"correlation,omitempty"`
	Meta        EnvelopeMeta    `json:"meta,omitempty"`
	Payload     json.RawMessage `json:"payload"`
}

Envelope is the canonical wire and in-process container for every Ether event.

func NewEnvelope

func NewEnvelope(eventType string, payload any, opts ...EnvelopeOption) (Envelope, error)

NewEnvelope marshals payload into an Envelope for eventType.

func (Envelope) CorrelationKey

func (e Envelope) CorrelationKey() string

CorrelationKey returns the envelope's effective correlation key.

func (Envelope) MetaMap

func (e Envelope) MetaMap() map[string]any

MetaMap returns the envelope's non-payload metadata as a plain map for condition evaluation and template interpolation under the "event" root.

func (Envelope) PayloadMap

func (e Envelope) PayloadMap() (map[string]any, error)

PayloadMap decodes ev.Payload into a map[string]any, preserving integer precision via json.Number.

type EnvelopeMeta

type EnvelopeMeta struct {
	// Durable hints that the event should be written to events_outbox even if
	// no live local subscriber is attached.
	Durable bool `json:"durable,omitempty"`
	// FlowDepth counts how many nested flow executions produced this event.
	// The flow runtime refuses to trigger new flows once FlowDepth reaches its cap.
	FlowDepth int `json:"flowDepth,omitempty"`
	// OriginRunID identifies the flow run that caused this event, if any.
	OriginRunID string `json:"originRunId,omitempty"`
	// DryRun marks synthetic test-run events; normal bus subscribers skip them.
	DryRun bool `json:"dryRun,omitempty"`
}

EnvelopeMeta carries runtime delivery hints and loop-protection metadata.

type EnvelopeOption

type EnvelopeOption func(*Envelope)

EnvelopeOption customizes an Envelope built by NewEnvelope or Bus.PublishTyped.

func WithCorrelation

func WithCorrelation(c Correlation) EnvelopeOption

WithCorrelation attaches structured correlation IDs to the event.

func WithDurable

func WithDurable() EnvelopeOption

WithDurable marks the envelope as durable.

func WithID

func WithID(id string) EnvelopeOption

WithID sets an explicit event ID.

func WithMeta

func WithMeta(m EnvelopeMeta) EnvelopeOption

WithMeta sets envelope delivery and loop-protection metadata.

func WithNode

func WithNode(node string) EnvelopeOption

WithNode sets the origin node ID.

func WithOccurredAt

func WithOccurredAt(t time.Time) EnvelopeOption

WithOccurredAt sets the event timestamp.

func WithSource

func WithSource(src string) EnvelopeOption

WithSource sets the event source ("ether" or "plugin:<id>").

func WithVersion

func WithVersion(v int) EnvelopeOption

WithVersion sets the event schema version.

type EventSchema

type EventSchema struct {
	Type        string        `json:"type"`
	Version     int           `json:"version"`
	Domain      string        `json:"domain"`
	Label       string        `json:"label"`
	Description string        `json:"description,omitempty"`
	Owner       string        `json:"owner"`
	Critical    bool          `json:"critical,omitempty"`
	Deprecated  bool          `json:"deprecated,omitempty"`
	ReplacedBy  string        `json:"replacedBy,omitempty"`
	LegacyNames []string      `json:"legacyNames,omitempty"`
	Fields      []FieldSchema `json:"fields"`
	Sample      any           `json:"sample,omitempty"`
}

EventSchema defines one event type in the catalogue: its metadata, version, typed payload fields, legacy aliases, and sample payload.

func (EventSchema) Field

func (s EventSchema) Field(path string) (FieldSchema, bool)

Field returns the schema for a dotted field path inside the event payload.

func (EventSchema) Redact

func (s EventSchema) Redact(payload map[string]any, opts RedactOptions) map[string]any

Redact returns a deep copy of payload with Secret fields masked and (when opts.StripPII is set) PII fields removed.

func (EventSchema) Validate

func (s EventSchema) Validate() error

Validate checks that s is well-formed and self-consistent.

type FieldSchema

type FieldSchema struct {
	Name        string       `json:"name"`
	Type        FieldType    `json:"type"`
	Label       string       `json:"label"`
	Description string       `json:"description,omitempty"`
	Unit        string       `json:"unit,omitempty"`
	Enum        []EnumOption `json:"enum,omitempty"`
	PII         bool         `json:"pii,omitempty"`
	Secret      bool         `json:"secret,omitempty"`
	Filterable  bool         `json:"filterable,omitempty"`
	Example     any          `json:"example,omitempty"`
}

FieldSchema describes one typed field inside an event payload.

func (FieldSchema) HasEnumValue

func (f FieldSchema) HasEnumValue(v string) bool

HasEnumValue reports whether v is one of the field's declared enum values.

type FieldType

type FieldType string

FieldType classifies a typed field in an event payload or flow action parameter.

const (
	FieldString     FieldType = "string"
	FieldInt        FieldType = "int"
	FieldFloat      FieldType = "float"
	FieldBool       FieldType = "bool"
	FieldDurationMS FieldType = "duration_ms"
	FieldTimestamp  FieldType = "timestamp"
	FieldEnum       FieldType = "enum"
	FieldStringList FieldType = "string_list"
	FieldObject     FieldType = "object"
)

func (FieldType) Valid

func (t FieldType) Valid() bool

Valid reports whether t is a recognized FieldType.

type FlowsBusDroppedPayload

type FlowsBusDroppedPayload struct {
	Subscriber   string `json:"subscriber" event:"label=Subscriber;desc=Name of the slow event bus subscriber;example=flows-engine"`
	EventType    string `json:"eventType" event:"label=Event Type;desc=Type of the event that was dropped;example=library.title.added"`
	DroppedTotal uint64 `json:"droppedTotal" event:"label=Dropped Total;desc=Cumulative count of dropped events for this subscriber;example=1"`
	Capacity     int    `json:"capacity" event:"label=Capacity;desc=Buffer capacity of the subscriber channel;example=256"`
}

type FlowsDigestScheduledPayload

type FlowsDigestScheduledPayload struct {
	Period        string    `json:"period" event:"label=Period;desc=Digest schedule cadence;example=weekly"`
	WindowStart   time.Time `` /* 128-byte string literal not displayed */
	WindowEnd     time.Time `json:"windowEnd,omitzero" event:"label=Window End;desc=End of the summarized activity window;example=2026-11-19T00:00:00Z"`
	TotalPlays    int       `json:"totalPlays" event:"label=Total Plays;desc=Total completed plays during the window;example=42"`
	UniqueViewers int       `json:"uniqueViewers" event:"label=Unique Viewers;desc=Count of distinct viewers active during the window;example=4"`
}

type FlowsFlowAutoDisabledPayload

type FlowsFlowAutoDisabledPayload struct {
	FlowID              string `json:"flowId" event:"label=Flow ID;desc=Identifier of the disabled flow;example=flow_notify_discord"`
	FlowName            string `json:"flowName" event:"label=Flow Name;desc=Display name of the disabled flow;example=Notify Discord on New Releases"`
	ConsecutiveFailures int    `json:"consecutiveFailures" event:"label=Consecutive Failures;desc=Failure count that tripped auto-disable;example=20"`
	LastError           string `` /* 126-byte string literal not displayed */
}

type FlowsRunFailedPayload

type FlowsRunFailedPayload struct {
	FlowID              string `json:"flowId" event:"label=Flow ID;desc=Identifier of the flow whose run failed;example=flow_notify_discord"`
	FlowName            string `json:"flowName" event:"label=Flow Name;desc=Display name of the flow;example=Notify Discord on New Releases"`
	RunID               string `json:"runId" event:"label=Run ID;desc=Identifier of the failed flow execution;example=run_01JABC"`
	NodeID              string `json:"nodeId,omitempty" event:"label=Node ID;desc=Graph node that failed;example=node_webhook_1"`
	Error               string `json:"error" event:"label=Error;desc=Error message reported by the failed node;example=webhook returned HTTP 500"`
	ConsecutiveFailures int    `json:"consecutiveFailures" event:"label=Consecutive Failures;desc=Count of consecutive failed runs for this flow;example=3"`
}

type IndexerBudgetExhaustedPayload

type IndexerBudgetExhaustedPayload struct {
	IndexerID   string     `json:"indexerId" event:"label=Indexer ID;example=idx_nzbgeek"`
	IndexerName string     `json:"indexerName" event:"label=Indexer name;example=NZBGeek"`
	Metric      string     `json:"metric" event:"label=Budget metric;enum=hits|grabs;example=hits"`
	Used        int        `json:"used" event:"label=Used count;example=1000"`
	Limit       int        `json:"limit" event:"label=Daily limit;example=1000"`
	ResetsAt    *time.Time `json:"resetsAt,omitempty" event:"label=Budget resets at;example=2026-11-20T00:00:00Z"`
}

IndexerBudgetExhaustedPayload is emitted when an indexer's daily budget is exhausted.

type IndexerBudgetWarningPayload

type IndexerBudgetWarningPayload struct {
	IndexerID   string  `json:"indexerId" event:"label=Indexer ID;example=idx_nzbgeek"`
	IndexerName string  `json:"indexerName" event:"label=Indexer name;example=NZBGeek"`
	Metric      string  `json:"metric" event:"label=Budget metric;enum=hits|grabs;example=hits"`
	Used        int     `json:"used" event:"label=Used count;example=800"`
	Limit       int     `json:"limit" event:"label=Daily limit;example=1000"`
	PercentUsed float64 `json:"percentUsed" event:"label=Percent used;unit=%;example=80"`
}

IndexerBudgetWarningPayload is emitted when an indexer's daily hit or grab budget crosses the warning threshold.

type IndexerRateLimitedPayload

type IndexerRateLimitedPayload struct {
	IndexerID    string `json:"indexerId" event:"label=Indexer ID;example=idx_nzbgeek"`
	IndexerName  string `json:"indexerName" event:"label=Indexer name;example=NZBGeek"`
	RetryAfterMS int64  `json:"retryAfterMs" event:"label=Retry after;duration_ms;unit=ms;example=60000"`
	StatusCode   int    `json:"statusCode,omitempty" event:"label=HTTP status code;example=429"`
}

IndexerRateLimitedPayload is emitted when an indexer returns a rate-limit response.

type IndexerRequestFailedPayload

type IndexerRequestFailedPayload struct {
	IndexerID   string `json:"indexerId" event:"label=Indexer ID;example=idx_nzbgeek"`
	IndexerName string `json:"indexerName" event:"label=Indexer name;example=NZBGeek"`
	Kind        string `json:"kind" event:"label=Request kind;example=search"`
	StatusCode  int    `json:"statusCode,omitempty" event:"label=HTTP status code;example=503"`
	Error       string `json:"error" event:"label=Error message;example=indexer returned HTTP 503"`
	LatencyMS   int64  `json:"latencyMs,omitempty" event:"label=Latency;duration_ms;unit=ms;example=1240"`
}

IndexerRequestFailedPayload is emitted when an indexer search or fetch request fails.

type IndexerServiceOutagePayload

type IndexerServiceOutagePayload struct {
	IndexerID           string `json:"indexerId" event:"label=Indexer ID;example=idx_nzbgeek"`
	IndexerName         string `json:"indexerName" event:"label=Indexer name;example=NZBGeek"`
	Kind                string `json:"kind,omitempty" event:"label=Indexer kind;example=newznab"`
	ConsecutiveFailures int    `json:"consecutiveFailures" event:"label=Consecutive failures;example=3"`
	Error               string `json:"error" event:"label=Error message;example=connection timed out"`
}

IndexerServiceOutagePayload is emitted when an indexer trips its circuit breaker.

type IndexerServiceRecoveredPayload

type IndexerServiceRecoveredPayload struct {
	IndexerID        string `json:"indexerId" event:"label=Indexer ID;example=idx_nzbgeek"`
	IndexerName      string `json:"indexerName" event:"label=Indexer name;example=NZBGeek"`
	Kind             string `json:"kind,omitempty" event:"label=Indexer kind;example=newznab"`
	OutageDurationMS int64  `json:"outageDurationMs" event:"label=Outage duration;duration_ms;unit=ms;example=305000"`
}

IndexerServiceRecoveredPayload is emitted when an indexer recovers from an outage.

type LibraryBatchAddedPayload

type LibraryBatchAddedPayload struct {
	LibraryID    string   `json:"libraryId" event:"label=Library ID;desc=Identifier of the library that received the batch;example=catalog"`
	LibraryName  string   `json:"libraryName" event:"label=Library Name;desc=Display name of the library;example=TV Shows"`
	MediaType    string   `` /* 146-byte string literal not displayed */
	ShowKey      string   `json:"showKey,omitempty" event:"label=Show Key;desc=Series key when the batch groups episodes of one show;example=show:95396"`
	ShowTitle    string   `` /* 130-byte string literal not displayed */
	Season       int      `json:"season,omitempty" event:"label=Season;desc=Season number when the batch groups one season;example=2"`
	EpisodeCount int      `json:"episodeCount,omitempty" event:"label=Episode Count;desc=Number of episodes included in the batch;example=8"`
	ItemCount    int      `json:"itemCount" event:"label=Item Count;desc=Total number of newly added items in the batch;example=8"`
	TitleNames   []string `` /* 148-byte string literal not displayed */
	WindowSec    int      `json:"windowSec" event:"label=Window;desc=Debounce aggregation window in seconds;unit=s;example=15"`
	PosterURL    string   `` /* 128-byte string literal not displayed */
}

type LibraryCollectionRebuiltPayload

type LibraryCollectionRebuiltPayload struct {
	CollectionID   string `json:"collectionId" event:"label=Collection ID;desc=Identifier of the rebuilt collection;example=trending-movies"`
	CollectionName string `json:"collectionName" event:"label=Collection Name;desc=Display name of the collection;example=Trending Movies"`
	SourceKind     string `json:"sourceKind" event:"label=Source Kind;desc=Primary source kind populating the collection;example=tmdb_trending"`
	ItemCount      int    `json:"itemCount" event:"label=Item Count;desc=Total titles in the collection after rebuild;example=40"`
	Added          int    `json:"added" event:"label=Added;desc=Number of titles newly added to the collection;example=5"`
	Removed        int    `json:"removed" event:"label=Removed;desc=Number of titles removed from the collection;example=3"`
	DurationMS     int64  `` /* 130-byte string literal not displayed */
}

type LibraryEpisodeAiredPayload

type LibraryEpisodeAiredPayload struct {
	ShowKey       string `json:"showKey" event:"label=Show Key;desc=Canonical rating key of the series;example=show:95396"`
	ShowTitle     string `json:"showTitle" event:"label=Show Title;desc=Name of the series;example=Severance"`
	EpisodeKey    string `json:"episodeKey" event:"label=Episode Key;desc=Canonical rating key of the newly aired episode;example=episode:95396:2:1"`
	EpisodeTitle  string `json:"episodeTitle" event:"label=Episode Title;desc=Title of the newly aired episode;example=Hello Ms. Cobel"`
	Season        int    `json:"season" event:"label=Season;desc=Season number;example=2"`
	Episode       int    `json:"episode" event:"label=Episode;desc=Episode number;example=1"`
	AirDate       string `json:"airDate,omitempty" event:"label=Air Date;desc=ISO calendar air date of the episode;example=2025-01-17"`
	FollowerCount int    `json:"followerCount" event:"label=Follower Count;desc=Number of household viewers following this show;example=3"`
}

type LibraryMetadataFailedPayload

type LibraryMetadataFailedPayload struct {
	Provider  string `json:"provider" event:"label=Provider;desc=Metadata provider that returned an error;example=tmdb"`
	TitleKey  string `json:"titleKey" event:"label=Title Key;desc=Canonical rating key whose metadata fetch failed;example=movie:603"`
	MediaType string `json:"mediaType" event:"label=Media Type;desc=Type of item being fetched;enum=movie|show|season|episode|other;example=movie"`
	Error     string `json:"error" event:"label=Error;desc=Failure reason returned by the metadata provider;example=upstream status 502"`
}

type LibrarySyncCompletedPayload

type LibrarySyncCompletedPayload struct {
	LibraryID   string `json:"libraryId" event:"label=Library ID;desc=Identifier of the library that finished syncing;example=catalog"`
	LibraryName string `json:"libraryName" event:"label=Library Name;desc=Display name of the library;example=Catalog"`
	SourceKind  string `json:"sourceKind" event:"label=Source Kind;desc=Backing sync provider kind;example=tmdb"`
	Added       int    `json:"added" event:"label=Added;desc=Number of items added during sync;example=24"`
	Updated     int    `json:"updated" event:"label=Updated;desc=Number of items updated during sync;example=110"`
	Removed     int    `json:"removed" event:"label=Removed;desc=Number of items removed during sync;example=2"`
	DurationMS  int64  `json:"durationMs" event:"label=Duration;desc=Total sync duration in milliseconds;duration_ms;unit=ms;example=4250"`
}

type LibrarySyncFailedPayload

type LibrarySyncFailedPayload struct {
	LibraryID   string `json:"libraryId" event:"label=Library ID;desc=Identifier of the library whose sync failed;example=catalog"`
	LibraryName string `json:"libraryName" event:"label=Library Name;desc=Display name of the library;example=Catalog"`
	SourceKind  string `json:"sourceKind" event:"label=Source Kind;desc=Backing sync provider kind;example=tmdb"`
	Error       string `json:"error" event:"label=Error;desc=Error reported by the sync pass;example=tmdb rate limit exceeded"`
}

type LibrarySyncStartedPayload

type LibrarySyncStartedPayload struct {
	LibraryID   string `json:"libraryId" event:"label=Library ID;desc=Identifier of the library being synced;example=catalog"`
	LibraryName string `json:"libraryName" event:"label=Library Name;desc=Display name of the library;example=Catalog"`
	SourceKind  string `json:"sourceKind" event:"label=Source Kind;desc=Backing sync provider kind;example=tmdb"`
	Trigger     string `` /* 126-byte string literal not displayed */
}

type LibraryTitleAddedPayload

type LibraryTitleAddedPayload struct {
	LibraryID   string   `json:"libraryId" event:"label=Library ID;desc=Identifier of the library that received the title;example=catalog"`
	LibraryName string   `json:"libraryName" event:"label=Library Name;desc=Display name of the library;example=Movies"`
	TitleKey    string   `json:"titleKey" event:"label=Title Key;desc=Canonical Ether rating key for the title;example=movie:603"`
	TitleName   string   `json:"titleName" event:"label=Title Name;desc=Title or episode name;example=The Matrix"`
	ShowTitle   string   `json:"showTitle,omitempty" event:"label=Show Title;desc=Parent series title for seasons and episodes;example=Severance"`
	Season      int      `json:"season,omitempty" event:"label=Season;desc=Season number for television items;example=2"`
	Episode     int      `json:"episode,omitempty" event:"label=Episode;desc=Episode number for television episodes;example=1"`
	MediaType   string   `json:"mediaType" event:"label=Media Type;desc=Type of library item added;enum=movie|show|season|episode|other;example=movie"`
	Year        int      `json:"year,omitempty" event:"label=Year;desc=Release year;example=1999"`
	Genres      []string `json:"genres,omitempty" event:"label=Genres;desc=Genres associated with the title;example=Action,Science Fiction"`
	PosterURL   string   `json:"posterUrl,omitempty" event:"label=Poster URL;desc=Poster artwork URL or path;example=/library/metadata/603/thumb"`
}

type LibraryTitleAvailablePayload

type LibraryTitleAvailablePayload struct {
	TitleKey       string `json:"titleKey" event:"label=Title Key;desc=Canonical rating key of the title;example=movie:603"`
	TitleName      string `json:"titleName" event:"label=Title Name;desc=Display title that became playable;example=The Matrix"`
	MediaType      string `json:"mediaType" event:"label=Media Type;desc=Type of media item;enum=movie|show|season|episode|other;example=movie"`
	Year           int    `json:"year,omitempty" event:"label=Year;desc=Release year;example=1999"`
	Source         string `json:"source" event:"label=Source;desc=Subsystem that established availability;example=watchlist"`
	WatchedByCount int    `json:"watchedByCount,omitempty" event:"label=Watchlist Count;desc=Number of viewers tracking this title;example=2"`
}

type LibraryTitleUnavailablePayload

type LibraryTitleUnavailablePayload struct {
	TitleKey  string `json:"titleKey" event:"label=Title Key;desc=Canonical rating key of the title;example=movie:603"`
	TitleName string `json:"titleName" event:"label=Title Name;desc=Display title that lost playability;example=The Matrix"`
	MediaType string `json:"mediaType" event:"label=Media Type;desc=Type of media item;enum=movie|show|season|episode|other;example=movie"`
	Reason    string `json:"reason" event:"label=Reason;desc=Reason the title is no longer playable;example=no healthy releases available"`
}

type LibraryWatchlistSyncedPayload

type LibraryWatchlistSyncedPayload struct {
	Provider   string `json:"provider" event:"label=Provider;desc=Watchlist provider synced;example=plex"`
	ViewerID   int64  `json:"viewerId" event:"label=Viewer ID;desc=Household viewer whose watchlist was synced;example=1"`
	Added      int    `json:"added" event:"label=Added;desc=Number of newly added watchlist items;example=3"`
	Removed    int    `json:"removed" event:"label=Removed;desc=Number of removed watchlist items;example=1"`
	TotalItems int    `json:"totalItems" event:"label=Total Items;desc=Total watchlist items tracked after sync;example=28"`
	DurationMS int64  `json:"durationMs" event:"label=Duration;desc=Sync duration in milliseconds;duration_ms;unit=ms;example=640"`
}

type LiveTVChannelStoppedPayload

type LiveTVChannelStoppedPayload struct {
	ChannelID   string `json:"channelId" event:"label=Channel ID;example=ch_espn"`
	ChannelName string `json:"channelName" event:"label=Channel name;example=ESPN HD"`
	SourceID    string `json:"sourceId,omitempty" event:"label=Stream source ID;example=src_primary"`
	ViewerID    int64  `json:"viewerId,omitempty" event:"label=Viewer ID;example=42"`
	WatchedMS   int64  `json:"watchedMs" event:"label=Watched duration;duration_ms;unit=ms;example=1800000"`
	BytesServed int64  `json:"bytesServed,omitempty" event:"label=Bytes served;unit=bytes;example=640000000"`
	Mode        string `json:"mode,omitempty" event:"label=Playout mode;example=broadcast"`
}

LiveTVChannelStoppedPayload is emitted when a Live TV channel session ends.

type LiveTVChannelTunedPayload

type LiveTVChannelTunedPayload struct {
	ChannelID     string `json:"channelId" event:"label=Channel ID;example=ch_espn"`
	ChannelName   string `json:"channelName" event:"label=Channel name;example=ESPN HD"`
	ChannelNumber string `json:"channelNumber,omitempty" event:"label=Channel number;example=206"`
	SourceID      string `json:"sourceId,omitempty" event:"label=Stream source ID;example=src_primary"`
	ProviderID    string `json:"providerId,omitempty" event:"label=Provider ID;example=prov_iptv_1"`
	Mode          string `json:"mode,omitempty" event:"label=Playout mode;example=broadcast"`
	ViewerID      int64  `json:"viewerId,omitempty" event:"label=Viewer ID;example=42"`
	Username      string `json:"username,omitempty" event:"label=Viewer username;pii;example=alex"`
	Client        string `json:"client,omitempty" event:"label=Client;example=Vela tvOS"`
}

LiveTVChannelTunedPayload is emitted when a viewer tunes a Live TV channel.

type LiveTVGuideFailedPayload

type LiveTVGuideFailedPayload struct {
	SourceID   string  `json:"sourceId" event:"label=Source ID;example=prov_iptv_1"`
	SourceName string  `json:"sourceName,omitempty" event:"label=Source name;example=Primary IPTV"`
	Error      string  `json:"error" event:"label=Error message;example=HTTP 502 fetching XMLTV guide"`
	StaleHours float64 `json:"staleHours,omitempty" event:"label=Guide staleness;unit=h;example=14.5"`
}

LiveTVGuideFailedPayload is emitted when a Live TV guide/source refresh fails.

type LiveTVGuideRefreshedPayload

type LiveTVGuideRefreshedPayload struct {
	SourceID   string `json:"sourceId" event:"label=Source ID;example=prov_iptv_1"`
	SourceName string `json:"sourceName,omitempty" event:"label=Source name;example=Primary IPTV"`
	Channels   int    `json:"channels" event:"label=Channels;example=240"`
	Programs   int    `json:"programs" event:"label=Programs;example=14800"`
	DurationMS int64  `json:"durationMs" event:"label=Refresh duration;duration_ms;unit=ms;example=3250"`
}

LiveTVGuideRefreshedPayload is emitted when a Live TV guide/source refresh completes.

type LiveTVInputLostPayload

type LiveTVInputLostPayload struct {
	ChannelID   string `json:"channelId" event:"label=Channel ID;example=ch_espn"`
	ChannelName string `json:"channelName,omitempty" event:"label=Channel name;example=ESPN HD"`
	SourceID    string `json:"sourceId,omitempty" event:"label=Stream source ID;example=src_primary"`
	Transport   string `json:"transport,omitempty" event:"label=Upstream transport;example=hls"`
	Reconnects  int    `json:"reconnects" event:"label=Reconnect attempts;example=3"`
	Error       string `json:"error" event:"label=Error message;example=upstream EOF after reconnect limit"`
	HasBackup   bool   `json:"hasBackup" event:"label=Backup source available;example=true"`
}

LiveTVInputLostPayload is emitted when a live channel input fails terminally.

type LiveTVInputRecoveredPayload

type LiveTVInputRecoveredPayload struct {
	ChannelID   string `json:"channelId" event:"label=Channel ID;example=ch_espn"`
	ChannelName string `json:"channelName,omitempty" event:"label=Channel name;example=ESPN HD"`
	SourceID    string `json:"sourceId,omitempty" event:"label=Stream source ID;example=src_primary"`
	Transport   string `json:"transport,omitempty" event:"label=Upstream transport;example=hls"`
	DowntimeMS  int64  `json:"downtimeMs" event:"label=Downtime;duration_ms;unit=ms;example=4200"`
	Reconnects  int    `json:"reconnects" event:"label=Reconnect attempts;example=1"`
}

LiveTVInputRecoveredPayload is emitted when a stalled live input resumes delivering media.

type LiveTVInputStalledPayload

type LiveTVInputStalledPayload struct {
	ChannelID      string `json:"channelId" event:"label=Channel ID;example=ch_espn"`
	ChannelName    string `json:"channelName,omitempty" event:"label=Channel name;example=ESPN HD"`
	SourceID       string `json:"sourceId,omitempty" event:"label=Stream source ID;example=src_primary"`
	Transport      string `json:"transport,omitempty" event:"label=Upstream transport;example=hls"`
	DataAgeMS      int64  `json:"dataAgeMs" event:"label=Data age;duration_ms;unit=ms;example=8500"`
	ReserveDepthMS int64  `json:"reserveDepthMs" event:"label=Reserve depth;duration_ms;unit=ms;example=2000"`
	StallAfterMS   int64  `json:"stallAfterMs" event:"label=Stall threshold;duration_ms;unit=ms;example=8000"`
	Reconnects     int    `json:"reconnects" event:"label=Reconnect attempts;example=1"`
}

LiveTVInputStalledPayload is emitted when an upstream live input stalls.

type LiveTVProviderAuthFailedPayload

type LiveTVProviderAuthFailedPayload struct {
	ProviderID   string `json:"providerId" event:"label=Provider ID;example=prov_iptv_1"`
	ProviderName string `json:"providerName,omitempty" event:"label=Provider name;example=Primary IPTV"`
	AccountID    string `json:"accountId,omitempty" event:"label=Account ID;example=acct_1"`
	StatusCode   int    `json:"statusCode,omitempty" event:"label=HTTP status code;example=401"`
	Error        string `json:"error" event:"label=Error message;example=provider rejected credentials"`
}

LiveTVProviderAuthFailedPayload is emitted when a Live TV provider rejects credentials.

type LiveTVProviderLimitReachedPayload

type LiveTVProviderLimitReachedPayload struct {
	ProviderID        string `json:"providerId" event:"label=Provider ID;example=prov_iptv_1"`
	ProviderName      string `json:"providerName,omitempty" event:"label=Provider name;example=Primary IPTV"`
	ActiveConnections int    `json:"activeConnections" event:"label=Active connections;example=2"`
	MaxConnections    int    `json:"maxConnections" event:"label=Max connections;example=2"`
	ChannelID         string `json:"channelId,omitempty" event:"label=Requested channel ID;example=ch_espn"`
}

LiveTVProviderLimitReachedPayload is emitted when a provider's concurrent tuner limit is saturated.

type LiveTVSourceCooldownPayload

type LiveTVSourceCooldownPayload struct {
	ChannelID  string     `json:"channelId" event:"label=Channel ID;example=ch_espn"`
	SourceID   string     `json:"sourceId" event:"label=Stream source ID;example=src_primary"`
	Failures   int        `json:"failures" event:"label=Consecutive failures;example=2"`
	ErrorClass string     `json:"errorClass,omitempty" event:"label=Error class;example=timeout"`
	RetryAfter *time.Time `json:"retryAfter,omitempty" event:"label=Retry after;example=2026-11-19T12:05:00Z"`
}

LiveTVSourceCooldownPayload is emitted when a stream source enters backoff cooldown.

type LiveTVSourceDegradedPayload

type LiveTVSourceDegradedPayload struct {
	ChannelID        string  `json:"channelId" event:"label=Channel ID;example=ch_espn"`
	ChannelName      string  `json:"channelName,omitempty" event:"label=Channel name;example=ESPN HD"`
	SourceID         string  `json:"sourceId" event:"label=Stream source ID;example=src_primary"`
	DamagePerHour    float64 `json:"damagePerHour" event:"label=Damage per hour;example=6.5"`
	StallsPerHour    float64 `json:"stallsPerHour" event:"label=Stalls per hour;example=4.2"`
	MaxKeyframeGapMS int64   `json:"maxKeyframeGapMs" event:"label=Max keyframe gap;duration_ms;unit=ms;example=9200"`
	MediaSec         float64 `json:"mediaSec" event:"label=Observed media duration;unit=s;example=1800"`
}

LiveTVSourceDegradedPayload is emitted when a channel source shows sustained health degradation.

type LiveTVSourceFailoverPayload

type LiveTVSourceFailoverPayload struct {
	ChannelID    string `json:"channelId" event:"label=Channel ID;example=ch_espn"`
	ChannelName  string `json:"channelName,omitempty" event:"label=Channel name;example=ESPN HD"`
	FromSourceID string `json:"fromSourceId,omitempty" event:"label=Previous source ID;example=src_primary"`
	ToSourceID   string `json:"toSourceId,omitempty" event:"label=Next source ID;example=src_backup"`
	Reason       string `json:"reason,omitempty" event:"label=Failover reason;example=input stalled"`
	Mode         string `json:"mode,omitempty" event:"label=Playout mode;example=broadcast"`
}

LiveTVSourceFailoverPayload is emitted when a live channel switches to another source.

type PlaybackAdmissionDeniedPayload

type PlaybackAdmissionDeniedPayload struct {
	TitleKey  string `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
	TitleName string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	ViewerID  int64  `json:"viewerId,omitempty" event:"label=Viewer ID;example=42"`
	Username  string `json:"username,omitempty" event:"label=Viewer username;pii;example=alex"`
	Client    string `json:"client,omitempty" event:"label=Client;example=Vela iOS"`
	Remote    bool   `json:"remote,omitempty" event:"label=Remote access;example=true"`
	Policy    string `json:"policy,omitempty" event:"label=Policy;example=bedtime"`
	Reason    string `json:"reason" event:"label=Denial reason;example=bedtime quiet hours active"`
}

PlaybackAdmissionDeniedPayload is emitted when playback admission is denied by policy.

type PlaybackClientContext

type PlaybackClientContext struct {
	ID       string `json:"id,omitempty" event:"label=Client ID;example=appletv-living-room"`
	Name     string `json:"name,omitempty" event:"label=Client name;example=Living Room Apple TV"`
	Platform string `json:"platform,omitempty" event:"label=Client platform;example=tvOS"`
	Product  string `json:"product,omitempty" event:"label=Client product;example=Vela"`
	Version  string `json:"version,omitempty" event:"label=Client version;example=1.8.0"`
	Protocol string `json:"protocol,omitempty" event:"label=Client protocol;enum=vela|plex|jellyfin|emby|dlna|webdav|silo;example=vela"`
}

PlaybackClientContext describes the playback client device and protocol.

type PlaybackConcurrencyExceededPayload

type PlaybackConcurrencyExceededPayload struct {
	SessionID         string `json:"sessionId,omitempty" event:"label=Session ID;example=sess_02"`
	PlayID            string `json:"playId,omitempty" event:"label=Play ID;example=play_02"`
	Limit             int    `json:"limit" event:"label=Stream limit;example=2"`
	ActiveStreams     int    `json:"activeStreams" event:"label=Active streams;example=2"`
	ActiveTranscodes  int    `json:"activeTranscodes,omitempty" event:"label=Active transcodes;example=1"`
	DistinctActiveIPs int    `json:"distinctActiveIPs,omitempty" event:"label=Distinct active IPs;example=2"`
	PlaybackSessionContext
}

PlaybackConcurrencyExceededPayload is emitted when a viewer hits their concurrent stream limit.

type PlaybackMarkerEnteredPayload

type PlaybackMarkerEnteredPayload struct {
	SessionID  string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID     string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	MarkerKind string `json:"markerKind" event:"label=Marker kind;enum=intro|credits|commercial|recap;example=intro"`
	StartMS    int64  `json:"startMs" event:"label=Marker start;duration_ms;unit=ms;example=45000"`
	EndMS      int64  `json:"endMs" event:"label=Marker end;duration_ms;unit=ms;example=125000"`
	PositionMS int64  `json:"positionMs" event:"label=Current position;duration_ms;unit=ms;example=46000"`
	PlaybackSessionContext
}

PlaybackMarkerEnteredPayload is emitted when playback enters a known marker span.

type PlaybackMarkerExitedPayload

type PlaybackMarkerExitedPayload struct {
	SessionID  string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID     string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	MarkerKind string `json:"markerKind" event:"label=Marker kind;enum=intro|credits|commercial|recap;example=intro"`
	PositionMS int64  `json:"positionMs" event:"label=Current position;duration_ms;unit=ms;example=126000"`
	PlaybackSessionContext
}

PlaybackMarkerExitedPayload is emitted when playback leaves a marker span.

type PlaybackNetworkContext

type PlaybackNetworkContext struct {
	RemoteIP string `json:"remoteIP,omitempty" event:"label=Remote IP;pii;example=203.0.113.42"`
	Location string `json:"location,omitempty" event:"label=Network location;enum=lan|wan;example=wan"`
	Country  string `json:"country,omitempty" event:"label=Country;example=US"`
	City     string `json:"city,omitempty" event:"label=City;example=Austin"`
	ASN      string `json:"asn,omitempty" event:"label=ASN;example=AS7922"`
	IsRelay  bool   `json:"isRelay,omitempty" event:"label=Relayed connection;example=false"`
}

PlaybackNetworkContext describes network locality for a playback session.

type PlaybackServerContext

type PlaybackServerContext struct {
	ActiveStreams      int `json:"activeStreams,omitempty" event:"label=Server active streams;example=3"`
	ActiveTranscodes   int `json:"activeTranscodes,omitempty" event:"label=Server active transcodes;example=1"`
	ActiveDirectPlays  int `json:"activeDirectPlays,omitempty" event:"label=Server direct plays;example=2"`
	TotalBandwidthKbps int `json:"totalBandwidthKbps,omitempty" event:"label=Server total bandwidth;unit=kbps;example=42000"`
}

PlaybackServerContext carries live aggregate counts across the server.

type PlaybackSessionCompletedPayload

type PlaybackSessionCompletedPayload struct {
	SessionID        string  `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID           string  `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	WatchedMS        int64   `json:"watchedMs" event:"label=Watched duration;duration_ms;unit=ms;example=7500000"`
	WatchedRatio     float64 `json:"watchedRatio" event:"label=Watched ratio;example=0.92"`
	ThresholdPercent int     `json:"thresholdPercent" event:"label=Watched threshold;unit=%;example=90"`
	PlaybackSessionContext
}

PlaybackSessionCompletedPayload is emitted when playback crosses the watched threshold.

type PlaybackSessionContext

type PlaybackSessionContext struct {
	TitleKey      string                 `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
	TitleName     string                 `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	ShowTitle     string                 `json:"showTitle,omitempty" event:"label=Show title;example=Severance"`
	Season        int                    `json:"season,omitempty" event:"label=Season number;example=1"`
	Episode       int                    `json:"episode,omitempty" event:"label=Episode number;example=1"`
	MediaType     string                 `json:"mediaType,omitempty" event:"label=Media type;enum=movie|episode|live|trailer;example=movie"`
	Year          int                    `json:"year,omitempty" event:"label=Release year;example=1999"`
	LibraryID     string                 `json:"libraryId,omitempty" event:"label=Library ID;example=movies"`
	LibraryName   string                 `json:"libraryName,omitempty" event:"label=Library name;example=Movies"`
	ContentRating string                 `json:"contentRating,omitempty" event:"label=Content rating;example=R"`
	Genres        []string               `json:"genres,omitempty" event:"label=Genres;example=Action,Science Fiction"`
	Labels        []string               `json:"labels,omitempty" event:"label=Labels;example=4k-collection"`
	Actors        []string               `json:"actors,omitempty" event:"label=Actors;example=Keanu Reeves,Carrie-Anne Moss"`
	Directors     []string               `json:"directors,omitempty" event:"label=Directors;example=Lana Wachowski,Lilly Wachowski"`
	Studio        string                 `json:"studio,omitempty" event:"label=Studio;example=Warner Bros."`
	DurationMS    int64                  `json:"durationMs,omitempty" event:"label=Duration;duration_ms;unit=ms;example=8160000"`
	PosterURL     string                 `json:"posterUrl,omitempty" event:"label=Poster URL;example=/img/poster/movie:603"`
	Source        PlaybackSourceContext  `json:"source"`
	Stream        PlaybackStreamContext  `json:"stream"`
	Viewer        PlaybackViewerContext  `json:"viewer"`
	Client        PlaybackClientContext  `json:"client"`
	Network       PlaybackNetworkContext `json:"network"`
	Server        PlaybackServerContext  `json:"server"`
}

PlaybackSessionContext is embedded in playback session, stream, marker, and concurrency events so flows can filter on title, source, stream, viewer, client, network, and live server counts without extra lookups.

type PlaybackSessionFailedPayload

type PlaybackSessionFailedPayload struct {
	SessionID string `json:"sessionId,omitempty" event:"label=Session ID;example=sess_01"`
	PlayID    string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	Stage     string `json:"stage,omitempty" event:"label=Failure stage;example=open"`
	Error     string `json:"error" event:"label=Error message;example=all releases failed verification"`
	ReleaseID string `json:"releaseId,omitempty" event:"label=Release ID;example=rel_01"`
	Indexer   string `json:"indexer,omitempty" event:"label=Indexer;example=NZBGeek"`
	PlaybackSessionContext
}

PlaybackSessionFailedPayload is emitted when playback fails to start or continue.

type PlaybackSessionPausedPayload

type PlaybackSessionPausedPayload struct {
	SessionID  string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID     string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	PositionMS int64  `json:"positionMs" event:"label=Position;duration_ms;unit=ms;example=1245000"`
	PlaybackSessionContext
}

PlaybackSessionPausedPayload is emitted when playback transitions to paused.

type PlaybackSessionResumedPayload

type PlaybackSessionResumedPayload struct {
	SessionID   string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID      string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	PositionMS  int64  `json:"positionMs" event:"label=Position;duration_ms;unit=ms;example=1245000"`
	PausedForMS int64  `json:"pausedForMs" event:"label=Paused duration;duration_ms;unit=ms;example=185000"`
	PlaybackSessionContext
}

PlaybackSessionResumedPayload is emitted when playback resumes from pause.

type PlaybackSessionStartedPayload

type PlaybackSessionStartedPayload struct {
	SessionID string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID    string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	PlaybackSessionContext
}

PlaybackSessionStartedPayload is emitted when a playback session starts.

type PlaybackSessionStoppedPayload

type PlaybackSessionStoppedPayload struct {
	SessionID    string  `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID       string  `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	PositionMS   int64   `json:"positionMs" event:"label=Position;duration_ms;unit=ms;example=3600000"`
	BytesServed  int64   `json:"bytesServed" event:"label=Bytes served;unit=bytes;example=1450000000"`
	WatchedRatio float64 `json:"watchedRatio" event:"label=Watched ratio;example=0.44"`
	StopReason   string  `json:"stopReason,omitempty" event:"label=Stop reason;example=client_stopped"`
	PlaybackSessionContext
}

PlaybackSessionStoppedPayload is emitted when a playback session stops.

type PlaybackSessionTerminatedPayload

type PlaybackSessionTerminatedPayload struct {
	SessionID string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID    string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	ViewerID  int64  `json:"viewerId,omitempty" event:"label=Viewer ID;example=42"`
	Actor     string `json:"actor,omitempty" event:"label=Actor;example=owner"`
	Reason    string `json:"reason,omitempty" event:"label=Reason;example=transcode_policy"`
	Message   string `json:"message,omitempty" event:"label=Message shown to viewer;example=Please choose a direct-play client for 4K playback."`
}

PlaybackSessionTerminatedPayload is emitted when an operator or flow terminates a session.

type PlaybackSourceContext

type PlaybackSourceContext struct {
	Container         string `json:"container,omitempty" event:"label=Source container;desc=Container format of the source file;example=mkv"`
	VideoCodec        string `json:"videoCodec,omitempty" event:"label=Source video codec;desc=Codec of the source video track;example=hevc"`
	VideoResolution   string `` /* 151-byte string literal not displayed */
	VideoWidth        int    `json:"videoWidth,omitempty" event:"label=Source video width;unit=px;example=3840"`
	VideoHeight       int    `json:"videoHeight,omitempty" event:"label=Source video height;unit=px;example=2160"`
	VideoDynamicRange string `` /* 155-byte string literal not displayed */
	AudioCodec        string `json:"audioCodec,omitempty" event:"label=Source audio codec;example=truehd"`
	AudioChannels     int    `json:"audioChannels,omitempty" event:"label=Source audio channels;example=8"`
	BitrateKbps       int    `json:"bitrateKbps,omitempty" event:"label=Source bitrate;unit=kbps;example=48500"`
	FileSizeBytes     int64  `json:"fileSizeBytes,omitempty" event:"label=Source file size;unit=bytes;example=38400000000"`
}

PlaybackSourceContext describes the underlying source media being played.

type PlaybackSourceFailoverPayload

type PlaybackSourceFailoverPayload struct {
	SessionID     string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID        string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	TitleKey      string `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
	TitleName     string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	FromReleaseID string `json:"fromReleaseId,omitempty" event:"label=Previous release ID;example=rel_01"`
	ToReleaseID   string `json:"toReleaseId,omitempty" event:"label=Next release ID;example=rel_02"`
	FromIndexer   string `json:"fromIndexer,omitempty" event:"label=Previous indexer;example=NZBGeek"`
	ToIndexer     string `json:"toIndexer,omitempty" event:"label=Next indexer;example=DrunkenSlug"`
	Reason        string `json:"reason,omitempty" event:"label=Failover reason;example=missing articles"`
	Attempt       int    `json:"attempt" event:"label=Failover attempt;example=1"`
}

PlaybackSourceFailoverPayload is emitted when a session switches releases mid-playback.

type PlaybackStreamContext

type PlaybackStreamContext struct {
	Delivery          string  `` /* 138-byte string literal not displayed */
	VideoDecision     string  `json:"videoDecision,omitempty" event:"label=Video decision;enum=direct_play|copy|transcode;example=transcode"`
	AudioDecision     string  `json:"audioDecision,omitempty" event:"label=Audio decision;enum=direct_play|copy|transcode;example=copy"`
	SubtitleDecision  string  `` /* 128-byte string literal not displayed */
	Container         string  `json:"container,omitempty" event:"label=Stream container;example=hls"`
	VideoCodec        string  `json:"videoCodec,omitempty" event:"label=Stream video codec;example=h264"`
	VideoResolution   string  `json:"videoResolution,omitempty" event:"label=Stream resolution;enum=4k|1080p|720p|480p;example=1080p"`
	VideoHeight       int     `json:"videoHeight,omitempty" event:"label=Stream video height;unit=px;example=1080"`
	VideoDynamicRange string  `json:"videoDynamicRange,omitempty" event:"label=Stream dynamic range;enum=sdr|hdr10|dv|hlg;example=sdr"`
	AudioCodec        string  `json:"audioCodec,omitempty" event:"label=Stream audio codec;example=aac"`
	AudioChannels     int     `json:"audioChannels,omitempty" event:"label=Stream audio channels;example=6"`
	BitrateKbps       int     `json:"bitrateKbps,omitempty" event:"label=Stream bitrate;unit=kbps;example=8000"`
	BandwidthKbps     int     `json:"bandwidthKbps,omitempty" event:"label=Estimated bandwidth;unit=kbps;example=9200"`
	HWDecode          bool    `json:"hwDecode,omitempty" event:"label=Hardware decode;example=true"`
	HWEncode          bool    `json:"hwEncode,omitempty" event:"label=Hardware encode;example=true"`
	TranscodeSpeed    float64 `json:"transcodeSpeed,omitempty" event:"label=Transcode speed;unit=x;example=2.4"`
	Throttled         bool    `json:"throttled,omitempty" event:"label=Transcode throttled;example=false"`
}

PlaybackStreamContext describes the active delivery pipeline for a playback session.

type PlaybackStreamDecisionPayload

type PlaybackStreamDecisionPayload struct {
	SessionID        string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID           string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	PreviousDelivery string `json:"previousDelivery,omitempty" event:"label=Previous delivery;enum=direct_play|remux|transcode;example=direct_play"`
	Delivery         string `json:"delivery" event:"label=Delivery mode;enum=direct_play|remux|transcode;example=transcode"`
	VideoDecision    string `json:"videoDecision,omitempty" event:"label=Video decision;enum=direct_play|copy|transcode;example=transcode"`
	AudioDecision    string `json:"audioDecision,omitempty" event:"label=Audio decision;enum=direct_play|copy|transcode;example=copy"`
	SubtitleDecision string `` /* 128-byte string literal not displayed */
	MaxHeight        int    `json:"maxHeight,omitempty" event:"label=Target max height;unit=px;example=1080"`
	BitrateKbps      int    `json:"bitrateKbps,omitempty" event:"label=Target bitrate;unit=kbps;example=8000"`
	HWDecode         bool   `json:"hwDecode,omitempty" event:"label=Hardware decode;example=true"`
	HWEncode         bool   `json:"hwEncode,omitempty" event:"label=Hardware encode;example=true"`
	Reason           string `json:"reason,omitempty" event:"label=Decision reason;example=Client bitrate limit exceeded"`
	PlaybackSessionContext
}

PlaybackStreamDecisionPayload is emitted when the delivery or transcode decision is set or changed.

type PlaybackStreamQualityChangedPayload

type PlaybackStreamQualityChangedPayload struct {
	SessionID       string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID          string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	FromHeight      int    `json:"fromHeight,omitempty" event:"label=Previous height;unit=px;example=2160"`
	ToHeight        int    `json:"toHeight,omitempty" event:"label=New height;unit=px;example=1080"`
	FromBitrateKbps int    `json:"fromBitrateKbps,omitempty" event:"label=Previous bitrate;unit=kbps;example=20000"`
	ToBitrateKbps   int    `json:"toBitrateKbps,omitempty" event:"label=New bitrate;unit=kbps;example=8000"`
	Reason          string `json:"reason,omitempty" event:"label=Change reason;example=client_selected_quality"`
}

PlaybackStreamQualityChangedPayload is emitted when target video height or bitrate changes.

type PlaybackStreamSeekedPayload

type PlaybackStreamSeekedPayload struct {
	SessionID string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID    string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	FromMS    int64  `json:"fromMs" event:"label=From position;duration_ms;unit=ms;example=60000"`
	ToMS      int64  `json:"toMs" event:"label=To position;duration_ms;unit=ms;example=180000"`
	DeltaMS   int64  `json:"deltaMs" event:"label=Seek delta;duration_ms;unit=ms;example=120000"`
}

PlaybackStreamSeekedPayload is emitted when the viewer seeks across a playback timeline.

type PlaybackStreamStalledPayload

type PlaybackStreamStalledPayload struct {
	SessionID  string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID     string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	StallCount int    `json:"stallCount" event:"label=Stall count;example=1"`
	PositionMS int64  `json:"positionMs" event:"label=Position;duration_ms;unit=ms;example=915000"`
	BufferMS   int64  `json:"bufferMs" event:"label=Buffer depth;duration_ms;unit=ms;example=0"`
	PlaybackSessionContext
}

PlaybackStreamStalledPayload is emitted when playback stalls/rebuffers.

type PlaybackTranscodeFallbackPayload

type PlaybackTranscodeFallbackPayload struct {
	SessionID        string `json:"sessionId" event:"label=Session ID;example=sess_01"`
	PlayID           string `json:"playId,omitempty" event:"label=Play ID;example=play_01"`
	FromHWAccel      string `json:"fromHWAccel" event:"label=Previous hardware accelerator;example=videotoolbox"`
	ToEncoder        string `json:"toEncoder" event:"label=Fallback encoder;example=libx264"`
	Reason           string `json:"reason" event:"label=Fallback reason;example=hardware encoder session init failed"`
	ActiveTranscodes int    `json:"activeTranscodes,omitempty" event:"label=Active transcodes;example=2"`
}

PlaybackTranscodeFallbackPayload is emitted when hardware transcoding falls back to software.

type PlaybackViewerContext

type PlaybackViewerContext struct {
	ID                int64    `json:"id,omitempty" event:"label=Viewer ID;example=42"`
	Username          string   `json:"username,omitempty" event:"label=Viewer username;pii;example=alex"`
	Role              string   `json:"role,omitempty" event:"label=Viewer role;enum=owner|viewer;example=viewer"`
	Tags              []string `json:"tags,omitempty" event:"label=Viewer tags;example=household,4k"`
	ActiveStreams     int      `json:"activeStreams,omitempty" event:"label=Viewer active streams;example=1"`
	ActiveTranscodes  int      `json:"activeTranscodes,omitempty" event:"label=Viewer active transcodes;example=1"`
	DistinctActiveIPs int      `json:"distinctActiveIPs,omitempty" event:"label=Viewer distinct IPs;example=1"`
}

PlaybackViewerContext describes the viewer and their current concurrency state.

type PluginHealthDegradedPayload

type PluginHealthDegradedPayload struct {
	PluginID            string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name                string `json:"name" event:"label=Name;desc=Display name of the plugin;example=Trakt Helper"`
	Status              string `json:"status" event:"label=Status;desc=Degraded health status reported for the plugin;example=error"`
	Restarts            int64  `json:"restarts" event:"label=Restarts;desc=Total runtime restart count;example=3"`
	ConsecutiveFailures int    `json:"consecutiveFailures" event:"label=Consecutive Failures;desc=Recent consecutive failure count;example=2"`
	LastError           string `json:"lastError" event:"label=Last Error;desc=Most recent failure message;example=timeout waiting for rpc response"`
}

type PluginHealthRecoveredPayload

type PluginHealthRecoveredPayload struct {
	PluginID   string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name       string `json:"name" event:"label=Name;desc=Display name of the plugin;example=Trakt Helper"`
	DowntimeMS int64  `` /* 133-byte string literal not displayed */
}

type PluginJobFailedPayload

type PluginJobFailedPayload struct {
	PluginID   string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name       string `json:"name" event:"label=Name;desc=Display name of the plugin;example=Trakt Helper"`
	Job        string `json:"job" event:"label=Job;desc=Name or call identifier of the failed plugin job;example=sync_lists"`
	Kind       string `` /* 129-byte string literal not displayed */
	Error      string `json:"error" event:"label=Error;desc=Failure message returned by the job;example=status 503: upstream unavailable"`
	DurationMS int64  `` /* 128-byte string literal not displayed */
}

type PluginPackageInstalledPayload

type PluginPackageInstalledPayload struct {
	PluginID    string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name        string `json:"name" event:"label=Name;desc=Display name of the plugin;example=Trakt Helper"`
	Version     string `json:"version" event:"label=Version;desc=Installed plugin version;example=1.2.0"`
	Kind        string `json:"kind" event:"label=Kind;desc=Plugin capability category;example=integration"`
	RuntimeKind string `json:"runtimeKind" event:"label=Runtime;desc=Execution runtime for the plugin;example=wasm"`
	Verified    bool   `json:"verified" event:"label=Verified;desc=Whether the package signature was verified;example=true"`
}

type PluginPackageRemovedPayload

type PluginPackageRemovedPayload struct {
	PluginID string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name     string `json:"name" event:"label=Name;desc=Display name of the removed plugin;example=Trakt Helper"`
	Version  string `json:"version" event:"label=Version;desc=Version that was removed;example=1.3.0"`
}

type PluginPackageUpdatedPayload

type PluginPackageUpdatedPayload struct {
	PluginID    string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name        string `json:"name" event:"label=Name;desc=Display name of the plugin;example=Trakt Helper"`
	FromVersion string `json:"fromVersion" event:"label=From Version;desc=Previously installed version;example=1.2.0"`
	ToVersion   string `json:"toVersion" event:"label=To Version;desc=Newly installed version;example=1.3.0"`
	Auto        bool   `json:"auto" event:"label=Automatic;desc=True when applied by auto-update;example=true"`
}

type PluginQuotaExceededPayload

type PluginQuotaExceededPayload struct {
	PluginID  string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name      string `json:"name" event:"label=Name;desc=Display name of the plugin;example=Trakt Helper"`
	QuotaKind string `json:"quotaKind" event:"label=Quota Kind;desc=Resource quota that was exceeded;example=events_outbox"`
	Used      int64  `json:"used" event:"label=Used;desc=Current usage count or bytes;example=512"`
	Limit     int64  `json:"limit" event:"label=Limit;desc=Configured quota limit;example=512"`
	Drops     int64  `json:"drops" event:"label=Drops;desc=Number of items or events dropped;example=4"`
}

type PluginStateDisabledPayload

type PluginStateDisabledPayload struct {
	PluginID string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name     string `json:"name" event:"label=Name;desc=Display name of the plugin;example=Trakt Helper"`
	Reason   string `json:"reason" event:"label=Reason;desc=Reason the plugin was disabled;example=owner"`
}

type PluginStateEnabledPayload

type PluginStateEnabledPayload struct {
	PluginID string `json:"pluginId" event:"label=Plugin ID;desc=Unique plugin identifier;example=com.example.trakt-helper"`
	Name     string `json:"name" event:"label=Name;desc=Display name of the plugin;example=Trakt Helper"`
	Shadow   bool   `json:"shadow" event:"label=Shadow Mode;desc=Whether the plugin is running in shadow mode;example=false"`
}

type ProviderAuthRejectedPayload

type ProviderAuthRejectedPayload struct {
	ProviderID   string `json:"providerId" event:"label=Provider ID;example=debrid_rd"`
	ProviderName string `json:"providerName" event:"label=Provider name;example=Real-Debrid"`
	Kind         string `json:"kind" event:"label=Provider kind;example=realdebrid"`
	StatusCode   int    `json:"statusCode,omitempty" event:"label=Status code;example=401"`
	Error        string `json:"error" event:"label=Error message;example=invalid API token"`
}

ProviderAuthRejectedPayload is emitted when a provider rejects credentials or an API key.

type ProviderConnectionsSaturatedPayload

type ProviderConnectionsSaturatedPayload struct {
	ProviderID        string `json:"providerId" event:"label=Provider ID;example=usenet_primary"`
	ProviderName      string `json:"providerName" event:"label=Provider name;example=Newshosting"`
	ActiveConnections int    `json:"activeConnections" event:"label=Active connections;example=20"`
	MaxConnections    int    `json:"maxConnections" event:"label=Max connections;example=20"`
	WaitingReaders    int    `json:"waitingReaders" event:"label=Waiting readers;example=4"`
}

ProviderConnectionsSaturatedPayload is emitted when all provider connection slots are occupied with waiting readers.

type ProviderDebridCachedPayload

type ProviderDebridCachedPayload struct {
	ProviderID   string `json:"providerId" event:"label=Provider ID;example=debrid_rd"`
	ProviderName string `json:"providerName" event:"label=Provider name;example=Real-Debrid"`
	InfoHash     string `json:"infoHash" event:"label=Torrent info hash;example=0123456789abcdef0123456789abcdef01234567"`
	TitleKey     string `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
	TitleName    string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	SizeBytes    int64  `json:"sizeBytes,omitempty" event:"label=File size;unit=bytes;example=18400000000"`
	WaitMS       int64  `json:"waitMs" event:"label=Wait duration;duration_ms;unit=ms;example=1450"`
}

ProviderDebridCachedPayload is emitted when a debrid torrent becomes cached and ready.

type ProviderDebridFailedPayload

type ProviderDebridFailedPayload struct {
	ProviderID   string `json:"providerId,omitempty" event:"label=Provider ID;example=debrid_rd"`
	ProviderName string `json:"providerName,omitempty" event:"label=Provider name;example=Real-Debrid"`
	InfoHash     string `json:"infoHash" event:"label=Torrent info hash;example=0123456789abcdef0123456789abcdef01234567"`
	TitleKey     string `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
	Error        string `json:"error" event:"label=Error message;example=provider refused torrent"`
}

ProviderDebridFailedPayload is emitted when a debrid acquisition or uncached download fails.

type ProviderQuotaExhaustedPayload

type ProviderQuotaExhaustedPayload struct {
	ProviderID   string `json:"providerId" event:"label=Provider ID;example=debrid_rd"`
	ProviderName string `json:"providerName" event:"label=Provider name;example=Real-Debrid"`
	Kind         string `json:"kind" event:"label=Provider kind;example=realdebrid"`
	Metric       string `json:"metric" event:"label=Quota metric;example=active_downloads"`
	Used         int64  `json:"used" event:"label=Used quota;example=10"`
	Limit        int64  `json:"limit" event:"label=Quota limit;example=10"`
}

ProviderQuotaExhaustedPayload is emitted when a provider quota or active download limit is exhausted.

type ProviderQuotaWarningPayload

type ProviderQuotaWarningPayload struct {
	ProviderID   string  `json:"providerId" event:"label=Provider ID;example=debrid_rd"`
	ProviderName string  `json:"providerName" event:"label=Provider name;example=Real-Debrid"`
	Kind         string  `json:"kind" event:"label=Provider kind;example=realdebrid"`
	Metric       string  `json:"metric" event:"label=Quota metric;example=active_downloads"`
	Used         int64   `json:"used" event:"label=Used quota;example=8"`
	Limit        int64   `json:"limit" event:"label=Quota limit;example=10"`
	PercentUsed  float64 `json:"percentUsed" event:"label=Percent used;unit=%;example=80"`
}

ProviderQuotaWarningPayload is emitted when a provider quota approaches exhaustion.

type ProviderServiceOutagePayload

type ProviderServiceOutagePayload struct {
	ProviderID   string `json:"providerId" event:"label=Provider ID;example=usenet_primary"`
	ProviderName string `json:"providerName" event:"label=Provider name;example=Newshosting"`
	Kind         string `json:"kind" event:"label=Provider kind;example=usenet"`
	Error        string `json:"error" event:"label=Error message;example=connection refused"`
	BackoffSec   int    `json:"backoffSec" event:"label=Backoff duration;unit=s;example=60"`
}

ProviderServiceOutagePayload is emitted when a Usenet or debrid provider enters outage backoff.

type ProviderServiceRecoveredPayload

type ProviderServiceRecoveredPayload struct {
	ProviderID       string `json:"providerId" event:"label=Provider ID;example=usenet_primary"`
	ProviderName     string `json:"providerName" event:"label=Provider name;example=Newshosting"`
	Kind             string `json:"kind" event:"label=Provider kind;example=usenet"`
	OutageDurationMS int64  `json:"outageDurationMs" event:"label=Outage duration;duration_ms;unit=ms;example=180000"`
}

ProviderServiceRecoveredPayload is emitted when a provider recovers from outage or auth failure.

type Recorder

type Recorder struct {
	// contains filtered or unexported fields
}

Recorder captures events published to a Bus for assertions in tests.

func NewRecorder

func NewRecorder(bus *Bus, patterns ...string) *Recorder

NewRecorder attaches a capturing subscriber to bus for patterns (default "*").

func (*Recorder) AssertNone

func (r *Recorder) AssertNone(t TestTB, pattern string, wait time.Duration)

AssertNone fails t if any event matching pattern is recorded within wait.

func (*Recorder) Close

func (r *Recorder) Close()

Close unsubscribes and waits for the recorder goroutine to exit.

func (*Recorder) Events

func (r *Recorder) Events() []Envelope

Events returns a copy of all recorded envelopes in arrival order.

func (*Recorder) OfType

func (r *Recorder) OfType(pattern string) []Envelope

OfType returns all recorded envelopes matching pattern (exact or prefix).

func (*Recorder) Reset

func (r *Recorder) Reset()

Reset clears previously recorded events.

func (*Recorder) WaitFor

func (r *Recorder) WaitFor(t TestTB, pattern string, timeout time.Duration) Envelope

WaitFor blocks until an event matching pattern is recorded or timeout expires.

func (*Recorder) WaitForFunc

func (r *Recorder) WaitForFunc(t TestTB, desc string, pred func(Envelope) bool, timeout time.Duration) Envelope

WaitForFunc blocks until pred returns true for a recorded event or timeout expires.

type RedactOptions

type RedactOptions struct {
	// StripPII removes fields marked PII: true (used for plugins lacking viewer identity grants).
	StripPII bool
}

RedactOptions controls how EventSchema.Redact sanitizes a payload map.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry stores typed EventSchema definitions for built-in and plugin events. It is safe for concurrent use.

func NewBuiltinRegistry

func NewBuiltinRegistry() *Registry

NewBuiltinRegistry returns a Registry pre-populated with all built-in Ether event schemas.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty event schema registry.

func (*Registry) Domains

func (r *Registry) Domains() []string

Domains returns the sorted distinct domains currently registered.

func (*Registry) Get

func (r *Registry) Get(eventType string) (EventSchema, bool)

Get returns the EventSchema for eventType.

func (*Registry) GetByLegacy

func (r *Registry) GetByLegacy(legacyName string) (EventSchema, bool)

GetByLegacy resolves a legacy notify or plugin event name to its canonical schema.

func (*Registry) List

func (r *Registry) List() []EventSchema

List returns all registered schemas sorted by domain then type.

func (*Registry) ListByDomain

func (r *Registry) ListByDomain(domain string) []EventSchema

ListByDomain returns all registered schemas in domain, sorted by type.

func (*Registry) MustRegister

func (r *Registry) MustRegister(s EventSchema)

MustRegister registers s and panics on error (intended for static built-in schemas).

func (*Registry) Register

func (r *Registry) Register(s EventSchema) error

Register adds a single EventSchema to the registry.

func (*Registry) RemovePlugin

func (r *Registry) RemovePlugin(pluginID string)

RemovePlugin removes every EventSchema owned by pluginID.

func (*Registry) ReplacePlugin

func (r *Registry) ReplacePlugin(pluginID string, schemas []EventSchema) error

ReplacePlugin atomically swaps every EventSchema owned by pluginID.

func (*Registry) ValidatePayload

func (r *Registry) ValidatePayload(eventType string, raw json.RawMessage) error

ValidatePayload validates a JSON payload against the registered EventSchema. Unknown extra fields are permitted so additive schema changes stay backwards-compatible.

func (*Registry) Version

func (r *Registry) Version() uint64

Version monotonically increments on every registry mutation.

type ResolverPinCreatedPayload

type ResolverPinCreatedPayload struct {
	TitleKey    string `json:"titleKey" event:"label=Title key;example=movie:603"`
	TitleName   string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	ReleaseID   string `json:"releaseId" event:"label=Release ID;example=rel_01"`
	ReleaseName string `json:"releaseName,omitempty" event:"label=Release name;example=The.Matrix.1999.2160p.REMUX"`
	Note        string `json:"note,omitempty" event:"label=Pin note;example=Best Atmos mix"`
	Actor       string `json:"actor,omitempty" event:"label=Actor;example=owner"`
}

ResolverPinCreatedPayload is emitted when an owner pins a release to a title.

type ResolverPinRejectedPayload

type ResolverPinRejectedPayload struct {
	TitleKey  string `json:"titleKey" event:"label=Title key;example=movie:603"`
	TitleName string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	ReleaseID string `json:"releaseId" event:"label=Release ID;example=rel_01"`
	Client    string `json:"client,omitempty" event:"label=Client;example=Vela iOS"`
	Reason    string `json:"reason" event:"label=Rejection reason;example=release exceeds client resolution ceiling"`
}

ResolverPinRejectedPayload is emitted when a pinned release is rejected for a client request.

type ResolverPinRemovedPayload

type ResolverPinRemovedPayload struct {
	TitleKey  string `json:"titleKey" event:"label=Title key;example=movie:603"`
	TitleName string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	ReleaseID string `json:"releaseId,omitempty" event:"label=Release ID;example=rel_01"`
	Actor     string `json:"actor,omitempty" event:"label=Actor;example=owner"`
}

ResolverPinRemovedPayload is emitted when a release pin is removed.

type ResolverPinUnhealthyPayload

type ResolverPinUnhealthyPayload struct {
	TitleKey  string `json:"titleKey" event:"label=Title key;example=movie:603"`
	TitleName string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	ReleaseID string `json:"releaseId" event:"label=Release ID;example=rel_01"`
	Status    string `json:"status" event:"label=Pin health status;example=unhealthy"`
	Reason    string `json:"reason" event:"label=Unhealthy reason;example=missing articles on all providers"`
}

ResolverPinUnhealthyPayload is emitted when a pinned release becomes unhealthy or unplayable.

type ResolverReleaseBlocklistedPayload

type ResolverReleaseBlocklistedPayload struct {
	ReleaseID   string `json:"releaseId" event:"label=Release ID;example=rel_01"`
	ReleaseName string `json:"releaseName,omitempty" event:"label=Release name;example=The.Matrix.1999.BAD-GROUP"`
	TitleKey    string `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
	Indexer     string `json:"indexer,omitempty" event:"label=Indexer;example=NZBGeek"`
	Reason      string `json:"reason" event:"label=Blocklist reason;example=corrupt audio track"`
	Actor       string `json:"actor,omitempty" event:"label=Actor;example=owner"`
}

ResolverReleaseBlocklistedPayload is emitted when a release is added to the blocklist.

type ResolverReleaseSelectedPayload

type ResolverReleaseSelectedPayload struct {
	TitleKey    string `json:"titleKey" event:"label=Title key;example=movie:603"`
	ReleaseID   string `json:"releaseId" event:"label=Release ID;example=rel_01"`
	ReleaseName string `json:"releaseName" event:"label=Release name;example=The.Matrix.1999.2160p.UHD.BluRay.REMUX.HEVC-GROUP"`
	Indexer     string `json:"indexer,omitempty" event:"label=Indexer;example=NZBGeek"`
	Protocol    string `json:"protocol,omitempty" event:"label=Protocol;example=usenet"`
	SizeBytes   int64  `json:"sizeBytes,omitempty" event:"label=Release size;unit=bytes;example=38400000000"`
	Resolution  string `json:"resolution,omitempty" event:"label=Resolution;example=2160p"`
	HDR         string `json:"hdr,omitempty" event:"label=HDR format;example=hdr10"`
	Score       int    `json:"score,omitempty" event:"label=Ranking score;example=940"`
	Pinned      bool   `json:"pinned" event:"label=Pinned release;example=false"`
}

ResolverReleaseSelectedPayload is emitted when the resolver selects a winning release.

type ResolverSearchCompletedPayload

type ResolverSearchCompletedPayload struct {
	TitleKey        string `json:"titleKey" event:"label=Title key;example=movie:603"`
	TitleName       string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	MediaType       string `json:"mediaType,omitempty" event:"label=Media type;enum=movie|episode|live|trailer;example=movie"`
	CandidateCount  int    `json:"candidateCount" event:"label=Candidates found;example=18"`
	EligibleCount   int    `json:"eligibleCount" event:"label=Eligible candidates;example=6"`
	WinnerReleaseID string `json:"winnerReleaseId,omitempty" event:"label=Winner release ID;example=rel_01"`
	DurationMS      int64  `json:"durationMs" event:"label=Search duration;duration_ms;unit=ms;example=420"`
	CacheHit        bool   `json:"cacheHit" event:"label=Cache hit;example=false"`
}

ResolverSearchCompletedPayload is emitted when a release search succeeds.

type ResolverSearchEmptyPayload

type ResolverSearchEmptyPayload struct {
	TitleKey        string `json:"titleKey" event:"label=Title key;example=movie:603"`
	TitleName       string `json:"titleName,omitempty" event:"label=Title name;example=The Matrix"`
	MediaType       string `json:"mediaType,omitempty" event:"label=Media type;enum=movie|episode|live|trailer;example=movie"`
	ProfileID       string `json:"profileId,omitempty" event:"label=Quality profile;example=4k-hdr"`
	IndexersQueried int    `json:"indexersQueried" event:"label=Indexers queried;example=3"`
	RejectedCount   int    `json:"rejectedCount" event:"label=Rejected candidates;example=9"`
	TopRejection    string `json:"topRejection,omitempty" event:"label=Top rejection reason;example=below minimum resolution"`
}

ResolverSearchEmptyPayload is emitted when resolution finds no playable release.

type SubscriberStats

type SubscriberStats struct {
	Name      string   `json:"name"`
	Patterns  []string `json:"patterns"`
	Delivered uint64   `json:"delivered"`
	Dropped   uint64   `json:"dropped"`
	Queued    int      `json:"queued"`
	Capacity  int      `json:"capacity"`
}

SubscriberStats is a point-in-time snapshot of one subscriber's health.

type Subscription

type Subscription struct {
	// contains filtered or unexported fields
}

Subscription receives matching Envelopes on a bounded channel.

func (*Subscription) C

func (s *Subscription) C() <-chan Envelope

C returns the read-only delivery channel for this subscription.

func (*Subscription) Stats

func (s *Subscription) Stats() SubscriberStats

Stats returns point-in-time delivery and overflow counters for s.

func (*Subscription) Unsubscribe

func (s *Subscription) Unsubscribe()

Unsubscribe detaches this subscription and closes its delivery channel.

type SubscriptionOptions

type SubscriptionOptions struct {
	// Name identifies this subscriber in stats and drop logs.
	Name string
	// Buffer bounds unread events queued for this subscriber.
	Buffer int
	// Patterns selects events by exact type ("playback.session.started"),
	// wildcard prefix ("playback.*", "livetv.input.*", "plugin:com.acme/*"),
	// trailing delimiter prefix ("playback."), or "*" for all events.
	// Empty defaults to "*".
	Patterns []string
	// IncludeDryRun opts into synthetic test-run events (default false).
	IncludeDryRun bool
}

SubscriptionOptions configures one Bus subscriber.

type SystemBackupCompletedPayload

type SystemBackupCompletedPayload struct {
	Kind        string `` /* 130-byte string literal not displayed */
	SizeBytes   int64  `json:"sizeBytes" event:"label=Size;desc=Total archive size in bytes;unit=bytes;example=48234496"`
	DurationMS  int64  `` /* 126-byte string literal not displayed */
	Destination string `` /* 139-byte string literal not displayed */
	Encrypted   bool   `json:"encrypted" event:"label=Encrypted;desc=Whether backup secrets are encrypted;example=true"`
}

type SystemBackupFailedPayload

type SystemBackupFailedPayload struct {
	Kind                string `` /* 130-byte string literal not displayed */
	Error               string `json:"error" event:"label=Error;desc=Reason the backup failed;example=no space left on device"`
	ConsecutiveFailures int    `json:"consecutiveFailures" event:"label=Consecutive Failures;desc=Number of consecutive failed backups;example=2"`
}

type SystemDiskLowPayload

type SystemDiskLowPayload struct {
	Volume      string  `json:"volume" event:"label=Volume;desc=Logical Ether storage volume name;example=data"`
	Path        string  `json:"path" event:"label=Path;desc=Filesystem path checked;example=/var/lib/ether"`
	FreeBytes   int64   `json:"freeBytes" event:"label=Free Bytes;desc=Remaining free space in bytes;unit=bytes;example=536870912"`
	TotalBytes  int64   `json:"totalBytes" event:"label=Total Bytes;desc=Total filesystem capacity in bytes;unit=bytes;example=107374182400"`
	PercentUsed float64 `json:"percentUsed" event:"label=Percent Used;desc=Percentage of filesystem capacity currently used;unit=%;example=99.5"`
}

type SystemHealthChangedPayload

type SystemHealthChangedPayload struct {
	FromStatus string `` /* 133-byte string literal not displayed */
	ToStatus   string `` /* 131-byte string literal not displayed */
	Component  string `json:"component" event:"label=Component;desc=Subsystem whose health changed;example=database"`
	Summary    string `` /* 132-byte string literal not displayed */
}

type SystemReachabilityChangedPayload

type SystemReachabilityChangedPayload struct {
	Scope      string `json:"scope" event:"label=Scope;desc=Reachability probe scope;enum=internal|external|remote_access;example=remote_access"`
	FromStatus string `` /* 134-byte string literal not displayed */
	ToStatus   string `` /* 128-byte string literal not displayed */
	URL        string `json:"url,omitempty" event:"label=URL;desc=Checked endpoint address or URL;example=https://1-2-3-4.abc.plex.direct:32400"`
	StatusCode int    `json:"statusCode,omitempty" event:"label=Status Code;desc=HTTP status code returned by the probe if applicable;example=502"`
	LatencyMS  int64  `` /* 126-byte string literal not displayed */
	Error      string `json:"error,omitempty" event:"label=Error;desc=Probe failure reason when unreachable;example=connection timed out"`
}

type SystemServerCrashedPayload

type SystemServerCrashedPayload struct {
	Version    string `json:"version" event:"label=Version;desc=Ether server version;example=0.3.17"`
	ExitReason string `` /* 127-byte string literal not displayed */
	Watcher    string `json:"watcher,omitempty" event:"label=Watcher;desc=Supervisor or watcher process that observed the crash;example=ether-watch"`
}

type SystemServerStartedPayload

type SystemServerStartedPayload struct {
	Version   string `json:"version" event:"label=Version;desc=Ether server version;example=0.3.17"`
	Mode      string `json:"mode" event:"label=Mode;desc=Runtime deployment mode;enum=standalone|cluster;example=standalone"`
	NodeID    string `json:"nodeId" event:"label=Node ID;desc=Local node identifier;example=node-a"`
	StartupMS int64  `` /* 130-byte string literal not displayed */
}

type SystemServerStoppingPayload

type SystemServerStoppingPayload struct {
	Version        string `json:"version" event:"label=Version;desc=Ether server version;example=0.3.17"`
	Reason         string `json:"reason" event:"label=Reason;desc=Shutdown reason;example=signal"`
	ActiveSessions int    `json:"activeSessions" event:"label=Active Sessions;desc=Active playback sessions at shutdown;example=1"`
}

type SystemUpdateAvailablePayload

type SystemUpdateAvailablePayload struct {
	CurrentVersion string `json:"currentVersion" event:"label=Current Version;desc=Currently running Ether version;example=0.3.16"`
	NewVersion     string `json:"newVersion" event:"label=New Version;desc=Newly available Ether version;example=0.3.17"`
	Channel        string `json:"channel" event:"label=Channel;desc=Release channel;example=stable"`
	Critical       bool   `json:"critical" event:"label=Critical;desc=True if the update fixes a critical issue;example=false"`
}

type SystemUpdateInstalledPayload

type SystemUpdateInstalledPayload struct {
	FromVersion string `json:"fromVersion" event:"label=From Version;desc=Version before upgrade;example=0.3.16"`
	ToVersion   string `json:"toVersion" event:"label=To Version;desc=Version after upgrade;example=0.3.17"`
	Channel     string `json:"channel" event:"label=Channel;desc=Release channel;example=stable"`
	Auto        bool   `json:"auto" event:"label=Automatic;desc=True when installed automatically;example=true"`
}

type SystemUpdateRolledBackPayload

type SystemUpdateRolledBackPayload struct {
	FailedVersion   string `json:"failedVersion" event:"label=Failed Version;desc=Version that failed verification and was rolled back;example=0.3.17"`
	RestoredVersion string `json:"restoredVersion" event:"label=Restored Version;desc=Previous working version restored;example=0.3.16"`
	Reason          string `json:"reason" event:"label=Reason;desc=Reason the upgrade was rolled back;example=health check failed after restart"`
}

type TestTB

type TestTB interface {
	Helper()
	Fatalf(format string, args ...any)
	Cleanup(func())
}

TestTB is the subset of testing.TB used by test helpers so importing internal/events in production binaries never pulls in testing's init flags.

type VaultPackCompactedPayload

type VaultPackCompactedPayload struct {
	PacksCompacted int   `json:"packsCompacted" event:"label=Packs compacted;example=3"`
	BytesReclaimed int64 `json:"bytesReclaimed" event:"label=Bytes reclaimed;unit=bytes;example=52428800"`
	DurationMS     int64 `json:"durationMs" event:"label=Compaction duration;duration_ms;unit=ms;example=840"`
}

VaultPackCompactedPayload is emitted when vault pack compaction finishes.

type VaultPayloadMissingPayload

type VaultPayloadMissingPayload struct {
	VaultKey string `json:"vaultKey" event:"label=Vault key;example=nzb:sha256:abc123"`
	PackID   string `json:"packId,omitempty" event:"label=Pack ID;example=pack_0001"`
	NodeID   string `json:"nodeId,omitempty" event:"label=Node ID;example=node-1"`
	TitleKey string `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
}

VaultPayloadMissingPayload is emitted when a vault record's pack payload cannot be read.

type VaultQuotaWarningPayload

type VaultQuotaWarningPayload struct {
	UsedBytes   int64   `json:"usedBytes" event:"label=Used bytes;unit=bytes;example=858993459"`
	BudgetBytes int64   `json:"budgetBytes" event:"label=Budget bytes;unit=bytes;example=1073741824"`
	PercentUsed float64 `json:"percentUsed" event:"label=Percent used;unit=%;example=80"`
	RecordCount int     `json:"recordCount" event:"label=Record count;example=1420"`
}

VaultQuotaWarningPayload is emitted when vault disk usage nears its configured cap.

type VaultRecordDeadPayload

type VaultRecordDeadPayload struct {
	VaultKey    string `json:"vaultKey" event:"label=Vault key;example=nzb:sha256:abc123"`
	Kind        string `json:"kind,omitempty" event:"label=Record kind;example=nzb"`
	TitleKey    string `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
	ReleaseName string `json:"releaseName,omitempty" event:"label=Release name;example=The.Matrix.1999.2160p.REMUX"`
	Reason      string `json:"reason,omitempty" event:"label=Reason;example=missing articles"`
}

VaultRecordDeadPayload is emitted when a vault record is marked dead.

type VaultRecordStoredPayload

type VaultRecordStoredPayload struct {
	VaultKey        string `json:"vaultKey" event:"label=Vault key;example=nzb:sha256:abc123"`
	Kind            string `json:"kind" event:"label=Record kind;example=nzb"`
	TitleKey        string `json:"titleKey,omitempty" event:"label=Title key;example=movie:603"`
	ReleaseName     string `json:"releaseName,omitempty" event:"label=Release name;example=The.Matrix.1999.2160p.REMUX"`
	SizeBytes       int64  `json:"sizeBytes" event:"label=Uncompressed size;unit=bytes;example=163840"`
	CompressedBytes int64  `json:"compressedBytes" event:"label=Compressed size;unit=bytes;example=48210"`
	PackID          string `json:"packId,omitempty" event:"label=Pack ID;example=pack_0001"`
}

VaultRecordStoredPayload is emitted when a release record is stored in the vault.

type ViewerAccessChangedPayload

type ViewerAccessChangedPayload struct {
	ViewerID         int64    `json:"viewerId" event:"label=Viewer ID;desc=Numeric identifier of the updated viewer;example=7"`
	Username         string   `json:"username" event:"label=Username;desc=Viewer display name or username;pii;example=alex"`
	StreamLimit      int      `json:"streamLimit" event:"label=Stream Limit;desc=Maximum concurrent streams allowed (0 means unlimited);example=2"`
	MaxContentRating string   `json:"maxContentRating,omitempty" event:"label=Max Content Rating;desc=Maximum allowed content maturity rating;example=PG-13"`
	AllowedLibraries []string `` /* 139-byte string literal not displayed */
	Actor            string   `json:"actor,omitempty" event:"label=Actor;desc=Owner or subsystem that updated access;example=owner"`
}

type ViewerAccountDeactivatedPayload

type ViewerAccountDeactivatedPayload struct {
	ViewerID int64  `json:"viewerId" event:"label=Viewer ID;desc=Numeric identifier of the deactivated viewer;example=7"`
	Username string `json:"username" event:"label=Username;desc=Viewer display name or username;pii;example=alex"`
	Reason   string `json:"reason" event:"label=Reason;desc=Why the viewer account was paused or deactivated;example=paused_by_owner"`
	Actor    string `json:"actor,omitempty" event:"label=Actor;desc=Owner or subsystem that deactivated the viewer;example=owner"`
}

type ViewerAccountJoinedPayload

type ViewerAccountJoinedPayload struct {
	ViewerID int64  `json:"viewerId" event:"label=Viewer ID;desc=Numeric identifier of the new viewer;example=7"`
	Username string `json:"username" event:"label=Username;desc=Viewer display name or username;pii;example=alex"`
	Role     string `json:"role" event:"label=Role;desc=Membership role assigned to the viewer;enum=owner|home|friend|local|guest;example=local"`
	Source   string `json:"source" event:"label=Source;desc=How the viewer account was created;example=invite"`
	InviteID string `json:"inviteId,omitempty" event:"label=Invite ID;desc=Identifier of the invite used if applicable;example=inv_9f2a4c8e1b0d"`
}

type ViewerAccountMergedPayload

type ViewerAccountMergedPayload struct {
	FromViewerID int64  `json:"fromViewerId" event:"label=Source Viewer ID;desc=Viewer account merged away;example=9"`
	IntoViewerID int64  `json:"intoViewerId" event:"label=Target Viewer ID;desc=Surviving viewer account;example=7"`
	Actor        string `json:"actor,omitempty" event:"label=Actor;desc=Owner or subsystem that initiated the merge;example=owner"`
}

type ViewerInviteAcceptedPayload

type ViewerInviteAcceptedPayload struct {
	InviteID string `json:"inviteId" event:"label=Invite ID;desc=Non-secret identifier for the redeemed invite;example=inv_9f2a4c8e1b0d"`
	ViewerID int64  `json:"viewerId" event:"label=Viewer ID;desc=Viewer account bound to the invite;example=7"`
	Username string `json:"username" event:"label=Username;desc=Viewer display name or username;pii;example=alex"`
}

type ViewerInviteCreatedPayload

type ViewerInviteCreatedPayload struct {
	InviteID  string    `json:"inviteId" event:"label=Invite ID;desc=Non-secret identifier for the invite;example=inv_9f2a4c8e1b0d"`
	Label     string    `json:"label,omitempty" event:"label=Label;desc=Display label or intended viewer name for the invite;example=Alex"`
	MaxUses   int       `json:"maxUses" event:"label=Max Uses;desc=Maximum times the invite may be redeemed;example=1"`
	ExpiresAt time.Time `json:"expiresAt,omitzero" event:"label=Expires At;desc=Expiration timestamp of the invite;example=2026-11-26T12:00:00Z"`
	Actor     string    `json:"actor,omitempty" event:"label=Actor;desc=Owner or subsystem that created the invite;example=owner"`
}

type ViewerRatingSubmittedPayload

type ViewerRatingSubmittedPayload struct {
	ViewerID  int64   `json:"viewerId" event:"label=Viewer ID;desc=Viewer who submitted the rating;example=7"`
	Username  string  `json:"username" event:"label=Username;desc=Viewer display name or username;pii;example=alex"`
	TitleKey  string  `json:"titleKey" event:"label=Title Key;desc=Canonical rating key of the rated title;example=movie:603"`
	TitleName string  `json:"titleName" event:"label=Title Name;desc=Display name of the rated title;example=The Matrix"`
	Rating    float64 `json:"rating" event:"label=Rating;desc=Numeric rating submitted by the viewer;example=9.5"`
}

type ViewerSafetyUpdatedPayload

type ViewerSafetyUpdatedPayload struct {
	ViewerID           int64  `json:"viewerId" event:"label=Viewer ID;desc=Numeric identifier of the viewer;example=7"`
	Username           string `json:"username" event:"label=Username;desc=Viewer display name or username;pii;example=alex"`
	RemoteDisabled     bool   `json:"remoteDisabled" event:"label=Remote Disabled;desc=Whether remote streaming outside the LAN is blocked;example=false"`
	MaxBitrateKbps     int    `` /* 130-byte string literal not displayed */
	BedtimeEnabled     bool   `json:"bedtimeEnabled" event:"label=Bedtime Enabled;desc=Whether quiet-hours viewing restrictions are active;example=true"`
	BlockedGenresCount int    `json:"blockedGenresCount" event:"label=Blocked Genres;desc=Count of genres blocked for this viewer;example=2"`
	Actor              string `json:"actor,omitempty" event:"label=Actor;desc=Owner or subsystem that updated safety settings;example=owner"`
}

type ViewerWatchScrobbledPayload

type ViewerWatchScrobbledPayload struct {
	ViewerID  int64  `json:"viewerId" event:"label=Viewer ID;desc=Viewer whose watch state changed;example=7"`
	Username  string `json:"username" event:"label=Username;desc=Viewer display name or username;pii;example=alex"`
	TitleKey  string `json:"titleKey" event:"label=Title Key;desc=Canonical rating key of the title;example=movie:603"`
	TitleName string `json:"titleName" event:"label=Title Name;desc=Display name of the title;example=The Matrix"`
	MediaType string `json:"mediaType" event:"label=Media Type;desc=Type of media scrobbled;enum=movie|show|season|episode|other;example=movie"`
	Watched   bool   `json:"watched" event:"label=Watched;desc=True when marked watched and false when marked unwatched;example=true"`
	Source    string `json:"source" event:"label=Source;desc=Source of the watch state update;example=scrobble"`
}

Jump to

Keyboard shortcuts

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