actions

package
v0.3.17 Latest Latest
Warning

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

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

Documentation

Overview

Package actions implements and registers all built-in Flow actions defined in docs/design/flows.md §4.4. Every action declares a typed flows.ActionSpec, supports DryRun mode cleanly without external side effects, enforces strict bounds, and communicates with Ether subsystems through narrow interfaces.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func All

func All(deps Deps) []flows.ActionHandler

All returns all 13 built-in Flow action handlers bound to deps.

func BuiltinHTTPClient

func BuiltinHTTPClient() *http.Client

BuiltinHTTPClient constructs the default SSRF-safe outbound HTTP client used by http.webhook, layered over Ether's egress transport and safefetch guard.

func NewDigestGenerate

func NewDigestGenerate(deps Deps) flows.ActionHandler

NewDigestGenerate constructs the built-in digest.generate action handler. It produces a grouped "Recently Added" and/or activity newsletter digest in both responsive HTML (auto-escaped) and plain text, collapsing multiple episodes into seasons and shows, with poster thumbnails and optional shareable self-hosted HTML output.

func NewFlowSetVariable

func NewFlowSetVariable(_ Deps) flows.ActionHandler

NewFlowSetVariable constructs the built-in flow.set_variable action handler. Because setting run-scoped variables has no external side effect, it executes even during DryRun so downstream conditions and templates evaluate faithfully.

func NewHTTPWebhook

func NewHTTPWebhook(deps Deps) flows.ActionHandler

NewHTTPWebhook constructs the built-in http.webhook action handler.

func NewLibraryExport

func NewLibraryExport(deps Deps) flows.ActionHandler

NewLibraryExport constructs the built-in library.export action handler.

func NewLibraryRefresh

func NewLibraryRefresh(deps Deps) flows.ActionHandler

NewLibraryRefresh constructs the built-in library.refresh action handler.

func NewMQTTPublish

func NewMQTTPublish(deps Deps) flows.ActionHandler

NewMQTTPublish constructs the built-in mqtt.publish action handler.

func NewNotifySend

func NewNotifySend(deps Deps) flows.ActionHandler

NewNotifySend constructs the built-in notify.send action handler.

func NewPlaybackStopSession

func NewPlaybackStopSession(deps Deps) flows.ActionHandler

NewPlaybackStopSession constructs the built-in playback.stop_session action. It supports explicit session targeting as well as dynamic selectors (lowest_priority_transcode, oldest_paused, viewer_oldest) and routes termination through the same path Plex /status/sessions/terminate uses.

func NewRegistry

func NewRegistry(deps Deps) (*flows.InMemoryActionRegistry, error)

NewRegistry builds a fresh InMemoryActionRegistry pre-populated with all built-in Flow actions.

func NewReleasePin

func NewReleasePin(deps Deps) flows.ActionHandler

NewReleasePin constructs the built-in release.pin action handler.

func NewReleaseUnpin

func NewReleaseUnpin(deps Deps) flows.ActionHandler

NewReleaseUnpin constructs the built-in release.unpin action handler.

func NewSourceRefresh

func NewSourceRefresh(deps Deps) flows.ActionHandler

NewSourceRefresh constructs the built-in source.refresh action handler.

func NewViewerRestrict

func NewViewerRestrict(deps Deps) flows.ActionHandler

NewViewerRestrict constructs the built-in viewer.restrict action handler.

func NewViewerUnrestrict

func NewViewerUnrestrict(deps Deps) flows.ActionHandler

NewViewerUnrestrict constructs the built-in viewer.unrestrict action handler.

func RegisterAll

func RegisterAll(reg flows.ActionRegistry, deps Deps) error

RegisterAll registers every built-in Flow action into reg.

func Specs

func Specs() []flows.ActionSpec

Specs returns the ActionSpec metadata for all 13 built-in actions without requiring live subsystem dependencies.

Types

type ActiveSession

