From 0929fcb3d2b908666450f5856055f0717791c5a5 Mon Sep 17 00:00:00 2001 From: Karthic Raghupathi Date: Sat, 27 Jun 2026 19:32:28 -0400 Subject: [PATCH] docs(agi): document FastAGI hangup signaling --- doc/examples/fastagi.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/examples/fastagi.rst b/doc/examples/fastagi.rst index c6fa0fb..4a05d25 100644 --- a/doc/examples/fastagi.rst +++ b/doc/examples/fastagi.rst @@ -70,3 +70,31 @@ up:: time.sleep(1) fastagi_core.kill() + +Hangup signaling +---------------- + +Asterisk sends FastAGI hangup notifications over the same network connection used for command +responses. If ``HANGUP`` arrives while pystrix is waiting for a command response, pystrix consumes +that notification and continues reading the actual response from Asterisk. + +If a channel hangs up while a long-running application such as ``Dial`` is active, Asterisk may also +send a final ``HANGUP`` after the FastAGI handler has already returned and the socket has been +closed. On some Asterisk versions this can appear in the Asterisk console as an +``ast_carefulwrite`` ``Broken pipe`` error even though the FastAGI handler completed normally. + +Set ``AGISIGHUP`` before entering FastAGI if Asterisk should not send those hangup notifications:: + + exten => 97153654,1,Progress() + same => n,Set(AGISIGHUP=no) + same => n,AGI(agi://127.0.0.1/router) + +If Asterisk should instead stop AGI processing as soon as it detects the hangup, set +``AGIEXITONHANGUP`` before entering FastAGI; Asterisk closes the AGI connection itself in this +case:: + + exten => 97153654,1,Progress() + same => n,Set(AGIEXITONHANGUP=yes) + same => n,AGI(agi://127.0.0.1/router) + +A closed FastAGI connection is reported to pystrix as :class:`agi.AGISIGPIPEHangup`.