Skip to main content

UTCP WebSocket Plugin

WebSocket communication protocol plugin for UTCP, enabling real-time bidirectional communication with maximum flexibility to support ANY WebSocket endpoint format.

Key Feature: Maximum Flexibility

The WebSocket plugin is designed to work with ANY existing WebSocket endpoint without modification.

Unlike other implementations that enforce specific message structures, this plugin:

  • ✅ No enforced request format: Use message templates with UTCP_ARG_arg_name_UTCP_ARG placeholders
  • ✅ No enforced response format: Returns raw responses by default
  • ✅ Works with existing endpoints: No need to modify your WebSocket servers
  • ✅ Flexible templating: Support dict or string message templates

This addresses the UTCP principle: "Talk to as many WebSocket endpoints as possible."

Features

  • ✅ Maximum Flexibility: Works with ANY WebSocket endpoint without modification
  • ✅ Flexible Message Templates: Dict or string templates with UTCP_ARG_arg_name_UTCP_ARG placeholders
  • ✅ No Enforced Structure: Send/receive messages in any format
  • ✅ Real-time Communication: Bidirectional WebSocket connections
  • ✅ Multiple Authentication: API Key, Basic Auth, and OAuth2 support
  • ✅ Connection Management: Keep-alive, reconnection, and connection pooling
  • ✅ Streaming Support: Both single-response and streaming execution
  • ✅ Security Enforced: WSS required (or ws://localhost for development); a redirect of the upgrade is never followed, and a manual discovered from a remote origin may not point tool calls or an OAuth2 token URL at loopback

Installation

pip install utcp-websocket

For development:

pip install -e plugins/communication_protocols/websocket

Quick Start

Basic Usage (No Template - Maximum Flexibility)

from utcp.utcp_client import UtcpClient

# Works with ANY WebSocket endpoint - just sends arguments as JSON
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "my_websocket",
        "call_template_type": "websocket",
        "url": "wss://api.example.com/ws"
    }]
})

# Sends: {"user_id": "123", "action": "getData"}
result = await client.call_tool("my_websocket.get_data", {
    "user_id": "123",
    "action": "getData"
})

With Message Template (Dict)

{
    "name": "formatted_ws",
    "call_template_type": "websocket",
    "url": "wss://api.example.com/ws",
    "message": {
        "type": "request",
        "action": "UTCP_ARG_action_UTCP_ARG",
        "params": {
            "user_id": "UTCP_ARG_user_id_UTCP_ARG",
            "query": "UTCP_ARG_query_UTCP_ARG"
        }
    }
}

Calling with {"action": "search", "user_id": "123", "query": "test"} sends:

{
  "type": "request",
  "action": "search",
  "params": {
    "user_id": "123",
    "query": "test"
  }
}

With Message Template (String)

{
    "name": "text_ws",
    "call_template_type": "websocket",
    "url": "wss://iot.example.com/ws",
    "message": "CMD:UTCP_ARG_command_UTCP_ARG;DEVICE:UTCP_ARG_device_id_UTCP_ARG;VALUE:UTCP_ARG_value_UTCP_ARG"
}

Calling with {"command": "SET_TEMP", "device_id": "dev123", "value": "25"} sends:

CMD:SET_TEMP;DEVICE:dev123;VALUE:25

Configuration Options

WebSocketCallTemplate Fields

