sharing-sockets-with-so-reuseport-in-zig
Skill2 starsChanged 8 months agoMITView on GitHub
Writes Zig code for sharing TCP/UDP sockets between unrelated processes using SO_REUSEPORT. Use when implementing multi-process socket sharing, zero-downtime restarts, load balancing across processes, or when user mentions SO_REUSEPORT, reuseport, socket sharing, or graceful restart in a Zig project.
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- building-lit-componentsSkill
- building-static-site-rss-feedsSkill
- building-templ-componentsSkill
- checking-wsh-vrtSkill
- committing-codeSkill
- creating-agent-skillsSkill
- creating-test-casesSkill
- deploying-with-isucon-ansibleSkill
- designing-isucon-architectureSkill
- frontend-designSkill
- operating-isucon-servers-via-sshSkill
- planning-wsh-improvementsSkill
- porting-isucon-rust-to-goSkill
- releasing-zig-with-goreleaserSkill
- running-isucon-as-an-agentSkill
- tuning-isucon-linux-and-nginxSkill
- using-go-tool-directiveSkill
- using-grafana-mcpSkill
- using-unocss-with-templSkill
- winning-isuconSkill
- winning-web-speed-hackathonSkill
- writing-feature-specSkill
- writing-implementation-tasksSkill
- writing-isucon-arch-subagent-tasksSkill
- writing-project-constitutionSkill
- writing-technical-designSkill
- writing-zig-cli-toolsSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Write Zig code that shares sockets between unrelated processes using SO_REUSEPORT.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Sharing Sockets with SO_REUSEPORT in Zig
Write Zig code that shares sockets between unrelated processes using SO_REUSEPORT. Use this skill when building multi-process servers, implementing zero-downtime deployments, or distributing connections across independent Zig processes.
Quick Start
Minimal SO_REUSEPORT TCP server in Zig -- each process independently binds to the same port:
const std = @import("std");
const posix = std.posix;
pub fn main() !void {
const address = try std.net.Address.parseIp("0.0.0.0", 8080);
const sockfd = try posix.socket(
posix.AF.INET,
posix.SOCK.STREAM | posix.SOCK.CLOEXEC,
posix.IPPROTO.TCP,
);
defer posix.close(sockfd);
// SO_REUSEPORT MUST be set BEFORE bind()
try posix.setsockopt(sockfd, posix.SOL.SOCKET, posix.SO.REUSEPORT, &std.mem.toBytes(@as(c_int, 1)));
try posix.setsockopt(sockfd, posix.SOL.SOCKET, posix.SO.REUSEADDR, &std.mem.toBytes(@as(c_int, 1)));
try posix.bind(sockfd, &address.any, address.getOsSockLen());
try posix.listen(sockfd, 128);
std.debug.print("Listening on :8080 (pid={})\n", .{std.os.linux.getpid()});
while (true) {
var client_addr: posix.sockaddr = undefined;
var addr_len: posix.socklen_t = @sizeOf(posix.sockaddr);
const client_fd = try posix.accept(sockfd, &client_addr, &addr_len, posix.SOCK.CLOEXEC);
defer posix.close(client_fd);
const response = "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK";
_ = try posix.write(client_fd, response);
}
}Compile and run multiple instances: each process independently accepts connections, kernel distributes via hash.
Critical Rules
SO_REUSEPORTbeforebind()-- mandatory ordering; setting after bind has no effect- ALL sockets must set
SO_REUSEPORT-- including the very first one; otherwise subsequent binds fail withEADDRINUSE - Same effective UID -- kernel enforces all processes in a reuseport group share the same EUID
- Use raw posix API --
std.net.Address.listen()withreuse_address = truesets bothSO_REUSEADDRandSO_REUSEPORT, but for explicit control useposix.setsockopt()directly
Zig Socket API Cheat Sheet
Option value conversion
posix.setsockopt() takes []const u8. Convert typed values:
// Integer options (c_int)
try posix.setsockopt(fd, posix.SOL.SOCKET, posix.SO.REUSEPORT,
&std.mem.toBytes(@as(c_int, 1)));
// Struct options
const timeout = posix.timeval{ .tv_sec = 5, .tv_usec = 0 }; // .sec/.usec in Zig 0.14+
try posix.setsockopt(fd, posix.SOL.SOCKET, posix.SO.RCVTIMEO,
std.mem.asBytes(&timeout));Key constants
| Constant | Path | Value (x86_64) |
SO.REUSEPORT | posix.SO.REUSEPORT | 15 |
SO.REUSEADDR | posix.SO.REUSEADDR | 2 |
SOL.SOCKET | posix.SOL.SOCKET | 1 |
AF.INET | posix.AF.INET | 2 |
SOCK.STREAM | posix.SOCK.STREAM | 1 |
SOCK.CLOEXEC | posix.SOCK.CLOEXEC | 0o2000000 |
Address creation
// From string
const addr = try std.net.Address.parseIp("0.0.0.0", 8080);
// From raw bytes
const addr = std.net.Address.initIp4(.{ 127, 0, 0, 1 }, 8080);
// Pass to bind: &addr.any and addr.getOsSockLen()Common Patterns
Zero-Downtime Restart
- New process starts, sets
SO_REUSEPORT, binds, listens -- joins existing reuseport group - Kernel splits incoming connections across old + new processes (hash-based)
- Signal old process to stop accepting (close listen fd)
- Old process drains in-flight requests, then exits
Gotcha: During listener count change, in-flight TCP handshakes may get RST'd (~2-3 per million connections). On Linux 5.14+, enable socket migration: sysctl net.ipv4.tcp_migrate_req=1.
High-Level API Alternative
const address = try std.net.Address.parseIp("0.0.0.0", 8080);
var server = try address.listen(.{
.reuse_address = true, // sets BOTH SO_REUSEADDR and SO_REUSEPORT
.kernel_backlog = 128,
});
defer server.deinit();
const conn = try server.accept(); // returns Server.ConnectionNote: reuse_address = true enables SO_REUSEPORT on Linux. This is a known naming inconsistency (see zig#24838).
Detailed References
- SO_REUSEPORT internals, security, eBPF steering: See SO_REUSEPORT.md
- Zig socket API details, raw syscalls, error handling: See ZIG-SOCKET-API.md
- Full code examples (multi-process server, graceful restart, UDP): See EXAMPLES.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

