PluginRegistry
Context-owned capability registry. Removal aborts and drains calls before teardown.
class PluginRegistryContext-owned capability registry. Removal aborts and drains calls before teardown.
Constructors
constructor
constructor(
player: LegacyPlayerContext,
blocked: () => readonly string[] = ...,
hostId?: string,
)Create an independent host.
Parameters
| Name | Type | Description |
|---|---|---|
| player | LegacyPlayerContext | Structural source context. |
| blocked | () => readonly string[]Default: ... | Default disabled source IDs supplied by the owning Player. |
| hostId? | string | Owning deployment, absent in ordinary embedded execution. |
Properties
playerreadonly
readonly player: LegacyPlayerContextStructural source context.
Methods
defineProvider
defineProvider<K extends "playback.backend">(name: K): voidEnable a local singleton capability before setup. Source hosts do not enable playback providers.
Parameters
| Name | Type | Description |
|---|---|---|
| name | K | Provider capability name. |
Returns
void
providerSignal
providerSignal<K extends "playback.backend">(name: K): AbortSignal | undefinedRead the selected provider registration lifetime.
Parameters
| Name | Type | Description |
|---|---|---|
| name | K | Provider capability name. |
Returns
AbortSignal | undefined
Registration cancellation signal, absent for the default implementation.
selectProvider
selectProvider<K extends "playback.backend">(
name: K,
dispose: () => Promise<void>,
): ProviderMap[K] | undefinedSelect and seal a provider before resource initialization. Later replacement registrations fail.
Parameters
| Name | Type | Description |
|---|---|---|
| name | K | Provider capability name. |
| dispose | () => Promise<void> | Release owned framework resources before plugin teardown. |
Returns
ProviderMap[K] | undefined
The active implementation, or undefined for the framework default.
defineOperation
defineOperation<K extends keyof OperationMap>(
name: K,
policy: OperationMap[K]["policy"],
synchronous: boolean = false,
): voidDefine a declaration-merged operation before registering handlers.
Parameters
| Name | Type | Description |
|---|---|---|
| name | K | Operation name. |
| policy | OperationMap[K]["policy"] | Dispatch policy matching its contract. |
| synchronous | booleanDefault: false | Whether callbacks must complete before returning; required for interception. |
Returns
void
has
has(id: string, hostId?: string): booleanWhether an ID is reserved or active.
Parameters
| Name | Type | Description |
|---|---|---|
| id | string | Plugin ID. |
| hostId? | string | Optional deployment constraint. |
Returns
boolean
providers
providers(operation: keyof OperationMap): ProviderReference[]List active provider/deployment references in priority and registration order.
Parameters
| Name | Type | Description |
|---|---|---|
| operation | keyof OperationMap | Capability to inspect. |
Returns
ProviderReference[]
Unique eligible provider/deployment references.
hasHost
hasHost(hostId: string): booleanCheck whether a deployment has an owned registration.
Parameters
| Name | Type | Description |
|---|---|---|
| hostId | string | Deployment identity. |
Returns
boolean
describe
describe(
): {
id: string;
provides: "playback.backend"[];
operations: (keyof OperationMap)[];
protocols: string[];
priorities: {
[k: string]: number;
};
subscriptions: {
operation: keyof OperationMap;
priority: number;
guildIds: readonly string[] | undefined;
order: number;
}[];
}[]Advertise only active local operation handlers and supplied provider capabilities.
Returns
{
id: string;
provides: "playback.backend"[];
operations: (keyof OperationMap)[];
protocols: string[];
priorities: {
[k: string]: number;
};
subscriptions: {
operation: keyof OperationMap;
priority: number;
guildIds: readonly string[] | undefined;
order: number;
}[];
}[]
Serializable provider capability descriptions.
registerHost
registerHost(host: RemotePluginHostOptions, signal: AbortSignal = ...): Promise<void>Register all advertised providers from an existing HTTP deployment.
Parameters
| Name | Type | Description |
|---|---|---|
| host | RemotePluginHostOptions | Existing deployment and authentication. |
| signal | AbortSignalDefault: ... | Caller lifetime. |
Returns
Promise<void>
supportsProtocol
supportsProtocol(protocol: string, options: ExecuteOptions = {}): booleanWhether an active matching handler explicitly accepts a protocol.
Parameters
| Name | Type | Description |
|---|---|---|
| protocol | string | Query prefix without punctuation. |
| options | ExecuteOptionsDefault: {} | Source targeting and block list. |
Returns
boolean
protocolMatches
protocolMatches(
protocol: string,
options: ExecuteOptions = {},
): {
pluginId: string;
hostId: string | undefined;
score: number;
}[]Ordered owners of a custom query protocol.
Parameters
| Name | Type | Description |
|---|---|---|
| protocol | string | Registered protocol prefix. |
| options | ExecuteOptionsDefault: {} | Targeting and block list. |
Returns
{
pluginId: string;
hostId: string | undefined;
score: number;
}[]
Eligible provider identities, in dispatch order.
register
register<O>(registration: PluginRegistration<O>): Promise<void>Register and initialize a source descriptor, reserving its ID synchronously.
Parameters
| Name | Type | Description |
|---|---|---|
| registration | PluginRegistration<O> | Descriptor produced by definePlugin. |
Returns
Promise<void>
unregister
unregister(id: string, hostId?: string): Promise<boolean>Abort new and active work, drain handlers, and release resources. Handlers must cooperate with cancellation.
Parameters
| Name | Type | Description |
|---|---|---|
| id | string | Plugin ID. |
| hostId? | string | Optional deployment identity when the provider exists on multiple hosts. |
Returns
Promise<boolean>
Whether the registration existed.
ready
destroy
destroy(): Promise<void>Destroy all registrations, attempting every cleanup even when one fails.
Returns
Promise<void>
hasCapability
hasCapability(operation: keyof OperationMap): booleanWhether an operation has active subscribers. Does not scan unrelated registrations.
Parameters
| Name | Type | Description |
|---|---|---|
| operation | keyof OperationMap | Capability name. |
Returns
boolean
Whether at least one active handler exists.
assertNotDispatching
assertNotDispatching(): voidReject reentrant application operations from synchronous capability handlers.
Returns
void
executeSync
executeSync<K extends keyof OperationMap>(
operation: K,
input: OperationInput<K>,
options: ExecuteOptions = {},
): OperationResult<K>Dispatch a synchronous local capability without scheduling promises.
Parameters
| Name | Type | Description |
|---|---|---|
| operation | K | Capability defined with synchronous execution. |
| input | OperationInput<K> | Validated operation payload. |
| options | ExecuteOptionsDefault: {} | Scope and cancellation constraints. |
Returns
OperationResult<K>
The selected result, or transformed input for pipe operations.
execute
execute<K extends keyof OperationMap>(
operation: K,
input: OperationInput<K>,
options: ExecuteOptions = {},
): Promise<OperationResult<K>>Execute using the operation's declared policy. Genuine failures reject immediately.
Parameters
| Name | Type | Description |
|---|---|---|
| operation | K | Typed operation name. |
| input | OperationInput<K> | Operation payload. |
| options | ExecuteOptionsDefault: {} | Target, block list and cancellation. |
serialize
serialize(
entity: Playlist | Track<unknown>,
options: ExecuteOptions = {},
): Promise<SerializedEntityUnion>Serialize using modern application-metadata transformations. Plain model serialization remains synchronous.
Parameters
| Name | Type | Description |
|---|---|---|
| entity | Playlist | Track<unknown> | Track or playlist to persist. |
| options | ExecuteOptionsDefault: {} | Cancellation and provider scope. |
Returns
Promise<SerializedEntityUnion>
A validated JSON persistence payload, without playback grants or live streams.
restore
restore(
payload: unknown,
options: ExecuteOptions = {},
): Promise<Playlist | Track<unknown>>Restore through modern metadata transformations and the existing schema validator.
Parameters
| Name | Type | Description |
|---|---|---|
| payload | unknown | Untrusted persistence payload. |
| options | ExecuteOptionsDefault: {} | Cancellation and provider scope. |
resolveStream
resolveStream(track: Track, options: StreamResolutionOptions = {}): Promise<MediaSource>Resolve and normalize a track for the already selected Remedia node.
Parameters
| Name | Type | Description |
|---|---|---|
| track | Track | Data model with a portable provider reference. |
| options | StreamResolutionOptionsDefault: {} | Target node mode and cancellation. |
Returns
Promise<MediaSource>