Field Type Required Default Description
call_template_type string Yes "websocket" Must be "websocket"
url string Yes - WebSocket URL (wss:// or ws://localhost)
message string|dict No null Message template with UTCP_ARG_arg_name_UTCP_ARG placeholders
response_format string No null Expected response format ("json", "text", "raw")
protocol string No null WebSocket subprotocol
keep_alive boolean No true Enable persistent connection with heartbeat
timeout integer No 30 Timeout in seconds
headers object No null Static headers for handshake
header_fields array No null Tool arguments to map to headers
auth object No null Authentication configuration

Message Templating

No Template (Default - Maximum Flexibility)

If message is not specified, arguments are sent as-is in JSON format:

# Config
{"call_template_type": "websocket", "url": "wss://api.example.com/ws"}

# Call
await client.call_tool("ws.tool", {"foo": "bar", "baz": 123})

# Sends exactly:
{"foo": "bar", "baz": 123}

This works with any WebSocket endpoint that accepts JSON.

Dict Template

Use dict templates for structured messages:

{
    "message": {
        "jsonrpc": "2.0",
        "method": "UTCP_ARG_method_UTCP_ARG",
        "params": "UTCP_ARG_params_UTCP_ARG",
        "id": 1
    }
}

String Template

Use string templates for text-based protocols:

{
    "message": "GET UTCP_ARG_resource_UTCP_ARG HTTP/1.1\r\nHost: UTCP_ARG_host_UTCP_ARG\r\n\r\n"
}

Nested Templates

Templates work recursively in dicts and lists:

{
    "message": {
        "type": "command",
        "data": {
            "commands": ["UTCP_ARG_cmd1_UTCP_ARG", "UTCP_ARG_cmd2_UTCP_ARG"],
            "metadata": {
                "user": "UTCP_ARG_user_UTCP_ARG",
                "timestamp": "2025-01-01"
            }
        }
    }
}

Response Handling

No Format Specification (Default)

By default, responses are returned as-is (maximum flexibility):

# Returns whatever the WebSocket sends - could be JSON string, text, or binary
result = await client.call_tool("ws.tool", {...})

JSON Format

Parse responses as JSON:

{
    "call_template_type": "websocket",
    "url": "wss://api.example.com/ws",
    "response_format": "json"
}

Text Format

Return responses as text strings:

{
    "response_format": "text"
}

Raw Format

Return responses without any processing:

{
    "response_format": "raw"
}

Real-World Examples

Example 1: Stock Price WebSocket (No Template)

Works with existing stock APIs without modification:

{
    "name": "stocks",
    "call_template_type": "websocket",
    "url": "wss://stream.example.com/stocks",
    "auth": {
        "auth_type": "api_key",
        "api_key": "${STOCK_API_KEY}",
        "var_name": "Authorization",
        "location": "header"
    }
}

# Sends: {"symbol": "AAPL", "action": "subscribe"}
await client.call_tool("stocks.subscribe", {
    "symbol": "AAPL",
    "action": "subscribe"
})

Example 2: IoT Device Control (String Template)

{
    "name": "iot",
    "call_template_type": "websocket",
    "url": "wss://iot.example.com/devices",
    "message": "DEVICE:UTCP_ARG_device_id_UTCP_ARG CMD:UTCP_ARG_command_UTCP_ARG VAL:UTCP_ARG_value_UTCP_ARG"
}

# Sends: "DEVICE:light_01 CMD:SET_BRIGHTNESS VAL:75"
await client.call_tool("iot.control", {
    "device_id": "light_01",
    "command": "SET_BRIGHTNESS",
    "value": "75"
})

Example 3: JSON-RPC WebSocket (Dict Template)

{
    "name": "jsonrpc",
    "call_template_type": "websocket",
    "url": "wss://rpc.example.com/ws",
    "message": {
        "jsonrpc": "2.0",
        "method": "UTCP_ARG_method_UTCP_ARG",
        "params": "UTCP_ARG_params_UTCP_ARG",
        "id": 1
    },
    "response_format": "json"
}

# Sends: {"jsonrpc": "2.0", "method": "getUser", "params": "{\"id\": 123}", "id": 1}
# Note: params is stringified since it's a non-string value in the template
result = await client.call_tool("jsonrpc.call", {
    "method": "getUser",
    "params": {"id": 123}
})

Example 4: Chat Application (Dict Template)

{
    "name": "chat",
    "call_template_type": "websocket",
    "url": "wss://chat.example.com/ws",
    "message": {
        "type": "message",
        "channel": "UTCP_ARG_channel_UTCP_ARG",
        "user": "UTCP_ARG_user_UTCP_ARG",
        "text": "UTCP_ARG_text_UTCP_ARG",
        "timestamp": "{{now}}"
    }
}

Authentication

API Key Authentication

{
    "auth": {
        "auth_type": "api_key",
        "api_key": "${API_KEY}",
        "var_name": "Authorization",
        "location": "header"
    }
}

Basic Authentication

{
    "auth": {
        "auth_type": "basic",
        "username": "${USERNAME}",
        "password": "${PASSWORD}"
    }
}

OAuth2 Authentication

{
    "auth": {
        "auth_type": "oauth2",
        "client_id": "${CLIENT_ID}",
        "client_secret": "${CLIENT_SECRET}",
        "token_url": "https://auth.example.com/token",
        "scope": "read write"
    }
}

Streaming Responses

async for chunk in client.call_tool_streaming("ws.stream", {"query": "data"}):
    print(chunk)

Security

  • WSS Required: Production URLs must use wss:// for encrypted communication
  • Localhost Exception: ws://localhost and ws://127.0.0.1 allowed for development
  • Authentication: Full support for API Key, Basic Auth, and OAuth2
  • Token Caching: OAuth2 tokens are cached for reuse; refresh must be handled by the service or manual re-auth.

Best Practices

  1. Start Simple: Don't use message template unless your endpoint requires specific format
  2. Use WSS in Production: Always use wss:// for secure connections
  3. Set Appropriate Timeouts: Configure timeouts based on expected response times
  4. Test Without Template First: Try without message template to see if it works
  5. Add Template Only When Needed: Only add message template if endpoint requires specific structure

Comparison with Enforced Formats

Approach Flexibility Works with Existing Endpoints
UTCP WebSocket (This Plugin) ✅ Maximum ✅ Yes - works with any endpoint
Enforced request/response structure ❌ Limited ❌ No - requires endpoint modification
UTCP-specific message format ❌ Limited ❌ No - only works with UTCP servers

Testing

Run tests:

pytest plugins/communication_protocols/websocket/tests/ -v

With coverage:

pytest plugins/communication_protocols/websocket/tests/ --cov=utcp_websocket --cov-report=term-missing

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

License

Mozilla Public License 2.0 (MPL-2.0)

Metadata

Release files for utcp-websocket 1.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for utcp-websocket 1.2.1
File Size Uploaded Provenance Actions
utcp_websocket-1.2.1.tar.gz 29.4 kB Without provenance Details for utcp_websocket-1.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for utcp-websocket 1.2.1
File Interpreter ABI Platform Actions
utcp_websocket-1.2.1-py3-none-any.whl Python 3 none any Details for utcp_websocket-1.2.1-py3-none-any.whl

Total release size: 50.9 kB

Release files / utcp_websocket-1.2.1.tar.gz

Download URL utcp_websocket-1.2.1.tar.gz
Size 29.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a77972d301150d4e57b0c476dd5ed3bd82808ec92325b89b3b36cc0fd55c3b1f
BLAKE2b-256 checksum
How to use checksums
7402dd75bfe9b3a4f5ba2d7f10b72f4ddbbf566525d28231aa2bdd22e72271ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.5

Release files / utcp_websocket-1.2.1-py3-none-any.whl

Download URL utcp_websocket-1.2.1-py3-none-any.whl
Size 21.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
22efc1c4a6c7cc0ea2905ffeb7250512434b424b078fcfe7c585373f9836181d
BLAKE2b-256 checksum
How to use checksums
670bb9bbdfb7e8acc93e16f8c12498557b49ebbe9fb896fde7af2d347aac32ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.5

Security for utcp-websocket 1.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page