gRPC Service API

The WebSocket Manager exposes a gRPC service defined in Protos/websocketmanager.proto. It also supports HTTP/JSON via gRPC transcoding.

Service Definition

service WebSocketManager {
  rpc Connect (ConnectRequest) returns (ConnectResponse) {
    option (google.api.http) = {
      post: "/v1/connections"
      body: "*"
    };
  };
  rpc List (ListRequest) returns (ListResponse) {
    option (google.api.http) = {
      get: "/v1/connections"
    };
  };
  rpc Disconnect (DisconnectRequest) returns (DisconnectResponse) {
    option (google.api.http) = {
      delete: "/v1/connections/{id}"
    };
  };
  rpc StartPublish (StartPublishRequest) returns (StartPublishResponse) {
    option (google.api.http) = {
      post: "/v1/connections/{id}/publish"
      body: "*"
    };
  };
  rpc StopPublish (StopPublishRequest) returns (StopPublishResponse) {
    option (google.api.http) = {
      post: "/v1/connections/{id}/stop-publish"
    };
  };
  rpc Send (SendRequest) returns (SendResponse) {
    option (google.api.http) = {
      post: "/v1/connections/{id}/send"
      body: "*"
    };
  };
  rpc SendRaw (SendRawRequest) returns (SendRawResponse) {
    option (google.api.http) = {
      post: "/v1/connections/{id}/send-raw"
      body: "*"
    };
  };
}

RPC Methods

Connect

Establishes a new WebSocket connection.

HTTP: POST /v1/connections

Request:

message ConnectRequest {
  string url = 1;
  bool auto_reconnect = 2;
}

Field	Type	Description
`url`	`string`	The WebSocket server URL (required)
`auto_reconnect`	`bool`	Whether to enable auto-reconnect on failure

Response:

message ConnectResponse {
  string id = 1;
  string status = 2;
}

Field	Type	Description
`id`	`string`	The unique connection ID
`status`	`string`	Connection status (e.g., "connected")

Error Responses: - InvalidArgument - URL is empty - Unknown - Connection failed

List

Retrieves all active WebSocket connections.

HTTP: GET /v1/connections

Request:

message ListRequest {
}

(empty request body)

Response:

message ListResponse {
  repeated WebSocketConnection connections = 1;
}

Field	Type	Description
`connections`	`repeated WebSocketConnection`	List of all active connections

WebSocketConnection Message:

message WebSocketConnection {
  string id = 1;
  string url = 2;
  string status = 3;
  string topic = 4;
  string instance_id = 5;
}

Field	Type	Description
`id`	`string`	Unique connection identifier
`url`	`string`	WebSocket server URL
`status`	`string`	Current status (disconnected, connecting, connected, reconnecting)
`topic`	`string`	Pub/sub topic for publishing (empty if not publishing)
`instance_id`	`string`	ID of the service instance that owns this connection

Disconnect

Disconnects and removes a WebSocket connection.

HTTP: DELETE /v1/connections/{id}

Request:

message DisconnectRequest {
  string id = 1;
}

Field	Type	Description
`id`	`string`	The connection ID to disconnect (required)

Response:

message DisconnectResponse {
}

(empty response)

Error Responses: - NotFound - Connection not found - FailedPrecondition - Not the owner of this connection

StartPublish

Configures a connection to publish messages to a Dapr pub/sub topic.

HTTP: POST /v1/connections/{id}/publish

Request:

message StartPublishRequest {
  string id = 1;
  string topic = 2;
}

Field	Type	Description
`id`	`string`	The connection ID (required)
`topic`	`string`	The Dapr pub/sub topic name (required)

Response:

message StartPublishResponse {
}

Error Responses: - NotFound - Connection not found - InvalidArgument - Topic is empty - FailedPrecondition - WebSocket is not connected - FailedPrecondition - Not the owner of this connection

StopPublish

Stops publishing messages for a connection.

HTTP: POST /v1/connections/{id}/stop-publish

Request:

message StopPublishRequest {
  string id = 1;
}

Field	Type	Description
`id`	`string`	The connection ID (required)

Response:

message StopPublishResponse {
}

Error Responses: - NotFound - Connection not found

Send

Sends a message and waits for a correlated response.

HTTP: POST /v1/connections/{id}/send

Request:

message SendRequest {
  string id = 1;
  string message = 2;
  int32 timeout_ms = 3;
}

Field	Type	Description
`id`	`string`	The connection ID (required)
`message`	`string`	The message to send (required)
`timeout_ms`	`int32`	Timeout in milliseconds to wait for response (required)

Response:

message SendResponse {
  string response = 1;
}

Field	Type	Description
`response`	`string`	The response message from the WebSocket server

Error Responses: - NotFound - Connection not found - FailedPrecondition - WebSocket is not connected - DeadlineExceeded - Request timed out - Unknown - Send operation failed

Implementation Detail: The message is wrapped with a correlation ID before sending. Responses are matched by extracting the correlation ID from the response JSON.

SendRaw

Sends a raw message without waiting for a response.

HTTP: POST /v1/connections/{id}/send-raw

Request:

message SendRawRequest {
  string id = 1;
  string message = 2;
}

Field	Type	Description
`id`	`string`	The connection ID (required)
`message`	`string`	The message to send (required)

Response:

message SendRawResponse {
}

Error Responses: - NotFound - Connection not found - FailedPrecondition - WebSocket is not connected - Unknown - Send operation failed

gRPC Error Handling

All methods return gRPC status codes with appropriate error messages:

Status Code	Condition
`OK`	Operation successful
`InvalidArgument`	Invalid request parameters (empty URL, empty topic)
`NotFound`	Connection not found
`FailedPrecondition`	Precondition failed (not connected, not owner)
`DeadlineExceeded`	Send/SendAndWait timeout
`Unknown`	Unexpected errors

Protocol Buffers Package

The service is defined in package virtufin:

package virtufin;
option csharp_namespace = "Virtufin.WebSocketManager.Protos";

HTTP to gRPC Mapping

All methods are accessible via both gRPC and HTTP/JSON using gRPC transcoding:

Method	HTTP	gRPC
Connect	`POST /v1/connections`	`WebSocketManager.Connect`
List	`GET /v1/connections`	`WebSocketManager.List`
Disconnect	`DELETE /v1/connections/{id}`	`WebSocketManager.Disconnect`
StartPublish	`POST /v1/connections/{id}/publish`	`WebSocketManager.StartPublish`
StopPublish	`POST /v1/connections/{id}/stop-publish`	`WebSocketManager.StopPublish`
Send	`POST /v1/connections/{id}/send`	`WebSocketManager.Send`
SendRaw	`POST /v1/connections/{id}/send-raw`	`WebSocketManager.SendRaw`

Generated C# Classes

The proto file generates the following classes in namespace Virtufin.WebSocketManager.Protos:

WebSocketManager.WebSocketManagerBase - Base class for service implementation
WebSocketManager.WebSocketManagerClient - Client for service invocation
WebSocketManager.WebSocketManagerServer - Server interface
Request/Response message classes: ConnectRequest, ConnectResponse, ListRequest, ListResponse, DisconnectRequest, DisconnectResponse, StartPublishRequest, StartPublishResponse, StopPublishRequest, StopPublishResponse, SendRequest, SendResponse, SendRawRequest, SendRawResponse