网络调用链的超时设置经常被当成单个服务的独立参数，但如果站在整条链路看，上游超时和下游超时之间存在严格的约束关系：下游的超时时间必须小于上游剩余可等待时间。Ruby服务在接入HTTP API、数据库、缓存或远程过程调用时，如果没有主动计算剩余超时并传递给下游，就可能出现上游已经超时返回、下游仍在执行的情况。这个问题不是Ruby独有，只是Ruby生态里的很多HTTP客户端默认不会自动传播截止时间，需要开发者在代码里显式处理。

一、超时传播的核心：剩余时间预算

在一个典型调用链中，上游服务通常给本次请求设置一个总超时，例如3秒。这个总超时是从上游接收到客户端请求开始，到它必须给出响应的最长时间。当上游调用下游API时，不能把整个3秒都分配给下游，因为上游还需要时间处理参数、记录日志、处理响应等。若下游超时配置为3秒或更长，上游可能在第3秒就向客户端返回超时，但下游服务仍在执行。服务器端并不会因为客户端断开就自动终止业务线程，尤其Ruby应用如果使用Puma等多线程模型，该线程会继续持有连接和内存，直到自然完成或达到自己的超时。

这种下游超时大于上游剩余时间的情况会带来至少三类后果：一是连接池被无效请求占满；二是写操作可能在上游已经认为失败后提交，造成结果不一致；三是级联放大长尾延迟。原因还在于大多数Ruby HTTP客户端把超时拆成open_timeout、read_timeout、write_timeout，它们表示的是单个socket操作等待时间，而不是整个请求的生命周期。比如read_timeout设置为5秒，指的是每次等待TCP包到达的最长间隔，而不是请求必须在5秒内完成。如果服务端每4秒发送一个字节，请求可能跑30秒也不触发read_timeout。

因此，实现下游超时小于上游超时，不是简单把下游参数改小一个数字，而是要根据上游已经消耗的时间动态计算remaining等于total减去elapsed，并把remaining作为下游的硬截止时间。当remaining小于等于零时，不再发起调用。这个思路对应到更一般的超时传播机制，就是为请求维护一个deadline，每一次下游调用都从同一个deadline扣减时间。

二、Ruby中的时间计算与客户端配置

Ruby里计算耗时推荐用Process.clock_gettime(Process::CLOCK_MONOTONIC)，不要用Time.now。系统时间可能被NTP调整，出现时间回退，导致elapsed计算为负，进而错误地放大下游超时。单调时钟不受系统时间修改影响，更适合计算时间间隔。通过减法可以得到已经过去的秒数，再和上游总预算比较。下面是一个基于Net::HTTP的示例，它在发起请求前动态计算remaining，并给自身处理留出缓冲。

require 'net/http'
require 'uri'
def call_with_budget(url, upstream_timeout)
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + upstream_timeout
  uri = URI(url)
  http = Net::HTTP.new(uri.host, uri.port)
  if uri.scheme == 'https'
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
  end
  remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
  return if remaining <= 0
  # 给自身处理留出 100ms 缓冲，避免上游刚好超时
  downstream_timeout = remaining - 0.1
  downstream_timeout = 0.05 if downstream_timeout <= 0
  http.open_timeout = downstream_timeout
  http.read_timeout = downstream_timeout
  request = Net::HTTP::Get.new(uri.request_uri)
  http.request(request)
end

上面代码里的upstream_timeout是上游分配给本次调用的总预算，deadline是单调时钟下的截止点。每次真正发起HTTP请求前，都重新读取当前时间并计算remaining。减去100毫秒的缓冲是为了给Ruby进程调度、DNS解析、响应体读取后的处理留出时间，否则下游虽然按remaining设置超时，但上游可能已经因时间耗尽而断开。Net::HTTP的open_timeout和read_timeout都设置成downstream_timeout，这个值必然小于上游剩余时间，满足传播原则。

如果使用Faraday，可以在连接选项中根据剩余时间动态覆盖超时，不要只在初始化时设置一次。因为同一份连接或同一个客户端实例可能被多个上游请求复用，固定超时无法适应不同的剩余预算。下面是基于Faraday的简化写法，把超时塞进请求级options中。

require 'faraday'
class BudgetAwareClient
  def initialize(base_url)
    @conn = Faraday.new(url: base_url) do |f|
      f.adapter Faraday.default_adapter
    end
  end
  def get(path, upstream_timeout)
    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + upstream_timeout
    @conn.get(path) do |req|
      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
      return if remaining <= 0
      timeout = [remaining - 0.05, 0.05].max
      req.options.timeout = timeout
      req.options.open_timeout = timeout
    end
  end
