{"id":6299,"library":"wslink","title":"wslink","description":"wslink is a Python/JavaScript library designed for robust communication over WebSockets. It facilitates easy bi-directional communication, supporting Remote Procedure Calls (RPC) from client to server and publish/subscribe patterns from server to client, including binary attachments. Maintained by Kitware, it is actively developed with a frequent release cadence, often driven by semantic versioning.","status":"active","version":"2.5.6","language":"en","source_language":"en","source_url":"https://github.com/Kitware/wslink","tags":["websocket","rpc","publish-subscribe","client-server","python","javascript"],"install":[{"cmd":"pip install wslink","lang":"bash","label":"Install wslink for Python server"}],"dependencies":[],"imports":[{"note":"Core class for defining a wslink RPC server.","symbol":"Server","correct":"from wslink import Server"},{"note":"Base class for handling WebSocket connections, typically subclassed for custom protocols.","symbol":"WslinkHandler","correct":"from wslink.websocket import WslinkHandler"},{"note":"Provides the RPC and pub/sub mechanisms for the wslink server.","symbol":"WslinkServerProtocol","correct":"from wslink.protocols import WslinkServerProtocol"},{"note":"Utility function to start the wslink WebSocket server.","symbol":"run_wslink","correct":"from wslink.websocket import run_wslink"}],"quickstart":{"code":"import asyncio\nimport logging\n\nfrom wslink import Server\nfrom wslink.websocket import WslinkHandler, run_wslink\nfrom wslink.protocols import WslinkServerProtocol\n\n# Configure logging for better visibility\nlogging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')\nlogger = logging.getLogger(__name__)\n\nclass MyProtocol(WslinkServerProtocol):\n    \"\"\"A simple protocol demonstrating RPC.\"\"\"\n\n    def initialize(self):\n        # Register this protocol for RPC calls\n        self.registerVtkWebProtocol(self)\n        logger.info(\"MyProtocol initialized.\")\n\n    @Server.expose(\"my.hello\")\n    def hello_world(self, name=\"World\"):\n        \"\"\"An RPC method that returns a greeting.\"\"\"\n        logger.info(f\"RPC 'my.hello' called with name='{name}'.\")\n        return f\"Hello, {name} from wslink!\"\n\n    @Server.expose(\"my.add\")\n    def add_numbers(self, a, b):\n        \"\"\"An RPC method that adds two numbers.\"\"\"\n        logger.info(f\"RPC 'my.add' called with a={a}, b={b}.\")\n        return a + b\n\nclass MyWslinkHandler(WslinkHandler):\n    \"\"\"Custom wslink handler to use our protocol.\"\"\"\n    protocol_class = MyProtocol\n\nasync def main():\n    # Set the host and port for the WebSocket server\n    host = \"127.0.0.1\"\n    port = 8080\n\n    logger.info(f\"Starting wslink server on ws://{host}:{port}\")\n    logger.info(\"Press Ctrl+C to stop the server.\")\n\n    # Run the wslink server\n    await run_wslink(\n        port=port,\n        host=host,\n        ws=MyWslinkHandler,\n        # Optionally, set a secret for client authentication:\n        # secret=os.environ.get('WSLINK_SECRET', 'your_default_secret')\n    )\n\nif __name__ == \"__main__\":\n    try:\n        asyncio.run(main())\n    except KeyboardInterrupt:\n        logger.info(\"Server stopped by user (KeyboardInterrupt).\")\n    except Exception as e:\n        logger.error(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions relying on `aiohttp` for transport (observed in `v2.x`)."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Use `pip install wslink` for your Python backend services. For web-based frontends, install the client library using `npm install @kitware/wslink`.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}