Class GatewayClient

Namespace

Virtufin.Api.Client

Assembly

Virtufin.Api.Client.dll

Dynamic proxy for the API Gateway. Service names are accessed as properties, and backend RPC methods are called dynamically on the returned ServiceClient.

client.Gateway.workmanager triggers TryGetMember(GetMemberBinder, out object?), which creates or returns a cached ServiceClient for "workmanager". service.ListWorkers() triggers TryGetMember(GetMemberBinder, out object?), which returns a callable that invokes via the Gateway's InvokeJson RPC.

Provides service discovery, method listing, invocation, publishing, and streaming capabilities.

public class GatewayClient : DynamicObject, IDynamicMetaObjectProvider

Inheritance

object

DynamicObject

GatewayClient

Implements

IDynamicMetaObjectProvider

Inherited Members

DynamicObject.GetDynamicMemberNames()

DynamicObject.GetMetaObject(Expression)

DynamicObject.TryBinaryOperation(BinaryOperationBinder, object, out object)

DynamicObject.TryConvert(ConvertBinder, out object)

DynamicObject.TryCreateInstance(CreateInstanceBinder, object[], out object)

DynamicObject.TryDeleteIndex(DeleteIndexBinder, object[])

DynamicObject.TryDeleteMember(DeleteMemberBinder)

DynamicObject.TryGetIndex(GetIndexBinder, object[], out object)

DynamicObject.TryInvoke(InvokeBinder, object[], out object)

DynamicObject.TryInvokeMember(InvokeMemberBinder, object[], out object)

DynamicObject.TrySetIndex(SetIndexBinder, object[], object)

DynamicObject.TrySetMember(SetMemberBinder, object)

DynamicObject.TryUnaryOperation(UnaryOperationBinder, out object)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using var client = new ApiClient();
var workers = await client.Gateway.workmanager.ListWorkers();
// Equivalent to:
var workers = await client.InvokeAsync("workmanager", "ListWorkers");

Constructors

GatewayClient(GrpcChannel)

Creates a new GatewayClient with the specified gRPC channel.

public GatewayClient(GrpcChannel channel)

Parameters

channel GrpcChannel

The gRPC channel to use for communication.

Methods

DeleteStateAsync(string, string, bool, CancellationToken)

Deletes a state entry and broadcasts a delete event to subscribers asynchronously.

public Task<DeleteStateResponse> DeleteStateAsync(string service, string key, bool includeValue = false, CancellationToken cancellationToken = default)

Parameters

service string

The service name.

key string

The state key.

includeValue bool

If true, the last value is included in the state change event payload.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DeleteStateResponse>

DeleteStateResponse with success status.

GetAllStateAsync(string, CancellationToken)

Gets all state key-value pairs asynchronously for a service.

public Task<Dictionary<string, string>> GetAllStateAsync(string service, CancellationToken cancellationToken = default)

Parameters

service string

The service name.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<Dictionary<string, string>>

Dictionary of key-value pairs.

GetService(string)

Gets a client for a specific service.

public ServiceClient GetService(string name)

Parameters

name string

The service name.

Returns

ServiceClient

A ServiceClient for the service.

Remarks

ServiceClients are cached internally. Calling this method multiple times with the same service name returns the same cached instance.

GetStateAsync(string, string, CancellationToken)

Gets a single state value asynchronously by service and key.

public Task<(string Value, string Etag)> GetStateAsync(string service, string key, CancellationToken cancellationToken = default)

Parameters

service string

The service name.

key string

The state key.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<(string Value, string Etag)>

Tuple of (value, etag).

InvokeAsync(string, string, Dictionary<string, object?>?)

Invokes a method on a service asynchronously.

public Task<Dictionary<string, object?>> InvokeAsync(string service, string method, Dictionary<string, object?>? requestData = null)

Parameters

service string

The service name.

method string

The method name.

requestData Dictionary<string, object>

Optional request data as dictionary.

Returns

Task<Dictionary<string, object>>

The response as a dictionary.

Remarks

The polymorphic Dictionary<string, object?> payload is (de)serialized via Virtufin.Api.Client.GatewayClient.JsonOptions, which sets an explicit DefaultJsonTypeInfoResolver so reflection-based dispatch works regardless of the process-wide IsReflectionEnabledByDefault flag. See Virtufin.Api.Client.GatewayClient.JsonOptions for the AOT caveat.

Exceptions

InvalidOperationException

Thrown when the invocation fails.

ListMethodsAsync(string)

Lists all methods for a given service asynchronously.

public Task<List<Dictionary<string, object?>>> ListMethodsAsync(string service)

Parameters

service string

The service name.

Returns

Task<List<Dictionary<string, object>>>

List of method information dictionaries.

ListServicesAsync()

