Reuse HTTP connections and add close() to both clients

[zeevmoney]

Linear issues

• PER-16344: reuse one HTTP session per client instead of opening a connection for every request.

Why

Every request opened and closed its own aiohttp.ClientSession: the five HTTP methods of SimpleHttpClient (used by permit.api.*, permit.elements and permit.pdp_api.*) and the five PDP calls of the enforcer (check, bulk_check, authorized_users, get_user_permissions, get_user_tenants). Each call paid for a new TCP connection, plus a TLS handshake when the PDP or the API is reached over https. The blocking client also created a new event loop for every call.

What changed

Async client (permit.Permit)

• permit/utils/http_sessions.py: LoopSessions keeps one aiohttp session per event loop, opened by the first request from that loop. Each client has two: one for the Permit API, one for the PDP. Sessions carry no headers, base URL or timeout: each request passes its own, resolved as ClientSession(base_url=...) resolved it, so the bytes on the wire are unchanged (the existing wire tests pass unchanged). Sessions use TCPConnector(limit=0) and DummyCookieJar.
• Permit._share_sessions() gives the client's two sessions to every API object, HTTP client and the enforcer. No constructor signature changed.
• await permit.close() and async with Permit(...) as permit:. close() closes the session of its own loop, marks closed the sessions of closed loops, and hands the close to loops running in other threads, waiting for each while that loop runs. The sessions are closed side by side: one that fails to close does not stop the others, and the first error is raised afterwards. A session still open afterwards (its loop stopped first, its close failed, or close() was cancelled) is kept for the next close() or request. close() can be called again, and a request after it opens new connections.
• Without close(), sessions are closed when a loop shuts down its async generators (asyncio.run(), asyncio.Runner, pytest-asyncio), when the client is garbage collected while its loop runs (also through the cycle collector), and at interpreter exit. A forked child sets the sessions it inherits aside and opens its own.

Blocking client (permit.sync.Permit)

• permit/utils/sync.py: each client runs its blocking calls, and those of every API object it holds, on one event loop in a daemon thread named permit-sync-loop, started on the first call. The deprecation call site is set in each call's task, the caller's other context variables reach it, many threads can share one client, and a call's exception is raised in the caller with its original type, traceback and cause.
• permit.close() and with Permit(...) as permit: wait for the calls in flight, close the sessions on the background loop, then stop and join the thread. A call or close() that another thread makes meanwhile waits for it to finish. A blocking call or close() made on the client's own background thread raises RuntimeError instead of deadlocking. async with on the blocking client raises TypeError, and type checkers reject it.
• A client that is never closed has its thread stopped when it is garbage collected, or at interpreter exit, where calls still in flight are cancelled so the exit is never held up. A forked child starts a thread of its own, including when it was forked during a close().

Both clients

• With proxy_facts_via_pdp on, wait_for_sync() yields a copy that uses its parent's sessions (and, on the blocking client, its thread). The copy's close() does nothing, and the parent's close() closes them. With it off (the default), wait_for_sync() yields the client itself.
• README: a "Connections" section. CONTRIBUTING: a "Connection reuse" section (the keep-alive test server and the benchmark command).
• Tests: tests/keepalive_server.py, a local HTTP/1.1 server that keeps connections open and counts them; tests/test_async_session_lifecycle.py; tests/test_sync_lifecycle.py; tests/benchmark_connection_reuse.py, with tests/test_benchmark_connection_reuse.py running it in the offline suite; and the async lifecycle in tests/type_check/consumer.py.

Behaviour changes

• Connections are reused: per client, one pool for the API and one for the PDP, per event loop. Idle connections stay open for aiohttp's default keep-alive of 15 s, and each pool caches DNS for aiohttp's default 10 s.
• New public API: Permit.close(), Permit.__aenter__/__aexit__, permit.sync.Permit.close(), __enter__/__exit__.
• permit.sync.Permit runs its calls on a daemon thread per client, started on the first call. Calls from many threads run concurrently on that loop. A call or close() made on that thread raises RuntimeError; before, such a call ran in a worker thread.
• aiohttp's single retry on a dropped keep-alive connection now applies to GET, PUT and DELETE requests. POST and PATCH requests are not retried, so if a server drops an idle connection just as it is reused, check() can fail with PermitConnectionError.
• An async client used on a loop closed with loop.close() alone leaves that loop's keep-alive connections open until the garbage collector frees them, and Python reports each with a ResourceWarning. Before, every request closed its own connection.
• Importing permit registers atexit hooks and, outside Windows, os.register_at_fork hooks. On Python 3.12+, forking after a blocking client has made a call triggers Python's own DeprecationWarning about forking a process that runs threads.
• SimpleHttpClient (internal) raises TypeError for client_config keys other than base_url, headers and timeout, and no longer writes timeout into the dict it is given. The unused **kwargs passthrough of both _build_http_client methods is gone.
• permit/api/base.py imports yarl and multidict directly, so both are now declared in [project].dependencies: multidict>=6.7.0,<7 and yarl>=1.21.0,<2. Both are aiohttp dependencies already. These floors are the first releases with wheels for every supported Python (3.10 to 3.14t), so they are higher than aiohttp's own floors.
• SyncClass objects that no client holds, such as SyncPermitApiClient(config) built directly, still run each call in an event loop of their own.

