Fix SSL shutdown timeout for streaming connections

[bdraco]

What do these changes do?

This PR addresses issue #11091 by adding a configurable ssl_shutdown_timeout parameter to control the SSL shutdown handshake timeout. This fixes the 30-second blocking issue when closing SSL connections, particularly affecting Azure Blob Storage streaming endpoints.

Problem

In aiohttp 3.12.4, users experience a 30-second delay when closing SSL connections to streaming endpoints (like Azure Blob Storage). The root cause is that the SSL shutdown handshake can timeout when the remote server doesn't respond to the shutdown notification, causing Python's asyncio to wait for the full default timeout period.

Solution

Added a new ssl_shutdown_timeout parameter with a default value of 0.1 seconds (100ms) to:

• TCPConnector - Controls the timeout passed to both:
  • loop.create_connection() for direct HTTPS connections (Python 3.11+ only)
  • loop.start_tls() for HTTPS proxy CONNECT tunnels (Python 3.11+ only)
• ClientSession - Convenience parameter that passes through to the connector

This provides a reasonable balance between:

1. Giving servers time to acknowledge the SSL shutdown (preventing "connection reset" errors)
2. Avoiding excessive delays during connection cleanup (fixing the 30-second block)

Note: The ssl_shutdown_timeout parameter only takes effect on Python 3.11+ where the asyncio SSL methods support this parameter. On earlier Python versions, the parameter is accepted but has no effect.

Changes

Core Implementation

• aiohttp/connector.py:
  • Added ssl_shutdown_timeout parameter to TCPConnector.__init__()
  • Modified _create_direct_connection() to unconditionally pass the timeout to loop.create_connection() for all connections (Python 3.11+)
  • Modified _start_tls_connection() to pass the timeout to loop.start_tls() (Python 3.11+)
• aiohttp/client.py: Added ssl_shutdown_timeout parameter to ClientSession.__init__() and passed it to TCPConnector when creating one

Documentation

• Updated docs/client_reference.rst with parameter documentation for both classes
• Added clear explanation of the parameter's purpose and default value
• Documented that the parameter only takes effect on Python 3.11+
• Marked as added in version 3.12.5

Tests

• Added unit tests to verify parameter storage and passing
• Added functional test to verify the timeout works correctly with streaming connections

Usage

# Using default 0.1 second timeout
async with aiohttp.ClientSession() as session:
    # SSL connections will have 0.1s shutdown timeout
    
# Custom timeout
async with aiohttp.ClientSession(ssl_shutdown_timeout=0.5) as session:
    # SSL connections will have 0.5s shutdown timeout
    
# Disable timeout (wait indefinitely)
async with aiohttp.ClientSession(ssl_shutdown_timeout=None) as session:
    # SSL connections will wait indefinitely for shutdown

Backward Compatibility

This change is fully backward compatible:

• Default value (0.1s) provides reasonable behavior for most use cases
• Existing code continues to work without modification
• Users experiencing issues can adjust the timeout as needed

Testing

The PR includes comprehensive tests:

1. Unit tests verify the parameter is correctly stored and passed between components
2. Functional test simulates a streaming SSL connection and verifies the timeout behavior
3. All existing tests continue to pass

References

• Fixes SSL Shutdown error in 3.12.4 #11091
• Related to Python's asyncio SSL implementation changes
• Similar issues have been reported with other async libraries using SSL

Are there changes in behavior for the user?

shutdown will no longer take 30s max

Is it a substantial burden for the maintainers to support this?

no

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.82%. Comparing base (b1da65e) to head (f917e87).
⚠️ Report is 312 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #11094      +/-   ##
==========================================
+ Coverage   98.81%   98.82%   +0.01%     
==========================================
  Files         129      129              
  Lines       41395    41493      +98     
  Branches     2231     2234       +3     
==========================================
+ Hits        40906    41007     +101     
+ Misses        339      337       -2     
+ Partials      150      149       -1     

Flag	Coverage Δ
CI-GHA	98.71% <98.01%> (+<0.01%)	⬆️
OS-Linux	98.42% <98.01%> (-0.01%)	⬇️
OS-Windows	96.69% <98.01%> (+0.01%)	⬆️
OS-macOS	97.61% <98.01%> (-0.01%)	⬇️
Py-3.10.11	97.38% <46.53%> (-0.14%)	⬇️
Py-3.10.17	97.90% <46.53%> (-0.13%)	⬇️
Py-3.11.12	98.06% <86.13%> (+0.01%)	⬆️
Py-3.11.9	97.55% <86.13%> (-0.03%)	⬇️
Py-3.12.10	98.45% <86.13%> (-0.04%)	⬇️
Py-3.13.3	98.44% <86.13%> (-0.03%)	⬇️
Py-3.9.13	97.27% <47.47%> (-0.12%)	⬇️
Py-3.9.22	97.78% <47.47%> (-0.11%)	⬇️
Py-pypy7.3.16	89.09% <47.47%> (-4.94%)	⬇️
VM-macos	97.61% <98.01%> (-0.01%)	⬇️
VM-ubuntu	98.42% <98.01%> (-0.01%)	⬇️
VM-windows	96.69% <98.01%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[codspeed-hq]

