Skip to content

API Reference

Complete gRPC API documentation for the Virtufin WorkManager service.

Generated API Documentation

Table of Contents

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
Config IReadOnlyDictionary<string, string>? Optional worker-instance defaults, immutable after creation. Delivered to the worker on every incoming trigger CloudEvent as extension attributes (not process environment variables — safe across co-located workers). A worker's own payload field, when present, takes precedence over its Config fallback.
Tags IReadOnlyDictionary<string, string>? Optional initial resource tags for filtering/discovery

Returns: The newly created worker's ID.

Exceptions: - EngineNotFoundException: No engine registered for the MIME type.

LoadCode

Loads new code into an existing worker. The CodeSource is a discriminated union: pass a CodeSourceUrl or a CodeSourceContent depending on whether the new code is reachable at a URL or already in memory.

public async Task LoadCode(Guid id, CodeSource codeSource, CancellationToken cancellationToken = default)

Parameters:

Parameter Type Description
id Guid Worker ID
codeSource CodeSource CodeSourceUrl(url) or CodeSourceContent(bytes)
cancellationToken CancellationToken Optional cancellation token

Exceptions: - WorkerNotFoundException: Worker does not exist. - ArgumentException: Content is empty (CodeSourceContent) or URL is not absolute http/https (CodeSourceUrl).

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
Config Dictionary<string, string>? Worker-instance defaults set at creation (see CreateWorkerRequest.Config above)
Tags Dictionary<string, string>? Currently-set resource tags (filtering/discovery — not injected into engine)

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.

GetTag

Returns the current value of a single tag on a worker. Returns null if the tag is not set. Tags are resource metadata (NOT injected into the worker process) used for filtering and discovery.

public string? GetTag(Guid id, string key)
Parameter Type Description
id Guid Worker ID
key string The tag name

Returns: The current value, or null if unset.

GetTags

Returns a snapshot of all tags currently set on a worker.

public IReadOnlyDictionary<string, string> GetTags(Guid id)
Parameter Type Description
id Guid Worker ID

Returns: All current tag entries (possibly empty).

SetTag

Sets (or replaces) a single tag on a worker. Tags are resource metadata and do NOT affect engine execution.

public void SetTag(Guid id, string key, string value)
Parameter Type Description
id Guid Worker ID
key string Tag name
value string Tag value

SetTags

Replaces the worker's entire tag map with the supplied dictionary.

public void SetTags(Guid id, IDictionary<string, string> tags)
Parameter Type Description
id Guid Worker ID
tags IDictionary<string, string> New tag map (empty clears all)

Limits: Max 50 tags per worker, keys ≤ 128 chars, values ≤ 1024 chars.

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
}