API Reference

Complete gRPC API documentation for the Virtufin WorkManager service.

Generated API Documentation

• C# SDK Reference — Auto-generated docs for Virtufin.WorkManager and Virtufin.WorkManager.Client
• Python SDK Reference — Auto-generated docs for virtufin-workmanager package
• TypeScript SDK Reference — Auto-generated docs for TypeScript client

---

Table of Contents

• WorkManager Component
• IEngineRegistry
• WorkerRegistry
• Exceptions
• WorkerStatus Enum

---

WorkManager (Components/WorkManager.cs)

Main service component managing worker lifecycle, subscriptions, and processing.

CreateWorkerAsync

Creates a new worker without starting it. Call StartWorkerAsync to begin 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
}