Lists all available services asynchronously.

public Task<List<string>> ListServicesAsync()

Returns

Task<List<string>>

List of service names.

PublishEventAsync(string, byte[], Dictionary<string, string>?, CancellationToken)

Publishes an event to a topic asynchronously.

public Task<PublishResponse> PublishEventAsync(string topic, byte[] data, Dictionary<string, string>? metadata = null, CancellationToken cancellationToken = default)

Parameters

topic string

The topic name.

data byte[]

The event data as bytes.

metadata Dictionary<string, string>

Optional metadata dictionary.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<PublishResponse>

PublishResponse with success status.

PublishWithResultAsync(string, byte[], string, TimeSpan?, Dictionary<string, string>?, string?, CancellationToken)

Publishes to a topic and waits for a correlated response on a reply topic. Implements the request-reply pattern over pub/sub using correlation IDs.

public Task<PubsubSubscribeResponse> PublishWithResultAsync(string topic, byte[] data, string replyTopic, TimeSpan? timeout = null, Dictionary<string, string>? metadata = null, string? correlationId = null, CancellationToken cancellationToken = default)

Parameters

topic string

The topic to publish the request to.

data byte[]

The request data as bytes.

replyTopic string

The topic to listen for responses on.

timeout TimeSpan?

Maximum time to wait for a response (default: 30s).

metadata Dictionary<string, string>

Optional additional metadata to include.

correlationId string

Optional correlation ID (auto-generated if null).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<PubsubSubscribeResponse>

The correlated PubsubSubscribeResponse.

Exceptions

TimeoutException

Thrown if no response arrives within the timeout.

SaveStateAsync(string, string, string, string?, bool, CancellationToken)

Saves state and broadcasts a change event to subscribers asynchronously.

public Task<SaveStateResponse> SaveStateAsync(string service, string key, string value, string? etag = null, bool includeValue = false, CancellationToken cancellationToken = default)

Parameters

service string

The service name.

key string

The state key.

value string

The state value.

etag string

Optional etag for concurrency.

includeValue bool

If true, the value is included in the state change event payload.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<SaveStateResponse>

SaveStateResponse with success status.

Subscribe(IEnumerable<string>?, IEnumerable<string>?, IEnumerable<string>?, CancellationToken)

Subscribes to events from specified services and topics.

public AsyncServerStreamingCall<TopicEventRequest> Subscribe(IEnumerable<string>? services = null, IEnumerable<string>? topics = null, IEnumerable<string>? eventTypes = null, CancellationToken cancellationToken = default)

Parameters

services IEnumerable<string>

List of service names to subscribe to (empty for all).

topics IEnumerable<string>

List of topics to subscribe to (empty for all).

eventTypes IEnumerable<string>

List of event types to subscribe to (empty for all).

cancellationToken CancellationToken

Cancellation token.

Returns

AsyncServerStreamingCall<TopicEventRequest>

The async call handle. Dispose to cancel subscription.

SubscribeAsync(IStreamEventHandler, IEnumerable<string>?, IEnumerable<string>?, IEnumerable<string>?, CancellationToken)

Subscribes to events with a handler callback.

public Task SubscribeAsync(IStreamEventHandler handler, IEnumerable<string>? services = null, IEnumerable<string>? topics = null, IEnumerable<string>? eventTypes = null, CancellationToken cancellationToken = default)

Parameters

handler IStreamEventHandler

Handler to receive events.

services IEnumerable<string>

Optional service filter.

topics IEnumerable<string>

Optional topic filter.

eventTypes IEnumerable<string>

Optional event type filter.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Task that completes when subscription is cancelled.

SubscribeToTopic(string, CancellationToken)

Subscribes to a pub/sub topic and streams events.

public AsyncServerStreamingCall<PubsubSubscribeResponse> SubscribeToTopic(string topic, CancellationToken cancellationToken = default)

Parameters

topic string

The topic name.

cancellationToken CancellationToken

Cancellation token.

Returns

AsyncServerStreamingCall<PubsubSubscribeResponse>

Async streaming call for PubsubSubscribeResponse. Dispose to cancel.

TryGetMember(GetMemberBinder, out object?)

Dynamic property access returns a ServiceClient for the named service.

public override bool TryGetMember(GetMemberBinder binder, out object? result)

Parameters

binder GetMemberBinder

result object

Returns

bool

UnsubscribeFromTopicAsync(string, CancellationToken)

Unsubscribes from a pub/sub topic.

public Task<UnsubscribeResponse> UnsubscribeFromTopicAsync(string subscriptionId, CancellationToken cancellationToken = default)

Parameters

subscriptionId string

The subscription ID to cancel.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<UnsubscribeResponse>

UnsubscribeResponse with success status.