end

Faraday的底层适配器会把这些值转换为对应HTTP库的超时参数。重点不是具体客户端，而是每次请求都动态计算，而不是在初始化时写死。如果项目里已经封装了统一的HTTP客户端，可以把deadline作为参数传入，避免调用方自己维护开始时间。

三、重试、连接池与异步任务中的超时传播

重试是超时传播最容易出错的场景。假设上游总预算2秒，第一次调用下游消耗了1.2秒后失败，如果重试时仍然设置2秒超时，那么本次链路的实际最长耗时可能变成2加1.2秒，已经大幅超过上游预期。正确做法是每次重试前重新计算remaining，并且只在remaining大于一个最小阈值时才重试，否则直接返回超时或降级。Ruby常见的retryable、faraday-retry等机制都可以在retry_if或自定义块里判断剩余时间。

异步任务和队列任务也要考虑超时传播。例如上游HTTP请求已经超时返回，但Ruby后台线程仍在执行一个耗时SQL或外部API写入。下游数据库查询可能没有设置statement_timeout，或者设置了5秒，而上游只等了2秒。此时数据库会继续占用锁、写入数据或消耗连接。虽然可以通过线程取消来尝试停止，但Ruby线程的kill和raise都不是安全的协作式取消，可能让代码停在ensure块以外的地方。更稳妥的方案是让下游资源本身有硬超时，例如PostgreSQL的statement_timeout、Redis的timeout、HTTP客户端的read_timeout，并且这些超时必须小于上游剩余时间。

连接池也会放大这个事故。如果每个超时请求都占着一个连接不释放，后续请求会堆积，最终表现为线程全部阻塞、健康检查失败。很多Ruby服务使用ActiveRecord的connection_pool，默认checkout_timeout是5秒，如果数据库查询没有超时，而HTTP上游已经断开，这些数据库连接被无效占用。排查这类问题时，可以记录请求进入时的deadline、每次下游调用前的remaining、调用后的elapsed，用结构化日志输出，方便定位是哪个下游没有遵守超时约束。

四、验证与压测：如何确认配置生效

单纯看配置值并不能证明超时传播正确，需要通过压测和故障注入验证。可以在测试环境设置一个慢接口，例如sleep 0.6秒后返回，把上游调用预算设为0.5秒，然后观察下游服务是否在约0.4秒左右收到客户端断开或错误，而不是继续执行完sleep。Ruby测试代码可以使用Rack模拟服务，记录实际处理耗时。下面脚本用WEBrick起一个慢服务，客户端用预算0.2秒调用，观察下游是否提前结束。

require 'webrick'
require 'net/http'
require 'uri'
server = WEBrick::HTTPServer.new(Port: 0, BindAddress: '127.0.0.1')
server.mount_proc('/slow') do |_req, res|
  sleep 1
  res.status = 200
  res.body = 'finished'
end
Thread.new { server.start }
port = server.config[:Port]
begin
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 0.2
  remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
  uri = URI("http://127.0.0.1:#{port}/slow")
  http = Net::HTTP.new(uri.host, uri.port)
  http.open_timeout = remaining
  http.read_timeout = remaining
  begin
    http.request(Net::HTTP::Get.new(uri.request_uri))
  rescue Net::ReadTimeout => e
    puts "client timeout after expected budget: #{e.class}"
  end
ensure
  server.shutdown
end

运行这段脚本时，客户端会在大约0.2秒时抛出Net::ReadTimeout，服务端的sleep 1仍会继续执行，但这正好验证了问题：如果服务端逻辑包含写操作，必须依赖服务端自身的超时或幂等机制来收敛。要让下游真正停下来，不能只靠客户端断开，还要把上游预算传导到服务端处理线程。常见的做法是服务端接收请求时也配置deadline，例如Web服务器如Puma的request_timeout参数、Rack middleware主动检查请求头里的剩余时间，或者数据库语句超时。

在Ruby服务中，可以通过自定义Rack middleware从请求头读取上游传递的剩余时间信息。虽然HTTP没有标准超时头，但可以在内部服务之间约定一个类似X-Request-Deadline的头，传递毫秒级时间戳或剩余毫秒。中间件解析后，把截止时间写入请求环境，后续数据库查询或下游HTTP调用都可以基于它计算剩余预算。这比只依赖Rack服务器自身的超时更精细，也能把超时原则贯穿到整个服务内部。