Table of Contents

Class PluginServer

Namespace
DotBoxD.Plugins
Assembly
DotBoxD.Plugins.dll

In-process server-extension convenience surface: register a batch kernel under a service contract, then obtain a typed proxy that invokes it request/response. Plugin-facing remote facades usually expose the same capability from the domain surface they extend.

public sealed class PluginServer : IDisposable
Inheritance
PluginServer
Implements
Inherited Members
Extension Methods

Properties

Events 

public PluginEventAdapterRegistry Events { get; }

Property Value

PluginEventAdapterRegistry

Hooks 

public HookRegistry Hooks { get; }

Property Value

HookRegistry

Kernels 

public KernelRegistry Kernels { get; }

Property Value

KernelRegistry

Subscriptions 

public SubscriptionRegistry Subscriptions { get; }

Property Value

SubscriptionRegistry

Methods

BindContext<T>(string, Action<T>?) 

public LiveContext<T> BindContext<T>(string name, Action<T>? initialize = null) where T : class

Parameters

name string
initialize Action<T>

Returns

LiveContext<T>

Type Parameters

T

BindValue<T>(string, T) 

public LiveValue<T> BindValue<T>(string name, T initialValue)

Parameters

name string
initialValue T

Returns

LiveValue<T>

Type Parameters

T

Create(IPluginMessageSink?, Action<SandboxHostBuilder>?, SandboxPolicy?, ExecutionMode, Action<SubscriptionDeliveryFault>?) 

public static PluginServer Create(IPluginMessageSink? messages, Action<SandboxHostBuilder>? configureHost, SandboxPolicy? defaultPolicy, ExecutionMode executionMode, Action<SubscriptionDeliveryFault>? onSubscriptionFault)

Parameters

messages IPluginMessageSink
configureHost Action<SandboxHostBuilder>
defaultPolicy SandboxPolicy
executionMode ExecutionMode
onSubscriptionFault Action<SubscriptionDeliveryFault>

Returns

PluginServer

Create(IPluginMessageSink?, Action<SandboxHostBuilder>?, SandboxPolicy?, ExecutionMode, Action<SubscriptionDeliveryFault>?, Action<ResultHookFault>?) 

public static PluginServer Create(IPluginMessageSink? messages = null, Action<SandboxHostBuilder>? configureHost = null, SandboxPolicy? defaultPolicy = null, ExecutionMode executionMode = ExecutionMode.Auto, Action<SubscriptionDeliveryFault>? onSubscriptionFault = null, Action<ResultHookFault>? onResultHookFault = null)

Parameters

messages IPluginMessageSink
configureHost Action<SandboxHostBuilder>
defaultPolicy SandboxPolicy
executionMode ExecutionMode
onSubscriptionFault Action<SubscriptionDeliveryFault>
onResultHookFault Action<ResultHookFault>

Returns

PluginServer

CreateSession()

Creates a new ownership session. Every kernel installed through the session is tagged with it as the owner, so no other session can replace or mutate it; disposing the session revokes and unregisters the kernels it owns. Use one session per untrusted connection.

public PluginSession CreateSession()

Returns

PluginSession

Dispose()

Releases the owned SandboxHost (compiled executable cache, generated load contexts, hotness state, and other host-owned execution resources) so a host that retires a plugin server (per tenant, world, test, or reload) can deterministically reclaim them through the public plugin API. After disposal the lifecycle entrypoints (InstallAsync(PluginPackage, SandboxPolicy?, CancellationToken), Uninstall(string)) throw ObjectDisposedException. Disposal is idempotent.

public void Dispose()

GetRequiredCapabilities(PluginPackage)

Analyzes a package against this server's registered host bindings and returns the concrete capabilities its verified module requires. Use this to build a least-privilege install policy from host-trusted binding metadata instead of trusting the package manifest.

public IReadOnlyList<string> GetRequiredCapabilities(PluginPackage package)

Parameters

package PluginPackage

Returns

IReadOnlyList<string>

InstallAsync(PluginPackage, SandboxPolicy?, CancellationToken) 

public ValueTask<InstalledKernel> InstallAsync(PluginPackage package, SandboxPolicy? policy = null, CancellationToken cancellationToken = default)

Parameters

package PluginPackage
policy SandboxPolicy
cancellationToken CancellationToken

Returns

ValueTask<InstalledKernel>

