Skip to content

API Reference

The WebSocket Manager exposes a gRPC-based API defined in websocketmanager.proto. All endpoints are available over HTTP/2 with optional JSON transcoding support.

Generated API Documentation

Table of Contents

gRPC Endpoints

Method Type Description
Connect Unary Establish a new WebSocket connection
List Unary List all managed WebSocket connections
Disconnect Unary Disconnect and remove a connection
StartPublish Unary Start publishing messages to a Dapr topic
StopPublish Unary Stop publishing messages
Send Unary Send a message and wait for a correlated response
SendRaw Unary Send a message without waiting for a response

Messages

ConnectRequest

Request to establish a new WebSocket connection.

Field Type Description
url string WebSocket server URL to connect to (e.g., ws://localhost:8080)
auto_reconnect bool Automatically reconnect on connection failure
tags map<string, string> Optional resource tags for filtering/discovery

Response: ConnectResponse

ConnectResponse

Response returned after a successful connection.

Field Type Description
connection_id string Unique identifier for the established connection
status ConnectionStatus Current status of the connection

ListRequest

Field Type Description
filters repeated TagFilter Optional filters (AND semantics). Only connections matching ALL filter key-value pairs are returned. Empty = no filter.

Response: ListResponse

ListResponse

Field Type Description
connections repeated WebSocketConnection List of all WebSocket connections

WebSocketConnection

Represents a managed external WebSocket connection.

Field Type Description
id string Unique connection identifier
url string WebSocket server URL
status ConnectionStatus Current connection state
instance_id string Owning service instance ID
topic string Dapr pub/sub topic (when publishing)
tags map<string, string> Currently-set resource tags (filtering/discovery — not forwarded to remote websocket)
created_at google.protobuf.Timestamp Connection creation timestamp

DisconnectRequest

Field Type Description
id string ID of the connection to disconnect

Response: DisconnectResponse (empty)

StartPublishRequest

Field Type Description
id string Connection ID to start publishing for
topic string Dapr pub/sub topic name

Response: StartPublishResponse (empty)

StopPublishRequest

Field Type Description
id string Connection ID to stop publishing for

Response: StopPublishResponse (empty)

SendRequest

Sends a message through a WebSocket connection and waits for a correlated response.

Field Type Description
id string Connection ID to send through
message string Message payload
timeout_ms int32 Timeout in milliseconds for the response

Response: SendResponse

SendResponse

Field Type Description
response string Response from the WebSocket server

SendRawRequest

Sends a message without waiting for a correlating response.

Field Type Description
id string Connection ID to send through
message string Message payload

Response: SendRawResponse (empty)

Tag RPCs

RPC HTTP Description
SetTag POST /v1/connections/{id}/tags/{key} Set a single tag on a connection
GetTag GET /v1/connections/{id}/tags/{key} Get a single tag value
SetTags PUT /v1/connections/{id}/tags Replace all tags on a connection
GetTags GET /v1/connections/{id}/tags Get all tags for a connection

Tags are resource metadata used for filtering and discovery. They are NOT forwarded to the remote websocket server. Limits: 50 tags per connection, key ≤ 128 chars, value ≤ 1024 chars.

ListConnections accepts filters: repeated TagFilter { key, value } — only connections matching ALL filter entries are returned (AND semantics). Empty filters = no filtering.

Enums

ConnectionStatus

Value Description
UNKNOWN Unknown status
CONNECTING Connection attempt in progress
CONNECTED Connected and ready
DISCONNECTED Not connected
ERROR Connection error state

Usage Examples

gRPC (C#)

using Virtufin.WebSocketManager.Client;
using Grpc.Net.Client;

var channel = GrpcChannel.ForAddress("https://localhost:5002");
var client = new WebSocketManagerClient(channel);

var response = await client.ConnectAsync(new ConnectRequest
{
    Url = "ws://echo.websocket.org",
    AutoReconnect = true
});

Console.WriteLine($"Connected: {response.ConnectionId}");

await client.SendAsync(new SendRequest
{
    Id = response.ConnectionId,
    Message = "Hello WebSocket!",
    TimeoutMs = 5000
});

Python

from virtufin.websocketmanager.client import WebSocketManagerClient

async with WebSocketManagerClient(host="localhost", port=5002) as client:
    connection = await client.connect("ws://echo.websocket.org")
    print(f"Connected: {connection.connection_id}")

    response = await client.send(connection.connection_id, "Hello WebSocket!", timeout_ms=5000)
    print(f"Response: {response.response}")

TypeScript

import { createClient } from "@connectrpc/connect";
import { WebSocketManager } from "./generated/websocketmanager_pb.js";

const client = createClient(WebSocketManager, transport);

const response = await client.connect({
  url: "ws://echo.websocket.org",
  autoReconnect: true
});

console.log(`Connected: ${response.connectionId}`);

const sendResponse = await client.send({
  id: response.connectionId,
  message: "Hello WebSocket!",
  timeoutMs: 5000
});

HTTP/JSON Transcoded Endpoints

The following REST endpoints are available when JSON transcoding is enabled:

Method Path gRPC Equivalent
POST /v1/connect Connect
GET /v1/connections List
DELETE /v1/connections/{id} Disconnect
POST /v1/connections/{id}/publish StartPublish
DELETE /v1/connections/{id}/publish StopPublish
POST /v1/connections/{id}/send Send
POST /v1/connections/{id}/sendraw SendRaw

Error Handling

All gRPC methods return standard grpc::StatusCode values:

Status Scenario
NOT_FOUND Connection ID not found
INVALID_ARGUMENT Invalid URL or parameters
DEADLINE_EXCEEDED Send timed out waiting for response
UNAVAILABLE Server not reachable
ALREADY_EXISTS Connection already established
INTERNAL WebSocket protocol error