Add ELECTRIC_TCP_READ_TIMEOUT for the HTTP keep-alive idle timeout (#4716)

## What

Adds `ELECTRIC_TCP_READ_TIMEOUT` to configure ThousandIsland's
`read_timeout` (default 60s), which doubles as Bandit's HTTP keep-alive
idle timeout: connections that have waited this long for their next
request are closed. The option mirrors `ELECTRIC_TCP_SEND_TIMEOUT`
(human-readable duration) and threads through `tcp_read_timeout` →
`thousand_island_options/1`. Default is unchanged (`nil` →
ThousandIsland's 60s).

Includes a docs entry in `website/docs/sync/api/config.md` and a
changeset.

## Why

When Electric runs behind a connection-pooling proxy, the target's
keep-alive timeout must **exceed** the proxy's idle timeout. If it
doesn't, the proxy can reuse a pooled connection at the same moment
Bandit's idle timer closes it (the close is a bare FIN — nothing
announces it in-band), and the resulting TCP reset surfaces to clients
as an intermittent `502 Bad Gateway`.

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: alco

.changeset/tidy-donuts-brush.md

@@ -0,0 +1,9 @@
+---
+"@core/sync-service": patch
+---
+
+Add `ELECTRIC_TCP_READ_TIMEOUT` to configure the socket read / HTTP keep-alive
+idle timeout (ThousandIsland's `read_timeout`, default 60s). When Electric runs
+behind a connection-pooling proxy such as an AWS ALB, this must be set above
+the proxy's idle timeout — otherwise the proxy races Electric's unannounced
+idle close when reusing a pooled connection and clients see intermittent 502s.

packages/sync-service/config/runtime.exs

@@ -299,6 +299,8 @@ config :electric,
   handler_fullsweep_after: env!("ELECTRIC_TWEAKS_HANDLER_FULLSWEEP_AFTER", :integer, nil),
   tcp_send_timeout:
     env!("ELECTRIC_TCP_SEND_TIMEOUT", &Electric.Config.parse_human_readable_time!/1, nil),
+  tcp_read_timeout:
+    env!("ELECTRIC_TCP_READ_TIMEOUT", &Electric.Config.parse_human_readable_time!/1, nil),
   feature_flags: env!("ELECTRIC_FEATURE_FLAGS", &Electric.Config.parse_feature_flags/1, nil),
   manual_table_publishing?: env!("ELECTRIC_MANUAL_TABLE_PUBLISHING", :boolean, nil),
   publication_refresh_period:

packages/sync-service/lib/electric/application.ex

@@ -366,6 +366,12 @@ defmodule Electric.Application do
         send_timeout -> [send_timeout: send_timeout]
       end
 
+    read_timeout_opts =
+      case get_env(opts, :tcp_read_timeout) do
+        nil -> []
+        read_timeout -> [read_timeout: read_timeout]
+      end
+
     ipv6_opts =
       if get_env(opts, :listen_on_ipv6?) do
         [:inet6]
@@ -383,7 +389,7 @@ defmodule Electric.Application do
         n -> [genserver_options: [spawn_opt: [fullsweep_after: n]]]
       end
 
-    acceptor_opts ++ transport_opts ++ genserver_opts
+    acceptor_opts ++ read_timeout_opts ++ transport_opts ++ genserver_opts
   end
 
   defp cowboy_options(opts) do

packages/sync-service/lib/electric/config.ex

@@ -59,6 +59,13 @@ defmodule Electric.Config do
     long_poll_timeout: 20_000,
     http_api_num_acceptors: nil,
     tcp_send_timeout: :timer.seconds(30),
+    # Socket read/keep-alive timeout (ThousandIsland's read_timeout). Bandit reaps
+    # keep-alive connections that have been idle for this long. When Electric runs
+    # behind a connection-pooling proxy (ALB, nginx, etc.), this MUST exceed the
+    # proxy's idle timeout — otherwise the proxy races Bandit's unannounced close
+    # when reusing a pooled connection and surfaces the reset as a 502.
+    # nil keeps ThousandIsland's default (60s).
+    tcp_read_timeout: nil,
     cache_max_age: 60,
     cache_stale_age: 60 * 5,
     chunk_bytes_threshold: Electric.ShapeCache.LogChunker.default_chunk_size_threshold(),

packages/sync-service/test/electric/config_test.exs

@@ -51,6 +51,15 @@ defmodule Electric.ConfigTest do
       Electric.Application.api_server()
     end
 
+    test "api_server/1 maps tcp_read_timeout to a top-level ThousandIsland option" do
+      [{Bandit, bandit_opts}] = Electric.Application.api_server(tcp_read_timeout: 180_000)
+
+      assert bandit_opts[:thousand_island_options][:read_timeout] == 180_000
+
+      [{Bandit, default_opts}] = Electric.Application.api_server([])
+      refute Keyword.has_key?(default_opts[:thousand_island_options], :read_timeout)
+    end
+
     test "configuration/1", ctx do
       Electric.Application.configuration(
         Keyword.take(ctx.initial_config, [:replication_connection_opts])

website/docs/sync/api/config.md

@@ -285,6 +285,18 @@ This environment variable increases this timeout.
 
 </EnvVarConfig>
 
+### ELECTRIC_TCP_READ_TIMEOUT
+
+<EnvVarConfig
+    name="ELECTRIC_TCP_READ_TIMEOUT"
+    defaultValue="60s"
+    example="180s">
+Socket read timeout, which doubles as the HTTP keep-alive idle timeout: Electric closes a connection that has been waiting this long for its next request. Defaults to 60 seconds.
+
+When Electric runs behind a connection-pooling reverse proxy or load balancer (AWS ALB, nginx, etc.), set this **above** the proxy's idle timeout. If the proxy's timeout is longer, the proxy can reuse a pooled connection at the same moment Electric closes it, and the resulting TCP reset surfaces to clients as an intermittent `502 Bad Gateway`. For example, behind an AWS ALB with the default 60-second idle timeout, set `ELECTRIC_TCP_READ_TIMEOUT=120s`.
+
+</EnvVarConfig>
+
 ### ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD
 
 <EnvVarConfig