{"id":26596967,"url":"https://github.com/harmony-co/zuws","last_synced_at":"2025-07-12T15:09:14.802Z","repository":{"id":283869454,"uuid":"896962470","full_name":"harmony-co/zuws","owner":"harmony-co","description":"Opinionated zig bindings for uWebSockets","archived":false,"fork":false,"pushed_at":"2025-03-22T17:18:36.000Z","size":21,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-22T18:26:48.757Z","etag":null,"topics":["bindings","uwebsockets","zig","zig-library","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harmony-co.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}},"created_at":"2024-12-01T18:20:19.000Z","updated_at":"2025-03-22T17:18:39.000Z","dependencies_parsed_at":"2025-03-22T18:27:30.226Z","dependency_job_id":"edb5ab67-1d49-40cc-9f61-a8b41512f9f1","html_url":"https://github.com/harmony-co/zuws","commit_stats":null,"previous_names":["harmony-co/zuws"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmony-co%2Fzuws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmony-co%2Fzuws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmony-co%2Fzuws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmony-co%2Fzuws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harmony-co","download_url":"https://codeload.github.com/harmony-co/zuws/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245137279,"owners_count":20566726,"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":["bindings","uwebsockets","zig","zig-library","zig-package","ziglang"],"created_at":"2025-03-23T17:21:04.163Z","updated_at":"2025-07-12T15:09:14.796Z","avatar_url":"https://github.com/harmony-co.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zuws\n\nOpinionated zig bindings for [`uWebSockets`](https://github.com/uNetworking/uWebSockets).\n\n# Installation\n\nCurrently zig does not support nested submodules, the recommended way is to add zuws as a submodule.\n\n```sh\ngit submodule add git@github.com:harmony-co/zuws.git\n```\n\nIn your `build.zig.zon` file add the following:\n\n```zig\n.dependencies = .{\n    .zuws = .{\n        .path = \"zuws\", // or the path you saved zuws to\n    },\n},\n```\n\nAnd import it on your `build.zig` file:\n\n```zig\nconst zuws = b.dependency(\"zuws\", .{\n    .target = target,\n    .optimize = optimize,\n    .debug_logs = true,\n    .ssl = false,\n    .no_zlib = false,\n    .with_proxy = false,\n});\n\nexe.root_module.addImport(\"zuws\", zuws.module(\"zuws\"));\n```\n\n\u003e [!NOTE]\n\u003e The raw C bindings are available via `zuws.module(\"uws\")`\n\n# Usage\n\n```zig\nconst uws = @import(\"zuws\");\nconst App = uws.App;\nconst Request = uws.Request;\nconst Response = uws.Response;\n\npub fn main() !void {\n    const app: App = try .init();\n    defer app.deinit();\n\n    app.get(\"/hello\", hello);\n    app.listen(3000, null);\n    app.run();\n}\n\nfn hello(res: *Response, _: *Request) void {\n    const str = \"Hello World!\\n\";\n    res.end(str, false);\n}\n```\n\n## SSL support via BoringSSL\n\nEnabling ssl in `zuws` is as simple as passing `.ssl = true` to the build options, once enabled `App.init` will now ask for the options which can be found [here](https://github.com/uNetworking/uSockets/blob/182b7e4fe7211f98682772be3df89c71dc4884fa/src/libusockets.h#L127).\n\nYou can also check our [example](./examples/hello-world-ssl) for using ssl.\n\n# Grouping\n\nGrouping is not something provided by uws itself and instead is an abstraction we provide to aid developers.\n\nThe grouping API has a `comptime` and a `runtime` variant, most of the time you will want to use the `comptime` variant, but for the rare cases where adding routes at runtime dynamically is needed the functionality is there.\n\n## Creating groups at `comptime`\n\n```zig\nconst app: App = try .init();\ndefer app.deinit();\n\nconst my_group = App.Group.initComptime(\"/v1\")\n    .get(\"/example\", someHandler);\n\n// This will create the following route:\n// /v1/example\napp.comptimeGroup(my_group);\n```\n\n## Creating groups at `runtime`\n\n```zig\nconst app: App = try .init();\ndefer app.deinit();\n\nvar gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;\nconst allocator = gpa.allocator();\n\nvar my_group = App.Group.init(allocator, \"/v1\");\ntry my_group.get(\"/example\", someHandler);\n\n// This will create the following route:\n// /v1/example\ntry app.group(my_group);\n\n// We highly recommend you deinit the group\n// after you don't need it anymore\nmy_group.deinit();\n\n\n```\n\n## Combining groups together\n\nWe provide 2 different ways of combining groups together.\n\n### Grouping\n\n```zig\nconst app: App = try .init();\ndefer app.deinit();\n\nconst api = App.Group.initComptime(\"/api\");\nconst v1 = App.Group.initComptime(\"/v1\")\n    .get(\"/example\", someHandler);\n\n_ = api.group(v1);\n\n// This will create the following route:\n// /api/v1/example\napp.comptimeGroup(api);\n```\n\n### Merging\n\n```zig\nconst app: App = try .init();\ndefer app.deinit();\n\nconst v1 = App.Group.initComptime(\"/v1\")\n    .get(\"/example\", someHandler);\nconst v2 = App.Group.initComptime(\"/v2\");\n\n_ = v2.merge(v1);\n\n// This will create the following route:\n// /v2/example\napp.comptimeGroup(v2);\n```\n\n# Running the Examples\n\nTo run the provided examples in `zuws` you can clone the repository (don't forget to initialize the submodules), and run the following command:\n\n```zsh\nzig build example -- \u003cexample-name\u003e\n```\n\nYou can also generate the assembly of a specific example using the following:\n\n```zsh\nzig build example-asm -- \u003cexample-name\u003e\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharmony-co%2Fzuws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharmony-co%2Fzuws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharmony-co%2Fzuws/lists"}