Stowage/bore
2
0
Fork 0
mirror of https://github.com/ekzhang/bore.git synced 2026-04-18 22:50:21 +00:00
Code Issues Projects Releases Packages Wiki Activity

Implement automatic client reconnection with exponential backoff and heartbeat timeout

Browse source 
- Add heartbeat timeout to client control connection using server heartbeats for dead connection detection
- Introduce exponential backoff with jitter for reconnection delays
- Add CLI flags: --no-reconnect to disable auto-reconnect, --max-reconnect-delay to configure backoff cap
- Classify authentication errors as fatal (never retried), all others retried automatically
- Configure TCP keepalive on control connections for OS-level dead connection detection
- Update documentation (README.md, CLAUDE.md) to describe reconnection behavior and new flags
- Add unit tests for backoff logic and error classification
This commit is contained in:
kfirfer 2026-02-17 14:35:36 +07:00
parent 042fa78742
commit a13e03372e
No known key found for this signature in database
GPG key ID: B2103FE1471D8A5E
9 changed files with 438 additions and 126 deletions
Download patch file Download diff file Expand all files Collapse all files

23
README.md
View file

@ -96,11 +96,13 @@ Arguments:
<LOCAL_PORT> The local port to expose [env: BORE_LOCAL_PORT=]
Options:
-l, --local-host <HOST> The local host to expose [default: localhost]
-t, --to <TO> Address of the remote server to expose local ports to [env: BORE_SERVER=]
-p, --port <PORT> Optional port on the remote server to select [default: 0]
-s, --secret <SECRET> Optional secret for authentication [env: BORE_SECRET]
-h, --help Print help
-l, --local-host <HOST> The local host to expose [default: localhost]
-t, --to <TO> Address of the remote server to expose local ports to [env: BORE_SERVER=]
-p, --port <PORT> Optional port on the remote server to select [default: 0]
-s, --secret <SECRET> Optional secret for authentication [env: BORE_SECRET]
--no-reconnect Disable automatic reconnection on connection loss
--max-reconnect-delay <SECONDS> Maximum delay between reconnection attempts [default: 64]
-h, --help Print help
```
### Self-Hosting
@ -139,6 +141,17 @@ Whenever the server obtains a connection on the remote port, it generates a secu
For correctness reasons and to avoid memory leaks, incoming connections are only stored by the server for up to 10 seconds before being discarded if the client does not accept them.
## Reconnection
By default, `bore` automatically reconnects to the server when the connection is lost (e.g., due to network interruptions). This makes it suitable for long-running deployments with service managers like systemd or launchd.
- **Automatic reconnection** is enabled by default with exponential backoff (1s, 2s, 4s, ... up to 64s max)
- **Authentication failures** (wrong secret) are never retried — the client exits immediately
- **`--no-reconnect`** disables automatic reconnection, restoring the legacy exit-on-disconnect behavior
- **`--max-reconnect-delay <SECONDS>`** configures the maximum backoff delay (default: 64 seconds)
Dead connections are detected via a heartbeat timeout: the server sends heartbeats every 500ms, and if no message is received within 8 seconds, the client treats the connection as dead and begins reconnecting. TCP keepalive is also configured as an additional safety net.
## Authentication
On a custom deployment of `bore server`, you can optionally require a _secret_ to prevent the server from being used by others. The protocol requires clients to verify possession of the secret on each TCP connection by answering random challenges in the form of HMAC codes. (This secret is only used for the initial handshake, and no further traffic is encrypted by default.)