etherplugin

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

README

etherplugin (Go SDK)

Go authoring package (github.com/braedonsaunders/ether/sdk/go) for Ether Plugin Protocol v1 (EPP/1).

Execution modes

  1. Native HTTP or WebSocket tunnel sidecar (ether.runtime.kind: "remote"): Compile a standard Go binary and call p.Serve(ctx, etherplugin.ServeOptions{}) (or mount p as an http.Handler). Host calls go over HTTP to /ether/plugin-host/* authenticated with X-Ether-Plugin-Credential.
  2. Hosted WebAssembly guest: not yet supported. Go 1.27.3 GOOS=wasip1 GOARCH=wasm emits wasi_snapshot_preview1 imports (including proc_exit, clock_time_get, and fd_write), which the runtime forbids. TinyGo is not installed here, so a compatible TinyGo build has not been verified. Use a sidecar until a guest is built and tested against Ether's raw WASM ABI.

Usage

package main

import (
	"context"
	"os/signal"
	"syscall"

	etherplugin "github.com/braedonsaunders/ether/sdk/go"
)

func main() {
	p := etherplugin.New(etherplugin.Definition{
		Manifest: etherplugin.Manifest{
			ID:      "org.ether.examples.hello",
			Name:    "Hello plugin",
			Version: "0.1.0",
			Ether: &etherplugin.EtherManifestBlock{
				Protocol:     1,
				Kind:         etherplugin.KindExtension,
				Capabilities: []etherplugin.Capability{etherplugin.CapListSource, etherplugin.CapUI},
				Summary:      "Minimal greeting plugin for Ether.",
				Runtime:      etherplugin.RuntimeDecl{Kind: "remote"},
			},
		},
		Routes: etherplugin.Routes{
			Catalog: func(ctx *etherplugin.Context, req etherplugin.CatalogRequest) (etherplugin.CatalogResponse, error) {
				return etherplugin.CatalogResponse{
					Metas: []etherplugin.CatalogItem{{
						ID:          "tt0133093",
						Type:        req.Type,
						Name:        "Hello from " + req.ID,
						ReleaseInfo: "1999",
					}},
				}, nil
			},
		},
	})

	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()
	_ = p.Serve(ctx, etherplugin.ServeOptions{})
}

Flows: events and actions

Declare CapEvents with Contributes.Events.Publish to emit schema-validated custom events to Ether Flows via ctx.PublishEvent(key, payload, correlation) (remote POST /ether/plugin-host/events/publish, rate-limited to 30/min). Declare CapFlowActions with Contributes.FlowActions and implement Routes.FlowAction to handle POST /ether/v1/flow-actions/{key} (or a custom declared /ether/... route); FlowActionRequest.IdempotencyKey carries X-Ether-Idempotency-Key for safe deduplication and FlowActionRequest.DryRun indicates a test/dry run.

WS8b interoperability test

Once internal/plugins/remote is present, run go test -tags ws8b ./sdk/examples/hello/go -run TestWS8bSDKInterop. It starts Ether's tunnel server and exercises the Go, Python, and TypeScript hello sidecars. It requires Python 3 and a Node version with TypeScript support and WebSocket. The Go SDK reconnects automatically after a dropped tunnel.

Tunnel recovery

Start(ctx, ServeOptions{Mode: "tunnel", ...}) returns after the initial credential authentication and hello/welcome handshake; initial failures are returned to the caller. After that, dropped connections retry serially with jittered exponential backoff (50–100 ms initially, capped at 5–10 seconds). Every attempt re-authenticates and repeats the handshake, with a 10-second connection/handshake timeout. A connection stable for a minute resets backoff.

In-flight calls fail on disconnect and are not replayed. Ether runtimes resolve the current connection for subsequent calls. handle.Done stays open during recovery; cancelling ctx or calling handle.Close() stops active I/O and any retry, closes the socket, and closes Done. Close is safe to call repeatedly. Request cancellation stops that handler without closing the shared tunnel.

Sidecars

A sidecar is a remote plugin whose program runs on a machine you choose and dials out to Ether over the ether-tunnel-v1 WebSocket. It needs no inbound port. Use one when the program must reach a local network, a USB device, or an installed tool that Ether's sandbox cannot.

Set ETHER_URL and pair once:

ETHER_URL=https://ether.example.com \
ETHER_PLUGIN_STATE_DIR=/data \
ETHER_PAIRING_CODE=PAIR-1234 \
./my-sidecar

The SDK exchanges the code once, saves the credential, and derives the tunnel URL from ETHER_URL. Create the code in Ether under Plugins › your plugin › Connect a sidecar; it is valid for 5 minutes and single use. On later restarts the saved credential is reused, so no new code is needed.

  • ETHER_URL — the server's http(s) base. The pair URL and the ws(s) tunnel URL are derived from it.
  • ETHER_PLUGIN_CREDENTIAL — an explicit credential; always wins.
  • ETHER_PLUGIN_STATE_DIR — where the credential is saved, else /data when it exists and is writable (a Docker volume), else the OS user config directory …/ether-plugins/<plugin id>/.
  • ETHER_PAIRING_CODE — a one-time code.

The credential is saved at <state dir>/credential (mode 0600, directory 0700) as JSON with the Ether URL it belongs to. If the tunnel rejects a saved credential, the file is deleted and startup fails with one line instead of reconnecting forever.

A Dockerfile that keeps the credential across restarts:

FROM golang:1.27 AS build
WORKDIR /src
COPY . .
RUN go build -o /out/sidecar ./cmd/sidecar

FROM gcr.io/distroless/static
COPY --from=build /out/sidecar /sidecar
VOLUME /data
ENV ETHER_PLUGIN_STATE_DIR=/data
ENTRYPOINT ["/sidecar"]

Declare how the console runs it with an ether.sidecar manifest block:

"ether": {
  "runtime": { "kind": "remote" },
  "sidecar": {
    "docker": "ghcr.io/you/my-sidecar:1.0.0",
    "docs": "https://example.com/my-sidecar"
  }
}

docker is an image reference; download (an https URL) with command (a single line) is the alternative; docs adds a setup link. With a Docker image the console shows a ready docker run command, mounting -v ether-<id>:/data so the saved credential survives a restart.

Documentation

Overview

Package etherplugin is the Go authoring SDK for Ether Plugin Protocol v1 (EPP/1).

It provides the same declarative router shape, settings decoder, localization helper, host service client, test harness, and capability templates as `@ether/plugin-sdk` (TypeScript) and `ether_plugin` (Python).

Execution modes

Go plugins run as native HTTP or WebSocket tunnel sidecars. Hosted Go is not supported: the standard Go wasip1 toolchain emits WASI imports, which Ether's sandbox rejects. See README.md for details.

Server packages under `internal/` and `cmd/` must not import this package.

Index

Constants

View Source
const (
	MinDataReadBytes    int64 = 8 << 20
	MaxDataReadBytes    int64 = 512 << 20
	MaxArchiveReadItems       = 4096
)

BlobHost provides bounded data services. RemoteHostClient implements it; obtain it with ctx.Host.(etherplugin.BlobHost) when starting from Host. The host enforces network grants and the plugin's library cache quota.

View Source
const (
	// DefaultFetchManyConcurrency and MaxFetchManyConcurrency bound the
	// per-call parallelism of Host.FetchMany.
	DefaultFetchManyConcurrency = 8
	MaxFetchManyConcurrency     = 8
	// MaxFetchManyRequests caps the number of requests per FetchMany call.
	MaxFetchManyRequests = 64
	// DefaultMaxFetchPerHost bounds concurrent requests to any single origin.
	DefaultMaxFetchPerHost = 6
)
View Source
const (
	// MaxKindVisibleIDs is the per-call batch cap for kinds.visible (#615).
	MaxKindVisibleIDs = 500
	// HeaderViewerToken carries the host-minted, request-scoped adapter viewer
	// proof header on frontend adapter calls (#615).
	HeaderViewerToken = "X-Ether-Viewer-Token"
)
View Source
const (
	// PairExchangePath accepts a one-time code and returns a credential.
	PairExchangePath = "/ether/plugins/pair"
	// TunnelPath is the WebSocket endpoint a paired sidecar dials.
	TunnelPath = "/ether/plugins/tunnel"
)

PairingPaths are the fixed Ether endpoints a sidecar uses to pair.

View Source
const (
	// TunnelProtocol is the WebSocket subprotocol for Ether remote plugin tunnels.
	TunnelProtocol = "ether-tunnel-v1"
	// DefaultMaxChunkBytes is the default chunk size for streamed file responses.
	DefaultMaxChunkBytes = 64 * 1024
)
View Source
const (
	MaxPosterBadgeSets     = 4
	MaxBadgeEntriesPerCall = 500
	MaxBadgeLabelsPerTitle = 3
	MaxBadgeLabelLen       = 16
	PosterBadgeQuotaTitles = 200_000
)

Poster badge bounds (#594).

View Source
const (
	KindSyncPull = "pull"
	KindSyncPush = "push"
)

Kind sync modes: pull (Ether walks browse/changes) or push (KindUpsert).

View Source
const DefaultKindExpandTTLHours = 168

DefaultKindExpandTTLHours is the default freshness window (7 days) for on-demand facet and person slice expansions when ttlHours is omitted or zero.

View Source
const HeaderIdempotencyKey = "X-Ether-Idempotency-Key"

HeaderIdempotencyKey carries the Flow step idempotency key on plugin flow action calls.

View Source
const MaxKindLibraryShelves = 40

MaxKindLibraryShelves is the maximum number of declared Recommended shelves per kind library.

View Source
const MaxKindLibraryTabs = 50

MaxKindLibraryTabs is the maximum number of declared sub-tabs per kind library.

Variables

View Source
var (
	ErrKindNotFound     = &RouteError{Status: http.StatusNotFound, Code: "not_found", Message: "Item not found."}
	ErrKindNotAvailable = &RouteError{Status: http.StatusOK, Code: "not_available", Message: "No source is available right now."}
)

Reserved plugin error codes Ether understands on kind routes.

View Source
var Fixtures = struct {
	PickToken     func(itemID string) string
	Movie         func() MetaItem
	CatalogItem   func() CatalogItem
	PlaybackEvent func(name string) EtherEvent
	Candidate     func() CandidateFacts
}{
	PickToken: func(itemID string) string {
		if itemID == "" {
			itemID = "ether:movie:1"
		}
		return "pick-v1:" + itemID + ":sig-test"
	},
	Movie: func() MetaItem {
		return MetaItem{
			CatalogItem: CatalogItem{
				ID:          "tt0133093",
				Type:        "movie",
				Name:        "The Matrix",
				ReleaseInfo: "1999",
				Description: "A computer hacker learns about the true nature of reality.",
				Genres:      []string{"Action", "Sci-Fi"},
				IMDBRating:  "8.7",
			},
		}
	},
	CatalogItem: func() CatalogItem {
		return CatalogItem{
			ID:          "tt0133093",
			Type:        "movie",
			Name:        "The Matrix",
			ReleaseInfo: "1999",
		}
	},
	PlaybackEvent: func(name string) EtherEvent {
		if name == "" {
			name = "playback.completed"
		}
		return EtherEvent{
			ID:       "evt_01",
			Name:     name,
			At:       "2026-11-02T12:00:00Z",
			ViewerID: 1,
			Payload: map[string]any{
				"titleId":  "tt0133093",
				"title":    "The Matrix",
				"progress": 0.95,
			},
		}
	},
	Candidate: func() CandidateFacts {
		return CandidateFacts{
			ReleaseID:  "rel_01",
			Name:       "The.Matrix.1999.2160p.UHD.BluRay.x265",
			Resolution: 2160,
			HDR:        []string{"DV", "HDR10"},
			VideoCodec: "hevc",
			Cached:     true,
			Verified:   true,
		}
	},
}

Fixtures provides sample EPP/1 records for plugin unit tests.

Functions

func AssertValidViewSpec

func AssertValidViewSpec(doc ViewSpecDocument) error

AssertValidViewSpec validates a ViewSpecDocument for structural rules and rejects any `*ClassName` fields.

func DecodeSettings

func DecodeSettings(
	schema *SettingsSchema,
	incoming map[string]any,
	defaults map[string]any,
) (map[string]any, map[string]string)

DecodeSettings applies schema defaults and validates incoming settings, returning the decoded settings map and any JSON-pointer keyed errors.

func LintCopy

func LintCopy(raw string, maxRunes int) string

LintCopy validates a user-visible string against Ether's copy rules. It returns an empty string when valid, or the plain reason when invalid.

func PairURL

func PairURL(base string) (string, error)

PairURL returns the absolute URL that exchanges a code for a credential.

func StateDir

func StateDir(explicit, pluginID string) (string, error)

StateDir resolves where the credential file is kept: an explicit dir, else /data when it exists and is writable (a Docker volume), else the OS user config dir under ether-plugins/<plugin id>/.

func TRef

func TRef(key string) string

TRef formats a "$t:<key>" localization reference for manifests and ViewSpecs.

func TunnelURL

func TunnelURL(base string) (string, error)

TunnelURL returns the absolute ws(s) tunnel URL for a server base.

func ViewerTokenFromContext

func ViewerTokenFromContext(ctx context.Context) (string, bool)

ViewerTokenFromContext returns the adapter viewer token attached by WithViewerToken (or automatically during FrontendAdapter dispatch).

func WithViewerToken

func WithViewerToken(ctx context.Context, token string) context.Context

WithViewerToken attaches the host-minted X-Ether-Viewer-Token from an incoming frontend adapter request onto ctx so KindVisible and KindBrowse authenticate as that request's viewer without passing a viewer ID (#615).

Types

type AICompleteRequest

type AICompleteRequest struct {
	Messages []AIMessage `json:"messages"`
	// Schema is an optional JSON Schema object (raw JSON or map[string]any
	// marshalled to JSON). When set, Ether extracts JSON from the model reply
	// and validates it against Schema before returning. External $ref URLs are
	// rejected.
	Schema json.RawMessage `json:"schema,omitempty"`
	// MaxTokens bounds output tokens (default 1024, max 4096).
	MaxTokens int `json:"maxTokens,omitempty"`
	// Temperature optionally adjusts sampling in [0, 2]; ignored safely by
	// providers/models that disallow explicit temperature.
	Temperature *float64 `json:"temperature,omitempty"`
	// TimeoutMS optionally tightens the call timeout (clamped to 30000 ms on
	// background/action routes, 20000 ms on interactive search routes, and the
	// enclosing call deadline).
	TimeoutMS int64 `json:"timeoutMs,omitempty"`
	// SearchQuery identifies the viewer's search text when calling ai.complete
	// on an interactive search route under permissions.ai: "complete+search".
	// Required on adapter search routes without a URL query param (e.g. GraphQL)
	// and used for normalized per-query caching.
	SearchQuery string `json:"searchQuery,omitempty"`
}

AICompleteRequest configures one completion on the owner's configured language model (#669).

type AICompleteResponse

type AICompleteResponse struct {
	// Text is the assistant reply (with reasoning blocks stripped). When Schema
	// was set, Text holds compact canonical JSON.
	Text string `json:"text"`
	// JSON holds the validated JSON value when Schema was set.
	JSON json.RawMessage `json:"json,omitempty"`
}

AICompleteResponse is the completion returned by AIHost.AIComplete.

type AIHost

type AIHost interface {
	AIComplete(ctx context.Context, req AICompleteRequest) (AICompleteResponse, error)
}

AIHost runs bounded completions on the owner's configured language model (requires permissions.ai: "complete", or "complete+search" for opted-in interactive search routes; every other viewer/client path stays refused). RemoteHostClient and MockHost implement it; Context.AIComplete uses it automatically.

type AIMessage

type AIMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

AIMessage is one chat turn sent to AIHost.AIComplete.

type ActionProposal

type ActionProposal struct {
	Category    string         `json:"category"`
	Description string         `json:"description"`
	Input       map[string]any `json:"input,omitempty"`
}

ActionProposal describes a confirmation proposal returned by an Action handler.

type ActionRequest

type ActionRequest struct {
	Action string         `json:"action"`
	Input  map[string]any `json:"input"`
}

ActionRequest is passed to an Action route handler.

type ActionResponse

type ActionResponse struct {
	Toast    string          `json:"toast,omitempty"`
	Refresh  bool            `json:"refresh,omitempty"`
	Open     string          `json:"open,omitempty"`
	Proposal *ActionProposal `json:"proposal,omitempty"`
}

ActionResponse is returned by an Action route handler.

type ArchiveExtractOptions

type ArchiveExtractOptions struct {
	LibraryKey string `json:"libraryKey,omitempty"`
	Name       string `json:"name,omitempty"`
}

type ArchiveExtractResult

type ArchiveExtractResult struct {
	Ref   string `json:"ref"`
	Size  int64  `json:"size"`
	SHA1  string `json:"sha1"`
	MD5   string `json:"md5"`
	CRC32 string `json:"crc32"`
}

type ArchiveMember

type ArchiveMember struct {
	Index int    `json:"index"`
	Name  string `json:"name"`
	Size  uint64 `json:"size"`
	// Unsafe names identify members only and must never be used as output paths.
	Unsafe       bool   `json:"unsafe,omitempty"`
	UnsafeReason string `json:"unsafeReason,omitempty"`
}

type ArchiveReadItem

type ArchiveReadItem struct {
	Member int   `json:"member"`
	Offset int64 `json:"offset"`
	Length int64 `json:"length"`
}

type ArchiveReadResult

type ArchiveReadResult struct {
	Index  int    `json:"index"`
	Member int    `json:"member"`
	Size   int    `json:"size"`
	Body   []byte `json:"body"`
}

type BadgeEntry

type BadgeEntry struct {
	Title  BadgeTitleRef `json:"title"`
	Labels []string      `json:"labels"`
}

BadgeEntry pushes or clears (empty Labels) poster badges for one title.

type BadgeTitleRef

type BadgeTitleRef struct {
	Type string `json:"type"`
	TMDB int64  `json:"tmdb,omitempty"`
	IMDB string `json:"imdb,omitempty"`
}

BadgeTitleRef identifies a canonical movie or show by TMDB and/or IMDb id.

type BadgeUsage

type BadgeUsage struct {
	Titles      int64 `json:"titles"`
	QuotaTitles int64 `json:"quotaTitles"`
}

BadgeUsage reports a plugin's badged title count and per-plugin title quota.

type BadgesHost

type BadgesHost interface {
	BadgesSet(ctx context.Context, setKey string, entries []BadgeEntry) error
	BadgesClear(ctx context.Context, setKey string) error
	BadgesUsage(ctx context.Context) (BadgeUsage, error)
}

BadgesHost pushes, clears, and inspects plugin-owned poster badges (#594). RemoteHostClient and MockHost implement it.

type BehaviorHints

type BehaviorHints struct {
	Adult                 bool `json:"adult,omitempty"`
	P2P                   bool `json:"p2p,omitempty"`
	Configurable          bool `json:"configurable,omitempty"`
	ConfigurationRequired bool `json:"configurationRequired,omitempty"`
}

BehaviorHints carries Stremio-compatible behavior hints.

type CacheDeleteHost

type CacheDeleteHost interface {
	CacheDelete(ctx context.Context, blobRef string) error
}

CacheDeleteHost deletes cached blobs from this plugin's own library cache namespaces. RemoteHostClient and MockHost implement it.

type CandidateFacts

type CandidateFacts struct {
	ReleaseID     string      `json:"releaseId"`
	Name          string      `json:"name"`
	Size          int64       `json:"size,omitempty"`
	Protocol      string      `json:"protocol,omitempty"`
	SourceClass   string      `json:"sourceClass,omitempty"`
	Indexer       string      `json:"indexer,omitempty"`
	Resolution    any         `json:"resolution,omitempty"`
	HDR           []string    `json:"hdr,omitempty"`
	VideoCodec    string      `json:"videoCodec,omitempty"`
	AudioCodecs   []string    `json:"audioCodecs,omitempty"`
	AudioChannels string      `json:"audioChannels,omitempty"`
	Languages     []string    `json:"languages,omitempty"`
	Subtitles     []string    `json:"subtitles,omitempty"`
	ReleaseType   string      `json:"releaseType,omitempty"`
	Group         string      `json:"group,omitempty"`
	Cached        bool        `json:"cached,omitempty"`
	Verified      bool        `json:"verified,omitempty"`
	ClientCaps    *ClientCaps `json:"clientCaps,omitempty"`
}

CandidateFacts is the release candidate structure passed to RankKey and CondMatch.

type Capability

type Capability string

Capability names a capability declared in manifest.ether.capabilities.

const (
	CapStreamSource    Capability = "stream_source"
	CapDebridProvider  Capability = "debrid_provider"
	CapListSource      Capability = "list_source"
	CapLiveTV          Capability = "livetv_channels"
	CapSubtitles       Capability = "subtitles"
	CapMarkers         Capability = "markers"
	CapNotify          Capability = "notify"
	CapEvents          Capability = "events"
	CapFlowActions     Capability = "flow_actions"
	CapRankingStep     Capability = "ranking_step"
	CapRuleCondition   Capability = "rule_condition"
	CapTools           Capability = "tools"
	CapUI              Capability = "ui"
	CapCatalogProvider Capability = "catalog_provider"
	CapKindResolver    Capability = "kind_resolver"
	CapFrontendAdapter Capability = "frontend_adapter"
	CapMatcher         Capability = "matcher"
	CapPosterBadges    Capability = "poster_badges"
)

type CatalogItem

type CatalogItem struct {
	ID          string   `json:"id"`
	Type        string   `json:"type"`
	Name        string   `json:"name"`
	Poster      string   `json:"poster,omitempty"`
	PosterShape string   `json:"posterShape,omitempty"`
	Background  string   `json:"background,omitempty"`
	Description string   `json:"description,omitempty"`
	ReleaseInfo string   `json:"releaseInfo,omitempty"`
	IMDBRating  string   `json:"imdbRating,omitempty"`
	Genres      []string `json:"genres,omitempty"`
}

CatalogItem is one item in a catalog response.

type CatalogProvider

type CatalogProvider interface {
	Browse(ctx *Context, req KindBrowseRequest) (KindPage, error)
	Detail(ctx *Context, kind, id string) (KindItem, error)
}

CatalogProvider serves browse and detail for one kind. Implement ChangesProvider too for delta pull sync; without it Ether re-walks.

type CatalogRequest

type CatalogRequest struct {
	Type   string            `json:"type"`
	ID     string            `json:"id"`
	Extra  map[string]string `json:"extra"`
	Skip   int               `json:"skip"`
	Search string            `json:"search,omitempty"`
	Genre  string            `json:"genre,omitempty"`
}

CatalogRequest is passed to a Catalog route handler.

type CatalogResponse

type CatalogResponse struct {
	Metas []CatalogItem `json:"metas"`
}

CatalogResponse is returned by a Catalog route handler.

type CatalogTitleSummary

type CatalogTitleSummary struct {
	ID     any    `json:"id"`
	Title  string `json:"title"`
	Type   string `json:"type"`
	Year   int    `json:"year,omitempty"`
	IMDBID string `json:"imdbId,omitempty"`
	TMDBID int    `json:"tmdbId,omitempty"`
}

CatalogTitleSummary is a catalog record returned by Host.CatalogSearch or Host.CatalogGet.

type ChangesProvider

type ChangesProvider interface {
	Changes(ctx *Context, req KindChangesRequest) (KindChangePage, error)
}

ChangesProvider is the optional delta feed for pull sync.

type ChannelInput

type ChannelInput struct {
	URL      string            `json:"url"`
	Name     string            `json:"name,omitempty"`
	Headers  map[string]string `json:"headers,omitempty"`
	Priority int               `json:"priority,omitempty"`
}

ChannelInput is one stream input for a Live TV channel.

type ChannelItem

type ChannelItem struct {
	ID      string         `json:"id"`
	Name    string         `json:"name"`
	Number  int            `json:"number,omitempty"`
	Group   string         `json:"group,omitempty"`
	GuideID string         `json:"guideId,omitempty"`
	Inputs  []ChannelInput `json:"inputs"`
}

ChannelItem is one Live TV channel.

type ChannelsMeta

type ChannelsMeta struct {
	Refresh string `json:"refresh,omitempty"`
	Test    bool   `json:"test"`
}

ChannelsMeta describes a Live TV channel contribution.

type ChannelsResponse

type ChannelsResponse struct {
	Channels []ChannelItem `json:"channels"`
}

ChannelsResponse is returned by a Channels route handler.

type ClientCaps

type ClientCaps struct {
	MaxHeight int      `json:"maxHeight,omitempty"`
	HDR       []string `json:"hdr,omitempty"`
	Codecs    []string `json:"codecs,omitempty"`
}

ClientCaps describes playback client capabilities passed to hot-path functions.

type CommandMeta

type CommandMeta struct {
	Key    string `json:"key"`
	Label  string `json:"label"`
	Action string `json:"action"`
}

CommandMeta describes a command contributed by a plugin.

type ConfigureResponse

type ConfigureResponse struct {
	Errors map[string]string `json:"errors"`
}

ConfigureResponse is returned by a Configure route handler.

type ContainerRef

type ContainerRef struct {
	Format         string      `json:"format,omitempty"` // "" (sniff)|rar|7z|zip
	Volumes        []VolumeRef `json:"volumes"`
	Member         string      `json:"member,omitempty"`
	MemberIndex    *int        `json:"memberIndex,omitempty"`
	PasswordSecret string      `json:"passwordSecret,omitempty"`
}

ContainerRef describes an archive member inside ordered volumes.

type Context

type Context struct {
	context.Context
	Manifest  Manifest
	Settings  map[string]any
	Locale    string
	PickToken string
	RequestID string
	Headers   map[string]string
	Query     map[string]string
	Ether     Host
	I18n      *I18n
}

Context is passed to every plugin route handler.

func FrontendContext

func FrontendContext(ctx context.Context) (*Context, bool)

FrontendContext returns the Ether plugin Context attached to a FrontendAdapter http.Request during dispatch, so ServeHTTP handlers can call pctx.KindVisible, pctx.KindBrowse, pctx.StreamURL, etc. directly (#615).

func (*Context) AIComplete

func (c *Context) AIComplete(req AICompleteRequest) (AICompleteResponse, error)

AIComplete runs a bounded completion against the owner's configured language model. Requires permissions.ai: "complete" (or "complete+search" for opted-in interactive search routes; every other viewer/client path stays refused).

func (*Context) KindBrowse

func (c *Context) KindBrowse(kindKey string, query KindBrowseQuery) (KindPage, error)

KindBrowse browses or searches kindKey with the library's Rules and viewer access policy applied for the requesting frontend-adapter viewer (#615). Only frontend adapter requests carrying Ether's authenticated viewer token may call it.

func (*Context) KindVisible

func (c *Context) KindVisible(kindKey string, ids []string) ([]string, error)

KindVisible evaluates the library's Rules and viewer access policy for a bounded batch (at most MaxKindVisibleIDs) of external IDs in kindKey (#615). Only frontend adapter requests carrying Ether's authenticated viewer token may call it.

func (*Context) PublishEvent

func (c *Context) PublishEvent(key string, payload any, corr *EventCorrelation) error

PublishEvent emits a manifest-declared plugin event onto Ether's event bus.

func (*Context) StreamPartURL

func (c *Context) StreamPartURL(itemRef string, partIndex int) (string, error)

StreamPartURL mints a short-lived, scoped ticket for one zero-based part of a multi-file kind item (#576) and returns the Ether stream URL to embed in a frontend adapter response.

func (*Context) StreamURL

func (c *Context) StreamURL(itemRef string) (string, error)

StreamURL mints a short-lived, scoped ticket for one of this plugin's own kind items and returns the Ether stream URL to embed in a frontend adapter response (spec §6.5). The viewer is taken from the request's X-Ether-Viewer header, which Ether injects after authenticating; the plugin never sees a credential. Bytes are served by Ether from the ticket, never by the plugin.

func (*Context) StreamURLWithOptions

func (c *Context) StreamURLWithOptions(itemRef string, opts StreamURLOptions) (string, error)

StreamURLWithOptions mints a short-lived, scoped ticket for one of this plugin's own kind items, optionally pinned to a zero-based part and/or a specific resolver PlayableSource.ID (#576, #661).

func (*Context) T

func (c *Context) T(key string, params map[string]any) string

T resolves a localized string key with optional parameter interpolation.

type Contributes

type Contributes struct {
	Source           *SourceMeta           `json:"source,omitempty"`
	Channels         *ChannelsMeta         `json:"channels,omitempty"`
	Subtitles        *SubtitlesMeta        `json:"subtitles,omitempty"`
	Markers          *MarkersMeta          `json:"markers,omitempty"`
	Notification     *NotificationMeta     `json:"notification,omitempty"`
	Events           *EventsMeta           `json:"events,omitempty"`
	FlowActions      []FlowActionMeta      `json:"flowActions,omitempty"`
	Integration      *IntegrationMeta      `json:"integration,omitempty"`
	ListSources      []ListSourceMeta      `json:"listSources,omitempty"`
	RankingSteps     []RankingStepMeta     `json:"rankingSteps,omitempty"`
	RuleConditions   []RuleConditionMeta   `json:"ruleConditions,omitempty"`
	PosterBadges     []PosterBadgeSetMeta  `json:"posterBadges,omitempty"`
	Tools            []ToolMeta            `json:"tools,omitempty"`
	Pages            []PageMeta            `json:"pages,omitempty"`
	Slots            []SlotMeta            `json:"slots,omitempty"`
	Commands         []CommandMeta         `json:"commands,omitempty"`
	MediaKinds       []MediaKindMeta       `json:"mediaKinds,omitempty"`
	FrontendAdapters []FrontendAdapterMeta `json:"frontendAdapters,omitempty"`
	Setup            *SetupMeta            `json:"setup,omitempty"`
}

Contributes declares the descriptors a plugin contributes to Ether.

type DataRange

type DataRange struct {
	Offset int64 `json:"offset"`
	Length int64 `json:"length"`
}

type DebridServiceRef

type DebridServiceRef struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

DebridServiceRef identifies one owner-configured debrid service (without exposing credentials) that holds a cached torrent or served an acquisition.

type Definition

type Definition struct {
	Manifest          Manifest
	Routes            Routes
	DefaultSettings   map[string]any
	Strings           StringsCatalog
	DefaultLocale     string
	Host              Host
	RemoteHostOptions RemoteHostOptions
}

Definition configures a new Plugin instance.

type EtherEvent

type EtherEvent struct {
	ID       string         `json:"id"`
	Name     string         `json:"name"`
	At       string         `json:"at"`
	ViewerID int64          `json:"viewerId,omitempty"`
	Payload  map[string]any `json:"payload,omitempty"`
}

EtherEvent is one event delivered in a batch to POST /ether/event.

type EtherManifestBlock

type EtherManifestBlock struct {
	Protocol     int             `json:"protocol"`
	Kind         PluginKind      `json:"kind"`
	Capabilities []Capability    `json:"capabilities,omitempty"`
	Summary      string          `json:"summary"`
	Author       *PluginAuthor   `json:"author,omitempty"`
	License      string          `json:"license,omitempty"`
	Repo         string          `json:"repo,omitempty"`
	Icon         string          `json:"icon,omitempty"`
	Runtime      RuntimeDecl     `json:"runtime"`
	Cluster      string          `json:"cluster,omitempty"`
	Health       *HealthDecl     `json:"health,omitempty"`
	Permissions  *Permissions    `json:"permissions,omitempty"`
	Settings     *SettingsSchema `json:"settings,omitempty"`
	Strings      map[string]any  `json:"strings,omitempty"`
	Schedule     []ScheduleEntry `json:"schedule,omitempty"`
	Contributes  *Contributes    `json:"contributes,omitempty"`
}

EtherManifestBlock holds the EPP/1 `ether` manifest block.

type EventCorrelation

type EventCorrelation struct {
	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"`
}

EventCorrelation links a published plugin event to related Ether entities.

type EventEnumOption

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

EventEnumOption describes one allowed option for an enum field or parameter.

type EventFieldMeta

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

EventFieldMeta describes one typed field in a published plugin event payload or flow action output object.

type EventFieldType

type EventFieldType string

EventFieldType classifies a typed field in a published event payload or flow action parameter/output schema.

const (
	EventFieldString     EventFieldType = "string"
	EventFieldInt        EventFieldType = "int"
	EventFieldFloat      EventFieldType = "float"
	EventFieldBool       EventFieldType = "bool"
	EventFieldDurationMS EventFieldType = "duration_ms"
	EventFieldTimestamp  EventFieldType = "timestamp"
	EventFieldEnum       EventFieldType = "enum"
	EventFieldStringList EventFieldType = "string_list"
	EventFieldObject     EventFieldType = "object"
)

type EventResponse

type EventResponse struct {
	Ack []string `json:"ack"`
}

EventResponse is returned by an Event route handler.

type EventsHost

type EventsHost interface {
	PublishEvent(ctx context.Context, key string, payload any, corr *EventCorrelation) error
}

EventsHost emits declared plugin events onto Ether's event bus. RemoteHostClient and MockHost implement it; Context.PublishEvent uses it automatically.

type EventsMeta

type EventsMeta struct {
	Subscribe []string             `json:"subscribe,omitempty"`
	Publish   []PublishedEventMeta `json:"publish,omitempty"`
}

EventsMeta declares subscribed event names and custom published event schemas.

type ExpandProvider

type ExpandProvider interface {
	Expand(ctx *Context, req KindExpandRequest) (KindExpandResponse, error)
}

ExpandProvider is the optional on-demand facet/person slice expander for kinds that declare browse.expand.

type FetchCacheRequest

type FetchCacheRequest struct {
	TimeoutMS             int64             `json:"timeoutMs,omitempty"`
	URL                   string            `json:"url"`
	Headers               map[string]string `json:"headers,omitempty"`
	KeepHeadersOnRedirect []string          `json:"keepHeadersOnRedirect,omitempty"`
	LibraryKey            string            `json:"libraryKey"`
	Name                  string            `json:"name"`
}

type FetchCacheResult

type FetchCacheResult struct {
	Blob   string `json:"blob"`
	Size   int64  `json:"size"`
	CRC32  string `json:"crc32"`
	MD5    string `json:"md5"`
	SHA1   string `json:"sha1"`
	Status int    `json:"status"`
}

type FetchManyHost

type FetchManyHost interface {
	FetchMany(ctx context.Context, reqs []HostFetchRequest, opts ...HostFetchManyOptions) ([]HostFetchManyResult, error)
}

FetchManyHost executes up to MaxFetchManyRequests outbound HTTP calls concurrently with bounded per-call and per-origin concurrency, returning ordered results with per-item error isolation (#703). RemoteHostClient and MockHost implement it.

type FieldOption

type FieldOption struct {
	Value string `json:"value"`
	Label string `json:"label"`
	Hint  string `json:"hint,omitempty"`
}

FieldOption is one selectable option for a select or multiSelect field.

type FieldProblem

type FieldProblem struct {
	Field   string `json:"field"`
	Message string `json:"message"`
}

FieldProblem describes one schema validation or copy-rule problem.

func LintSettingsSchema

func LintSettingsSchema(schema *SettingsSchema) []FieldProblem

LintSettingsSchema checks a SettingsSchema for forbidden kinds and copy-rule violations.

type FileRangeResponse

type FileRangeResponse struct {
	Status       int               `json:"status,omitempty"`
	ContentType  string            `json:"contentType,omitempty"`
	ContentRange string            `json:"contentRange,omitempty"`
	TotalSize    *int64            `json:"totalSize,omitempty"`
	Headers      map[string]string `json:"headers,omitempty"`
	Body         []byte            `json:"-"`
}

FileRangeResponse is returned by a File route handler.

type FileRequest

type FileRequest struct {
	Path     string `json:"path"`
	Range    string `json:"range,omitempty"`
	HeadOnly bool   `json:"headOnly,omitempty"`
}

FileRequest is passed to a File route handler.

type FlowActionMeta

type FlowActionMeta struct {
	Key         string                `json:"key"`
	Label       string                `json:"label"`
	Description string                `json:"description,omitempty"`
	Icon        string                `json:"icon,omitempty"`
	Route       string                `json:"route"`
	Idempotent  bool                  `json:"idempotent,omitempty"`
	SideEffect  *bool                 `json:"sideEffect,omitempty"`
	Timeout     string                `json:"timeout,omitempty"`
	Params      []FlowActionParamMeta `json:"params,omitempty"`
	Outputs     []EventFieldMeta      `json:"outputs,omitempty"`
}

FlowActionMeta declares one custom Flow action contributed by a plugin.

type FlowActionParamMeta

type FlowActionParamMeta struct {
	Key         string            `json:"key"`
	Type        EventFieldType    `json:"type"`
	Label       string            `json:"label"`
	Description string            `json:"description,omitempty"`
	Required    bool              `json:"required,omitempty"`
	Secret      bool              `json:"secret,omitempty"`
	Template    bool              `json:"template,omitempty"`
	Default     any               `json:"default,omitempty"`
	Enum        []EventEnumOption `json:"enum,omitempty"`
	Unit        string            `json:"unit,omitempty"`
	Picker      string            `json:"picker,omitempty"`
}

FlowActionParamMeta describes one configurable parameter of a plugin flow action.

type FlowActionRequest

type FlowActionRequest struct {
	Key            string         `json:"key,omitempty"`
	FlowID         string         `json:"flowId"`
	RunID          string         `json:"runId"`
	NodeID         string         `json:"nodeId"`
	IdempotencyKey string         `json:"idempotencyKey"`
	DryRun         bool           `json:"dryRun,omitempty"`
	Params         map[string]any `json:"params,omitempty"`
}

FlowActionRequest is passed to a FlowAction route handler.

type FlowActionResponse

type FlowActionResponse struct {
	Output map[string]any `json:"output,omitempty"`
	Branch string         `json:"branch,omitempty"`
}

FlowActionResponse is returned by a FlowAction route handler.

type FolderEntry

type FolderEntry struct {
	Name  string `json:"name"`
	Path  string `json:"path"`
	Dir   bool   `json:"dir"`
	Size  int64  `json:"size,omitempty"`
	Mtime int64  `json:"mtime,omitempty"`
}

FolderEntry describes one entry returned by Host.FoldersList or Host.FoldersStat.

type FolderHash

type FolderHash struct {
	Size    int64  `json:"size"`
	ModTime int64  `json:"modTime"`
	CRC32   string `json:"crc32"`
	MD5     string `json:"md5"`
	SHA1    string `json:"sha1"`
}

FolderHash contains digests, never file contents. ModTime is Unix seconds.

type FolderHashJob

type FolderHashJob struct {
	ID     string      `json:"id"`
	State  string      `json:"state"`
	Bytes  int64       `json:"bytes"`
	Result *FolderHash `json:"result,omitempty"`
	Error  string      `json:"error,omitempty"`
}

FolderHashJob is a pollable background hash. Bytes is the progress so far. Terminal states are done, canceled and error. Only done carries Result.

type FrontendAdapter

type FrontendAdapter interface {
	Handler() http.Handler
}

FrontendAdapter is a plugin-provided protocol surface (OPDS, Subsonic, custom). Ether authenticates the viewer first and forwards the request under /ether/v1/frontend/{key}; the handler sees X-Ether-Viewer headers and never a credential.

type FrontendAdapterMeta

type FrontendAdapterMeta struct {
	Key          string   `json:"key"`
	Label        string   `json:"label"`
	ProtocolHint string   `json:"protocolHint"` // opds|subsonic|custom
	PathPrefix   string   `json:"pathPrefix"`
	DefaultPort  int      `json:"defaultPort,omitempty"`
	Clients      []string `json:"clients,omitempty"`
	Auth         string   `json:"auth,omitempty"` // ether_token (default)|basic|none_lan
	Libraries    []string `json:"libraries,omitempty"`
	// SearchPaths optionally lists adapter subpaths (such as "/search",
	// "/rest/search3", or "/graphql") allowed to call ai.complete when
	// permissions.ai is "complete+search".
	SearchPaths []string `json:"searchPaths,omitempty"`
}

FrontendAdapterMeta declares one plugin-provided protocol surface.

type FrontendBlob

type FrontendBlob struct {
	LibraryKey  string `json:"libraryKey"`
	Ref         string `json:"ref"`
	MemberIndex *int   `json:"memberIndex,omitempty"`
}

FrontendBlob selects host-served bytes for a frontend adapter response.

type GuideRequest

type GuideRequest struct {
	ChannelID string `json:"channelId"`
	From      string `json:"from,omitempty"`
	To        string `json:"to,omitempty"`
}

GuideRequest is passed to a Guide route handler.

type GuideResponse

type GuideResponse struct {
	Programmes []ProgrammeItem `json:"programmes"`
}

GuideResponse is returned by a Guide route handler.

type HashRequest

type HashRequest struct {
	URL                   string            `json:"url"`
	Algo                  string            `json:"algo"`
	ExpectSize            *int64            `json:"expectSize,omitempty"`
	Headers               map[string]string `json:"headers,omitempty"`
	KeepHeadersOnRedirect []string          `json:"keepHeadersOnRedirect,omitempty"`
}

HashRequest requests an on-demand host-side remote digest without storing bytes. Optional Headers expand {secret:<name>} placeholders and follow redirects only within the same origin, strict same-site subdomains, or KeepHeadersOnRedirect (within granted network hosts, never across HTTPS->HTTP).

type HashResult

type HashResult struct {
	Pending   bool   `json:"pending,omitempty"`
	RetryInMS int64  `json:"retryInMs,omitempty"`
	Size      int64  `json:"size"`
	SHA256    string `json:"sha256,omitempty"`
	SHA1      string `json:"sha1,omitempty"`
	MD5       string `json:"md5,omitempty"`
}

type HealthDecl

type HealthDecl struct {
	Interval string `json:"interval,omitempty"`
}

HealthDecl configures periodic health checks.

type HealthResponse

type HealthResponse struct {
	Status string `json:"status"`
	Reason string `json:"reason,omitempty"`
}

HealthResponse is returned by a Health route handler.

type Host

type Host interface {
	KVGet(ctx context.Context, key string) (string, bool, error)
	KVPut(ctx context.Context, key, value string) error
	KVDelete(ctx context.Context, key string) error
	KVList(ctx context.Context, prefix string) ([]string, error)
	SecretGet(ctx context.Context, name string) (string, error)
	Fetch(ctx context.Context, req HostFetchRequest) (HostFetchResponse, error)
	CatalogSearch(ctx context.Context, query string, limit, offset int) ([]CatalogTitleSummary, error)
	CatalogGet(ctx context.Context, id string) (*CatalogTitleSummary, error)
	ViewerHistory(ctx context.Context, viewerID int64, limit, offset int) ([]ViewerWatchEntry, error)
	SetWatchState(ctx context.Context, viewerID int64, titleID string, watched bool) error
	UpsertCollection(ctx context.Context, collection map[string]any) error
	FoldersList(ctx context.Context, root, path string) ([]FolderEntry, error)
	FoldersStat(ctx context.Context, root, path string) (FolderEntry, error)
	FoldersHash(ctx context.Context, root, path string) (FolderHash, error)
	FoldersHashStart(ctx context.Context, root, path string) (FolderHashJob, error)
	FoldersHashPoll(ctx context.Context, id string) (FolderHashJob, error)
	FoldersHashCancel(ctx context.Context, id string) (FolderHashJob, error)
	NotifyOwner(ctx context.Context, text string) error
	Log(ctx context.Context, level, message string, attrs map[string]any) error
	// Content-kind host services. KindUpsert/KindDelete need a push-mode
	// kind; ResolveSources needs permissions.sources.
	KindUpsert(ctx context.Context, kindKey string, items []KindItem) (accepted int, err error)
	KindDelete(ctx context.Context, kindKey string, externalIDs []string) error
	KindItems(ctx context.Context, kindKey, cursor string, limit int) (KindPage, error)
	ResolveSources(ctx context.Context, q SourceQuery) ([]SourceCandidate, error)
	CachePut(ctx context.Context, libraryKey, name string, data []byte) (blobRef string, err error)
	CacheOpen(ctx context.Context, blobRef string) ([]byte, error)
	// StreamURL mints a short-lived, scoped ticket for one of this plugin's
	// own kind items and returns the Ether stream URL to embed in a
	// frontend adapter response (spec §6.5). viewerID is the viewer the
	// adapter authenticated.
	StreamURL(ctx context.Context, viewerID int64, itemRef string) (string, error)
}

Host provides access to Ether host services (KV, secrets, HTTP, catalog, viewers, collections, folders, owner notifications, and logging).

type HostError

type HostError struct {
	Status  int
	Code    string
	Message string
}

HostError is a structured error returned by Ether's plugin-host API, preserving the EPP error code (for example "not_configured", "rate_limited", "permission_denied", or "invalid_output") alongside the human message.

func (*HostError) Error

func (e *HostError) Error() string

type HostFetchError

type HostFetchError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

HostFetchError describes a per-item error returned by FetchMany.

type HostFetchManyOptions

type HostFetchManyOptions struct {
	Concurrency int `json:"concurrency,omitempty"`
}

HostFetchManyOptions configures a bounded concurrent FetchMany batch.

type HostFetchManyResult

type HostFetchManyResult struct {
	Status     int               `json:"status,omitempty"`
	Headers    map[string]string `json:"headers,omitempty"`
	Body       string            `json:"body,omitempty"`
	BodyBase64 string            `json:"bodyBase64,omitempty"`
	Error      *HostFetchError   `json:"error,omitempty"`
}

HostFetchManyResult is one ordered result from FetchMany. Either Error is non-nil or Status/Headers/Body carry the HTTP response (including non-2xx).

type HostFetchRequest

type HostFetchRequest struct {
	TimeoutMS             int64             `json:"timeoutMs,omitempty"`
	Method                string            `json:"method,omitempty"`
	URL                   string            `json:"url"`
	Headers               map[string]string `json:"headers,omitempty"`
	Body                  string            `json:"body,omitempty"`
	BodyBase64            string            `json:"bodyBase64,omitempty"`
	KeepHeadersOnRedirect []string          `json:"keepHeadersOnRedirect,omitempty"`
}

HostFetchRequest describes an outbound HTTP call via the host service.

type HostFetchResponse

type HostFetchResponse struct {
	Status     int               `json:"status"`
	Headers    map[string]string `json:"headers"`
	Body       string            `json:"body"`
	BodyBase64 string            `json:"bodyBase64,omitempty"`
}

HostFetchResponse is returned by Host.Fetch.

type I18n

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

I18n resolves localized strings with fallback to base language and "en".

func NewI18n

func NewI18n(catalog StringsCatalog, defaultLocale string) *I18n

NewI18n creates a localization helper backed by a StringsCatalog.

func (*I18n) Catalog

func (i *I18n) Catalog() StringsCatalog

Catalog returns the underlying locale catalog.

func (*I18n) T

func (i *I18n) T(rawKey string, params map[string]any, locale string) string

T resolves a key for the given locale and interpolates {param} placeholders.

type IntegrationMeta

type IntegrationMeta struct {
	Category string   `json:"category"`
	Adds     []string `json:"adds"`
	Connect  string   `json:"connect"`
	Test     bool     `json:"test,omitempty"`
}

IntegrationMeta describes an external service integration.

type ItemUnavailable

type ItemUnavailable struct {
	Code   string `json:"code"`
	Detail string `json:"detail,omitempty"`
}

ItemUnavailable explains why an item cannot currently be played.

type JobRequest

type JobRequest struct {
	Name         string          `json:"name"`
	Continuation json.RawMessage `json:"continuation,omitempty"`
}

JobRequest is passed to a Job route handler.

type JobResponse

type JobResponse map[string]any

JobResponse returns continueInMs, continuation and progress to continue; done:true completes, failed:string stops with an error. Ether caps jobs at the owner time ceiling (12h by default) and 1000000 calls; store checkpoints in KV for restart recovery.

type KVUsage

type KVUsage struct {
	Bytes      int64 `json:"bytes"`
	Keys       int64 `json:"keys"`
	QuotaBytes int64 `json:"quotaBytes"`
	QuotaKeys  int64 `json:"quotaKeys"`
}

KVUsage reports a plugin's current KV bytes (including the 256-byte charge per key), key count, and configured quotas (#591).

type KVUsageHost

type KVUsageHost interface {
	KVUsage(ctx context.Context) (KVUsage, error)
}

KVUsageHost reports current KV usage and quotas (#591). RemoteHostClient and MockHost implement it.

type KindArt

type KindArt struct {
	Role  string `json:"role"`
	Label string `json:"label"`
}

KindArt declares one artwork role beyond poster/backdrop/thumb/logo.

type KindArtRef

type KindArtRef struct {
	Role   string `json:"role"`
	URL    string `json:"url"`
	Width  int    `json:"width,omitempty"`
	Height int    `json:"height,omitempty"`
}

KindArtRef is one artwork reference on a KindItem.

type KindBrowseDecl

type KindBrowseDecl struct {
	Sorts        []string `json:"sorts,omitempty"`
	Facets       []string `json:"facets,omitempty"`
	Search       bool     `json:"search"`
	SearchFields []string `json:"searchFields,omitempty"`
	// LiveSearch: client searches also call the plugin's /search route
	// with a short budget; results are upserted and merged (§15.4).
	LiveSearch bool              `json:"liveSearch,omitempty"`
	Expand     *KindBrowseExpand `json:"expand,omitempty"`
}

KindBrowseDecl is how a kind library is browsed.

type KindBrowseExpand

type KindBrowseExpand struct {
	Facets   []string `json:"facets"`
	TTLHours int      `json:"ttlHours,omitempty"`
}

KindBrowseExpand configures on-demand background expansion for declared browse facets when a viewer opens a facet collection bucket or plugin person.

type KindBrowseQuery

type KindBrowseQuery = KindBrowseRequest

KindBrowseQuery is the query passed to kinds.browse from a frontend adapter (#615).

type KindBrowseRequest

type KindBrowseRequest struct {
	Kind     string `json:"-"` // filled from the route, never on the wire
	ParentID string `json:"parentId,omitempty"`
	Level    string `json:"level,omitempty"`
	Cursor   string `json:"cursor,omitempty"`
	Limit    int    `json:"limit,omitempty"`
	Sort     string `json:"sort,omitempty"`
	Desc     bool   `json:"desc,omitempty"`
	// Facets requires any of the listed values per field; AllFacets
	// requires every listed value and ExcludeFacets drops items having
	// any listed value. All three combine with AND.
	Facets        map[string][]string `json:"facets,omitempty"`
	AllFacets     map[string][]string `json:"allFacets,omitempty"`
	ExcludeFacets map[string][]string `json:"excludeFacets,omitempty"`
	Query         string              `json:"query,omitempty"`
	// Total controls whether kinds.browse computes KindPage.Total:
	// "" or "cheap" (default) returns Total only when O(1), "none" omits it,
	// and "exact" computes an exact Total (cached per library generation).
	Total string `json:"total,omitempty"`
}

KindBrowseRequest is Ether's browse/search request for one kind level.

type KindCacheDecl

type KindCacheDecl struct {
	MaxBytes int64  `json:"maxBytes,omitempty"`
	TTL      string `json:"ttl,omitempty"`
}

KindCacheDecl is the per-library blob cache budget; 0 means server default.

type KindChangePage

type KindChangePage struct {
	Upserts    []KindItem `json:"upserts,omitempty"`
	Deletes    []string   `json:"deletes,omitempty"`
	NextCursor string     `json:"nextCursor,omitempty"`
	Complete   bool       `json:"complete"`
}

KindChangePage is one delta page for pull sync.

type KindChangesRequest

type KindChangesRequest struct {
	Kind   string `json:"-"`
	Cursor string `json:"cursor,omitempty"`
	Limit  int    `json:"limit,omitempty"`
}

KindChangesRequest is Ether's delta-feed request.

type KindExpandRequest

type KindExpandRequest struct {
	Kind     string `json:"-"`
	Facet    string `json:"facet,omitempty"`
	Value    string `json:"value,omitempty"`
	ValueID  int64  `json:"valueId,omitempty"`
	ParentID string `json:"parentId,omitempty"`
	Level    string `json:"level,omitempty"`
	Cursor   string `json:"cursor,omitempty"`
}

KindExpandRequest asks a plugin to expand one declared facet bucket, plugin person slice, or container's children via POST /ether/v1/kinds/{kind}/expand.

type KindExpandResponse

type KindExpandResponse struct {
	Items      []KindItem `json:"items,omitempty"`
	Cursor     string     `json:"cursor,omitempty"`
	NextCursor string     `json:"nextCursor,omitempty"`
	Job        string     `json:"job,omitempty"`
}

KindExpandResponse is returned by POST /ether/v1/kinds/{kind}/expand. Either Items (with optional Cursor/NextCursor for further pages) or Job ("/ether/job/...") is populated.

type KindField

type KindField struct {
	Key     string   `json:"key"`
	Type    string   `json:"type"` // string|int|float|bool|date|duration|enum|strings|people
	Label   string   `json:"label"`
	Indexed bool     `json:"indexed,omitempty"`
	Enum    []string `json:"enum,omitempty"`
}

KindField is one declared item field.

type KindItem

type KindItem struct {
	Unavailable *ItemUnavailable           `json:"unavailable,omitempty"`
	ID          string                     `json:"id"`
	Level       string                     `json:"level"`
	ParentID    string                     `json:"parentId,omitempty"`
	Index       int                        `json:"index,omitempty"`
	Title       string                     `json:"title"`
	SortTitle   string                     `json:"sortTitle,omitempty"`
	Summary     string                     `json:"summary,omitempty"`
	Year        int                        `json:"year,omitempty"`
	Released    int64                      `json:"released,omitempty"` // unix seconds
	Rating      float64                    `json:"rating,omitempty"`
	Playable    bool                       `json:"playable,omitempty"`
	ChildCount  int                        `json:"childCount,omitempty"`
	LeafCount   int                        `json:"leafCount,omitempty"`
	Art         []KindArtRef               `json:"art,omitempty"`
	Fields      map[string]json.RawMessage `json:"fields,omitempty"`
	Hints       json.RawMessage            `json:"hints,omitempty"` // opaque JSON object, echoed to the resolver
	ETag        string                     `json:"etag,omitempty"`
}

KindItem is the standardised plugin item envelope. Ether assigns the stored identity; the plugin only ever sees its own external ID.

type KindItemPart

type KindItemPart struct {
	Index       int     `json:"index"`
	Name        string  `json:"name,omitempty"`
	MIME        string  `json:"mime,omitempty"`
	Size        int64   `json:"size,omitempty"`
	DurationSec float64 `json:"durationSec,omitempty"`
	FileIndex   *int    `json:"fileIndex,omitempty"`
}

KindItemPart describes one declared or resolve-time file/part on a multi-file KindItem (#576). Ether passes the zero-based index back in KindResolveRequest.PartIndex when resolving each part, or targets FileIndex inside a resolved multi-file release.

type KindLevel

type KindLevel struct {
	Key       string `json:"key"`
	Label     string `json:"label"`
	Role      string `json:"role,omitempty"` // item|artist|album|track|series|book|audiobook|part|show|episode|collection
	Playable  bool   `json:"playable,omitempty"`
	Container bool   `json:"container,omitempty"`
}

KindLevel is one hierarchy level of a kind.

type KindLibraryDecl

type KindLibraryDecl struct {
	Name        string             `json:"name"`
	Icon        string             `json:"icon,omitempty"`
	Card        string             `json:"card,omitempty"`        // poster (default)|landscape|square
	DateDisplay string             `json:"dateDisplay,omitempty"` // year (default)|date
	Tabs        []KindLibraryTab   `json:"tabs,omitempty"`        // up to 50; defaults to Recommended + Library
	Shelves     []KindLibraryShelf `json:"shelves,omitempty"`     // up to 40; default Recommended shelves
}

KindLibraryDecl is the library created for a kind on install.

type KindLibraryShelf

type KindLibraryShelf struct {
	Key       string   `json:"key"`
	Label     string   `json:"label"`
	Level     string   `json:"level,omitempty"`     // optional declared hierarchy level key
	Sort      string   `json:"sort,omitempty"`      // released (default)|title|added|year|rating|index|lastViewed
	Direction string   `json:"direction,omitempty"` // desc (default)|asc
	Facet     string   `json:"facet,omitempty"`     // single-facet shorthand (declared and indexed)
	Value     string   `json:"value,omitempty"`     // single value for facet
	Values    []string `json:"values,omitempty"`    // OR values for facet
	Filters   any      `json:"filters,omitempty"`   // map[string][]string, *KindLibraryTabFilter, KindLibraryTabRule or []KindLibraryTabRule
}

KindLibraryShelf declares one default Recommended shelf for a plugin library. Each shelf gets the stable row ID "plugin:<viewID>:shelf:<key>". Filters accepts a map[string][]string (facet map), *KindLibraryTabFilter, KindLibraryTabRule, or []KindLibraryTabRule.

type KindLibraryTab

type KindLibraryTab struct {
	Key               string                `json:"key"`
	Label             string                `json:"label"`
	Kind              string                `json:"kind"`                        // recommended|library|collections|people|view|live
	Level             string                `json:"level,omitempty"`             // optional declared hierarchy level (library, view, collections or people)
	Facet             string                `json:"facet,omitempty"`             // declared browse.facets entry (optional on collections; required people-type facet on people)
	Order             string                `json:"order,omitempty"`             // count|name (default count on collections, name on people)
	Card              string                `json:"card,omitempty"`              // landscape (default)|poster|square (live tabs only)
	Layout            string                `json:"layout,omitempty"`            // grid (default)|list|timeline (view tabs only)
	Search            *bool                 `json:"search,omitempty"`            // collections/people/view/live only; default true
	SearchPlaceholder string                `json:"searchPlaceholder,omitempty"` // localizable placeholder (<=60 chars; collections/people/view/live when search is enabled)
	Sort              string                `json:"sort,omitempty"`              // one of browse.sorts or lastViewed (facet collections or view)
	Direction         string                `json:"direction,omitempty"`         // asc|desc (facet collections or view)
	Filters           *KindLibraryTabFilter `json:"filters,omitempty"`           // saved filter rules (view tabs only)
}

KindLibraryTab declares one sub-tab shown inside a plugin library.

type KindLibraryTabFilter

type KindLibraryTabFilter struct {
	Match   string               `json:"match,omitempty"`   // "all" (default) or "any"
	Rules   []KindLibraryTabRule `json:"rules,omitempty"`   // matching conditions
	Exclude []KindLibraryTabRule `json:"exclude,omitempty"` // excluded conditions
}

KindLibraryTabFilter defines saved filter rules on a "view" tab.

type KindLibraryTabRule

type KindLibraryTabRule struct {
	Field string `json:"field"`
	Op    string `json:"op"`
	Value any    `json:"value,omitempty"`
}

KindLibraryTabRule is one filter condition inside a "view" tab's filters. Field may be "browse:<indexedField>", "viewer" (with value such as {"history":true}, {"watched":true}, {"unwatched":true}, {"inProgress":true}, {"favorite":true}, {"watchlist":true}, {"lastViewedAfter":unix}, {"lastViewedBefore":unix}), "year", "rating", or a mapped indexed field.

type KindLiveFilter

type KindLiveFilter struct {
	Key   string `json:"key"`
	Label string `json:"label"`
}

KindLiveFilter is one optional filter option returned by a live tab.

type KindLiveItem

type KindLiveItem struct {
	ID       string   `json:"id"`
	Title    string   `json:"title"`
	Subtitle string   `json:"subtitle,omitempty"`
	Badge    string   `json:"badge,omitempty"`
	Viewers  *int     `json:"viewers,omitempty"`
	Tags     []string `json:"tags,omitempty"`
	Thumb    string   `json:"thumb,omitempty"`
	Live     *bool    `json:"live,omitempty"`
}

KindLiveItem is one live stream item returned by POST /ether/v1/kinds/{kind}/live.

type KindLivePage

type KindLivePage struct {
	Items      []KindLiveItem   `json:"items"`
	Filters    []KindLiveFilter `json:"filters,omitempty"`
	NextCursor string           `json:"nextCursor,omitempty"`
}

KindLivePage is returned by POST /ether/v1/kinds/{kind}/live.

type KindLiveProvider

type KindLiveProvider interface {
	Live(ctx *Context, req KindLiveRequest) (KindLivePage, error)
	ResolveLive(ctx *Context, req KindLiveResolveRequest) (KindLiveResolveResponse, error)
}

KindLiveProvider serves a kind's declared "live" library tab: listing currently live streams and resolving an item ID into a playable stream URL.

type KindLiveRequest

type KindLiveRequest struct {
	Kind   string `json:"-"`
	Tab    string `json:"tab,omitempty"`
	Q      string `json:"q,omitempty"`
	Filter string `json:"filter,omitempty"`
	Cursor string `json:"cursor,omitempty"`
	Limit  int    `json:"limit,omitempty"`
}

KindLiveRequest asks a kind live provider for currently live items on a declared "live" library tab (POST /ether/v1/kinds/{kind}/live).

type KindLiveResolveRequest

type KindLiveResolveRequest struct {
	Kind string `json:"-"`
	ID   string `json:"id"`
}

KindLiveResolveRequest asks a kind live provider to resolve one live item ID into a playable stream URL (POST /ether/v1/kinds/{kind}/live/resolve).

type KindLiveResolveResponse

type KindLiveResolveResponse struct {
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers,omitempty"`
	MIME    string            `json:"mime,omitempty"`
	Title   string            `json:"title,omitempty"`
}

KindLiveResolveResponse is returned by POST /ether/v1/kinds/{kind}/live/resolve.

type KindMatchDecl

type KindMatchDecl struct {
	ThresholdDefault float64 `json:"thresholdDefault,omitempty"`
}

KindMatchDecl holds matcher defaults for a kind.

type KindMatchRequest

type KindMatchRequest struct {
	Kind       string            `json:"-"`
	Item       KindItem          `json:"item"`
	Candidates []SourceCandidate `json:"candidates"`
	Settings   map[string]any    `json:"settings,omitempty"`
}

KindMatchRequest asks a matcher to score candidates for one item.

type KindMatchResponse

type KindMatchResponse struct {
	Pending   bool             `json:"pending,omitempty"`
	RetryInMS int64            `json:"retryInMs,omitempty"`
	Job       string           `json:"job,omitempty"`
	Matches   []KindMatchScore `json:"matches"`
}

KindMatchResponse is a matcher's answer, best first.

type KindMatchScore

type KindMatchScore struct {
	CandidateRef string   `json:"candidateRef"`
	Score        float64  `json:"score"`
	Reasons      []string `json:"reasons,omitempty"`
}

KindMatchScore is one candidate score (0..1) with plain-language reasons.

type KindMatcher

type KindMatcher interface {
	Match(ctx *Context, req KindMatchRequest) (KindMatchResponse, error)
}

KindMatcher scores source candidates for one item.

type KindPage

type KindPage struct {
	Items      []KindItem `json:"items"`
	NextCursor string     `json:"nextCursor,omitempty"`
	Total      *int       `json:"total,omitempty"`
}

KindPage is one page of kind items; an empty NextCursor ends the walk.

type KindPolicyHost

type KindPolicyHost interface {
	KindVisible(ctx context.Context, kindKey string, ids []string) ([]string, error)
	KindBrowse(ctx context.Context, kindKey string, query KindBrowseQuery) (KindPage, error)
}

KindPolicyHost evaluates a plugin library's Rules and viewer access policy for the requesting frontend-adapter viewer (#615). RemoteHostClient and MockHost implement it. The viewer identity comes solely from the request's authenticated X-Ether-Viewer-Token on ctx, never from caller-supplied IDs.

type KindResolveRequest

type KindResolveRequest struct {
	Kind       string         `json:"-"`
	LibraryKey string         `json:"libraryKey"`
	Item       KindItem       `json:"item"`
	PartIndex  *int           `json:"partIndex,omitempty"`
	Source     string         `json:"source,omitempty"`
	Client     map[string]any `json:"client,omitempty"`
}

KindResolveRequest asks a resolver for playable sources for one item.

type KindResolveResponse

type KindResolveResponse struct {
	Pending   bool             `json:"pending,omitempty"`
	RetryInMS int64            `json:"retryInMs,omitempty"`
	Job       string           `json:"job,omitempty"`
	Sources   []PlayableSource `json:"sources"`
	Parts     []KindItemPart   `json:"parts,omitempty"`
	TTLSec    int              `json:"ttlSec,omitempty"`
}

KindResolveResponse is a resolver's ordered sources.

type KindResolver

type KindResolver interface {
	Resolve(ctx *Context, req KindResolveRequest) (KindResolveResponse, error)
}

KindResolver turns a playable item into ordered playable sources.

type KindSyncDecl

type KindSyncDecl struct {
	Mode    string `json:"mode"` // pull|push
	Refresh string `json:"refresh,omitempty"`
}

KindSyncDecl is how a kind's items reach Ether's store.

type ListSourceMeta

type ListSourceMeta struct {
	Key      string `json:"key"`
	Label    string `json:"label"`
	Hint     string `json:"hint,omitempty"`
	Catalog  string `json:"catalog"`
	Params   any    `json:"params,omitempty"`
	MaxItems int    `json:"maxItems,omitempty"`
	Refresh  string `json:"refresh,omitempty"`
}

ListSourceMeta describes a catalog list source.

type Manifest

type Manifest struct {
	ID            string               `json:"id"`
	Version       string               `json:"version"`
	Name          string               `json:"name"`
	Description   string               `json:"description,omitempty"`
	Background    string               `json:"background,omitempty"`
	Types         []string             `json:"types,omitempty"`
	Catalogs      []StremioCatalogDecl `json:"catalogs,omitempty"`
	Resources     []any                `json:"resources,omitempty"`
	IDPrefixes    []string             `json:"idPrefixes,omitempty"`
	BehaviorHints *BehaviorHints       `json:"behaviorHints,omitempty"`
	Ether         *EtherManifestBlock  `json:"ether,omitempty"`
}

Manifest is the EPP/1 manifest document served at GET /manifest.json.

type MarkerItem

type MarkerItem struct {
	Kind  string  `json:"kind"`
	Start float64 `json:"start"`
	End   float64 `json:"end"`
	Label string  `json:"label,omitempty"`
}

MarkerItem is one intro/credits/recap/preview marker.

type MarkersMeta

type MarkersMeta struct {
	Kinds []string `json:"kinds"`
}

MarkersMeta describes a playback markers contribution.

type MarkersRequest

type MarkersRequest struct {
	Type string `json:"type"`
	ID   string `json:"id"`
}

MarkersRequest is passed to a Markers route handler.

type MarkersResponse

type MarkersResponse struct {
	Markers []MarkerItem `json:"markers"`
}

MarkersResponse is returned by a Markers route handler.

type MediaKindMeta

type MediaKindMeta struct {
	Key     string          `json:"key"`
	Label   string          `json:"label"`
	Media   string          `json:"media,omitempty"` // video|music|audiobook|book|podcast|photo
	Library KindLibraryDecl `json:"library"`
	Levels  []KindLevel     `json:"levels"`
	Fields  []KindField     `json:"fields,omitempty"`
	Art     []KindArt       `json:"art,omitempty"`
	Present Presentations   `json:"present,omitempty"`
	Browse  KindBrowseDecl  `json:"browse"`
	Sync    KindSyncDecl    `json:"sync"`
	Cache   *KindCacheDecl  `json:"cache,omitempty"`
	Match   *KindMatchDecl  `json:"match,omitempty"`
}

MediaKindMeta declares one content kind; each kind becomes its own library.

type MetaItem

type MetaItem struct {
	CatalogItem
	Runtime  string      `json:"runtime,omitempty"`
	Cast     []string    `json:"cast,omitempty"`
	Director []string    `json:"director,omitempty"`
	Videos   []MetaVideo `json:"videos,omitempty"`
}

MetaItem is a full metadata record returned by a Meta route handler.

type MetaRequest

type MetaRequest struct {
	Type string `json:"type"`
	ID   string `json:"id"`
}

MetaRequest is passed to a Meta route handler.

type MetaResponse

type MetaResponse struct {
	Meta MetaItem `json:"meta"`
}

MetaResponse is returned by a Meta route handler.

type MetaVideo

type MetaVideo struct {
	ID        string `json:"id"`
	Title     string `json:"title"`
	Released  string `json:"released,omitempty"`
	Season    int    `json:"season,omitempty"`
	Episode   int    `json:"episode,omitempty"`
	Overview  string `json:"overview,omitempty"`
	Thumbnail string `json:"thumbnail,omitempty"`
}

MetaVideo describes one episode/video inside a MetaItem.

type MockHost

type MockHost struct {
	KV               map[string]string
	Badges           map[string]map[string][]string
	BadgeQuotaTitles int64
	Secrets          map[string]string
	Catalog          map[string]CatalogTitleSummary
	History          map[int64][]ViewerWatchEntry
	WatchState       map[string]bool
	Collections      []map[string]any
	Kinds            map[string][]KindItem      // kindKey -> pushed items, in upsert order
	KindHiddenIDs    map[string]map[string]bool // kindKey -> externalID -> hidden by mock library Rules (#615)
	KindPolicyFilter func(kindKey string, item KindItem) bool
	Sources          []SourceCandidate // returned by ResolveSources
	Blobs            map[string][]byte // cache blob ref -> bytes
	Folders          map[string][]FolderEntry
	PublishedEvents  []RecordedPublishedEvent
	Notifications    []string
	Logs             []RecordedLog
	FetchHandler     func(ctx context.Context, req HostFetchRequest) (HostFetchResponse, error)
	AIHandler        func(ctx context.Context, req AICompleteRequest) (AICompleteResponse, error)
	// LastStreamURLViewer/Item/Part/Source record the most recent StreamURL,
	// StreamPartURL, or StreamURLWithOptions call.
	LastStreamURLViewer int64
	LastStreamURLItem   string
	LastStreamURLPart   *int
	LastStreamURLSource string
	// contains filtered or unexported fields
}

MockHost is an in-memory Host implementation for unit tests.

func NewMockHost

func NewMockHost() *MockHost

NewMockHost creates an initialized MockHost.

func (*MockHost) AIComplete

AIComplete invokes AIHandler if set, or returns a *HostError with Code "not_configured".

func (*MockHost) BadgesClear

func (m *MockHost) BadgesClear(_ context.Context, setKey string) error

BadgesClear removes every badge in setKey from the in-memory store (#594).

func (*MockHost) BadgesSet

func (m *MockHost) BadgesSet(_ context.Context, setKey string, entries []BadgeEntry) error

BadgesSet stores or clears (empty Labels) poster badges in memory, enforcing the same label and per-plugin title bounds as Ether (#594).

func (*MockHost) BadgesUsage

func (m *MockHost) BadgesUsage(_ context.Context) (BadgeUsage, error)

BadgesUsage returns the distinct badged title count and configured quota (#594).

func (*MockHost) CacheDelete

func (m *MockHost) CacheDelete(_ context.Context, blobRef string) error

CacheDelete removes a stored blob from memory; deleting an absent ref succeeds.

func (*MockHost) CacheOpen

func (m *MockHost) CacheOpen(_ context.Context, blobRef string) ([]byte, error)

CacheOpen reads stored blob bytes back.

func (*MockHost) CachePut

func (m *MockHost) CachePut(_ context.Context, _, _ string, data []byte) (string, error)

CachePut stores bytes under a sha256 blob ref, like the real cache.

func (*MockHost) CatalogGet

func (m *MockHost) CatalogGet(_ context.Context, id string) (*CatalogTitleSummary, error)

CatalogGet returns a title by ID from the in-memory catalog.

func (*MockHost) CatalogSearch

func (m *MockHost) CatalogSearch(_ context.Context, query string, limit, offset int) ([]CatalogTitleSummary, error)

CatalogSearch searches the in-memory catalog by case-insensitive substring.

func (*MockHost) Fetch

Fetch invokes FetchHandler if set, or returns a 200 "{}" response.

func (*MockHost) FetchMany

func (m *MockHost) FetchMany(ctx context.Context, reqs []HostFetchRequest, opts ...HostFetchManyOptions) ([]HostFetchManyResult, error)

FetchMany executes reqs concurrently through Fetch with bounded concurrency and per-item error isolation, returning results in input order.

func (*MockHost) FoldersHash

func (*MockHost) FoldersHash(context.Context, string, string) (FolderHash, error)

func (*MockHost) FoldersHashCancel

func (*MockHost) FoldersHashCancel(context.Context, string) (FolderHashJob, error)

func (*MockHost) FoldersHashPoll

func (*MockHost) FoldersHashPoll(context.Context, string) (FolderHashJob, error)

func (*MockHost) FoldersHashStart

func (*MockHost) FoldersHashStart(context.Context, string, string) (FolderHashJob, error)

func (*MockHost) FoldersList

func (m *MockHost) FoldersList(_ context.Context, root, path string) ([]FolderEntry, error)

FoldersList returns folder entries for root/path.

func (*MockHost) FoldersStat

func (m *MockHost) FoldersStat(_ context.Context, root, path string) (FolderEntry, error)

FoldersStat returns a FolderEntry for root and path.

func (*MockHost) KVDelete

func (m *MockHost) KVDelete(_ context.Context, key string) error

KVDelete deletes a key from the in-memory KV store.

func (*MockHost) KVGet

func (m *MockHost) KVGet(_ context.Context, key string) (string, bool, error)

KVGet reads a key from the in-memory KV store.

func (*MockHost) KVList

func (m *MockHost) KVList(_ context.Context, prefix string) ([]string, error)

KVList lists keys matching prefix in sorted order.

func (*MockHost) KVPut

func (m *MockHost) KVPut(_ context.Context, key, value string) error

KVPut writes a key-value pair to the in-memory KV store.

func (*MockHost) KVUsage

func (m *MockHost) KVUsage(_ context.Context) (KVUsage, error)

KVUsage returns in-memory KV usage matching the host's 256-byte key charge.

func (*MockHost) KindBrowse

func (m *MockHost) KindBrowse(ctx context.Context, kindKey string, query KindBrowseQuery) (KindPage, error)

KindBrowse filters and pages MockHost.Kinds with KindHiddenIDs and KindPolicyFilter applied (#615). Requires a viewer token on ctx.

func (*MockHost) KindDelete

func (m *MockHost) KindDelete(_ context.Context, kindKey string, externalIDs []string) error

KindDelete drops recorded items by external id.

func (*MockHost) KindItems

func (m *MockHost) KindItems(_ context.Context, kindKey, cursor string, limit int) (KindPage, error)

KindItems pages recorded items; the cursor is the last item id seen.

func (*MockHost) KindUpsert

func (m *MockHost) KindUpsert(_ context.Context, kindKey string, items []KindItem) (int, error)

KindUpsert records pushed items under their kind, replacing same-id items.

func (*MockHost) KindVisible

func (m *MockHost) KindVisible(ctx context.Context, kindKey string, ids []string) ([]string, error)

KindVisible filters ids against MockHost.Kinds, KindHiddenIDs, and KindPolicyFilter (#615). Requires a viewer token on ctx (WithViewerToken).

func (*MockHost) Log

func (m *MockHost) Log(_ context.Context, level, message string, attrs map[string]any) error

Log appends a RecordedLog entry to Logs.

func (*MockHost) NotifyOwner

func (m *MockHost) NotifyOwner(_ context.Context, text string) error

NotifyOwner appends text to Notifications.

func (*MockHost) PublishEvent

func (m *MockHost) PublishEvent(_ context.Context, key string, payload any, corr *EventCorrelation) error

PublishEvent records one published plugin event on MockHost.

func (*MockHost) ResolveSources

func (m *MockHost) ResolveSources(_ context.Context, _ SourceQuery) ([]SourceCandidate, error)

ResolveSources returns the canned Sources.

func (*MockHost) SecretDelete

func (m *MockHost) SecretDelete(_ context.Context, name string) error

SecretDelete removes a derived secret from the in-memory secrets map.

func (*MockHost) SecretGet

func (m *MockHost) SecretGet(_ context.Context, name string) (string, error)

SecretGet reads a secret from the in-memory secrets map.

func (*MockHost) SecretSet

func (m *MockHost) SecretSet(_ context.Context, name, value string, _ int64) error

SecretSet stores (or deletes when empty) a derived secret in the in-memory secrets map.

func (*MockHost) SetWatchState

func (m *MockHost) SetWatchState(_ context.Context, viewerID int64, titleID string, watched bool) error

SetWatchState records watch state for viewerID:titleID.

func (*MockHost) StreamPartURL

func (m *MockHost) StreamPartURL(_ context.Context, viewerID int64, itemRef string, partIndex int) (string, error)

StreamPartURL mints a deterministic part-scoped stand-in URL and records the last call (#576).

func (*MockHost) StreamURL

func (m *MockHost) StreamURL(_ context.Context, viewerID int64, itemRef string) (string, error)

StreamURL mints a deterministic stand-in URL and records the last call, so a plugin's frontend adapter can be tested without a real ticket issuer.

func (*MockHost) StreamURLWithOptions

func (m *MockHost) StreamURLWithOptions(_ context.Context, viewerID int64, itemRef string, opts StreamURLOptions) (string, error)

StreamURLWithOptions mints a deterministic stand-in URL and records the viewer, item, optional part index, and optional source id (#576, #661).

func (*MockHost) UpsertCollection

func (m *MockHost) UpsertCollection(_ context.Context, collection map[string]any) error

UpsertCollection appends the collection to Collections.

func (*MockHost) ViewerHistory

func (m *MockHost) ViewerHistory(_ context.Context, viewerID int64, limit, offset int) ([]ViewerWatchEntry, error)

ViewerHistory returns watch history for viewerID.

type NotificationMeta

type NotificationMeta struct {
	Fields    any      `json:"fields,omitempty"`
	SendTest  bool     `json:"sendTest"`
	Formats   []string `json:"formats,omitempty"`
	MaxLength int      `json:"maxLength,omitempty"`
}

NotificationMeta describes a notification channel contribution.

type NotifyRequest

type NotifyRequest struct {
	Title    string         `json:"title,omitempty"`
	Message  string         `json:"message"`
	Event    string         `json:"event,omitempty"`
	Settings map[string]any `json:"settings,omitempty"`
}

NotifyRequest is passed to a Notify route handler.

type NotifyResponse

type NotifyResponse struct {
	OK      bool   `json:"ok"`
	Message string `json:"message,omitempty"`
}

NotifyResponse is returned by a Notify route handler.

type OpenStreamRequest

type OpenStreamRequest struct {
	StreamID string `json:"streamId"`
}

OpenStreamRequest is passed to an OpenStream route handler.

type OpenStreamResponse

type OpenStreamResponse struct {
	URL       string            `json:"url,omitempty"`
	Headers   map[string]string `json:"headers,omitempty"`
	ExpiresAt string            `json:"expiresAt,omitempty"`
	File      string            `json:"file,omitempty"`
}

OpenStreamResponse is returned by an OpenStream route handler.

type PageMeta

type PageMeta struct {
	Key   string `json:"key"`
	Label string `json:"label"`
	Route string `json:"route"`
	Group string `json:"group,omitempty"`
	Icon  string `json:"icon,omitempty"`
}

PageMeta describes a ViewSpec page contributed by a plugin.

type PairingInputs

type PairingInputs struct {
	// URL is the server's http(s) base (from ETHER_URL).
	URL string
	// Code is a one-time pairing code (from ETHER_PAIRING_CODE).
	Code string
	// Credential is an explicit credential; it always wins.
	Credential string
	// StateDir overrides where the credential file is kept.
	StateDir string
}

PairingInputs are the pairing settings read from options and the environment. Every SDK resolves them in the same order.

type PartStreamHost

type PartStreamHost interface {
	StreamPartURL(ctx context.Context, viewerID int64, itemRef string, partIndex int) (string, error)
}

PartStreamHost mints a short-lived, scoped ticket for a specific zero-based part of a multi-file kind item (#576). RemoteHostClient and MockHost implement it; Context.StreamPartURL uses it automatically.

type Permissions

type Permissions struct {
	Network     []string           `json:"network,omitempty"`
	Catalog     string             `json:"catalog,omitempty"`
	Viewers     *ViewerPermissions `json:"viewers,omitempty"`
	Collections string             `json:"collections,omitempty"`
	Folders     string             `json:"folders,omitempty"`
	Secrets     []string           `json:"secrets,omitempty"`
	// Sources lets a kind resolver ask Ether to find bytes: ""|none|search|acquire.
	Sources string `json:"sources,omitempty"`
	// AI lets a plugin call AIComplete on the owner's configured language model
	// (""|none|complete|complete+search; "complete" allows actions, jobs, sync,
	// and other non-viewer routes, while "complete+search" also allows bounded
	// 20 s cached calls on interactive search routes).
	AI string `json:"ai,omitempty"`
}

Permissions declares the host access a plugin requests.

type PlayableSource

type PlayableSource struct {
	Path    string `json:"path,omitempty"`
	ID      string `json:"id"`
	Label   string `json:"label,omitempty"`
	Pattern string `json:"pattern"` // range|download|direct|container|release|file
	MIME    string `json:"mime"`
	Size    int64  `json:"size,omitempty"`
	// SizeApproximate marks Size as an approximate hint (for example from a
	// Usenet release_files estimate) rather than an exact byte count.
	SizeApproximate       bool              `json:"sizeApproximate,omitempty"`
	DurationSec           float64           `json:"durationSec,omitempty"`
	URL                   string            `json:"url,omitempty"`
	Headers               map[string]string `json:"headers,omitempty"`
	KeepHeadersOnRedirect []string          `json:"keepHeadersOnRedirect,omitempty"`
	BlobRef               string            `json:"blobRef,omitempty"`
	SHA256                string            `json:"sha256,omitempty"`
	// SHA1 and CRC32 are hex digests checked against the served bytes,
	// including a release's selected file or container member; Size too.
	SHA1      string         `json:"sha1,omitempty"`
	CRC32     string         `json:"crc32,omitempty"`
	MaxBytes  int64          `json:"maxBytes,omitempty"`
	ExpiresAt int64          `json:"expiresAt,omitempty"`
	Container *ContainerRef  `json:"container,omitempty"`
	Release   *ReleaseHint   `json:"release,omitempty"`
	Parts     []KindItemPart `json:"parts,omitempty"`
}

PlayableSource is one candidate way to acquire an item's bytes. URL may carry {itemIndex}, {pageNumber}, {byteStart}, {byteEnd} and {byteRange} placeholders that Ether substitutes.

type Plugin

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

Plugin is a runnable Ether plugin instance.

func New

func New(def Definition) *Plugin

New constructs a Plugin from a Definition.

func NewCatalogTemplate

func NewCatalogTemplate(opts TemplateOptions) *Plugin

NewCatalogTemplate builds a starter catalog and metadata plugin.

func NewConditionTemplate

func NewConditionTemplate(opts TemplateOptions) *Plugin

NewConditionTemplate builds a starter rule-condition plugin.

func NewRankerTemplate

func NewRankerTemplate(opts TemplateOptions) *Plugin

NewRankerTemplate builds a starter release-ranking step plugin.

func NewScrobblerTemplate

func NewScrobblerTemplate(opts TemplateOptions) *Plugin

NewScrobblerTemplate builds a starter playback event subscriber plugin.

func NewSubtitlesTemplate

func NewSubtitlesTemplate(opts TemplateOptions) *Plugin

NewSubtitlesTemplate builds a starter subtitles provider plugin.

func NewViewTemplate

func NewViewTemplate(opts TemplateOptions) *Plugin

NewViewTemplate builds a starter ViewSpec UI and action plugin.

func (*Plugin) CondMatch

func (p *Plugin) CondMatch(candidate CandidateFacts, operator string, value any) bool

CondMatch invokes the plugin's CondMatch hot-path function.

func (*Plugin) Dispatch

func (p *Plugin) Dispatch(ctx context.Context, req RawRequest) RawResponse

Dispatch routes a RawRequest through the plugin and returns a RawResponse.

func (*Plugin) DispatchTunnelFrame

func (p *Plugin) DispatchTunnelFrame(ctx context.Context, frame TunnelFrame, maxChunkBytes int) []TunnelFrame

DispatchTunnelFrame executes a `"request"` TunnelFrame against a Plugin and returns the outgoing response frames (either a single `"response"` frame or a `"response_start"` / `"response_chunk"` / `"response_end"` sequence for `/ether/file/*` binary responses).

func (*Plugin) GetSettings

func (p *Plugin) GetSettings() map[string]any

GetSettings returns a copy of the plugin's active settings.

func (*Plugin) Manifest

func (p *Plugin) Manifest() Manifest

Manifest returns the plugin's Manifest.

func (*Plugin) OnCatalog

func (p *Plugin) OnCatalog(kind string, c CatalogProvider)

OnCatalog registers the catalogue provider for one declared kind.

func (*Plugin) OnFrontend

func (p *Plugin) OnFrontend(key string, a FrontendAdapter)

OnFrontend registers one declared frontend adapter.

func (*Plugin) OnLive

func (p *Plugin) OnLive(kind string, l KindLiveProvider)

OnLive registers the live-tab provider for one declared kind.

func (*Plugin) OnMatch

func (p *Plugin) OnMatch(kind string, m KindMatcher)

OnMatch registers the matcher for one declared kind.

func (*Plugin) OnResolve

func (p *Plugin) OnResolve(kind string, r KindResolver)

OnResolve registers the resolver for one declared kind.

func (*Plugin) OnSetupTest

func (p *Plugin) OnSetupTest(t SetupTester)

OnSetupTest registers the handler for /ether/v1/setup/{step}/test.

func (*Plugin) RankKey

func (p *Plugin) RankKey(candidate CandidateFacts, config map[string]any) int64

RankKey invokes the plugin's RankKey hot-path function.

func (*Plugin) Serve

func (p *Plugin) Serve(ctx context.Context, opts ServeOptions) error

Serve runs the plugin sidecar until ctx is cancelled.

func (*Plugin) ServeHTTP

func (p *Plugin) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements net/http.Handler for running a Plugin as an HTTP sidecar.

func (*Plugin) SetSettings

func (p *Plugin) SetSettings(incoming map[string]any) (map[string]any, map[string]string)

SetSettings validates and updates the plugin's settings.

func (*Plugin) Start

func (p *Plugin) Start(ctx context.Context, opts ServeOptions) (*ServeHandle, error)

Start launches the plugin sidecar in the background (either HTTP or WebSocket tunnel) and returns a ServeHandle that stops it when Close is called or ctx is cancelled.

type PluginAuthor

type PluginAuthor struct {
	Name string `json:"name,omitempty"`
	URL  string `json:"url,omitempty"`
}

PluginAuthor identifies the plugin author.

type PluginKind

type PluginKind string

PluginKind identifies the top-level plugin classification in manifest.ether.kind.

const (
	KindSource              PluginKind = "source"
	KindIntegration         PluginKind = "integration"
	KindNotificationChannel PluginKind = "notification_channel"
	KindLiveTVSource        PluginKind = "livetv_source"
	KindExtension           PluginKind = "extension"
	KindContent             PluginKind = "content"
)

type PosterBadgeSetMeta

type PosterBadgeSetMeta struct {
	Key         string `json:"key"`
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

PosterBadgeSetMeta declares one poster overlay badge set contributed by a plugin (#594).

type Presentations

type Presentations struct {
	AdapterOnly bool `json:"adapterOnly,omitempty"`
	Vela        *struct {
		Type    string `json:"type,omitempty"`    // movies|shows
		Default *bool  `json:"default,omitempty"` // optional default on/off suggestion
	} `json:"vela,omitempty"`
	Plex *struct {
		Base    string `json:"base,omitempty"`    // movie|show|artist|photo
		Default *bool  `json:"default,omitempty"` // optional default on/off suggestion
	} `json:"plex,omitempty"`
	MediaBrowser *struct {
		CollectionType string `json:"collectionType,omitempty"` // movies|tvshows|music|audiobooks|books|photos|homevideos
		// ItemTypes maps each level key to its Jellyfin/Emby item type:
		// Movie|Series|Season|Episode|MusicArtist|MusicAlbum|Audio|
		// AudioBook|Book|PhotoAlbum|Photo. Unmapped levels are inferred from
		// the kind's media class, level roles, and hierarchy shape.
		ItemTypes map[string]string `json:"itemTypes,omitempty"`
		Default   *bool             `json:"default,omitempty"` // optional default on/off suggestion
	} `json:"mediaBrowser,omitempty"`
	Stremio *struct {
		Type    string `json:"type,omitempty"`
		Default *bool  `json:"default,omitempty"`
	} `json:"stremio,omitempty"`
	Xtream *struct {
		Category string `json:"category,omitempty"`
		Default  *bool  `json:"default,omitempty"`
	} `json:"xtream,omitempty"`
	Silo *struct {
		Type    string `json:"type,omitempty"`
		Default *bool  `json:"default,omitempty"`
	} `json:"silo,omitempty"`
}

Presentations declares how a library is seen per protocol. Each app block describes how that app renders the library (never whether it is published, though Default may suggest starting off for an app). When an app block is omitted, Ether infers a fitting presentation from the kind's media class, level roles, and hierarchy shape.

type ProgrammeItem

type ProgrammeItem struct {
	ID          string   `json:"id,omitempty"`
	ChannelID   string   `json:"channelId,omitempty"`
	Title       string   `json:"title"`
	Subtitle    string   `json:"subtitle,omitempty"`
	Description string   `json:"description,omitempty"`
	Start       string   `json:"start"`
	Stop        string   `json:"stop"`
	Icon        string   `json:"icon,omitempty"`
	Categories  []string `json:"categories,omitempty"`
}

ProgrammeItem is one EPG programme entry.

type PublishedEventMeta

type PublishedEventMeta struct {
	Key         string           `json:"key"`
	Label       string           `json:"label"`
	Description string           `json:"description,omitempty"`
	Version     int              `json:"version,omitempty"`
	Fields      []EventFieldMeta `json:"fields,omitempty"`
}

PublishedEventMeta declares one custom event emitted via PublishEvent ("plugin:<pluginId>/<key>").

type RankingStepMeta

type RankingStepMeta struct {
	Key    string `json:"key"`
	Label  string `json:"label"`
	Hint   string `json:"hint,omitempty"`
	Editor any    `json:"editor,omitempty"`
	Budget any    `json:"budget,omitempty"`
}

RankingStepMeta describes a custom ranking step.

type RasterizeOptions

type RasterizeOptions struct {
	Width  int    `json:"width,omitempty"`
	Height int    `json:"height,omitempty"`
	Format string `json:"format,omitempty"`
}

RasterizeOptions selects the output size and format for CacheRasterize. A zero Width or Height keeps the SVG aspect ratio; Format is "png" (default) or "jpeg". Each dimension is bounded at 2048 by the host.

type RasterizeResult

type RasterizeResult struct {
	Blob        string `json:"blob"`
	ContentType string `json:"contentType"`
	Width       int    `json:"width"`
	Height      int    `json:"height"`
	Size        int64  `json:"size"`
}

RasterizeResult is returned by CacheRasterize: the new cached bitmap blob, its content type and pixel dimensions.

type RawRequest

type RawRequest struct {
	PluginID string            `json:"pluginId,omitempty"`
	Method   string            `json:"method,omitempty"`
	Path     string            `json:"path"`
	Query    map[string]string `json:"query,omitempty"`
	Headers  map[string]string `json:"headers,omitempty"`
	Body     json.RawMessage   `json:"body,omitempty"`
	Locale   string            `json:"locale,omitempty"`
}

RawRequest is the low-level transport-agnostic request passed to Plugin.Dispatch.

type RawResponse

type RawResponse struct {
	Blob       *FrontendBlob     `json:"blob,omitempty"`
	Status     int               `json:"status"`
	Headers    map[string]string `json:"headers,omitempty"`
	Body       json.RawMessage   `json:"body,omitempty"`
	BinaryBody []byte            `json:"-"`
}

RawResponse is the low-level transport-agnostic response returned by Plugin.Dispatch.

type RecordedLog

type RecordedLog struct {
	Level   string
	Message string
	Attrs   map[string]any
}

RecordedLog is one log message recorded by MockHost.

type RecordedPublishedEvent

type RecordedPublishedEvent struct {
	Key         string
	Payload     map[string]any
	Correlation *EventCorrelation
}

RecordedPublishedEvent is one plugin event recorded by MockHost.PublishEvent.

type ReleaseFile

type ReleaseFile struct {
	Index int    `json:"index"`
	Path  string `json:"path"`
	Size  int64  `json:"size"`
	// SizeApproximate is true when Size is a segment-derived decoded estimate
	// rather than an exact byte length (e.g. an NZB without readable PAR2/yEnc
	// headers). Exact sizes leave it false/omitted.
	SizeApproximate bool            `json:"sizeApproximate,omitempty"`
	Members         []ReleaseMember `json:"members,omitempty"`
}

ReleaseFile is one file inside a candidate release (release_files).

type ReleaseHint

type ReleaseHint struct {
	// FileIndex overrides candidate.fileIndex; out-of-range indices fail without fallback.
	FileIndex  *int             `json:"fileIndex,omitempty"`
	NZBURL     string           `json:"nzbUrl,omitempty"`
	Magnet     string           `json:"magnet,omitempty"`
	InfoHash   string           `json:"infoHash,omitempty"`
	TorrentURL string           `json:"torrentUrl,omitempty"`
	Candidate  *SourceCandidate `json:"candidate,omitempty"`
	// File selects an exact torrent path or unique basename, including non-video files.
	File           string     `json:"file,omitempty"`
	FileHint       string     `json:"fileHint,omitempty"`
	Track          *TrackHint `json:"track,omitempty"`
	PasswordSecret string     `json:"passwordSecret,omitempty"`
	// CachedOnly requires an already-cached debrid copy even when the owner turned
	// "Cached torrents only" off. Omit or leave false to follow the owner's debrid setting.
	CachedOnly bool `json:"cachedOnly,omitempty"`
	// FileCount optionally hints how many files a torrent contains when Ether has
	// not seen its file list yet (e.g. a magnet for one entry of a large collection),
	// so providers whose cache check cannot see zip-only 100+-file torrents (TorBox)
	// try a cached-only add instead of trusting a checkcached miss.
	FileCount int `json:"fileCount,omitempty"`
}

ReleaseHint hands a release to Ether's Usenet/debrid/torrent pipeline.

type ReleaseMember

type ReleaseMember struct {
	Index  int    `json:"index"`
	Path   string `json:"path"`
	Size   int64  `json:"size"`
	Stored bool   `json:"stored,omitempty"`
}

ReleaseMember is one non-directory file inside an archive (RAR, 7z, ZIP) returned by a release_files source query.

type RemoteHostClient

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

RemoteHostClient implements Host by calling `/ether/plugin-host/*` on the Ether server authenticated with `X-Ether-Plugin-Credential`.

func NewRemoteHostClient

func NewRemoteHostClient(opts RemoteHostOptions) *RemoteHostClient

NewRemoteHostClient creates a RemoteHostClient.

func (*RemoteHostClient) AIComplete

AIComplete runs a bounded text or JSON-Schema-validated completion against the owner's configured language model through POST /ether/plugin-host/ai/complete. Requires permissions.ai: "complete" (or "complete+search" on interactive search routes, forwarding X-Ether-Viewer-Token when present on ctx). When no model is configured, returns a *HostError with Code == "not_configured".

func (*RemoteHostClient) ArchiveExtract

func (c *RemoteHostClient) ArchiveExtract(ctx context.Context, blob string, member int, opts ...ArchiveExtractOptions) (ArchiveExtractResult, error)

ArchiveExtract streams an uncompressed ZIP, 7z or RAR member straight into the plugin's own library blob cache in one pass and returns its blob ref and SHA-1/MD5/CRC32 digests without buffering the member in plugin memory.

func (*RemoteHostClient) ArchiveList

func (c *RemoteHostClient) ArchiveList(ctx context.Context, blob string) ([]ArchiveMember, error)

func (*RemoteHostClient) ArchiveOpen

func (c *RemoteHostClient) ArchiveOpen(ctx context.Context, blob string, member int, r DataRange) ([]byte, error)

ArchiveOpen reads a bounded uncompressed ZIP, 7z or RAR member range. Compressed reads restart at the member or solid block beginning per call. Prefer large sequential chunks; decoder work and memory obey host grants.

func (*RemoteHostClient) ArchiveRead

func (c *RemoteHostClient) ArchiveRead(ctx context.Context, blob string, reads []ArchiveReadItem) ([]ArchiveReadResult, error)

ArchiveRead reads 1..4096 bounded archive member ranges in one host call while keeping the sum of requested lengths within the plugin's readBytes grant.

func (*RemoteHostClient) BadgesClear

func (c *RemoteHostClient) BadgesClear(ctx context.Context, setKey string) error

BadgesClear removes every badge in one declared set (#594).

func (*RemoteHostClient) BadgesSet

func (c *RemoteHostClient) BadgesSet(ctx context.Context, setKey string, entries []BadgeEntry) error

BadgesSet pushes poster badges for one declared badge set (#594).

func (*RemoteHostClient) BadgesUsage

func (c *RemoteHostClient) BadgesUsage(ctx context.Context) (BadgeUsage, error)

BadgesUsage reads the plugin's current badged title count and quota (#594).

func (*RemoteHostClient) CacheDelete

func (c *RemoteHostClient) CacheDelete(ctx context.Context, blobRef string) error

CacheDelete removes one cached blob from this plugin's own library cache namespaces, freeing its quota immediately. Deleting an absent or already evicted ref succeeds.

func (*RemoteHostClient) CacheOpen

func (c *RemoteHostClient) CacheOpen(ctx context.Context, blobRef string) ([]byte, error)

CacheOpen reads one cached blob back.

func (*RemoteHostClient) CachePut

func (c *RemoteHostClient) CachePut(ctx context.Context, libraryKey, name string, data []byte) (string, error)

CachePut stores one blob in a kind library's cache; the ref is content-addressed.

func (*RemoteHostClient) CacheRasterize

func (c *RemoteHostClient) CacheRasterize(ctx context.Context, libraryKey, name, blob string, opts RasterizeOptions) (RasterizeResult, error)

CacheRasterize rasterises an SVG already in the plugin's blob cache into a new cached bitmap blob under libraryKey/name, using Ether's bounded SVG rasteriser (source and output sizes are host-bounded, unsafe documents are refused, and rendered variants are cached host-side).

func (*RemoteHostClient) CacheRead

func (c *RemoteHostClient) CacheRead(ctx context.Context, blob string, r DataRange) ([]byte, error)

func (*RemoteHostClient) CatalogGet

func (c *RemoteHostClient) CatalogGet(ctx context.Context, id string) (*CatalogTitleSummary, error)

CatalogGet fetches one title summary from the Ether catalog.

func (*RemoteHostClient) CatalogSearch

func (c *RemoteHostClient) CatalogSearch(
	ctx context.Context,
	query string,
	limit, offset int,
) ([]CatalogTitleSummary, error)

CatalogSearch searches the Ether catalog.

func (*RemoteHostClient) Fetch

Fetch performs an outbound HTTP request.

func (*RemoteHostClient) FetchMany

FetchMany runs up to MaxFetchManyRequests outbound HTTP calls concurrently (bounded to MaxFetchManyConcurrency per batch and DefaultMaxFetchPerHost per origin), returning ordered results with per-item error isolation.

func (*RemoteHostClient) FetchToCache

func (*RemoteHostClient) FoldersHash

func (*RemoteHostClient) FoldersHashCancel

func (*RemoteHostClient) FoldersHashCancel(context.Context, string) (FolderHashJob, error)

func (*RemoteHostClient) FoldersHashPoll

func (*RemoteHostClient) FoldersHashPoll(context.Context, string) (FolderHashJob, error)

func (*RemoteHostClient) FoldersHashStart

func (*RemoteHostClient) FoldersList

func (c *RemoteHostClient) FoldersList(_ context.Context, _, _ string) ([]FolderEntry, error)

FoldersList is only supported in hosted mode; sidecars access local folders directly.

func (*RemoteHostClient) FoldersStat

func (c *RemoteHostClient) FoldersStat(_ context.Context, _, _ string) (FolderEntry, error)

FoldersStat is only supported in hosted mode; sidecars access local folders directly.

func (*RemoteHostClient) Hash

func (*RemoteHostClient) KVDelete

func (c *RemoteHostClient) KVDelete(ctx context.Context, key string) error

KVDelete deletes a key from the plugin's KV namespace.

func (*RemoteHostClient) KVGet

func (c *RemoteHostClient) KVGet(ctx context.Context, key string) (string, bool, error)

KVGet reads a key from the plugin's KV namespace.

func (*RemoteHostClient) KVList

func (c *RemoteHostClient) KVList(ctx context.Context, prefix string) ([]string, error)

KVList lists keys matching the given prefix in the plugin's KV namespace.

func (*RemoteHostClient) KVPut

func (c *RemoteHostClient) KVPut(ctx context.Context, key, value string) error

KVPut writes a key-value pair to the plugin's KV namespace.

func (*RemoteHostClient) KVUsage

func (c *RemoteHostClient) KVUsage(ctx context.Context) (KVUsage, error)

KVUsage reads the plugin's current KV byte/key usage and quotas.

func (*RemoteHostClient) KindBrowse

func (c *RemoteHostClient) KindBrowse(ctx context.Context, kindKey string, query KindBrowseQuery) (KindPage, error)

KindBrowse browses or searches kindKey with the library's Rules and viewer access policy applied for the requesting frontend-adapter viewer (#615). ctx must carry the incoming frontend adapter's X-Ether-Viewer-Token (via WithViewerToken, attached automatically by FrontendAdapter dispatch).

func (*RemoteHostClient) KindDelete

func (c *RemoteHostClient) KindDelete(ctx context.Context, kindKey string, externalIDs []string) error

KindDelete removes items from a push-mode kind library.

func (*RemoteHostClient) KindItems

func (c *RemoteHostClient) KindItems(ctx context.Context, kindKey, cursor string, limit int) (KindPage, error)

KindItems reads the plugin's own kind library back, keyset-paged.

func (*RemoteHostClient) KindUpsert

func (c *RemoteHostClient) KindUpsert(ctx context.Context, kindKey string, items []KindItem) (int, error)

KindUpsert pushes items into a push-mode kind library.

func (*RemoteHostClient) KindVisible

func (c *RemoteHostClient) KindVisible(ctx context.Context, kindKey string, ids []string) ([]string, error)

KindVisible evaluates the library's Rules and viewer access policy for a bounded batch (at most MaxKindVisibleIDs) of external IDs in kindKey (#615). ctx must carry the incoming frontend adapter's X-Ether-Viewer-Token (via WithViewerToken, attached automatically by FrontendAdapter dispatch).

func (*RemoteHostClient) Log

func (c *RemoteHostClient) Log(ctx context.Context, level, message string, attrs map[string]any) error

Log sends a structured log entry to Ether.

func (*RemoteHostClient) NotifyOwner

func (c *RemoteHostClient) NotifyOwner(ctx context.Context, text string) error

NotifyOwner sends an owner notification through Ether.

func (*RemoteHostClient) PublishEvent

func (c *RemoteHostClient) PublishEvent(ctx context.Context, key string, payload any, corr *EventCorrelation) error

PublishEvent emits a declared plugin event ("plugin:<id>/<key>") onto Ether's event bus through POST /ether/plugin-host/events/publish.

func (*RemoteHostClient) ResolveSources

func (c *RemoteHostClient) ResolveSources(ctx context.Context, q SourceQuery) ([]SourceCandidate, error)

ResolveSources asks Ether to find sources through its indexers/debrid.

func (*RemoteHostClient) RuntimeLimits

func (c *RemoteHostClient) RuntimeLimits(ctx context.Context) (RuntimeLimits, error)

func (*RemoteHostClient) SecretDelete

func (c *RemoteHostClient) SecretDelete(ctx context.Context, name string) error

SecretDelete removes a plugin-written derived secret declared in permissions.secrets (#660).

func (*RemoteHostClient) SecretGet

func (c *RemoteHostClient) SecretGet(_ context.Context, _ string) (string, error)

SecretGet is only available in hosted mode; remote plugins receive secrets via /ether/configure.

func (*RemoteHostClient) SecretSet

func (c *RemoteHostClient) SecretSet(ctx context.Context, name, value string, ttlSec int64) error

SecretSet stores a sealed derived secret under a name declared in permissions.secrets (#660). Passing an empty value deletes it.

func (*RemoteHostClient) SetWatchState

func (c *RemoteHostClient) SetWatchState(
	ctx context.Context,
	viewerID int64,
	titleID string,
	watched bool,
) error

SetWatchState updates the watch state for a granted viewer.

func (*RemoteHostClient) SettingsGet

func (c *RemoteHostClient) SettingsGet(ctx context.Context) (map[string]any, error)

SettingsGet reads the current non-secret settings from Ether.

func (*RemoteHostClient) StreamPartURL

func (c *RemoteHostClient) StreamPartURL(ctx context.Context, viewerID int64, itemRef string, partIndex int) (string, error)

StreamPartURL mints a scoped stream ticket for one zero-based part of a multi-file kind item (#576).

func (*RemoteHostClient) StreamURL

func (c *RemoteHostClient) StreamURL(ctx context.Context, viewerID int64, itemRef string) (string, error)

StreamURL mints a scoped stream ticket and returns the Ether stream URL for one of this plugin's own kind items (spec §6.5).

func (*RemoteHostClient) StreamURLWithOptions

func (c *RemoteHostClient) StreamURLWithOptions(ctx context.Context, viewerID int64, itemRef string, opts StreamURLOptions) (string, error)

StreamURLWithOptions mints a scoped stream ticket for one of this plugin's own kind items, optionally pinned to a zero-based part and/or resolver PlayableSource.ID (#576, #661).

func (*RemoteHostClient) UpsertCollection

func (c *RemoteHostClient) UpsertCollection(ctx context.Context, collection map[string]any) error

UpsertCollection creates or updates a plugin-managed collection.

func (*RemoteHostClient) ViewerHistory

func (c *RemoteHostClient) ViewerHistory(
	ctx context.Context,
	viewerID int64,
	limit, offset int,
) ([]ViewerWatchEntry, error)

ViewerHistory reads watch history for a granted viewer.

type RemoteHostOptions

type RemoteHostOptions struct {
	BaseURL    string
	Credential string
	HTTPClient *http.Client
}

RemoteHostOptions configures a RemoteHostClient for sidecar plugins.

type RouteError

type RouteError struct {
	Status  int
	Code    string
	Message string
}

RouteError represents a structured HTTP error returned by a plugin handler.

func NewRouteError

func NewRouteError(status int, code, message string) *RouteError

NewRouteError constructs a structured RouteError.

func (*RouteError) Error

func (e *RouteError) Error() string

type Routes

type Routes struct {
	Catalog          func(ctx *Context, req CatalogRequest) (CatalogResponse, error)
	Meta             func(ctx *Context, req MetaRequest) (MetaResponse, error)
	Stream           func(ctx *Context, req StreamRequest) (StreamResponse, error)
	OpenStream       func(ctx *Context, req OpenStreamRequest) (OpenStreamResponse, error)
	Subtitles        func(ctx *Context, req SubtitlesRequest) (SubtitlesResponse, error)
	SubtitleDownload func(ctx *Context, req SubtitleDownloadRequest) (SubtitleDownloadResponse, error)
	Markers          func(ctx *Context, req MarkersRequest) (MarkersResponse, error)
	Channels         func(ctx *Context) (ChannelsResponse, error)
	Guide            func(ctx *Context, req GuideRequest) (GuideResponse, error)
	Configure        func(ctx *Context, settings map[string]any) (ConfigureResponse, error)
	Test             func(ctx *Context) (TestResponse, error)
	Options          func(ctx *Context, field string) ([]FieldOption, error)
	Health           func(ctx *Context) (HealthResponse, error)
	Notify           func(ctx *Context, req NotifyRequest) (NotifyResponse, error)
	Event            func(ctx *Context, events []EtherEvent) (EventResponse, error)
	FlowAction       func(ctx *Context, req FlowActionRequest) (FlowActionResponse, error)
	View             func(ctx *Context, req ViewRequest) (ViewResponse, error)
	Action           func(ctx *Context, req ActionRequest) (ActionResponse, error)
	Tool             func(ctx *Context, req ToolRequest) (ToolResponse, error)
	Job              func(ctx *Context, req JobRequest) (JobResponse, error)
	File             func(ctx *Context, req FileRequest) (FileRangeResponse, error)
	RankKey          func(candidate CandidateFacts, config map[string]any) int64
	CondMatch        func(candidate CandidateFacts, operator string, value any) bool
}

Routes holds the capability handlers for a Plugin.

type RuleConditionMeta

type RuleConditionMeta struct {
	Key       string   `json:"key"`
	Label     string   `json:"label"`
	Operators []string `json:"operators,omitempty"`
	Editor    any      `json:"editor,omitempty"`
}

RuleConditionMeta describes a custom rule condition.

type RuntimeDecl

type RuntimeDecl struct {
	Kind   string         `json:"kind"`
	Entry  string         `json:"entry,omitempty"`
	Module string         `json:"module,omitempty"`
	Limits *RuntimeLimits `json:"limits,omitempty"`
}

RuntimeDecl declares how the plugin is executed.

type RuntimeLimits

type RuntimeLimits struct {
	FetchBytes           int64  `json:"fetchBytes,omitempty"`
	ArchiveMemberBytes   int64  `json:"archiveMemberBytes,omitempty"`
	ArchiveExpandedBytes int64  `json:"archiveExpandedBytes,omitempty"`
	ArchiveMembers       int    `json:"archiveMembers,omitempty"`
	MaxItems             int    `json:"maxItems,omitempty"`
	MemoryBytes          uint64 `json:"memoryBytes,omitempty"`
	ReadBytes            int64  `json:"readBytes,omitempty"`
	Deadline             string `json:"deadline,omitempty"`
	UnitBudget           int64  `json:"unitBudget,omitempty"`
	// PoolSize requests the hosted WASM instance pool size (default 2; default
	// owner ceiling 4, raisable up to 16).
	PoolSize int `json:"poolSize,omitempty"`
}

RuntimeLimits requests hosted/data resources within owner-controlled ceilings. Defaults: 32 MiB heap, 12h, effectively unlimited background work units.

type ScheduleEntry

type ScheduleEntry struct {
	Every string `json:"every"`
	Call  string `json:"call"`
}

ScheduleEntry declares a scheduled background job.

type SearchProvider

type SearchProvider interface {
	Search(ctx *Context, req KindBrowseRequest) (KindPage, error)
}

SearchProvider is the optional provider-side search route.

type SecretWriteHost

type SecretWriteHost interface {
	SecretSet(ctx context.Context, name, value string, ttlSec int64) error
	SecretDelete(ctx context.Context, name string) error
}

SecretWriteHost stores and removes sealed derived secrets declared in permissions.secrets (#660). Owner-configured settings secrets cannot be overwritten. RemoteHostClient and MockHost implement it.

type ServeHandle

type ServeHandle struct {
	// Done closes when the tunnel supervisor stops (ctx cancellation or Close).
	// Transient disconnects reconnect automatically. It is nil for HTTP servers.
	Done  <-chan struct{}
	Mode  string
	URL   string
	Port  int
	Close func() error
}

ServeHandle represents a running HTTP or tunnel sidecar session.

type ServeOptions

type ServeOptions struct {
	Mode       string
	Host       string
	Port       int
	TunnelURL  string
	Credential string
	// URL is the server's http(s) base (ETHER_URL). When set, the tunnel URL
	// and pair URL are derived from it and the SDK pairs with a code.
	URL string
	// StateDir overrides where the pairing credential is saved
	// (ETHER_PLUGIN_STATE_DIR).
	StateDir string
}

ServeOptions configures how Plugin.Serve runs in sidecar mode.

type SettingField

type SettingField struct {
	Key         string         `json:"key"`
	Kind        string         `json:"kind"`
	Label       string         `json:"label,omitempty"`
	Hint        string         `json:"hint,omitempty"`
	Required    bool           `json:"required,omitempty"`
	Default     any            `json:"default,omitempty"`
	Options     []FieldOption  `json:"options,omitempty"`
	Fields      []SettingField `json:"fields,omitempty"`
	Min         *float64       `json:"min,omitempty"`
	Max         *float64       `json:"max,omitempty"`
	Placeholder string         `json:"placeholder,omitempty"`
}

SettingField describes one leaf or group setting field.

func CollectSettingFields

func CollectSettingFields(schema *SettingsSchema) []SettingField

CollectSettingFields returns all leaf SettingFields from a SettingsSchema.

type SettingsGroup

type SettingsGroup struct {
	Key      string         `json:"key,omitempty"`
	Label    string         `json:"label,omitempty"`
	Hint     string         `json:"hint,omitempty"`
	Advanced bool           `json:"advanced,omitempty"`
	Fields   []SettingField `json:"fields"`
}

SettingsGroup groups related settings fields.

type SettingsSchema

type SettingsSchema struct {
	Ref    string          `json:"$ref,omitempty"`
	Fields []SettingField  `json:"fields,omitempty"`
	Groups []SettingsGroup `json:"groups,omitempty"`
}

SettingsSchema describes a plugin's configuration fields.

type SetupMeta

type SetupMeta struct {
	Steps []SetupStep `json:"steps"`
}

SetupMeta declares guided setup for any plugin kind.

type SetupStep

type SetupStep struct {
	Key      string   `json:"key"`
	Label    string   `json:"label"`
	Hint     string   `json:"hint,omitempty"`
	Fields   []string `json:"fields"`
	Test     string   `json:"test"`
	Required bool     `json:"required"`
}

SetupStep is one setup wizard step; an empty Test means saving is the step.

type SetupTestRequest

type SetupTestRequest struct {
	Step   string         `json:"step"`
	Fields map[string]any `json:"fields,omitempty"`
}

SetupTestRequest is Ether's setup-step test call: the step key plus the saved (non-secret) values of the step's fields.

type SetupTestResult

type SetupTestResult struct {
	OK     bool              `json:"ok"`
	Detail string            `json:"detail,omitempty"`
	Fields map[string]string `json:"fields,omitempty"`
}

SetupTestResult is a setup test's answer.

type SetupTester

type SetupTester interface {
	TestSetup(ctx *Context, req SetupTestRequest) (SetupTestResult, error)
}

SetupTester answers setup-step test calls.

type SlotMeta

type SlotMeta struct {
	Slot  string `json:"slot"`
	Key   string `json:"key"`
	Label string `json:"label"`
	Route string `json:"route"`
}

SlotMeta describes a UI slot contributed by a plugin.

type SourceCandidate

type SourceCandidate struct {
	InfoHash   string `json:"infoHash,omitempty"`
	Magnet     string `json:"magnet,omitempty"`
	TorrentURL string `json:"torrentUrl,omitempty"`
	NZBURL     string `json:"nzbUrl,omitempty"`
	// FileIndex selects a zero-based entry in the torrent provider file list; nil uses video selection.
	FileIndex *int   `json:"fileIndex,omitempty"`
	Title     string `json:"title,omitempty"`
	Size      int64  `json:"size,omitempty"`
	Seeders   int    `json:"seeders,omitempty"`
	Cached    bool   `json:"cached,omitempty"`
	// CachedBy lists the configured debrid services holding this torrent in
	// acquisition order (or the service that served debrid_acquire); omitted when uncached.
	CachedBy  []DebridServiceRef `json:"cachedBy,omitempty"`
	Indexer   string             `json:"indexer,omitempty"`
	IndexerID string             `json:"indexerId,omitempty"`
	// Score, Resolution, Source and Codec are populated on indexer_search
	// candidates whose release name identifies video; non-video candidates
	// leave them empty.
	Score      *int   `json:"score,omitempty"`
	Resolution int    `json:"resolution,omitempty"`
	Source     string `json:"source,omitempty"`
	Codec      string `json:"codec,omitempty"`
	// Files is populated only by a release_files query.
	Files []ReleaseFile `json:"files,omitempty"`
	// FileCount is the torrent's known file count when reported by an indexer
	// or release_files query.
	FileCount int `json:"fileCount,omitempty"`
	// UsenetCheck is populated only by a usenet_check query.
	UsenetCheck *UsenetCheckResult `json:"usenetCheck,omitempty"`

	// Ref names this candidate in match scores. Ether derives it from the
	// infohash/NZB when empty; matchers echo it verbatim.
	Ref string `json:"-"`
}

SourceCandidate is one Ether-found release for a resolver to rank. Torrent candidates carry infoHash, magnet, and/or torrentUrl and never set nzbUrl; Usenet candidates carry nzbUrl. Same-origin download links from indexer_search are stripped of indexer API keys and secrets so candidates can be cached safely; Ether re-attaches credentials at fetch time on the originating indexer's origin using indexerId.

func (SourceCandidate) CandidateRef

func (c SourceCandidate) CandidateRef() string

CandidateRef returns the stable ref matchers report for a candidate.

type SourceMeta

type SourceMeta struct {
	Class     string         `json:"class"`
	Abilities []string       `json:"abilities,omitempty"`
	Limits    map[string]any `json:"limits,omitempty"`
}

SourceMeta describes a stream source contribution.

type SourceQuery

type SourceQuery struct {
	Kind  string `json:"kind"` // indexer_search|debrid_check|debrid_acquire|release_files|usenet_check
	Query string `json:"query,omitempty"`
	// Category accepts comma-separated Newznab IDs or standard family names;
	// when set with an empty Query, indexer_search requests recent releases.
	Category string `json:"category,omitempty"`
	// Profile names the quality profile to score video release names against
	// on indexer_search; empty uses the owner's default profile.
	Profile    string   `json:"profile,omitempty"`
	InfoHashes []string `json:"infoHashes,omitempty"`
	InfoHash   string   `json:"infoHash,omitempty"`
	Magnet     string   `json:"magnet,omitempty"`
	// TorrentURL carries a torrent download or details page link when an
	// indexer did not supply an infoHash or magnet.
	TorrentURL string `json:"torrentUrl,omitempty"`
	// NZBURL carries a Usenet NZB link for usenet_check when not passing a
	// full Candidate from indexer_search.
	NZBURL string `json:"nzbUrl,omitempty"`
	// Candidate carries an indexer_search candidate back for release_files
	// or usenet_check.
	Candidate *SourceCandidate `json:"candidate,omitempty"`
	// FileCount optionally hints how many files a torrent contains when passing
	// a magnet or infoHash without a file list (e.g. large collection torrents
	// held as zip-only caches on TorBox).
	FileCount int `json:"fileCount,omitempty"`
}

SourceQuery asks Ether to find sources (Host.ResolveSources).

type StreamEtherExt

type StreamEtherExt struct {
	ID          string   `json:"id,omitempty"`
	ReleaseName string   `json:"releaseName,omitempty"`
	Size        int64    `json:"size,omitempty"`
	Languages   []string `json:"languages,omitempty"`
	Lazy        bool     `json:"lazy,omitempty"`
	File        string   `json:"file,omitempty"`
}

StreamEtherExt holds Ether-specific extensions on a StreamItem.

type StreamItem

type StreamItem struct {
	Name        string          `json:"name,omitempty"`
	Title       string          `json:"title,omitempty"`
	Description string          `json:"description,omitempty"`
	URL         string          `json:"url,omitempty"`
	InfoHash    string          `json:"infoHash,omitempty"`
	FileIdx     *int            `json:"fileIdx,omitempty"`
	YtID        string          `json:"ytId,omitempty"`
	ExternalURL string          `json:"externalUrl,omitempty"`
	Ether       *StreamEtherExt `json:"ether,omitempty"`
}

StreamItem is one playable candidate returned by a Stream route handler.

type StreamRequest

type StreamRequest struct {
	Type  string            `json:"type"`
	ID    string            `json:"id"`
	Extra map[string]string `json:"extra"`
}

StreamRequest is passed to a Stream route handler.

type StreamResponse

type StreamResponse struct {
	Streams []StreamItem `json:"streams"`
}

StreamResponse is returned by a Stream route handler.

type StreamURLOptions

type StreamURLOptions struct {
	PartIndex *int   `json:"partIndex,omitempty"`
	Source    string `json:"source,omitempty"`
}

StreamURLOptions scopes a frontend adapter stream ticket to a specific zero-based item part and/or resolver PlayableSource.ID (#576, #661).

type StreamURLOptionsHost

type StreamURLOptionsHost interface {
	StreamURLWithOptions(ctx context.Context, viewerID int64, itemRef string, opts StreamURLOptions) (string, error)
}

StreamURLOptionsHost mints a short-lived, scoped ticket for a specific zero-based part and/or resolver PlayableSource.ID of a kind item (#576, #661). RemoteHostClient and MockHost implement it; Context.StreamURLWithOptions uses it automatically.

type StremioCatalogDecl

type StremioCatalogDecl struct {
	Type  string              `json:"type"`
	ID    string              `json:"id"`
	Name  string              `json:"name,omitempty"`
	Extra []StremioExtraField `json:"extra,omitempty"`
}

StremioCatalogDecl declares a Stremio catalog in the manifest.

type StremioExtraField

type StremioExtraField struct {
	Name         string   `json:"name"`
	IsRequired   bool     `json:"isRequired,omitempty"`
	Options      []string `json:"options,omitempty"`
	OptionsLimit int      `json:"optionsLimit,omitempty"`
}

StremioExtraField declares a supported extra parameter on a catalog.

type StringsCatalog

type StringsCatalog map[string]map[string]string

StringsCatalog maps locale codes (e.g. "en", "fr-CA") to key-value tables.

type SubtitleDownloadRequest

type SubtitleDownloadRequest struct {
	ID     string `json:"id"`
	Lang   string `json:"lang"`
	Format string `json:"format"`
}

SubtitleDownloadRequest identifies a viewer-picked subtitle.

type SubtitleDownloadResponse

type SubtitleDownloadResponse struct {
	Format   string `json:"format"`
	Encoding string `json:"encoding"`
	Data     string `json:"data"`
}

SubtitleDownloadResponse carries subtitle text or base64-encoded bytes.

type SubtitleItem

type SubtitleItem struct {
	ID              string `json:"id"`
	URL             string `json:"url,omitempty"`
	Name            string `json:"name,omitempty"`
	Lang            string `json:"lang"`
	Label           string `json:"label,omitempty"`
	Format          string `json:"format,omitempty"`
	HearingImpaired bool   `json:"hearingImpaired,omitempty"`
}

SubtitleItem is one subtitle track returned by a Subtitles route handler.

type SubtitlesMeta

type SubtitlesMeta struct {
	Languages any      `json:"languages,omitempty"`
	Formats   []string `json:"formats,omitempty"`
}

SubtitlesMeta describes a subtitle provider contribution.

type SubtitlesRequest

type SubtitlesRequest struct {
	Type      string            `json:"type"`
	ID        string            `json:"id"`
	Extra     map[string]string `json:"extra"`
	PickToken string            `json:"pickToken"`
	VideoHash string            `json:"videoHash,omitempty"`
	VideoSize int64             `json:"videoSize,omitempty"`
	Filename  string            `json:"filename,omitempty"`
}

SubtitlesRequest is passed to a Subtitles route handler.

type SubtitlesResponse

type SubtitlesResponse struct {
	Subtitles []SubtitleItem `json:"subtitles"`
}

SubtitlesResponse is returned by a Subtitles route handler.

type TemplateOptions

type TemplateOptions struct {
	ID          string
	Name        string
	Version     string
	Summary     string
	Description string
}

TemplateOptions configures a capability starter template.

type TestHarness

type TestHarness struct {
	Plugin *Plugin
	Host   *MockHost
}

TestHarness wraps a Plugin and MockHost for ergonomic unit tests.

func NewTestHarness

func NewTestHarness(p *Plugin, host *MockHost) *TestHarness

NewTestHarness constructs a TestHarness for p.

func (*TestHarness) Action

func (h *TestHarness) Action(action string, input map[string]any) (int, ActionResponse, error)

Action calls POST /ether/action/{action}.

func (*TestHarness) Catalog

func (h *TestHarness) Catalog(typ, id string, extra map[string]string) (int, CatalogResponse, error)

Catalog calls GET /catalog/{type}/{id}[/{extra}].json.

func (*TestHarness) Configure

func (h *TestHarness) Configure(settings map[string]any) (int, ConfigureResponse, error)

Configure calls POST /ether/configure.

func (*TestHarness) Event

func (h *TestHarness) Event(events []EtherEvent) (int, EventResponse, error)

Event calls POST /ether/event.

func (*TestHarness) File

func (h *TestHarness) File(path, rangeHeader string) RawResponse

File calls GET /ether/file/{path}.

func (*TestHarness) FlowAction

func (h *TestHarness) FlowAction(key string, req FlowActionRequest) (int, FlowActionResponse, error)

FlowAction calls a plugin flow action route with X-Ether-Idempotency-Key.

func (*TestHarness) Health

func (h *TestHarness) Health() (int, HealthResponse, error)

Health calls GET /ether/health.

func (*TestHarness) Manifest

func (h *TestHarness) Manifest() (Manifest, error)

Manifest fetches and decodes GET /manifest.json.

func (*TestHarness) Markers

func (h *TestHarness) Markers(typ, id string) (int, MarkersResponse, error)

Markers calls GET /ether/markers/{type}/{id}.json.

func (*TestHarness) Meta

func (h *TestHarness) Meta(typ, id string) (int, MetaResponse, error)

Meta calls GET /meta/{type}/{id}.json.

func (*TestHarness) Options

func (h *TestHarness) Options(field string) (int, []FieldOption, error)

Options calls GET /ether/options/{field}.

func (*TestHarness) Request

func (h *TestHarness) Request(req RawRequest) RawResponse

Request dispatches a RawRequest against the plugin.

func (*TestHarness) Stream

func (h *TestHarness) Stream(typ, id string, extra map[string]string) (int, StreamResponse, error)

Stream calls GET /stream/{type}/{id}[/{extra}].json.

func (*TestHarness) Subtitles

func (h *TestHarness) Subtitles(typ, id, pickToken string, extra map[string]string) (int, SubtitlesResponse, RawResponse)

Subtitles calls GET /subtitles/{type}/{id}[/{extra}].json with optional pickToken.

func (*TestHarness) Test

func (h *TestHarness) Test() (int, TestResponse, error)

Test calls POST /ether/test.

func (*TestHarness) Tool

func (h *TestHarness) Tool(name string, input map[string]any) (int, ToolResponse, error)

Tool calls POST /ether/tool/{name}.

func (*TestHarness) View

func (h *TestHarness) View(page string, query map[string]string) (int, ViewResponse, error)

View calls GET /ether/view/{page} and validates the returned ViewSpecDocument.

type TestResponse

type TestResponse struct {
	OK      bool     `json:"ok"`
	Message string   `json:"message,omitempty"`
	Details []string `json:"details,omitempty"`
}

TestResponse is returned by a Test route handler.

type ToolMeta

type ToolMeta struct {
	Name        string         `json:"name"`
	Title       string         `json:"title"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"inputSchema"`
	ReadOnly    bool           `json:"readOnly,omitempty"`
	Destructive bool           `json:"destructive,omitempty"`
	OpenWorld   bool           `json:"openWorld,omitempty"`
}

ToolMeta describes an agent tool contributed by a plugin.

type ToolRequest

type ToolRequest struct {
	Name  string         `json:"name"`
	Input map[string]any `json:"input"`
}

ToolRequest is passed to a Tool route handler.

type ToolResponse

type ToolResponse map[string]any

ToolResponse is returned by a Tool route handler.

type TrackHint

type TrackHint struct {
	Disc   int    `json:"disc,omitempty"`
	Number int    `json:"number,omitempty"`
	Title  string `json:"title,omitempty"`
}

TrackHint identifies one track inside a multi-track audio release or archive when exact inner filenames are unknown before opening.

type TunnelError

type TunnelError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

TunnelError carries an error payload inside a TunnelFrame.

type TunnelFrame

type TunnelFrame struct {
	Type          string              `json:"type"`
	ID            string              `json:"id,omitempty"`
	RequestID     string              `json:"requestId,omitempty"`
	Protocol      string              `json:"protocol,omitempty"`
	Plugin        string              `json:"plugin,omitempty"`
	PluginID      string              `json:"pluginId,omitempty"`
	ConnectionID  string              `json:"connectionId,omitempty"`
	Features      []string            `json:"features,omitempty"`
	MaxChunkBytes int                 `json:"maxChunkBytes,omitempty"`
	Method        string              `json:"method,omitempty"`
	Path          string              `json:"path,omitempty"`
	Query         map[string][]string `json:"query,omitempty"`
	Headers       map[string][]string `json:"headers,omitempty"`
	Body          string              `json:"body,omitempty"`
	Data          string              `json:"data,omitempty"`
	Status        int                 `json:"status,omitempty"`
	Deadline      string              `json:"deadline,omitempty"`
	Error         *TunnelError        `json:"error,omitempty"`
}

TunnelFrame is one JSON message sent or received over the `ether-tunnel-v1` WebSocket.

type UsenetCheckResult

type UsenetCheckResult struct {
	Available bool `json:"available"`
	Checked   int  `json:"checked"`
	Missing   int  `json:"missing"`
	// Cached is true when this verdict came from Ether's bounded per-NZB
	// cache (including a recorded playback failure) rather than a fresh
	// NNTP check on this call.
	Cached bool `json:"cached,omitempty"`
	// PlaybackFailed is true when a prior real playback attempt against this
	// NZB failed with an article or release error.
	PlaybackFailed bool `json:"playbackFailed,omitempty"`
	// Reason carries a short diagnostic code when Available is false.
	Reason string `json:"reason,omitempty"`
	// CheckedAt is the Unix timestamp (seconds) when this verdict or
	// playback failure was recorded.
	CheckedAt int64 `json:"checkedAt,omitempty"`
}

UsenetCheckResult reports the sampled article availability verdict for one Usenet NZB release (usenet_check).

type ViewRequest

type ViewRequest struct {
	Page  string            `json:"page"`
	Query map[string]string `json:"query"`
}

ViewRequest is passed to a View route handler.

type ViewResponse

type ViewResponse struct {
	Spec ViewSpecDocument `json:"spec"`
	Data map[string]any   `json:"data"`
}

ViewResponse is returned by a View route handler.

type ViewSpecDocument

type ViewSpecDocument struct {
	SpecVersion int              `json:"specVersion"`
	Layout      string           `json:"layout"`
	Route       string           `json:"route,omitempty"`
	Header      []map[string]any `json:"header"`
	Body        []map[string]any `json:"body"`
}

ViewSpecDocument is a declarative ViewSpec v1 page specification.

type ViewerPermissions

type ViewerPermissions struct {
	Identity        string `json:"identity,omitempty"`
	WatchHistory    string `json:"watch_history,omitempty"`
	WriteWatchState string `json:"write_watch_state,omitempty"`
}

ViewerPermissions scopes viewer identity and watch-history access.

type ViewerWatchEntry

type ViewerWatchEntry struct {
	TitleID   string `json:"titleId"`
	Title     string `json:"title,omitempty"`
	WatchedAt string `json:"watchedAt,omitempty"`
	Completed bool   `json:"completed,omitempty"`
}

ViewerWatchEntry is one watch-history entry returned by Host.ViewerHistory.

type VolumeRef

type VolumeRef struct {
	URL                   string            `json:"url,omitempty"`
	Headers               map[string]string `json:"headers,omitempty"`
	KeepHeadersOnRedirect []string          `json:"keepHeadersOnRedirect,omitempty"`
	BlobRef               string            `json:"blobRef,omitempty"`
	Size                  int64             `json:"size"`
}

VolumeRef locates one archive volume by URL or blob cache reference.

Directories

Path Synopsis
kit
archivex
Package archivex lists and reads members of zip-shaped containers (zip, cbz, epub) with the standard library only, so hosted builds stay possible.
Package archivex lists and reads members of zip-shaped containers (zip, cbz, epub) with the standard library only, so hosted builds stay possible.
feedparse
Package feedparse turns RSS, Atom and JSON Feed documents into kind items: one feed is usually one root item with entries as leaves.
Package feedparse turns RSS, Atom and JSON Feed documents into kind items: one feed is usually one root item with entries as leaves.
hints
Package hints marshals typed resolver hints for KindItem.Hints.
Package hints marshals typed resolver hints for KindItem.Hints.
metaparse
Package metaparse reads embedded metadata (EPUB OPF, ComicInfo.xml, ID3v2, FLAC Vorbis comments) into plain maps a provider can copy into KindItem fields.
Package metaparse reads embedded metadata (EPUB OPF, ComicInfo.xml, ID3v2, FLAC Vorbis comments) into plain maps a provider can copy into KindItem fields.
scrape
Package scrape fetches pages through Ether's host HTTP service (so the manifest network allowlist applies) and pulls text and links out of simple HTML.
Package scrape fetches pages through Ether's host HTTP service (so the manifest network allowlist applies) and pulls text and links out of simple HTML.

Jump to

Keyboard shortcuts

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