type ActiveSession struct {
	ID            string
	ClientSession string // optional frontend session ID (e.g. Plex sessionId)
	ViewerID      string
	Username      string
	ViewerRole    string
	ViewerTags    []string
	ClientID      string
	ClientName    string
	Platform      string
	TitleKey      string
	TitleName     string
	State         string // "playing" | "paused" | "buffering" | "stopped"
	IsTranscode   bool
	VideoDecision string // "direct_play" | "copy" | "transcode"
	VideoHeight   int
	BitrateKbps   int
	IsRemote      bool
	StartedAt     time.Time
	PausedSince   time.Time
	LastActive    time.Time
	Node          string
}

ActiveSession is the normalized view of one active playback session used by playback.stop_session selectors.

type Deps

type Deps struct {
	Notify       Notifier
	Playback     PlaybackController
	HTTPClient   *http.Client
	TrustedHosts []string
	Viewers      ViewerController
	Restrictions *RestrictionStore
	Libraries    LibraryController
	Exports      ExportSink
	Digests      DigestSource
	Sources      SourceRefresher
	Releases     ReleasePinner
	Now          func() time.Time
	Log          *slog.Logger
}

Deps supplies subsystem adapters for built-in Flow actions. Nil dependencies cause only the actions relying on them to return a clear unavailable error when executed (specs remain inspectable and validatable even with empty Deps).

type DigestActivitySummary

type DigestActivitySummary struct {
	TotalPlays    int
	UniqueViewers int
	HoursWatched  float64
	TopTitles     []DigestTopTitle
}

DigestActivitySummary summarizes playback activity over a digest window.

type DigestItem

type DigestItem struct {
	TitleKey    string
	Title       string
	ShowKey     string
	ShowTitle   string
	Season      int
	Episode     int
	MediaType   string // "movie" | "show" | "episode"
	Year        int
	Summary     string
	Genres      []string
	Rating      float64
	PosterURL   string
	LinkURL     string
	LibraryName string
	AddedAt     time.Time
}

DigestItem is one recently added movie, show, or episode entry.

type DigestQuery

type DigestQuery struct {
	Since      time.Time
	Until      time.Time
	LibraryIDs []string
	MediaTypes []string
	MaxItems   int
}

DigestQuery specifies the time window and filters for digest.generate.

type DigestSource

type DigestSource interface {
	RecentlyAdded(ctx context.Context, q DigestQuery) ([]DigestItem, error)
	ActivitySummary(ctx context.Context, since, until time.Time) (DigestActivitySummary, error)
}

DigestSource retrieves recently added media and playback stats for digest.generate.

type DigestTopTitle

type DigestTopTitle struct {
	Title string
	Plays int
}

DigestTopTitle is a top-watched title included in activity digests.

type ExportArtifact

type ExportArtifact struct {
	Filename    string `json:"filename"`
	ExportPath  string `json:"exportPath"`
	DownloadURL string `json:"downloadUrl"`
	SizeBytes   int64  `json:"sizeBytes"`
}

ExportArtifact describes a persisted export or shareable digest file.

type ExportItem

