ocaml http/1, http/2 and websocket client and server library
fix(server): disable SO_REUSEPORT by default to prevent silent port conflicts
Previously reuse_port defaulted to true, allowing multiple processes to
bind the same port via SO_REUSEPORT. This caused confusing behavior where
a new server would start successfully but only receive a fraction of
connections (kernel load-balancing between processes).
Now reuse_port defaults to false. Binding to an already-used port fails
with a clear "Address already in use" error. Users who need SO_REUSEPORT
for intentional load balancing can enable it explicitly.
Bumps version to 0.2.1.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+66
-3
+46
CHANGELOG.md
+46
CHANGELOG.md
···
1
+
# Changelog
2
+
3
+
All notable changes to this project will be documented in this file.
4
+
5
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+
## [0.2.1] - 2026-01-04
9
+
10
+
### Fixed
11
+
12
+
- **Server port binding now fails correctly when port is already in use.** Previously, `reuse_port` defaulted to `true`, which enabled `SO_REUSEPORT` and allowed multiple processes to silently bind to the same port. This caused confusing behavior where a new server would start successfully but only receive a fraction of connections. Now `reuse_port` defaults to `false`, and binding to an already-used port will fail with a clear error.
13
+
14
+
### Changed
15
+
16
+
- `Server.default_config.reuse_port` now defaults to `false` instead of `true`.
17
+
- Users who intentionally want multiple processes sharing a port (for load balancing) can enable it explicitly via `{ config with reuse_port = true }`.
18
+
19
+
## [0.2.0] - 2026-01-03
20
+
21
+
### Added
22
+
23
+
- Phoenix-style three-layer plug architecture
24
+
- Pipeline module for reusable plug collections
25
+
- Endpoint module for global plug entry point
26
+
- Scoped authentication with `Plug.Auth` pipeline
27
+
28
+
### Changed
29
+
30
+
- Refactored plug system to match Phoenix conventions
31
+
- Improved router with per-route plug support
32
+
33
+
## [0.1.0] - Initial Release
34
+
35
+
### Added
36
+
37
+
- HTTP/1.1 and HTTP/2 client and server
38
+
- WebSocket support (RFC 6455)
39
+
- Server-Sent Events (SSE)
40
+
- Lock-free pub/sub messaging
41
+
- Connection pooling
42
+
- TLS support via tls-eio
43
+
- Static file serving
44
+
- Gzip/zstd compression
45
+
- CORS, CSRF, rate limiting plugs
46
+
- CLI tools: `hc` (client) and `hs` (file server)
+17
docs/getting-started/first-server.md
+17
docs/getting-started/first-server.md
···
104
104
| `with_protocol` | Http1_only | Protocol mode |
105
105
| `with_read_timeout` | 60.0 | Read timeout in seconds |
106
106
| `with_request_timeout` | 30.0 | Request processing timeout |
107
+
| `reuse_addr` | true | Set `SO_REUSEADDR` on listener socket |
108
+
| `reuse_port` | false | Set `SO_REUSEPORT` on listener socket |
109
+
110
+
### Socket Options
111
+
112
+
By default, `reuse_port` is disabled. If the port is already in use, the server will fail with an "Address already in use" error. This is the expected behavior for most use cases.
113
+
114
+
If you need multiple processes to share the same port (for load balancing), you can enable `SO_REUSEPORT`:
115
+
116
+
```ocaml
117
+
let config =
118
+
{ Hcs.Server.default_config with
119
+
port = 8080;
120
+
reuse_port = true }
121
+
```
122
+
123
+
With `reuse_port = true`, the kernel will distribute incoming connections across all processes bound to the same port.
107
124
108
125
## Protocol Modes
109
126
+1
-1
dune-project
+1
-1
dune-project
+1
-1
hcs.opam
+1
-1
hcs.opam
···
1
1
# This file is generated by dune, edit dune-project instead
2
2
opam-version: "2.0"
3
-
version: "0.2.0"
3
+
version: "0.2.1"
4
4
synopsis: "Eio based HTTP client/server library for OCaml 5+"
5
5
description:
6
6
"HCS is a HTTP client/server library for OCaml 5+ supporting HTTP/1.1, HTTP/2, and WebSocket. Built on Eio."