Lightning.Channels.Handler (Lightning v2.19.0-pre)

View Source

Philter handler that persists every proxied Channel request.

Lifecycle

Philter invokes three callbacks during the proxy lifecycle:

  1. handle_request_started — creates a ChannelRequest record synchronously. If the insert fails, the request is rejected with 503.

  2. handle_response_started — captures TTFB and response headers into handler state. May not be called — see below.

  3. handle_response_finished — creates a ChannelEvent and updates the ChannelRequest state.

Skipped handle_response_started

handle_response_started fires when the first response bytes arrive from the upstream (TTFB). If the upstream never sends a response, the callback is skipped entirely and handle_response_finished receives handler state from handle_request_started only — without ttfb_us, response_status, or response_headers.

This happens when:

  • DNS resolution fails (:nxdomain)
  • The upstream refuses the connection (:econnrefused)
  • The host or network is unreachable (:ehostunreach, :enetunreach)
  • The connection times out before any response (:connect_timeout)
  • The response times out before headers arrive (:timeout)
  • TLS handshake fails

All fields derived from handle_response_started are accessed via Map.get/2 with nil fallbacks, so this is safe. The classify_error/1 function translates known Philter error shapes into stable string identifiers for persistence.