type ExportItem struct {
	Key           string   `json:"key" xml:"key,attr"`
	Title         string   `json:"title" xml:"Title"`
	ShowTitle     string   `json:"showTitle,omitempty" xml:"ShowTitle,omitempty"`
	Season        int      `json:"season,omitempty" xml:"Season,omitempty"`
	Episode       int      `json:"episode,omitempty" xml:"Episode,omitempty"`
	MediaType     string   `json:"mediaType" xml:"MediaType"`
	Year          int      `json:"year,omitempty" xml:"Year,omitempty"`
	LibraryID     string   `json:"libraryId,omitempty" xml:"LibraryId,omitempty"`
	LibraryName   string   `json:"libraryName,omitempty" xml:"LibraryName,omitempty"`
	Summary       string   `json:"summary,omitempty" xml:"Summary,omitempty"`
	ContentRating string   `json:"contentRating,omitempty" xml:"ContentRating,omitempty"`
	Studio        string   `json:"studio,omitempty" xml:"Studio,omitempty"`
	Rating        float64  `json:"rating,omitempty" xml:"Rating,omitempty"`
	AddedAt       string   `json:"addedAt,omitempty" xml:"AddedAt,omitempty"`
	Genres        []string `json:"genres,omitempty" xml:"Genres>Genre,omitempty"`
	Actors        []string `json:"actors,omitempty" xml:"Actors>Actor,omitempty"`
	Directors     []string `json:"directors,omitempty" xml:"Directors>Director,omitempty"`
	Labels        []string `json:"labels,omitempty" xml:"Labels>Label,omitempty"`
	ExternalIDs   []string `json:"externalIds,omitempty" xml:"ExternalIds>Id,omitempty"`
	DurationMS    int64    `json:"durationMs,omitempty" xml:"DurationMs,omitempty"`
	Container     string   `json:"container,omitempty" xml:"Container,omitempty"`
	VideoCodec    string   `json:"videoCodec,omitempty" xml:"VideoCodec,omitempty"`
	VideoWidth    int      `json:"videoWidth,omitempty" xml:"VideoWidth,omitempty"`
	VideoHeight   int      `json:"videoHeight,omitempty" xml:"VideoHeight,omitempty"`
	DynamicRange  string   `json:"dynamicRange,omitempty" xml:"DynamicRange,omitempty"`
	AudioCodec    string   `json:"audioCodec,omitempty" xml:"AudioCodec,omitempty"`
	AudioChannels int      `json:"audioChannels,omitempty" xml:"AudioChannels,omitempty"`
	BitrateKbps   int      `json:"bitrateKbps,omitempty" xml:"BitrateKbps,omitempty"`
	FileSizeBytes int64    `json:"fileSizeBytes,omitempty" xml:"FileSizeBytes,omitempty"`
	PosterURL     string   `json:"posterUrl,omitempty" xml:"PosterUrl,omitempty"`
	BackdropURL   string   `json:"backdropUrl,omitempty" xml:"BackdropUrl,omitempty"`
	PlayURL       string   `json:"playUrl,omitempty" xml:"PlayUrl,omitempty"`
}

ExportItem is one normalized media item serialized by library.export.

type ExportQuery

type ExportQuery struct {
	Scope          string // "server" | "library" | "collection" | "playlist" | "item"
	TargetID       string
	MetadataLevel  int
	MediaInfoLevel int
	ArtworkLevel   int
	MaxItems       int
}

ExportQuery scopes what library.export retrieves from LibraryController.

type ExportSink

type ExportSink interface {
	Save(ctx context.Context, filename string, data []byte) (ExportArtifact, error)
}

ExportSink persists generated exports or shareable digest HTML files safely.

type FileExportSink

type FileExportSink struct {
	Dir             string
	BaseDownloadURL string // e.g. "/api/flows/exports"
	MaxBytes        int64
	MaxFiles        int
}

FileExportSink writes export and digest artifacts atomically inside Dir, enforcing bounded size and retention and rejecting any path traversal.

func (*FileExportSink) Save

func (s *FileExportSink) Save(_ context.Context, filename string, data []byte) (ExportArtifact, error)

Save atomically persists data to a sanitized filename inside s.Dir.

type LibraryController

type LibraryController interface {
	RefreshLibrary(ctx context.Context, libraryID string, fullSync bool) (RefreshResult, error)
	RefreshCollection(ctx context.Context, collectionID string) (RefreshResult, error)
	ListExportItems(ctx context.Context, q ExportQuery) ([]ExportItem, error)
}

LibraryController handles library/collection refresh and item enumeration for export.

type Notifier

type Notifier interface {
	DeliverToChannels(ctx context.Context, channelIDs []string, ev notify.Event, opts notify.DeliverOptions) ([]notify.DeliverResult, error)
	PublishMQTT(ctx context.Context, brokerID, topic string, payload []byte, qos byte, retain bool) error
}

Notifier delivers Flow notifications through configured notification channels and publishes MQTT messages via configured MQTT broker channels.

type PinResult

type PinResult struct {
	TitleKey    string
	TitleName   string
	ReleaseID   string
	ReleaseName string
}

PinResult reports the outcome of release.pin.

type PlaybackController

type PlaybackController interface {
	ListSessions(ctx context.Context) ([]ActiveSession, error)
	StopSession(ctx context.Context, sessionID, message string) error
}

PlaybackController lists active sessions and stops a session with a message delivered to the viewer's client (matching Plex /status/sessions/terminate).

type RefreshResult

type RefreshResult struct {
	Target     string `json:"target"`
	Kind       string `json:"kind"`
	Items      int    `json:"items"`
	DurationMS int64  `json:"durationMs"`
}

