API Reference
WorkManager (Components/WorkManager.cs)
Main service component managing worker lifecycle, subscriptions, and processing.
CreateWorkerAsync
Creates a new worker and starts processing.
public async Task<Guid> CreateWorkerAsync(CreateWorkerRequest request, CancellationToken cancellationToken = default)
Parameters:
| Parameter | Type | Description |
|---|---|---|
request |
CreateWorkerRequest |
Worker configuration |
cancellationToken |
CancellationToken |
Optional cancellation token |
CreateWorkerRequest:
| Field | Type | Description |
|---|---|---|
CodeSource |
CodeSource |
Source of worker code (CodeSourceUrl or CodeSourceContent) |
MimeType |
string |
MIME type (e.g., "text/x-python") |
Topic |
string |
Pub/sub topic to subscribe to |
Group |
string? |
Optional group for coordinated execution |
Returns: The newly created worker's ID.
Exceptions:
- EngineNotFoundException: No engine registered for the MIME type.
LoadCodeFromContent
Loads new code from inline content into an existing worker.
public async Task LoadCodeFromContent(Guid id, byte[] content, CancellationToken cancellationToken = default)
Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
Guid |
Worker ID |
content |
byte[] |
New code content (UTF-8 bytes) |
cancellationToken |
CancellationToken |
Optional cancellation token |
Exceptions:
- WorkerNotFoundException: Worker does not exist.
- ArgumentException: Content is empty.
LoadCodeFromUrl
Loads new code from a URL into an existing worker.
public async Task LoadCodeFromUrl(Guid id, Uri url, CancellationToken cancellationToken = default)
Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
Guid |
Worker ID |
url |
Uri |
Absolute HTTP or HTTPS URL |
cancellationToken |
CancellationToken |
Optional cancellation token |
Exceptions:
- WorkerNotFoundException: Worker does not exist.
- ArgumentException: URL is not absolute or has invalid scheme (not http/https).
DeleteWorkerAsync
Deletes a worker and its subscriptions.
public async Task DeleteWorkerAsync(Guid id, CancellationToken cancellationToken = default)
Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
Guid |
Worker ID |
cancellationToken |
CancellationToken |
Optional cancellation token |
Exceptions:
- WorkerNotFoundException: Worker does not exist.
StartWorkerAsync
Starts a stopped worker, resuming topic subscriptions and processing.
public async Task StartWorkerAsync(Guid id, CancellationToken cancellationToken = default)
Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
Guid |
Worker ID |
cancellationToken |
CancellationToken |
Optional cancellation token |
Exceptions:
- WorkerNotFoundException: Worker does not exist.
Notes: If worker is already running, this is a no-op.
StopWorkerAsync
Stops a running worker, pausing topic subscriptions and processing.
public async Task StopWorkerAsync(Guid id, CancellationToken cancellationToken = default)
Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
Guid |
Worker ID |
cancellationToken |
CancellationToken |
Optional cancellation token |
Exceptions:
- WorkerNotFoundException: Worker does not exist.
Notes: If worker is already stopped, this is a no-op.
ListWorkers
Lists all workers with their current status.
public IReadOnlyList<WorkerInfo> ListWorkers()
Returns: Read-only list of WorkerInfo records.
WorkerInfo fields:
| Field | Type | Description |
|-------|------|-------------|
| Id | Guid | Unique identifier |
| CodeSource | CodeSource | Original code source |
| MimeType | string | Content MIME type |
| Language | string | Programming language name |
| Topic | string | Subscribed topic |
| Group | string? | Coordination group |
| CreatedAt | DateTime | Creation timestamp |
| Status | WorkerStatus | Running or Stopped |
GetWorkerHistory
Gets the code change history for a worker.
public IReadOnlyList<HistoryEntry> GetWorkerHistory(Guid id)
Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
Guid |
Worker ID |
Returns: List of history entries (oldest first).
HistoryEntry fields:
| Field | Type | Description |
|-------|------|-------------|
| CodeSource | CodeSource | Code source at this point |
| CreatedAt | DateTime | When this version was loaded |
Exceptions:
- WorkerNotFoundException: Worker does not exist.
RecoverWorkersAsync
Recovers all workers from persistent state and resumes processing.
public async Task RecoverWorkersAsync(CancellationToken cancellationToken = default)
Parameters:
| Parameter | Type | Description |
|---|---|---|
cancellationToken |
CancellationToken |
Optional cancellation token |
Exceptions:
- EngineNotFoundException: An engine is missing for a recovered worker's MIME type.
Notes: All engines must be registered before calling this method.
RegisterEngine
Registers an engine to handle code execution for a specific content type.
public void RegisterEngine(ContentType contentType, string languageName, Func<IEngine> engineFactory)
Parameters:
| Parameter | Type | Description |
|---|---|---|
contentType |
ContentType |
Content type handled (e.g., new ContentType("text/x-python")) |
languageName |
string |
Human-readable language name |
engineFactory |
Func<IEngine> |
Factory function creating new engine instances |
Exceptions:
- InvalidOperationException: Engine already registered for this content type.
IEngineRegistry
Interface for engine registration and lookup.
Register
void Register(ContentType contentType, string languageName, Func<IEngine> engineFactory)
Unregister
bool Unregister(ContentType contentType)
Returns: true if an engine was unregistered; false if none existed.
GetEngine
IEngine? GetEngine(ContentType contentType)
Returns: New engine instance for the content type, or null if none registered.
ListEngines
IReadOnlyList<EngineInfo> ListEngines()
Returns: List of all registered engines with their MIME types and language names.
WorkerRegistry (Runtime/WorkerRegistry.cs)
In-memory worker storage.
Add
public void Add(Worker worker)
Exceptions:
- InvalidOperationException: Worker with same ID already exists.
Remove
public bool Remove(Guid id, out Worker? worker)
Returns: true if worker was removed; false if not found.
Get
public Worker? Get(Guid id)
Returns: Worker instance or null if not found.
GetAll
public IReadOnlyList<Worker> GetAll()
Returns: All registered workers.
Exists
public bool Exists(Guid id)
Returns: true if worker exists; false otherwise.
Exceptions
WorkerNotFoundException
Thrown when a worker operation targets a non-existent worker.
public sealed class WorkerNotFoundException : Exception
{
public Guid WorkerId { get; }
}
EngineNotFoundException
Thrown when no engine is registered for a requested MIME type.
public sealed class EngineNotFoundException : Exception
{
public string MimeType { get; }
}
WorkerStatus Enum
public enum WorkerStatus
{
Unspecified = 0,
Stopped = 1,
Running = 2
}