InstallPoolAsync(PluginPackage, int, SandboxPolicy?, CancellationToken) 

public ValueTask<InstalledKernelPool> InstallPoolAsync(PluginPackage package, int degreeOfParallelism, SandboxPolicy? policy = null, CancellationToken cancellationToken = default)

Parameters

package PluginPackage
degreeOfParallelism int
policy SandboxPolicy
cancellationToken CancellationToken

Returns

ValueTask<InstalledKernelPool>

InstallServerExtensionAsync(PluginPackage, SandboxPolicy?, CancellationToken)

Installs a server extension package: a kernel invoked request/response (via InvokeServerExtensionAsync(IReadOnlyList<SandboxValue>, CancellationToken)) rather than wired to an event. It is validated by DotBoxD.Plugins.Runtime.Rpc.RpcKernelPackageValidator because the manifest uses the existing rpcEntrypoint field and has no event subscription/contract.

public ValueTask<InstalledKernel> InstallServerExtensionAsync(PluginPackage package, SandboxPolicy? policy = null, CancellationToken cancellationToken = default)

Parameters

package PluginPackage
policy SandboxPolicy
cancellationToken CancellationToken

Returns

ValueTask<InstalledKernel>

RegisterEventAdapter<TEvent>(IPluginEventAdapter<TEvent>) 

public PluginServer RegisterEventAdapter<TEvent>(IPluginEventAdapter<TEvent> adapter)

Parameters

adapter IPluginEventAdapter<TEvent>

Returns

PluginServer

Type Parameters

TEvent

RegisterServerExtensionAsync<TService, TKernel>(SandboxPolicy?, CancellationToken)

Resolves TKernel's generated verified-IR package, installs it as a server extension, and binds the TService contract to it for ServerExtension<TService>().

public ValueTask<string> RegisterServerExtensionAsync<TService, TKernel>(SandboxPolicy? policy = null, CancellationToken cancellationToken = default) where TService : class where TKernel : class

Parameters

policy SandboxPolicy
cancellationToken CancellationToken

Returns

ValueTask<string>

Type Parameters

TService
TKernel

ServerExtension<TService>()

Returns a typed proxy implementing TService whose calls run the bound batch kernel request/response (arguments and results are marshaled to and from the sandbox). Throws if no extension was registered for the contract.

public TService ServerExtension<TService>() where TService : class

Returns

TService

Type Parameters

TService

Uninstall(string) 

public bool Uninstall(string pluginId)

Parameters

pluginId string

Returns

bool

UninstallPool(InstalledKernelPool) 

public bool UninstallPool(InstalledKernelPool pool)

Parameters

pool InstalledKernelPool

Returns

bool

WireHook(InstalledKernel, WireOptions?)

Wires an installed kernel into the hook pipeline for the event it subscribes to, selecting the terminal (Use / UseProjecting / UseResult / UseProjectingResult) from the kernel's trusted, recomputed classification. Replaces the per-event / per-terminal routing every host used to hand-write. The event is resolved by name from the registered adapters, so the host stays agnostic of plugin ids and event types. Throws when the subscribed event has no registered adapter.

public WireResult WireHook(InstalledKernel kernel, WireOptions? options = null)

Parameters

kernel InstalledKernel
options WireOptions

Returns

WireResult

Remarks

Opt-in convenience over public API: customize the routing decision via ClassifyOverride, build a custom by-name router on TryResolveErased(string, out IErasedPluginEventAdapter), or hand-write the equivalent directly with typed server.Hooks.On<TEvent>().Use(kernel) plus your own event-name → type dispatch.

WireSubscription(InstalledKernel, WireOptions?)

Wires an installed kernel into the subscription (fire-and-forget) pipeline for the event it subscribes to. A plain terminal is routed through IndexRegistry first (when supplied, UseIndex is set, and verified IR maps to indexed fields), falling back to the broad pipeline; a projecting terminal pushes to the plugin's native delegate. Result terminals are rejected — subscriptions have no result channel.

public WireResult WireSubscription(InstalledKernel kernel, WireOptions? options = null)

Parameters

kernel InstalledKernel
options WireOptions

Returns

WireResult

Remarks

Opt-in convenience; see WireHook(InstalledKernel, WireOptions?) for the customization seams and the hand-written equivalent (server.Subscriptions.On<TEvent>().Use(kernel)).