RefreshResult summarizes a completed library, collection, or source refresh.

type ReleasePinner

type ReleasePinner interface {
	PinRelease(ctx context.Context, titleKey, releaseID, note string) (PinResult, error)
	UnpinRelease(ctx context.Context, titleKey string) error
}

ReleasePinner pins and unpins releases for titles.

type RestrictionStore

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

RestrictionStore persists temporary viewer restrictions (DB-backed when db is non-nil, or in-memory for lightweight tests).

func NewMemoryRestrictionStore

func NewMemoryRestrictionStore(now func() time.Time) *RestrictionStore

NewMemoryRestrictionStore creates an in-memory RestrictionStore.

func NewRestrictionStore

func NewRestrictionStore(db *sql.DB, now func() time.Time) *RestrictionStore

NewRestrictionStore creates a DB-backed RestrictionStore.

func (*RestrictionStore) Delete

func (s *RestrictionStore) Delete(ctx context.Context, viewerID string) error

Delete removes any active restriction record for viewerID.

func (*RestrictionStore) Get

Get returns the active restriction record for viewerID, if any.

func (*RestrictionStore) RevertDue

func (s *RestrictionStore) RevertDue(ctx context.Context, viewers ViewerController) (int, error)

RevertDue restores every temporary viewer restriction whose RevertAt has elapsed and removes the stored record. Bounded to 100 viewers per pass.

func (*RestrictionStore) RunReverter

func (s *RestrictionStore) RunReverter(ctx context.Context, viewers ViewerController, interval time.Duration)

RunReverter periodically calls RevertDue until ctx is cancelled.

func (*RestrictionStore) SaveIfAbsentOrUpdate

func (s *RestrictionStore) SaveIfAbsentOrUpdate(ctx context.Context, rec ViewerRestrictionRecord) error

SaveIfAbsentOrUpdate preserves the original pre-restriction baseline when a viewer already has an active restriction record, while updating the applied patch, reason, and revert deadline.

type SourceRefresher

type SourceRefresher interface {
	RefreshSource(ctx context.Context, sourceKind, sourceID string) (RefreshResult, error)
}

SourceRefresher triggers Live TV, watchlist, or plugin source refreshes.

type ViewerController

type ViewerController interface {
	GetViewerPolicy(ctx context.Context, viewerID string) (ViewerPolicySnapshot, error)
	ApplyViewerPolicy(ctx context.Context, viewerID string, patch ViewerRestrictionPatch) error
}

ViewerController reads and applies viewer safety & account restrictions.

type ViewerPolicySnapshot

type ViewerPolicySnapshot struct {
	ViewerID       string `json:"viewerId"`
	RemoteDisabled bool   `json:"remoteDisabled"`
	MaxBitrateKbps int    `json:"maxBitrateKbps"`
	StreamLimit    int    `json:"streamLimit"`
	AccountEnabled bool   `json:"accountEnabled"`
}

ViewerPolicySnapshot captures the reversible viewer restriction fields.

type ViewerRestrictionPatch

type ViewerRestrictionPatch struct {
	RemoteDisabled *bool `json:"remoteDisabled,omitempty"`
	MaxBitrateKbps *int  `json:"maxBitrateKbps,omitempty"`
	StreamLimit    *int  `json:"streamLimit,omitempty"`
	AccountEnabled *bool `json:"accountEnabled,omitempty"`
}

ViewerRestrictionPatch specifies which fields to change on a viewer.

type ViewerRestrictionRecord

type ViewerRestrictionRecord struct {
	ViewerID  string                 `json:"viewerId"`
	Previous  ViewerPolicySnapshot   `json:"previous"`
	Applied   ViewerRestrictionPatch `json:"applied"`
	Reason    string                 `json:"reason,omitempty"`
	AppliedAt time.Time              `json:"appliedAt"`
	RevertAt  time.Time              `json:"revertAt,omitempty"`
}

ViewerRestrictionRecord stores the pre-restriction snapshot for a viewer so viewer.unrestrict or automatic revertAfter expiry restores prior settings instead of clobbering permanent owner configuration.

Jump to

Keyboard shortcuts

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