(Possibly helpful) TODO list for thread-safetiness?

[clin1234]

Free-Threading Analysis Report

Generated from https://github.com/devdanzin/ft-review-toolkit, in conjunction with Claude Code

Extension: aiohttp (4 Cython extensions + pure-Python asyncio layer)

Files covered: aiohttp/_http_parser.pyx, aiohttp/_http_writer.pyx,
aiohttp/_websocket/mask.pyx, aiohttp/_websocket/reader_py.py (compiled as
reader_c), aiohttp/connector.py, aiohttp/cookiejar.py,
aiohttp/client.py, aiohttp/web_protocol.py, aiohttp/web_server.py,
aiohttp/_websocket/writer.py

---

Migration Status

Status: DECLARED — structural migration done, significant runtime gaps remain

Timeline:

• 2025-09-04 945837cc2 — Fix thread safety of http writer; add freethreading_compatible=True to every Cython invocation in Makefile; add 3.14t CI matrix entry (fix thread safety of http writer #11464, add free-threading CI for Python 3.14 #11466)
• 2026-02-28 2d03bc457 — Fix test race on Python 3.14t (test_data_file) (#?)
• 2026-06-02 4eb358863 — Fix race condition in TCPConnector.close() (fix(connector): resolve race condition in TCPConnector.close() #12787)
• Last ft activity: ~11 days ago (as of 2026-06-12)
• Total ft-specific commits: 5 canonical commits

Declaration: freethreading_compatible=True in Makefile causes Cython to emit
Py_MOD_GIL_NOT_USED in the generated C. The extension will run without the GIL
on CPython 3.13t/3.14t.

What has been done:

• Global C buffer in _http_writer.pyx (the headline Cython race) — fixed 2025-09-04
• Free-threading CI job with PYTHON_GIL=0 — added 2025-09-04
• TCPConnector.close() TOCTOU — fixed 2026-06-02

What remains: No _PyEval_StopTheWorld usage anywhere (confirmed). All
remaining gaps are fixable with asyncio locks, threading locks,
call_soon_threadsafe, or immutable type substitutions.

---

Executive Summary

• Readiness: Moderate — declaration is present, but the cookie jar, connector
  pool, and DNS cache each have unaddressed races that affect any session with
  concurrent requests
• RACE findings: 3 — confirmed data races on shared mutable state
• UNSAFE findings: 4 — operations unsafe without GIL serialization
• PROTECT findings: 5 — shared state needing synchronization
• MIGRATE findings: 5 — structural improvements (immutability, distribution, subinterpreters)

---

Findings by Priority

RACE Findings (fix immediately) — 3

#	Finding	File:Line	Severity	Agents
1	Cython @freelist(250) on RawRequestMessage / RawResponseMessage — module-global C array and counter written non-atomically on every alloc/dealloc; concurrent parsers cause use-after-free	_http_parser.pyx:129,229	CRITICAL	shared-state, atomic-finder, unsafe-api
2	CookieJar.filter_cookies / update_cookies / _do_expiration race — concurrent calls from different request coroutines mutate _cookies, _expire_heap, _morsel_cache simultaneously with no lock	cookiejar.py:265–481	HIGH	unsafe-api
3	Module-level _SIMPLE_COOKIE = SimpleCookie() singleton mutated by concurrent _build_morsel calls — value_encode modifies BaseCookie.__data; concurrent calls corrupt coded values	cookiejar.py:38,489	HIGH	unsafe-api

UNSAFE Findings (fix before declaring free-threading support) — 4

#	Finding	File:Line	Severity
4	Connection.__del__ GC finalizer calls _release on connector pool from any GC thread — _acquired, _conns, and _cleanup_closed_transports mutated outside the event loop	connector.py:132–145,748–781	HIGH
5	PyBuffer_Release not called on exception paths in feed_data — when a Python callback (e.g. BadHttpMessage) raises during llhttp_execute, the Py_buffer export on the data object is never released	_http_parser.pyx:634–652	HIGH
6	_DNSCacheTable.next_addrs races on shared itertools.cycle iterator and OrderedDict.move_to_end — no lock; concurrent requests to the same host corrupt round-robin state	connector.py:831–837	MEDIUM
7	_cleanup_closed_transports appended from GC-thread _release while event-loop timer iterates and clears it — list realloc during iteration is use-after-free (root cause: Finding 4)	connector.py:429–433,778	MEDIUM

PROTECT Findings (add synchronization) — 5

#	Finding	File:Line	Severity
8	Server.requests_count += 1 is a non-atomic read-modify-write; gunicorn monitoring reads it cross-thread; lost updates cause max_requests shutdown to trigger late or never	web_server.py:72, web_protocol.py:679	HIGH
9	WebSocketWriter.send_frame() uncompressed/control-frame path bypasses _send_lock — a PING can interleave bytes with a large in-flight compressed frame, corrupting the WebSocket stream	_websocket/writer.py:80–82,171	MEDIUM
10	BaseConnector._closed check-then-set in _close_immediately is unguarded — two concurrent close() callers (e.g. user + GC finalizer) both pass the check and double-execute teardown	connector.py:462–465	MEDIUM
11	ClientSession.closed property loads self._connector twice — another thread calling close() can null it between the is None check and the .closed access, raising AttributeError	client.py:1377	MEDIUM
12	BaseConnector.connect() checks self._closed after await _create_connection — concurrent close() between the await and the check can leak the just-created TCP socket (never closed, never tracked)	connector.py:599–636	MEDIUM

MIGRATE Findings (structural changes) — 5

#	Finding	File:Line	Severity
13	cdef list _http_method populated by a for loop at module init — change to cdef tuple to prevent any future post-init mutation and remove mutable-container concern	_http_parser.pyx:105–109	MEDIUM
14	ALLOWED_CLOSE_CODES: Final[set[int]] — Final does not prevent runtime mutation; replace with frozenset to match intent and make reads lock-free	_websocket/reader_py.py:27	LOW
15	WebSocketDataQueue.read() enforces single-consumer with a bare assert (stripped by -O) — replace with an explicit RuntimeError or add asyncio.Lock for multi-consumer safety	_websocket/reader_py.py:117–126	LOW
16	No free-threaded (cpXXXt-tagged) wheels published to PyPI — cibuildwheel has no [tool.cibuildwheel.freethreading] section; users on 3.14t get a GIL-tagged wheel that silently re-enables the GIL	pyproject.toml (missing)	LOW
17	12× cdef object globals in _http_parser.pyx + _istr in _http_writer.pyx use m_size=-1 (no per-module state struct) — broken subinterpreter isolation; should migrate to PyModule_GetState	_http_parser.pyx:62–74, _http_writer.pyx:12	LOW

---

SAFE Patterns (confirmed safe)

• cdef frozenset ALLOWED_UPGRADES / SINGLETON_HEADERS (_http_parser.pyx:51,81): Immutable after init; frozenset.__contains__ is lock-free under free-threading
• cdef object class-cache globals (_http_parser.pyx:62–74): Written once at import under the import lock; read-only thereafter; safe for concurrent reads
• _http_method list reads (_http_parser.pyx:112–116): No post-init writes; http_method_str() is a pure reader — safe today (hardening to tuple is recommended)
• No nogil / Py_BEGIN_ALLOW_THREADS regions in any .pyx file — zero instances of "unsafe API called without GIL" in the extension code
• No _PyEval_StopTheWorld usage — confirmed by full-repo grep; none of the races require global quiescence to fix

---

Recommendations

Immediate (RACE — Findings 1–3)

1. Fix Finding 1 — disable Cython freelist for free-threading builds

Pass DEFAULT_FREELIST_SIZE=0 when building for Py_GIL_DISABLED, or guard the
decorator with a conditional. Cython ≥ 3.1 automatically disables freelists when
freethreading_compatible=True if and only if it is compiled against a
free-threading Python; verify the build environment and add an explicit guard:

# _http_parser.pyx
import sys as _sys
_FREELIST_SIZE = 0 if not getattr(_sys, "_is_gil_enabled", lambda: True)() else DEFAULT_FREELIST_SIZE

@cython.freelist(_FREELIST_SIZE)
cdef class RawRequestMessage:
    ...

Or simply remove @cython.freelist entirely from both RawRequestMessage (line 129)
and RawResponseMessage (line 229) and add a tracking issue to restore it only
for GIL-enabled builds.

2. Fix Finding 2 — add asyncio.Lock to CookieJar

# cookiejar.py __init__:
self._lock = asyncio.Lock()

async def update_cookies(self, cookies, response_url=URL()):
    async with self._lock:
        self._do_expiration()
        ...

async def filter_cookies(self, request_url):
    async with self._lock:
        return self._filter_cookies_unsafe(request_url)

All callers of filter_cookies and update_cookies are already async contexts
(client.py:642, response processing). An asyncio.Lock is the correct primitive
here — it does not block any OS thread and keeps everything on the event loop.

3. Fix Finding 3 — replace _SIMPLE_COOKIE singleton with a local instance

# cookiejar.py — replace module-level singleton:
# _SIMPLE_COOKIE = SimpleCookie()   ← REMOVE

# In _build_morsel:
def _build_morsel(self, cookie):
    if self._quote_cookie and ...:
        tmp = SimpleCookie()
        value, coded_value = tmp.value_encode(cookie.value)
    ...

The per-call allocation is negligible compared to the network I/O surrounding it.

Immediate (UNSAFE — Findings 4–7)

4. Fix Finding 4 — marshal Connection.__del__ back to the event loop

# connector.py Connection.__del__:
def __del__(self, _warnings=warnings):
    if self._protocol is not None:
        _warnings.warn(...)
        if self._loop.is_closed():
            return
        # Fixing 7 (cleanup_closed_transports) comes free with this change:
        self._loop.call_soon_threadsafe(
            lambda: self._connector._release(
                self._key, self._protocol, should_close=True
            )
        )
        self._protocol = None

loop.call_soon_threadsafe is one of the few APIs explicitly safe to call from
any OS thread. This single change also resolves Finding 7 by keeping all
_cleanup_closed_transports mutations on the event loop thread.

5. Fix Finding 5 — wrap llhttp_execute in try/finally for buffer release

# _http_parser.pyx feed_data (around line 634):
PyObject_GetBuffer(data, &self.py_buf, PyBUF_SIMPLE)
try:
    base = <char*>self.py_buf.buf
    data_len = <size_t>self.py_buf.len
    errno = cparser.llhttp_execute(self._cparser, base, data_len)
    # ... all nb/pos/tail logic ...
finally:
    PyBuffer_Release(&self.py_buf)
# Error-code checks and 'raise ex' follow the finally block unchanged.

6. Fix Finding 6 — add threading.Lock to _DNSCacheTable

class _DNSCacheTable:
    def __init__(self, ttl=None, limit=None):
        self._lock = threading.Lock()
        ...

    def next_addrs(self, key):
        with self._lock:
            loop, length = self._addrs_rr[key]
            addrs = list(islice(loop, length))
            next(loop)
            self._addrs_rr.move_to_end(key)
        return addrs

A threading.Lock (not asyncio.Lock) is correct here because next_addrs is
called from synchronous code paths. Finding 7 resolves automatically once
Finding 4 is fixed.

Short-term (PROTECT — Findings 8–12)

8. Fix Finding 8 — protect requests_count increment

If exact counts are required for max_requests enforcement, wrap the increment:

# web_protocol.py ~line 679:
with manager._requests_count_lock:   # add threading.Lock to Server.__init__
    manager.requests_count += 1

If a slightly imprecise count is acceptable (monitoring use only), document the
known imprecision and accept the race.

9. Fix Finding 9 — extend _send_lock to uncompressed/control-frame path

The asyncio.Lock already exists (self._send_lock); the fix is to acquire it
on the uncompressed branch:

# _websocket/writer.py send_frame:
if not (compress or self.compress) or opcode >= WS_CONTROL_FRAME_OPCODE:
    async with self._send_lock:
        self._write_websocket_frame(message, opcode, 0)
    return

10. Fix Finding 10 — guard _closed transitions in _close_immediately

# connector.py BaseConnector.__init__:
self._close_lock = threading.Lock()

# connector.py _close_immediately:
def _close_immediately(self, *, abort_ssl=False):
    with self._close_lock:
        if self._closed:
            return []
        self._closed = True
    ...

11. Fix Finding 11 — single local capture in ClientSession.closed

@property
def closed(self) -> bool:
    connector = self._connector  # atomic single load
    return connector is None or connector.closed

12. Fix Finding 12 — close leaked protocol in connect() error path

# connector.py connect() ~line 621:
if self._closed:
    proto.close()      # close the just-created connection before raising
    raise ClientConnectionError("Connector is closed.")

Longer-term (MIGRATE — Findings 13–17)

13. Fix Finding 13 — convert _http_method to tuple

cdef tuple _http_method = tuple(
    cparser.llhttp_method_name(<cparser.llhttp_method_t> i).decode('ascii')
    for i in range(METHODS_COUNT)
)

14. Fix Finding 14 — replace ALLOWED_CLOSE_CODES with frozenset

ALLOWED_CLOSE_CODES: Final[frozenset[int]] = frozenset(int(i) for i in WSCloseCode)

15. Fix Finding 15 — harden WebSocketDataQueue.read() single-consumer check

async def read(self) -> WSMessage:
    if self._waiter is not None:
        raise RuntimeError(
            "WebSocketDataQueue does not support concurrent read() calls"
        )
    ...

16. Fix Finding 16 — publish free-threaded wheels on PyPI

Add to pyproject.toml:

[tool.cibuildwheel.freethreading]
enable = true

Or set CIBW_FREE_THREADED_SUPPORT=1 in CI. Also consider adding the
Programming Language :: Python :: Free Threading :: 3 - Stable PyPI classifier
once RACE/UNSAFE findings above are resolved.

17. Fix Finding 17 — migrate Cython module globals to per-module state

Long-term refactor: change all cdef object module-level variables in
_http_parser.pyx (lines 62–74) and _istr in _http_writer.pyx (line 12) to
use a m_size > 0 module state struct accessed via PyModule_GetState. This is
required for correct subinterpreter isolation and is the CPython-recommended
pattern for free-threading extensions.

---

For a phased migration plan: /ft-review-toolkit:plan

[Dreamsorcerer]

It's an async library. I think our understanding of free-threaded support is that we don't block the GIL for users, but we don't expect our own code to be running threaded.

We don't want to sacrifice performance to locks etc. that are simply not needed in an async application. I suspect we'd be happy with the first suggestion in the Cython code, but have no plans to complete this list.

[clin1234]

C Extension Analysis Report

Generated from https://github.com/devdanzin/cext-review-toolkit, in conjunction with Claude Code

Extension: aiohttp (4 Cython extensions)

Scope: aiohttp/_http_parser.pyx, aiohttp/_http_writer.pyx,
aiohttp/_websocket/mask.pyx, aiohttp/_websocket/reader_py.py (compiled as
reader_c), supporting headers and build files.

---

Agents Run

Agent	Group	Mode
gil-discipline-checker	A	run
resource-lifecycle-checker	A	run
type-slot-checker	B	run
module-state-checker	B	run
version-compat-scanner	C	run
parity-checker	D	run
stable-abi-checker	D	run
c-complexity-analyzer	E	run
git-history-analyzer	F	run (last)
refcount-auditor	—	skipped (Cython mode: 95–100% FP from generator patterns)
error-path-analyzer	—	skipped (Cython mode)
null-safety-scanner	—	skipped (Cython mode)
pyerr-clear-auditor	—	skipped (Cython mode)

---

Executive Summary

aiohttp's Cython layer has correctly declared freethreading_compatible=True
and removed the only previously identified global C buffer race
(_http_writer.pyx, fixed 2025-09-04). Three new correctness gaps remain:
the @cython.freelist allocator on both message types is non-atomic and
causes use-after-free under concurrent parsers; two parity gaps in
_http_parser.pyx are confirmed-incomplete fixes from recent commits
(a TCP upgrade bypass and a missing pipeline-queue bound on the response
parser). The complexity hotspots in the WebSocket reader and HTTP parser
carry the highest probability of harboring the next latent bug, consistent
with a fix-to-feature ratio of 27% observed in git history. No
_PyEval_StopTheWorld usage exists anywhere in the tree; all fixes are
straightforward substitutions or one-line additions.

---

Extension Profile

Field	Value
Modules	_http_parser, _http_writer, _websocket.mask, _websocket.reader_c
Code generation	Cython 3.2.5
Python targets	≥ 3.10
Free-threading declared	Yes — freethreading_compatible=True in Makefile (all 3 Cython rules)
Limited API	No — py_limited_api absent from setup.py; PyByteArray_Resize is a blocker
Init style	Single-phase (m_size=-1 in generated C)
C library dependency	llhttp (vendored) via _cparser.pxd

---

Key Metrics

Dimension	Status	FIX	CONSIDER	Top Finding
GIL Discipline	Y	1	1	@cython.freelist(250) non-atomic race on both message types
Resource Lifecycle	G	0	1	Py_buffer OOM tail-slice path (HPE_PAUSED)
Type Slots	G	0	1	HttpParser instantiable via __new__ without _init
Module State	G	0	2	13× cdef object module globals break subinterpreter isolation
ABI Compliance	G	0	1	PyByteArray_Resize blocks stable ABI; abi3 infeasible
Version Compat	G	0	3	3× DEF deprecated in Cython 4
C/Python Parity	Y	2	1	"tcp" absent from ALLOWED_UPGRADES; max_msg_queue_size missing from HttpResponseParser
Complexity	G	0	5	_feed_data 183 LOC / CC 27 (WebSocket reader)
Refcount Safety	—	—	—	Skipped (Cython mode)
Error Handling	—	—	—	Skipped (Cython mode)
NULL Safety	—	—	—	Skipped (Cython mode)
PyErr_Clear Safety	—	—	—	Skipped (Cython mode)

G = No FIX findings · Y = 1–3 FIX findings · R = 4+ FIX findings

---

Findings by Priority

Must Fix (FIX) — 3

#	Finding	File:Line	Severity	Agents
1	@cython.freelist(250) on RawRequestMessage and RawResponseMessage — module-global C counter and object-pointer array written non-atomically on every alloc/dealloc; concurrent parsers (e.g. two feed_data calls on the same connection from different threads) cause use-after-free	_http_parser.pyx:129,229	CRITICAL	gil-discipline-checker, git-history-analyzer
2	ALLOWED_UPGRADES = frozenset({"websocket"}) — "tcp" missing; Python parser's _is_supported_upgrade() accepts {"tcp", "websocket"} (fixed there in commit 8f23712, March 2024); Cython parser silently rejects TCP upgrades 27 months later	_http_parser.pyx:51,484	HIGH	parity-checker, git-history-analyzer
3	HttpResponseParser.__init__ does not accept max_msg_queue_size and does not forward it to self._init() — pipelined response queue is unbounded; HttpRequestParser received the parameter in commit 93a2b1c but HttpResponseParser was not updated (confirmed twin-class omission)	_http_parser.pyx:752–762	HIGH	parity-checker, git-history-analyzer

---

Should Consider (CONSIDER) — 15

#	Finding	File:Line	Severity
4	data[pos:] slice at line 650 can raise MemoryError after llhttp_execute returns HPE_PAUSED; if it does, control jumps out before PyBuffer_Release at line 652 — buffer stays exported and the backing object cannot be resized or freed	_http_parser.pyx:648–652	MEDIUM
5	HttpParser and its Cython subclasses have __cinit__ (allocates C structs) but _init is a separate Python-level call; constructing via HttpParser.__new__(HttpResponseParser) without calling __init__ leaves _cparser allocated but unconfigured; _init is never a slot, so tp_init is a no-op on HttpParser itself	_http_parser.pyx:343–418	MEDIUM
6	12× cdef object module-level globals in _http_parser.pyx (lines 62–74: EMPTY_PAYLOAD, NO_EXTENSIONS, etc.) and _istr in _http_writer.pyx (line 12) are file-scope C statics (static PyObject*); the module was compiled with m_size=-1, so each subinterpreter shares the same static cells — subinterpreter isolation is broken	_http_parser.pyx:62–74, _http_writer.pyx:12	MEDIUM
7	cdef list _http_method populated at module init by a for loop — a mutable list as a module-scope static; mutating it post-init would silently corrupt method-name lookup for all parsers	_http_parser.pyx:105–109	LOW
8	DEF BUF_SIZE = 16 * 1024 in _http_writer.pyx — Cython DEF compile-time constants are deprecated since Cython 3.0 and removed in Cython 4; this DEF also feeds a C array dimension, which will need a const or enum replacement before migration	_http_writer.pyx:10	LOW
9	DEF DEFAULT_FREELIST_SIZE = 250 — same deprecation class as Finding 8; feeds the @cython.freelist argument that is also the target of FIX Finding 1	_http_parser.pyx:52	LOW
10	DEF METHODS_COUNT = 46 — same deprecation class; feeds the range in _http_method construction and must stay in sync with the llhttp method enum	_http_parser.pyx:103	LOW
11	_write_utf8 silently drops lone surrogates (return 0 at line 72 on \ud800–\udfff) while the pure-Python serializer raises UnicodeEncodeError; clients using the C writer get silent data truncation instead of an error	_http_writer.pyx:70–72	MEDIUM
12	PyByteArray_Resize and PyByteArray_GET_SIZE (non-limited API) are called directly from the generated Cython C; py_limited_api is absent from setup.py, so no abi3 claim is made — but if adoption is ever attempted, these two calls are the primary blocker alongside a buffer-protocol Py_buffer floor conflict with Python 3.10	setup.py, _http_parser.pyx	LOW
13	No cpXXXt-tagged (free-threaded) wheels are published to PyPI — cibuildwheel has no [tool.cibuildwheel.freethreading] section in pyproject.toml; users on CPython 3.13t/3.14t receive a GIL-compatible wheel that silently re-enables the GIL	pyproject.toml (absent)	LOW
14	WebSocketReader._feed_data: 183 LOC, cyclomatic complexity 27 — highest CC in the extension layer; recent commit 69344c6 reorganized the max_msg_size check location, adding a new branch cluster that raised CC	_websocket/reader_py.py:332–515	—
15	WebSocketReader._handle_frame: 136 LOC, CC 21 — interleaved opcode dispatch, masking, and continuation-frame logic; fragmented-mask bug was fixed here (commit e0cc020, April 2025) at the cost of additional branch depth	_websocket/reader_py.py:194–330	—
16	HttpParser.feed_data: 78 LOC, CC 16 — llhttp dispatch + OOM guard + tail logic; commit b5a5170 added buffer-pointer caching here; the HPE_PAUSED slice-raise gap (Finding 4) is in this function	_http_parser.pyx:602–680	—
17	HttpParser._on_headers_complete: 68 LOC, CC 14 — highest-churn function in git history alongside feed_data (18 substantive changes in 18 months); upgrade handling (FIX Finding 2) lives here	_http_parser.pyx:466–534	—
18	HttpParser._on_status_complete: 47 LOC, nesting depth 5 — response-status dispatch with inlined payload-size accounting	_http_parser.pyx:700–747	—

---

Tensions

• Module state vs. migration cost (_http_parser.pyx:62–74): module-state-checker
  flags the 12 cdef object globals as subinterpreter-isolation failures; c-complexity-analyzer
  notes that migrating them to a PyModule_GetState struct requires threading the module
  pointer through every callback that currently reads them as file-statics. This is a
  multi-week refactor; the subinterpreter use case is still rare for aiohttp. Deferring is
  rational — but the Py_mod_multiple_interpreters slot should be set to
  Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED so CPython rejects the mismatch explicitly.

• Stable ABI infeasibility (stable-abi-checker): PyByteArray_Resize has no
  limited-API equivalent; adopting abi3 would require a runtime-check workaround or
  replacement with bytes accumulation. The complexity cost is not justified given
  aiohttp's standard wheel publishing workflow. Recommendation is to explicitly reject
  abi3 rather than leave the door open.

---

Policy Decisions (POLICY) — 7

#	Finding
19	Change cdef list _http_method to cdef tuple — matches immutability intent; http_method_str() only reads it; no post-init mutation needed
20	Change ALLOWED_CLOSE_CODES: Final[set[int]] to frozenset — Final does not prevent runtime mutation; frozenset is lock-free under free-threading and matches ALLOWED_UPGRADES style
21	Latent nogil trap: llhttp_execute C callbacks (cb_on_url, cb_on_headers_complete, etc.) call back into Python from C — if a nogil block were ever introduced around llhttp_execute, these callbacks would execute without the GIL. Document this constraint and add a # NOGIL-UNSAFE comment at the llhttp_execute call site
22	Add Py_mod_multiple_interpreters slot to module init (set to Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED) — signals the incompatibility explicitly rather than silently misbehaving in subinterpreter contexts
23	requirements/cython.in has no upper bound (Cython with no version pin) — Cython 4 will remove DEF (Findings 8–10) and may change freelist behaviour; add Cython>=3.2,<4 until the migration is done
24	abi3 and free-threading are mutually exclusive in the current CPython ABI: do not add py_limited_api=True to setup.py — it would conflict with freethreading_compatible=True and produce incorrect wheel tags
25	cython_limited_api=True is absent from the Makefile; if abi3 is ever revisited, this flag and py_limited_api in setup.py must be set simultaneously; a half-applied change would produce a wheel that lies about its ABI compliance

---

Dismissed / Superseded Findings

ft-analysis.md Finding 5 — PyBuffer_Release not called on exception paths in
feed_data — DISMISSED by resource-lifecycle-checker during this analysis.

The llhttp callbacks (cb_on_url, cb_on_headers_complete, etc.) catch all
Python exceptions via try: ... except BaseException as ex: pyparser._last_error = ex; return -1. Because llhttp_execute has no Cython except annotation, control
unconditionally falls through to PyBuffer_Release at line 652 regardless of the
callback's return value. The stored exception is re-raised at line 668, which is
after the release. The ft-analysis was incorrect in classifying this as UNSAFE/HIGH.

Note: Finding 4 in this report identifies a residual, narrower gap on the HPE_PAUSED
tail-slice path — a distinct code location that the original ft finding did not specify.

---

Strengths

• ALLOWED_UPGRADES and SINGLETON_HEADERS — cdef frozenset; immutable after
  module init, lock-free under free-threading; frozenset.__contains__ is safe for
  concurrent reads.
• _serialize_headers buffer — switched from global cdef char BUFFER[BUF_SIZE]
  to stack-local allocation with a heap_allocated fallback flag (commit 945837c,
  2025-09-04); the headline Cython FT race is gone.
• feed_data buffer-pointer caching — base = <char*>self.py_buf.buf is captured
  before PyBuffer_Release; commit b5a5170 correctly fixed the use-after-release on
  the normal path.
• max_line_size cumulative enforcement — both cb_on_url and cb_on_status use
  accumulated-length checks; commit 36df6c1 was applied completely to both callbacks
  in one change; no twin-class gap exists here.
• mask.pyx — 48 lines, only 2 commits in its entire history; the XOR kernel is
  minimal and carries no thread-safety concerns.
• No nogil / Py_BEGIN_ALLOW_THREADS blocks — zero instances of GIL-released
  regions in any .pyx file; the extension never invokes CPython APIs without the GIL.
• No _PyEval_StopTheWorld — confirmed by full-repo grep; none of the races
  require global quiescence to fix.

---

Git History Insights

File	Total commits	Recent (2025–2026)	Fix-to-feature ratio	Risk level
_http_parser.pyx	67	18	~27%	HIGH
_websocket/reader_py.py	18	12	~33%	HIGH
_http_writer.pyx	12	5	~17%	MEDIUM
_websocket/mask.pyx	2	0	0%	LOW

Notable commit history:

• 2018, commit 28f1519 — Introduced @cython.freelist(DEFAULT_FREELIST_SIZE) on
  both RawRequestMessage and RawResponseMessage simultaneously; they have never been
  touched since; neither was audited when freethreading_compatible=True was added in
  2025.
• 2024-03, commit 8f23712 — Added "tcp" to _is_supported_upgrade() in the
  Python parser, scoped explicitly to "the pure python http parser"; the Cython
  ALLOWED_UPGRADES frozenset was not updated and still lacks "tcp" 27 months later.
• 2025-09-04, commit 945837c — Fixed global C buffer in _http_writer.pyx and
  added freethreading_compatible=True to all Cython invocations; _http_parser.pyx
  was only touched to remove a comment line — the freelist race was not audited.
• 2026-06 (recent), commit 93a2b1c — Added max_msg_queue_size to
  HttpRequestParser.__init__ and HttpParser._init; HttpResponseParser.__init__
  was not updated (confirmed twin-class omission, trivially reproducible).
• 2026-06, commit 36df6c1 — Enforced cumulative max_line_size on both
  cb_on_url and cb_on_status; fix is complete — no gap found.

The fix-to-feature ratio of ~27% across all parser files is elevated relative to a
healthy extension (typically ~10–15%). It reflects active correctness pressure on the
HTTP parser and suggests a systematic audit sweep is more effective than continued
point fixes.

---

Recommended Action Plan

Immediate (FIX items)

1. Fix Finding 1 — disable @cython.freelist for free-threading builds

   Both RawRequestMessage (line 129) and RawResponseMessage (line 229) must be
   addressed together — they were introduced in the same commit and carry identical risk.

   Option A — guard with a runtime check:

   import sys as _sys
   _FREELIST_SIZE = 0 if not getattr(_sys, "_is_gil_enabled", lambda: True)() else DEFAULT_FREELIST_SIZE
   
   @cython.freelist(_FREELIST_SIZE)
   cdef class RawRequestMessage:
       ...

   Option B — remove both decorators entirely and file a tracking issue to restore
   them only for GIL-enabled builds once Cython's freelist-disable-on-FT path is
   confirmed in the CI build environment.

2. Fix Finding 2 — add "tcp" to ALLOWED_UPGRADES

   # _http_parser.pyx line 51:
   cdef frozenset ALLOWED_UPGRADES = frozenset({"websocket", "tcp"})

   One-character change; mirrors the Python parser fix from commit 8f23712.

3. Fix Finding 3 — add max_msg_queue_size to HttpResponseParser.__init__

   Mirror HttpRequestParser.__init__ exactly:

   # _http_parser.pyx HttpResponseParser.__init__ (line 752):
   def __init__(
       self, protocol, loop, int limit, timer=None,
           size_t max_line_size=8190, size_t max_headers=128,
           size_t max_field_size=8190, payload_exception=None,
           bint response_with_body=True, bint read_until_eof=False,
           bint auto_decompress=True,
           Py_ssize_t max_msg_queue_size=0    # ADD THIS
   ):
       self._init(cparser.HTTP_RESPONSE, protocol, loop, limit, timer,
                  max_line_size, max_headers, max_field_size,
                  payload_exception, response_with_body, read_until_eof,
                  auto_decompress,
                  max_msg_queue_size)          # FORWARD IT

Short-term (CONSIDER items)

4. Fix Finding 4 — wrap HPE_PAUSED tail-slice in try/finally

   # _http_parser.pyx feed_data (around line 634):
   PyObject_GetBuffer(data, &self.py_buf, PyBUF_SIMPLE)
   try:
       base = <char*>self.py_buf.buf
       data_len = <size_t>self.py_buf.len
       errno = cparser.llhttp_execute(self._cparser, base, data_len)
       # ... nb / pos / tail logic including data[pos:] slice ...
   finally:
       PyBuffer_Release(&self.py_buf)
   # raise ex follows the finally block unchanged

5. Fix Finding 5 — document or guard HttpParser.__new__-without-__init__

   The simplest guard is to check self._cparser is not NULL at the top of every
   public method that calls into llhttp, raising RuntimeError("parser not initialized")
   if the check fails. Alternatively, initialize _cparser to NULL in __cinit__ and
   call a safe-default _init from __cinit__ with sentinel values that block
   feed_data from doing anything.

6. Fix Finding 11 — align surrogate behaviour with the Python writer

   In _write_utf8, replace the silent return 0 on surrogates with a Cython raise:

   # _http_writer.pyx line 72:
   raise UnicodeEncodeError("utf-8", ...)

   Or pass errors="surrogatepass" in the serialiser and document the intentional
   deviation. Currently the silence is undocumented and breaks parity.

7. Fix Findings 8–10 — migrate DEF constants before Cython 4 upgrade

   # Replace:
   DEF BUF_SIZE = 16 * 1024
   DEF DEFAULT_FREELIST_SIZE = 250
   DEF METHODS_COUNT = 46
   
   # With:
   BUF_SIZE = 16 * 1024                    # module-level Python int
   DEFAULT_FREELIST_SIZE = 250
   METHODS_COUNT = 46

   For BUF_SIZE feeding a C array dimension, use cdef enum or a cdef int constant
   depending on how the C array is declared in the generated code.

8. Fix Finding 13 — publish free-threaded wheels to PyPI

   Add to pyproject.toml:

   [tool.cibuildwheel.freethreading]
   enable = true

   Also add the Programming Language :: Python :: Free Threading :: 3 - Alpha PyPI
   classifier once FIX findings 1–3 above are resolved.

Longer-term (POLICY / structural)

9. Policy 19 — harden _http_method to tuple

   cdef tuple _http_method = tuple(
       cparser.llhttp_method_name(<cparser.llhttp_method_t>i).decode("ascii")
       for i in range(METHODS_COUNT)
   )

10. Policy 20 — convert ALLOWED_CLOSE_CODES to frozenset

    ALLOWED_CLOSE_CODES: Final[frozenset[int]] = frozenset(int(i) for i in WSCloseCode)

11. Policy 22 — add Py_mod_multiple_interpreters slot

    In the generated module init (or via a Cython cython: ... module_state directive
    when available), set m_slots to include:

    {Py_mod_multiple_interpreters, Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED}

12. Policy 23 — cap Cython version in requirements

    # requirements/cython.in:
    Cython>=3.2,<4
    

13. Finding 6 — migrate module-level globals to per-module state (long-term)

    All 12 cdef object globals in _http_parser.pyx (lines 62–74) and _istr in
    _http_writer.pyx (line 12) should migrate to a PyModule_GetState-backed struct.
    This requires m_size > 0 and threading the module pointer through every init
    callback. Scope this as a standalone PR; it does not block the FIX items above.

---

Notes

• Free-threaded interpreter on this system: python3t.exe (python3t -m pip for
  package management)
• The corresponding free-threading analysis (asyncio layer, cookie jar, connector pool,
  WebSocket writer lock gap) is in ft-analysis.md
• For a phased migration plan: /ft-review-toolkit:plan or /cext-review-toolkit:plan
• The ft-analysis.md Finding 5 (PyBuffer_Release on exception) is DISMISSED per the
  resource-lifecycle-checker findings in this report — do not file it as an issue