{"id":28651830,"url":"https://github.com/Thomvanoorschot/async_zocket","last_synced_at":"2025-06-13T06:05:40.533Z","repository":{"id":285123295,"uuid":"957134236","full_name":"Thomvanoorschot/async_zocket","owner":"Thomvanoorschot","description":"This repository contains a basic, non-blocking WebSocket client written in the Zig programming language. It leverages the xev event loop for asynchronous operations and is able to run non-blocking on a single thread.","archived":false,"fork":false,"pushed_at":"2025-06-06T18:18:57.000Z","size":1417,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T19:29:35.358Z","etag":null,"topics":["async","eventloop","libuv","libxev","non-blocking","singlethread","tcp-client","websocket-client","websocket-server","websockets","wss","zig-package","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","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/Thomvanoorschot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"zenodo":null}},"created_at":"2025-03-29T16:30:13.000Z","updated_at":"2025-06-01T11:15:44.000Z","dependencies_parsed_at":"2025-03-29T17:31:35.072Z","dependency_job_id":"12141a34-cb24-421b-8514-f6caf003ea4d","html_url":"https://github.com/Thomvanoorschot/async_zocket","commit_stats":null,"previous_names":["thomvanoorschot/xevzocket","thomvanoorschot/async_zocket"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Thomvanoorschot/async_zocket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomvanoorschot%2Fasync_zocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomvanoorschot%2Fasync_zocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomvanoorschot%2Fasync_zocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomvanoorschot%2Fasync_zocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Thomvanoorschot","download_url":"https://codeload.github.com/Thomvanoorschot/async_zocket/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomvanoorschot%2Fasync_zocket/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259592260,"owners_count":22881265,"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":["async","eventloop","libuv","libxev","non-blocking","singlethread","tcp-client","websocket-client","websocket-server","websockets","wss","zig-package","ziglang"],"created_at":"2025-06-13T06:01:38.987Z","updated_at":"2025-06-13T06:05:40.526Z","avatar_url":"https://github.com/Thomvanoorschot.png","language":"Zig","funding_links":[],"categories":["Network \u0026 Web"],"sub_categories":["Network"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"Project Logo\" width=\"500\" /\u003e\n\u003c/p\u003e\n\n# AsyncZocket\n\n## Overview\n\nAsyncZocket is a comprehensive WebSocket library for the Zig programming language, providing both client and server implementations. Built on the `xev` event loop library for high-performance asynchronous I/O operations, it offers a robust foundation for real-time communication applications. The library supports the full WebSocket protocol (RFC 6455) and can handle multiple concurrent connections efficiently on a single thread.\n\n## Features\n\n### Core WebSocket Support\n*   **Full RFC 6455 Compliance:** Complete implementation of the WebSocket protocol specification\n*   **Frame Types:** Support for Text, Binary, Close, Ping, and Pong frames\n*   **Proper Masking:** Client-side frame masking and server-side unmasking\n*   **Control Frame Handling:** Automatic Ping/Pong responses and proper Close handshake\n\n### Client Implementation\n*   **Non-blocking Client:** Asynchronous WebSocket client with connection queuing\n*   **Connection Management:** Automatic reconnection and connection state tracking\n*   **Write Queuing:** Buffers write operations before connection establishment\n*   **Flexible Configuration:** Configurable host, port, and path parameters\n\n### Server Implementation\n*   **High-Performance Server:** Multi-client server with configurable connection limits\n*   **Connection Pooling:** Efficient management of concurrent client connections\n*   **Callback-Based API:** Event-driven architecture with customizable handlers\n\n### Technical Features\n*   **Asynchronous I/O:** Built entirely on `xev` for non-blocking operations\n*   **Memory Efficient:** Smart buffer management and connection pooling\n*   **Single-Threaded:** Efficient event-loop based concurrency model\n\n## Getting Started\n\n### Installation\n\nUse fetch:\n```\nzig fetch --save https://github.com/Thomvanoorschot/async_zocket/archive/main.tar.gz\n```\n\nOr add AsyncZocket to your `build.zig.zon`:\n\n```zig\n.dependencies = .{\n    .async_zocket = .{\n        .url = \"https://github.com/thomvanoorschot/async_zocket/archive/main.tar.gz\",\n        .hash = \"...\", // Update with actual hash\n    },\n},\n```\n\n### Basic Client Usage\n\n```zig\nconst std = @import(\"std\");\nconst AsyncZocket = @import(\"async_zocket\");\nconst xev = @import(\"xev\");\n\n// Initialize event loop\nvar loop = try xev.Loop.init(.{});\ndefer loop.deinit();\n\n// Define message callback\nconst wrapperStruct = struct {\n    const Self = @This();\n    fn read_callback(context: *anyopaque, payload: []const u8) !void {\n        // You can access the context by casting it to the correct type\n        // const self = @as(*Self, @ptrCast(context));\n        // self.read_callback(self.callback_context, payload);\n        std.log.info(\"read_callback: {s}\\n\", .{payload});\n        _ = context;\n    }\n};\nvar ws = wrapperStruct{};\n\n// Create and connect client\nvar client = try AsyncZocket.Client.init(\n    std.heap.page_allocator,\n    \u0026loop,\n    .{\n        .host = \"127.0.0.1\",\n        .port = 8080,\n        .path = \"/ws\",\n    },\n    wrapperStruct.read_callback,\n    @ptrCast(\u0026ws)\n);\n\ntry client.connect();\n\n// Send a message\ntry client.write(\"Hello, WebSocket!\");\n\n// Run event loop\ntry loop.run(.until_done);\n```\n\n### Basic Server Usage\n\n```zig\nconst std = @import(\"std\");\nconst AsyncZocket = @import(\"async_zocket\");\nconst xev = @import(\"xev\");\n\n// Initialize event loop\nvar loop = try xev.Loop.init(.{});\ndefer loop.deinit();\n\n// Define callbacks\nconst wrapperStruct = struct {\n    const Self = @This();\n    fn accept_callback(\n        _: ?*anyopaque,\n        _: *xev.Loop,\n        _: *xev.Completion,\n        cc: *ClientConnection,\n    ) xev.CallbackAction {\n        cc.read();\n        return .rearm;\n    }\n    fn read_callback(\n        context: ?*anyopaque,\n        payload: []const u8,\n    ) void {\n        _ = context;\n        std.log.info(\"read_callback: {s}\", .{payload});\n        std.heap.page_allocator.free(payload);\n    }\n};\nvar ws = wrapperStruct{};\n\n// Create and start server\nvar server = try AsyncZocket.Server.init(\n    std.heap.page_allocator,\n    \u0026loop,\n    .{\n        .address = try std.net.Address.parseIp4(\"127.0.0.1\", 8080),\n        .max_connections = 100,\n    },\n    @ptrCast(\u0026ws),\n    wrapperStruct.accept_callback,\n    wrapperStruct.read_callback,\n);\n\nserver.accept();\n\n// Run event loop\ntry loop.run(.until_done);\n```\n\n## API Reference\n\n### Client\n\n- `Client.init()` - Initialize a new WebSocket client\n- `client.connect()` - Connect to the WebSocket server\n- `client.write()` - Send a text message\n- `client.read()` - Start reading incoming messages\n- `client.deinit()` - Clean up client resources\n\n### Server\n\n- `Server.init()` - Initialize a new WebSocket server\n- `server.accept()` - Start accepting client connections\n- `server.returnConnection()` - Return a closed connection to the pool\n- `server.deinit()` - Clean up server resources\n\n### Configuration\n\n**ClientConfig:**\n- `host: []const u8` - Server hostname or IP address\n- `port: u16` - Server port number\n- `path: []const u8` - WebSocket endpoint path\n\n**ServerOptions:**\n- `address: std.net.Address` - Server bind address\n- `max_connections: u31` - Maximum concurrent connections (default: 1024)\n\n## Project Status\n\n🚀 **Production Ready** - The library implements a complete WebSocket solution with both client and server capabilities.\n\n**Implemented Features:**\n- ✅ Full WebSocket protocol (RFC 6455) compliance\n- ✅ Client and server implementations\n- ✅ All frame types (Text, Binary, Control frames)\n- ✅ Proper masking and unmasking\n- ✅ Connection management and pooling\n- ✅ Asynchronous I/O with xev\n\n**Upcoming Features:**\n- 🔄 Fragmented message support\n- 🔄 SSL/TLS support (WSS)\n\n## Requirements\n\n- **Zig 0.15.0-dev** or later\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests, report bugs, or suggest features.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FThomvanoorschot%2Fasync_zocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FThomvanoorschot%2Fasync_zocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FThomvanoorschot%2Fasync_zocket/lists"}