{"id":14963421,"url":"https://github.com/alekay-software/websocket-std","last_synced_at":"2025-10-25T02:30:38.287Z","repository":{"id":222720206,"uuid":"639023182","full_name":"alekay-software/websocket-std","owner":"alekay-software","description":"Websocket implementation in rust with std support and static library with ffi support.","archived":false,"fork":false,"pushed_at":"2025-02-09T12:54:26.000Z","size":1344,"stargazers_count":4,"open_issues_count":12,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-09T13:35:56.494Z","etag":null,"topics":["c","cargo","esp-rs","esp32","ffi","rust","websocket"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alekay-software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-10T15:37:49.000Z","updated_at":"2024-11-08T04:55:56.000Z","dependencies_parsed_at":"2024-09-13T19:14:59.168Z","dependency_job_id":"9bd28680-4049-4511-be0b-816bd205017d","html_url":"https://github.com/alekay-software/websocket-std","commit_stats":{"total_commits":15,"total_committers":3,"mean_commits":5.0,"dds":0.4,"last_synced_commit":"99dac0753ed240cbdc658469de26e8010b7cc595"},"previous_names":["alekay-software/websocket-std"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alekay-software%2Fwebsocket-std","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alekay-software%2Fwebsocket-std/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alekay-software%2Fwebsocket-std/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alekay-software%2Fwebsocket-std/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alekay-software","download_url":"https://codeload.github.com/alekay-software/websocket-std/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237957597,"owners_count":19393724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cargo","esp-rs","esp32","ffi","rust","websocket"],"created_at":"2024-09-24T13:31:28.973Z","updated_at":"2025-10-25T02:30:32.629Z","avatar_url":"https://github.com/alekay-software.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# websocket-std\n\nThis is a WebSocket implementation in Rust that utilizes the standard library. Its goal is to function on low-resource devices such as microcontrollers, although it can also be applied in high-performance computer programs. I started the project for three main reasons:\n- Learn rust.\n- Publish a library in crates.io.\n- How to use the library from other languages. \n\nThe project is currently in beta phase, and while it is functional, further work is needed for the final version. Since I am a sole developer and cannot dedicate as much time as I would like, I have decided to publish it for those who want to try it out and contribute to the project [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nYou can use the library in the following ways:\n\n- In any Rust project that allows the use of the standard library, such as ``esp-rs`` with ``std`` support. Check out the [esp-rs docs](https://esp-rs.github.io/book/overview/using-the-standard-library.html) for more information.\n- In any C project, as it has a compatible FFI (Foreign Function Interface). You’ll need to compile the project as a static library and link it appropriately. Refer to this guide ([static lib usage](./ffi/README.md)) for more details.\n\n**Feel free to explore the project and contribute! 🚀**\n\n---\n\n## Installation\n```toml\n[dependencies]\nwebsocket-std = \"0.0.6\"\n```\n\n## Static library\nIn the ``ffi/`` folder you will find the ``websocket-std.h`` header and a compiled static library for the xtensa architecture of the esp32 microcontroller from espressif.\n\nYou can use this static library in your esp idf and arduino projects for esp32. Check [ffi/xtensa-esp32-idf](./ffi/xtensa-esp32-espidf/README.md) for more information.\n\n## Examples\n\nThe [examples](./examples/) folder contains various examples of how to use ``websocket-std``.\n\n## Features\n\n### Sync Client\n\nThe sync client manage an internal event loop, when you call a function to perform a websocket operation (``init``, ``send``, ...)\nit will be queued and as soon as you call the ``event_loop`` function it will perform one input (something was received)\nand one output (something to send to server) operations in one execution.\n\nYou can also use ``threads`` to work with the library. Check [examples](./examples/) for more information.\n\n#### What works\n- Send text messages.\n- Handle received text messages.\n- Handle on connection events.\n- Handle on close events.\n- Work with websocket protocols.\n- Set the maximun length of the text that the websocket will send for each dataframe.\n\n#### Comming\n- Websocket over SSL.\n- Send and receive binary data.\n- Websocket extensions.\n\n### Sync Server\n\nI'm planning also to introduce in the library a ``sync server`` following the same philosophy as the sync client.\n\n---\n\n## MCUs Tested\n\n- ``ESP32`` using **esp-rs** with std support\n- ``ESP32`` using ``arduino`` framework in a ``PlatformIO`` project. (Should also work with esp-idf proyects).\n\n---\n\n# Test\n\nSince is my first rust big project I started using the following tools for testing and code coveragera, but I would like to\ndefine another way of doing that because the test coverage reports are not the bests. I'm open to hear better ways of doing testing in rust.\n\n## Execute all test\n\n\n```console\ncargo test\n```\n\n## Generate coverage report\n\n### Requirements\n\n#### Install ``grcov`` tool\n\n1. Install the llvm-tools or llvm-tools-preview component\n```console\nrustup component add llvm-tools-preview\n```\n\n2. Ensure that the following environment variable is set up\n```console\nexport RUSTFLAGS=\"-Cinstrument-coverage\"\n```\n\n3. Ensure each test runs gets its own profile information by defining the LLVM_PROFILE_FILE environment variable (%p will be replaced by the process ID, and %m by the binary signature)\n```console\nexport LLVM_PROFILE_FILE=\"websocket-std-%p-%m.profraw\"\n```\n\n4. Install grcov\n\n```console\ncargo install grcov\n```\n\n### Generate report\n\nEnsure that there isn't compilation or test errors.\n1. Build the code\n```console\ncargo build\n```\n\n2. Run tests and ensure that all are ``OK``\n```console\ncargo test\n```\n\n3. Be sure that the variables are exported. \n- RUSTFLAGS\n- LLVM_PROFILE_FILE\n\n4. Generate coverage report as HTML\n```console\ngrcov . --binary-path ./target/debug/deps/ -s . -t html --branch --ignore-not-existing --ignore '../*' --ignore \"/*\" -o target/coverage --excl-line grcov-excl-line\n```\n\nThe report will be generated at ``target/coverage/``, open ``index.html`` with a browser to see the results.\n\n---\n\n## Python websocket server\n\nSince the library doesn't have a way to create websocket servers, here you will find an echo server example in python to test\nthe client.\n\n### Requirements\n- pip install websockets==11.0.3\n\n### Code\n```python\nimport asyncio\nfrom websockets.server import serve\n\nHOST  = \"0.0.0.0\"\nPORT  = 3000\nprotocol = [\"superchat\", \"app\", \"chat\"]\n\nasync def echo(websocket):\n    async for message in websocket:\n        if websocket.open:\n            await websocket.send(message)\n\nasync def main():\n    async with serve(echo, HOST, PORT, subprotocols=protocol):\n        print(f\"Websocket server running on: {HOST}:{PORT}\")\n        await asyncio.Future()  # run forever\n\nasyncio.run(main())\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falekay-software%2Fwebsocket-std","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falekay-software%2Fwebsocket-std","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falekay-software%2Fwebsocket-std/lists"}