wslink

Warnings

• gotcha The wslink server may not reliably detect all forms of client disconnections (e.g., abrupt network loss). This can lead to `ConnectionResetError` exceptions in server logs or the server continuing to manage stale connections indefinitely, potentially impacting stability and resource usage.
  Fix: Implement robust client-side reconnection logic. On the server, consider implementing application-level heartbeats or more aggressive session timeout mechanisms. Monitor server logs for `ConnectionResetError` and potentially integrate graceful server restarts or more sophisticated session cleanup strategies.
• gotcha Protocol compatibility between the Python server and the JavaScript/C++ client is crucial. Mismatched `wslink` library versions or incompatible RPC method signatures between client and server can lead to communication failures or unexpected behavior.
  Fix: Ensure that the `wslink` library versions used on both the client and server sides are compatible. Always consult the official documentation and changelog when upgrading either component to verify protocol changes or API updates.
• gotcha This PyPI package (`wslink`) provides the Python server-side implementation. The corresponding client-side library for web browsers (JavaScript) is distributed separately via npm under the name `@kitware/wslink`. Attempting to use Python server modules directly in a browser environment or vice-versa will result in errors.
  Fix: Use `pip install wslink` for your Python backend services. For web-based frontends, install the client library using `npm install @kitware/wslink`.

Install

• pip install wslink Install wslink for Python server

Imports

• Server

  from wslink import Server

  Core class for defining a wslink RPC server.
• WslinkHandler

  from wslink.websocket import WslinkHandler

  Base class for handling WebSocket connections, typically subclassed for custom protocols.
• WslinkServerProtocol

  from wslink.protocols import WslinkServerProtocol

  Provides the RPC and pub/sub mechanisms for the wslink server.
• run_wslink

  from wslink.websocket import run_wslink

  Utility function to start the wslink WebSocket server.

Quickstart

This quickstart demonstrates how to create a basic `wslink` Python server with two Remote Procedure Call (RPC) methods: `my.hello` for greetings and `my.add` for adding numbers. It defines a custom protocol and handler, then uses `run_wslink` to start the server. Clients can connect via WebSocket to `ws://127.0.0.1:8080` and call the exposed methods.

import asyncio
import logging

from wslink import Server
from wslink.websocket import WslinkHandler, run_wslink
from wslink.protocols import WslinkServerProtocol

# Configure logging for better visibility
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logger = logging.getLogger(__name__)

class MyProtocol(WslinkServerProtocol):
    """A simple protocol demonstrating RPC."""

    def initialize(self):
        # Register this protocol for RPC calls
        self.registerVtkWebProtocol(self)
        logger.info("MyProtocol initialized.")

    @Server.expose("my.hello")
    def hello_world(self, name="World"):
        """An RPC method that returns a greeting."""
        logger.info(f"RPC 'my.hello' called with name='{name}'.")
        return f"Hello, {name} from wslink!"

    @Server.expose("my.add")
    def add_numbers(self, a, b):
        """An RPC method that adds two numbers."""
        logger.info(f"RPC 'my.add' called with a={a}, b={b}.")
        return a + b

class MyWslinkHandler(WslinkHandler):
    """Custom wslink handler to use our protocol."""
    protocol_class = MyProtocol

async def main():
    # Set the host and port for the WebSocket server
    host = "127.0.0.1"
    port = 8080

    logger.info(f"Starting wslink server on ws://{host}:{port}")
    logger.info("Press Ctrl+C to stop the server.")

    # Run the wslink server
    await run_wslink(
        port=port,
        host=host,
        ws=MyWslinkHandler,
        # Optionally, set a secret for client authentication:
        # secret=os.environ.get('WSLINK_SECRET', 'your_default_secret')
    )

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        logger.info("Server stopped by user (KeyboardInterrupt).")
    except Exception as e:
        logger.error(f"An unexpected error occurred: {e}")