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 ¶
- func All(deps Deps) []flows.ActionHandler
- func BuiltinHTTPClient() *http.Client
- func NewDigestGenerate(deps Deps) flows.ActionHandler
- func NewFlowSetVariable(_ Deps) flows.ActionHandler
- func NewHTTPWebhook(deps Deps) flows.ActionHandler
- func NewLibraryExport(deps Deps) flows.ActionHandler
- func NewLibraryRefresh(deps Deps) flows.ActionHandler
- func NewMQTTPublish(deps Deps) flows.ActionHandler
- func NewNotifySend(deps Deps) flows.ActionHandler
- func NewPlaybackStopSession(deps Deps) flows.ActionHandler
- func NewRegistry(deps Deps) (*flows.InMemoryActionRegistry, error)
- func NewReleasePin(deps Deps) flows.ActionHandler
- func NewReleaseUnpin(deps Deps) flows.ActionHandler
- func NewSourceRefresh(deps Deps) flows.ActionHandler
- func NewViewerRestrict(deps Deps) flows.ActionHandler
- func NewViewerUnrestrict(deps Deps) flows.ActionHandler
- func RegisterAll(reg flows.ActionRegistry, deps Deps) error
- func Specs() []flows.ActionSpec
- type ActiveSession
- type Deps
- type DigestActivitySummary
- type DigestItem
- type DigestQuery
- type DigestSource
- type DigestTopTitle
- type ExportArtifact
- type ExportItem
- type ExportQuery
- type ExportSink
- type FileExportSink
- type LibraryController
- type Notifier
- type PinResult
- type PlaybackController
- type RefreshResult
- type ReleasePinner
- type RestrictionStore
- func (s *RestrictionStore) Delete(ctx context.Context, viewerID string) error
- func (s *RestrictionStore) Get(ctx context.Context, viewerID string) (ViewerRestrictionRecord, bool, error)
- func (s *RestrictionStore) RevertDue(ctx context.Context, viewers ViewerController) (int, error)
- func (s *RestrictionStore) RunReverter(ctx context.Context, viewers ViewerController, interval time.Duration)
- func (s *RestrictionStore) SaveIfAbsentOrUpdate(ctx context.Context, rec ViewerRestrictionRecord) error
- type SourceRefresher
- type ViewerController
- type ViewerPolicySnapshot
- type ViewerRestrictionPatch
- type ViewerRestrictionRecord
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 ¶
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 ¶
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 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 ¶
func (s *RestrictionStore) Get(ctx context.Context, viewerID string) (ViewerRestrictionRecord, bool, error)
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.