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

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

Empty request to list all managed connections.

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)
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)

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