Release notes

Connections are now reused. Each client keeps one HTTP connection pool for the Permit API and one for the PDP, instead of opening a new connection, and a TLS handshake, for every request. In a local benchmark of 500 sequential check() calls on loopback, each client opened 1 connection instead of 500. The median time per call went from about 0.39-0.44 ms to 0.17-0.18 ms on the async client, and from 0.52-0.54 ms to 0.23-0.24 ms on the blocking client. Against a remote PDP or over https, each reused connection also saves a round trip and a TLS handshake.

• New: await permit.close() and async with Permit(...) as permit: on the async client; permit.close() and with Permit(...) as permit: on permit.sync.Permit. close() can be called again, and a closed client reconnects on its next call.
• With proxy_facts_via_pdp on, a client yielded by wait_for_sync() uses its parent's connections, and its own close() does nothing. With it off (the default), wait_for_sync() yields the client itself.
• The async client keeps its connections per event loop. They are closed automatically when asyncio.run() (or anything else that shuts down the loop's async generators) ends, when the client is garbage collected while its loop runs, or at interpreter exit. If you drive an event loop yourself, call await permit.close() on it before loop.close(). A loop closed without that leaves its connections open until the garbage collector frees them, and Python then reports a ResourceWarning, which fails test suites that turn warnings into errors.
• permit.sync.Permit now runs its calls on one event loop per client, in a background daemon thread it starts on the first call, so calls from every thread share the client's connections. close() waits for calls in flight, and a call or close() made from another thread meanwhile waits for it. A client that is never closed is cleaned up when it is garbage collected or at interpreter exit, and the thread never blocks exit. A blocking call or close() made on the client's own background thread raises RuntimeError instead of deadlocking. async with on the blocking client raises TypeError, and type checkers reject it.
• A child process created by fork() leaves its parent's connections alone and opens its own.
• Because connections are pooled, aiohttp's own single retry on a dropped keep-alive connection now applies to GET, PUT and DELETE requests. POST and PATCH requests, such as check() and the API's update calls, are not retried.

How it was tested

• Offline suite on Python 3.11.14: 787 passed, 3 skipped, 0 warnings (filterwarnings=error), 5 runs on each pydantic lane. The base had 661 passed, 3 skipped.
• Also on Python 3.10.19, 3.12.12, 3.13.9, 3.14.7 and 3.14.7 free-threaded (2 runs each), and on 3.10 with the floor dependencies (aiohttp 3.14.3, pydantic 1.10.18): 787 passed each time.
• New lifecycle tests count connections at the keep-alive server. They cover:
  • reuse, and one client across two successive asyncio.run() calls;
  • close(), the context managers, idempotent close and use after close;
  • many threads on one blocking client, and a blocking call from a thread that runs a loop;
  • re-entrant calls, close() racing calls and a second close();
  • loops in other threads that end or stop during close(), and sessions that fail to close;
  • fork, and fork during close();
  • garbage collection and interpreter exit with no warning;
  • the daemon thread stopped by close(), and timeouts keeping their traceback.
• mypy clean on both pydantic lanes. Typing surface: 4 passed on each lane. pytest --collect-only -m e2e: 42 collected. CI script tests: 223 passed. API coverage report: exit 0. pre-commit: all hooks pass. uv lock --check, actionlint and zizmor: clean.
• Benchmark, uv run --locked python -m tests.benchmark_connection_reuse --calls 500, 3 runs each on 127.0.0.1 (Python 3.11.14, macOS arm64). The base numbers run the same script against the permit package of ef5a791:

Version	Client	Connections	p50 ms	mean ms
base ef5a791	async	500	0.385-0.436	0.408-0.526
base ef5a791	sync	500	0.522-0.544	0.533-0.561
this PR	async	1	0.172-0.183	0.190-0.198
this PR	sync	1	0.226-0.240	0.231-0.255

• Mutation testing of the lifecycle tests: 27 mutants in the last round, 26 killed and 1 equivalent survivor (a filter on gather outcomes no reachable path distinguishes). Earlier rounds checked the async and sync units and the merge.
• e2e tests were type-checked and collected only. CI runs them.

Owner actions before merge

• Squash-merge: the intermediate commits d676947, a50aac3 and b9eee07 fail tests/test_fix_sync_parity.py (the async close() lands before the blocking client overrides it). Every later commit passes the offline suite.
• Confirm the connection settings: no cap on concurrent connections (TCPConnector(limit=0)), aiohttp's 15 s keep-alive, and no retry of POST and PATCH requests on a dropped pooled connection.
• Accept the documented limit for loops closed with loop.close() alone (a ResourceWarning at garbage collection).
• Pre-existing and not changed here: a request timeout reaches the caller as a bare asyncio.TimeoutError, and an api_url or pdp with a path breaks permit.api, permit.elements and permit.pdp_api.
• Free-threaded Python 3.14 is not in the CI matrix; it was checked locally.

🤖 Generated with Claude Code

[linear-code]

PER-16344

[github-actions]

Dependency Security Audit

Scanned: pyproject.toml dependencies + dev group, resolved at Python 3.10 (the current resolution, and the lowest versions the published specs permit under each pydantic major)

✅ No known vulnerabilities found.

Both the resolved dependency set and the lowest versions the published specs permit are clean at HIGH and CRITICAL.