sock v0.3.1 — Adaptive I/O refactor

[hayabusa-cloud]

Introduction

• sock is a zero-allocation socket library for Go, providing TCP, UDP, Unix, SCTP, and raw socket types built directly on the zcall assembly syscall package. All sockets are created with SOCK_NONBLOCK and SOCK_CLOEXEC flags and return iofd.FD file descriptors for integration with io_uring async I/O. Address serialization is zero-allocation, encoding directly into kernel sockaddr structures without intermediate heap objects.
• The package implements an adaptive I/O model following the Three-Tier Progress Model (Strike-Spin-Adapt) with network-tuned backoff for deadline-based retry, and provides Linux-specific features including SO_ZEROCOPY, SCM_RIGHTS file descriptor passing, TCP_INFO diagnostics, multicast group management, and UDP batch operations via sendmmsg/recvmmsg.

Usage

TCP echo with adaptive I/O

// Server: listen on ephemeral port, accept with deadline-driven retry.
ln, _ := sock.ListenTCP4(&sock.TCPAddr{IP: sock.IPv4LoopBack})
defer ln.Close()
srvAddr := ln.Addr().(*sock.TCPAddr)

// Client: adaptive connect retries on EINPROGRESS until handshake completes.
go func() {
	dialer := sock.TCPDialer{Timeout: 3 * time.Second}
	client, _ := dialer.Dial4(nil, srvAddr)
	defer client.Close()
	client.SetWriteDeadline(time.Now().Add(2 * time.Second))
	client.Write([]byte("hello sock"))
	client.SetReadDeadline(time.Now().Add(2 * time.Second))
	var buf [64]byte
	n, _ := client.Read(buf[:])
	fmt.Println(string(buf[:n])) // "hello sock"
}()

// Accept with deadline activates Strike → Adapt → ErrTimedOut retry.
ln.SetDeadline(time.Now().Add(5 * time.Second))
conn, _ := ln.Accept()
defer conn.Close()
conn.SetDeadline(time.Now().Add(2 * time.Second))
var buf [64]byte
n, _ := conn.Read(buf[:])
conn.Write(buf[:n]) // echo back

UDP datagram exchange

// Server: bind unconnected UDP socket.
srv, _ := sock.ListenUDP4(&sock.UDPAddr{IP: sock.IPv4LoopBack})
defer srv.Close()
srvAddr := srv.LocalAddr().(*sock.UDPAddr)

// Client: bind and send datagram to server.
client, _ := sock.ListenUDP4(&sock.UDPAddr{IP: sock.IPv4LoopBack})
defer client.Close()
client.SetWriteDeadline(time.Now().Add(2 * time.Second))
client.WriteTo([]byte("hello udp"), srvAddr)

// Server: receive and echo back to sender.
var buf [512]byte
srv.SetReadDeadline(time.Now().Add(2 * time.Second))
n, from, _ := srv.ReadFrom(buf[:])
srv.SetWriteDeadline(time.Now().Add(2 * time.Second))
srv.WriteTo(buf[:n], from)

// Client: receive echo.
client.SetReadDeadline(time.Now().Add(2 * time.Second))
n, _, _ = client.ReadFrom(buf[:])
fmt.Println(string(buf[:n])) // "hello udp"

Highlights

This release refactors the adaptive I/O layer to handle ErrInterrupted (EINTR) uniformly across all operation types, splits Unix domain socket address encoding by platform for correctness on Linux versus BSD/Darwin, fixes SCTP_CONTEXT to use the correct sctp_assoc_value kernel structure, and adds a comprehensive examples package.

What's Changed

Bug Fixes

• SCTP_CONTEXT ABI: Fix Set/Get to use sctp_assoc_value structure instead of plain int, matching the Linux kernel ABI (fix: tighten edge-case contracts for Unix, SCTP, and adaptive I/O #29)
• Unix EOF semantics: Return io.EOF only for SOCK_STREAM; SOCK_DGRAM and SOCK_SEQPACKET now correctly return (0, nil) for empty messages (fix: tighten edge-case contracts for Unix, SCTP, and adaptive I/O #29)
• Unix WriteTo validation: Reject mismatched address networks with ErrAddressFamilyNotSupported (fix: tighten edge-case contracts for Unix, SCTP, and adaptive I/O #29)
• Unix network strings: Pass correct network string ("unix", "unixgram", "unixpacket") through decodeUnixAddr via new unixSocketNetwork helper (fix: tighten edge-case contracts for Unix, SCTP, and adaptive I/O #29)

Features

• Adaptive EINTR handling: Extract retryInterrupted helper to restart syscalls on EINTR; applied to all adaptive paths (read, write, accept) (fix: tighten edge-case contracts for Unix, SCTP, and adaptive I/O #29, fix: consolidate adaptive I/O EINTR retry logic #30)
• Adaptive message I/O: Add adaptiveReadMsg and adaptiveWriteMsg variants for UDP message operations (ReadFromUDP, WriteToUDP, ReadMsgUDP, WriteMsgUDP), replacing inline retry loops (fix: consolidate adaptive I/O EINTR retry logic #30)
• Examples package: Add examples/ with TCP client/server, UDP unicast/multicast, event loop, and stream helper examples as executable test files (feat: add user-facing TCP, UDP, and event-loop examples #28)

Improvements

• Unix sockaddr platform split: Split encoding/decoding into platform-specific files (sockaddr_unix_linux.go, sockaddr_unix_bsd.go) with encodeUnixSockaddrPath and unixSockaddrPath (fix: tighten edge-case contracts for Unix, SCTP, and adaptive I/O #29)
• Sockaddr conversion: Consolidate sockaddr-to-address conversion in TCP, UDP, SCTP, and raw socket dial/listen paths using SockaddrToTCPAddr, SockaddrToUDPAddr helpers (fix: tighten edge-case contracts for Unix, SCTP, and adaptive I/O #29)

Compatibility

• Go: 1.26+
• Platforms: Linux 6.18+ (recommended)

---

This discussion was created from the release sock v0.3.1 — Adaptive I/O refactor.