CodSpeed Performance Report

Merging #11094 will not alter performance

_{Comparing shutdown_timeout (f917e87) with master (b1da65e)}

Summary

✅ 59 untouched benchmarks

[jabbera]

This issue burned us pretty badly today. Down for almost 8 hours. I get it's not your fault, just adding my 2c that something needs to be done and we all know Microsoft isn't the speediest roadrunner in the race.

[patchback]

Backport to 3.12: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply 50bb06b on top of patchback/backports/3.12/50bb06be197b249ab91a4cef33ef7e10ffd4d95a/pr-11094

Backporting merged PR #11094 into master

1. Ensure you have a local repo clone of your fork. Unless you cloned it
   from the upstream, this would be your origin remote.
2. Make sure you have an upstream repo added as a remote too. In these
   instructions you'll refer to it by the name upstream. If you don't
   have it, here's how you can add it:

   $ git remote add upstream https://github.com/aio-libs/aiohttp.git

3. Ensure you have the latest copy of upstream and prepare a branch
   that will hold the backported code:

   $ git fetch upstream
   $ git checkout -b patchback/backports/3.12/50bb06be197b249ab91a4cef33ef7e10ffd4d95a/pr-11094 upstream/3.12

4. Now, cherry-pick PR Fix SSL shutdown timeout for streaming connections #11094 contents into that branch:

   $ git cherry-pick -x 50bb06be197b249ab91a4cef33ef7e10ffd4d95a

   If it'll yell at you with something like fatal: Commit 50bb06be197b249ab91a4cef33ef7e10ffd4d95a is a merge but no -m option was given., add -m 1 as follows instead:

   $ git cherry-pick -m1 -x 50bb06be197b249ab91a4cef33ef7e10ffd4d95a

5. At this point, you'll probably encounter some merge conflicts. You must
   resolve them in to preserve the patch from PR Fix SSL shutdown timeout for streaming connections #11094 as close to the
   original as possible.
6. Push this branch to your fork on GitHub:

   $ git push origin patchback/backports/3.12/50bb06be197b249ab91a4cef33ef7e10ffd4d95a/pr-11094

7. Create a PR, ensure that the CI is green. If it's not — update it so that
   the tests and any other checks pass. This is it!
   Now relax and wait for the maintainers to process your pull request
   when they have some cycles to do reviews. Don't worry — they'll tell you if
   any improvements are necessary when the time comes!

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

[patchback]

Backport to 3.13: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply 50bb06b on top of patchback/backports/3.13/50bb06be197b249ab91a4cef33ef7e10ffd4d95a/pr-11094

Backporting merged PR #11094 into master

1. Ensure you have a local repo clone of your fork. Unless you cloned it
   from the upstream, this would be your origin remote.
2. Make sure you have an upstream repo added as a remote too. In these
   instructions you'll refer to it by the name upstream. If you don't
   have it, here's how you can add it:

   $ git remote add upstream https://github.com/aio-libs/aiohttp.git

3. Ensure you have the latest copy of upstream and prepare a branch
   that will hold the backported code:

   $ git fetch upstream
   $ git checkout -b patchback/backports/3.13/50bb06be197b249ab91a4cef33ef7e10ffd4d95a/pr-11094 upstream/3.13

4. Now, cherry-pick PR Fix SSL shutdown timeout for streaming connections #11094 contents into that branch:

   $ git cherry-pick -x 50bb06be197b249ab91a4cef33ef7e10ffd4d95a

   If it'll yell at you with something like fatal: Commit 50bb06be197b249ab91a4cef33ef7e10ffd4d95a is a merge but no -m option was given., add -m 1 as follows instead:

   $ git cherry-pick -m1 -x 50bb06be197b249ab91a4cef33ef7e10ffd4d95a

5. At this point, you'll probably encounter some merge conflicts. You must
   resolve them in to preserve the patch from PR Fix SSL shutdown timeout for streaming connections #11094 as close to the
   original as possible.
6. Push this branch to your fork on GitHub:

   $ git push origin patchback/backports/3.13/50bb06be197b249ab91a4cef33ef7e10ffd4d95a/pr-11094

7. Create a PR, ensure that the CI is green. If it's not — update it so that
   the tests and any other checks pass. This is it!
   Now relax and wait for the maintainers to process your pull request
   when they have some cycles to do reviews. Don't worry — they'll tell you if
   any improvements are necessary when the time comes!

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.