From 753c8bb38bbdb8952bf95baf2f8e9410b7e8934f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 14 Aug 2026 17:37:45 +0900 Subject: [PATCH 1/8] test(policy): expose integer-subclass pool-count boundary --- .../test_connection_pool_count_value_types.py | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 tests/test_connection_pool_count_value_types.py diff --git a/tests/test_connection_pool_count_value_types.py b/tests/test_connection_pool_count_value_types.py new file mode 100644 index 00000000..e1a5a456 --- /dev/null +++ b/tests/test_connection_pool_count_value_types.py @@ -0,0 +1,41 @@ +"""Security contracts for exact connection-pool count value types.""" + +from __future__ import annotations + +import pytest + +from egressweave import EgressConnectionPoolPolicy + + +class _ConnectionCountSubclass(int): + """Represent an unreviewed integer subclass crossing trusted configuration.""" + + +@pytest.mark.parametrize( + "field_name", + ["max_connections", "max_keepalive_connections"], +) +def test_connection_pool_policy_rejects_integer_subclasses(field_name: str) -> None: + """Reject non-exact integers before retaining finite pool-capacity values.""" + with pytest.raises(TypeError, match=field_name): + EgressConnectionPoolPolicy( + **{field_name: _ConnectionCountSubclass(1)} # type: ignore[arg-type] + ) + + +def test_connection_pool_policy_keeps_reviewed_count_input_forms() -> None: + """Continue accepting exact integers and reviewed ASCII decimal strings.""" + exact_integer = EgressConnectionPoolPolicy( + max_connections=8, + max_keepalive_connections=2, + ) + decimal_string = EgressConnectionPoolPolicy( + max_connections="8", + max_keepalive_connections="2", + ) + + assert type(exact_integer.max_connections) is int + assert type(exact_integer.max_keepalive_connections) is int + assert decimal_string == exact_integer + assert type(decimal_string.max_connections) is int + assert type(decimal_string.max_keepalive_connections) is int From 21d61428791b6f7a807a3ec412156b598bbcfbbe Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 14 Aug 2026 17:41:21 +0900 Subject: [PATCH 2/8] fix(policy): require exact integer pool counts --- src/egressweave/connection_pool_policy.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/egressweave/connection_pool_policy.py b/src/egressweave/connection_pool_policy.py index f372dc79..93574602 100644 --- a/src/egressweave/connection_pool_policy.py +++ b/src/egressweave/connection_pool_policy.py @@ -22,7 +22,7 @@ def _normalize_connection_count( """Return one exact ASCII-compatible connection-count limit.""" if isinstance(value, bool): raise TypeError(f"{field_name} must be an integer or ASCII decimal string") - if isinstance(value, int): + if type(value) is int: normalized = value elif isinstance(value, str): if not value or not value.isascii() or not value.isdecimal(): From 024f846a0007498ff7b7a3b01fad6d35f6de117b Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 14 Aug 2026 17:42:02 +0900 Subject: [PATCH 3/8] docs(policy): explain exact pool-count value forms --- .../connection-pool-resource-limits.md | 45 +++++++++++-------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/research/connection-pool-resource-limits.md b/docs/research/connection-pool-resource-limits.md index 88471aa5..e730d172 100644 --- a/docs/research/connection-pool-resource-limits.md +++ b/docs/research/connection-pool-resource-limits.md @@ -18,13 +18,17 @@ an exact `EgressConnectionPoolPolicy` with different documented field values instead. This boundary does not claim EgressWeave sandboxes arbitrary Python code already executing inside the embedding process. -`max_connections` must be a positive integer or ASCII decimal string. -`max_keepalive_connections` may be zero to retain no idle connections but must -not exceed total capacity. `keepalive_expiry_seconds` must be a finite -non-negative real number and may be zero for immediate expiry. Booleans, -fractional counts, signed or non-ASCII count text, negative values, non-finite -expiry values, unrelated objects, and contradictory capacities fail during -trusted policy construction. +`max_connections` must be an exact built-in `int` greater than zero or an ASCII +decimal string. `max_keepalive_connections` accepts the same reviewed forms, +may be zero to retain no idle connections, and must not exceed total capacity. +Integer subclasses are rejected before normalization so caller-defined numeric +behavior cannot cross the trusted configuration boundary. A caller using an +integer subclass must migrate by converting its validated value to an exact +built-in integer or an approved ASCII decimal string before constructing the +policy. `keepalive_expiry_seconds` must be a finite non-negative real number and +may be zero for immediate expiry. Booleans, fractional counts, signed or +non-ASCII count text, negative values, non-finite expiry values, unrelated +objects, and contradictory capacities fail during trusted policy construction. ## Standards basis @@ -54,18 +58,21 @@ and portable across standalone and modular integrations. 1. Both public `EgressPolicy` constructors accept the same immutable pool policy. 2. Trusted construction accepts only the exact `EgressConnectionPoolPolicy` type; subclasses are rejected before transport pool values are read. -3. Total connection capacity is always positive and finite. -4. Idle capacity is finite, may be zero, and cannot exceed total capacity. -5. Idle expiry is finite and non-negative; `None` cannot disable reclamation. -6. Synchronous and asynchronous HTTPCore pools receive the exact normalized +3. Count fields accept only exact built-in integers or reviewed ASCII decimal + strings; integer subclasses and booleans are rejected. +4. Total connection capacity is always positive and finite. +5. Idle capacity is finite, may be zero, and cannot exceed total capacity. +6. Idle expiry is finite and non-negative; `None` cannot disable reclamation. +7. Synchronous and asynchronous HTTPCore pools receive the exact normalized values from the policy. -7. No transport imports HTTPX's private `DEFAULT_LIMITS` object. -8. The normalized pool policy participates in deterministic policy and decision +8. No transport imports HTTPX's private `DEFAULT_LIMITS` object. +9. The normalized pool policy participates in deterministic policy and decision fingerprints without recording live connection state. -9. Defaults, valid environment-style count text, invalid configuration, - relational invariants, exact policy-type enforcement, sync/async delegation, - public API exposure, and fingerprint drift are covered by offline regression - tests with complete production statement and branch coverage. +10. Defaults, valid environment-style count text, invalid configuration, + relational invariants, exact policy-type and count-type enforcement, + sync/async delegation, public API exposure, and fingerprint drift are covered + by offline regression tests with complete production statement and branch + coverage. ## Operational guidance @@ -80,7 +87,9 @@ assuming it is universally safer. Applications that previously subclassed `EgressConnectionPoolPolicy` must migrate to an exact instance and configure the supported finite fields directly. -The exact-type check runs during trusted startup, before a pool or request can +Applications that supplied integer subclasses for either count must convert the +validated count to an exact built-in `int` or an approved ASCII decimal string. +Both exact-type checks run during trusted startup, before a pool or request can consume those values. ## References From 89d9012af9a6bda7fc13169173f6476459bccc24 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 14 Aug 2026 17:42:25 +0900 Subject: [PATCH 4/8] test(docs): lock exact pool-count migration guidance --- ...nnection_pool_count_value_documentation.py | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 tests/test_connection_pool_count_value_documentation.py diff --git a/tests/test_connection_pool_count_value_documentation.py b/tests/test_connection_pool_count_value_documentation.py new file mode 100644 index 00000000..1daee8d8 --- /dev/null +++ b/tests/test_connection_pool_count_value_documentation.py @@ -0,0 +1,23 @@ +"""Documentation contracts for exact connection-pool count value types.""" + +from __future__ import annotations + +from pathlib import Path + +REPOSITORY_ROOT = Path(__file__).resolve().parents[1] +POOL_GUIDE_PATH = ( + REPOSITORY_ROOT / "docs" / "research" / "connection-pool-resource-limits.md" +) + + +def test_connection_pool_guide_documents_exact_builtin_count_values() -> None: + """Keep operator guidance aligned with the primitive-value integrity boundary.""" + guide = " ".join(POOL_GUIDE_PATH.read_text(encoding="utf-8").split()) + + for fragment in ( + "exact built-in `int`", + "Integer subclasses are rejected", + "must migrate", + "approved ASCII decimal string", + ): + assert fragment in guide From 8bac04eb7d2b65e5d05f662ec937fc7b1492ed3c Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 15 Aug 2026 19:10:43 +0900 Subject: [PATCH 5/8] test(security): reject connection-count string subclasses --- .../test_connection_pool_count_value_types.py | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/tests/test_connection_pool_count_value_types.py b/tests/test_connection_pool_count_value_types.py index e1a5a456..f38dbfeb 100644 --- a/tests/test_connection_pool_count_value_types.py +++ b/tests/test_connection_pool_count_value_types.py @@ -11,6 +11,14 @@ class _ConnectionCountSubclass(int): """Represent an unreviewed integer subclass crossing trusted configuration.""" +class _ExplodingCountString(str): + """Expose polymorphic string inspection in trusted count normalization.""" + + def isascii(self) -> bool: + """Fail if normalization invokes a subclass-controlled text method.""" + raise AssertionError("string subclass isascii executed") + + @pytest.mark.parametrize( "field_name", ["max_connections", "max_keepalive_connections"], @@ -23,6 +31,20 @@ def test_connection_pool_policy_rejects_integer_subclasses(field_name: str) -> N ) +@pytest.mark.parametrize( + "field_name", + ["max_connections", "max_keepalive_connections"], +) +def test_connection_pool_policy_rejects_string_subclasses_before_inspection( + field_name: str, +) -> None: + """Reject non-exact strings before invoking their text protocol methods.""" + with pytest.raises(TypeError, match=field_name): + EgressConnectionPoolPolicy( + **{field_name: _ExplodingCountString("1")} # type: ignore[arg-type] + ) + + def test_connection_pool_policy_keeps_reviewed_count_input_forms() -> None: """Continue accepting exact integers and reviewed ASCII decimal strings.""" exact_integer = EgressConnectionPoolPolicy( From dbce33d31d9bf5839214341e129f1d1347caa9df Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 15 Aug 2026 19:12:31 +0900 Subject: [PATCH 6/8] fix(security): reject connection-count string subclasses --- src/egressweave/connection_pool_policy.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/egressweave/connection_pool_policy.py b/src/egressweave/connection_pool_policy.py index 93574602..90e6d03b 100644 --- a/src/egressweave/connection_pool_policy.py +++ b/src/egressweave/connection_pool_policy.py @@ -24,7 +24,7 @@ def _normalize_connection_count( raise TypeError(f"{field_name} must be an integer or ASCII decimal string") if type(value) is int: normalized = value - elif isinstance(value, str): + elif type(value) is str: if not value or not value.isascii() or not value.isdecimal(): raise ValueError(f"{field_name} must be an ASCII decimal string") normalized = int(value, 10) @@ -56,10 +56,10 @@ class EgressConnectionPoolPolicy: ``max_connections`` is the maximum number of concurrent TCP connections the pool may own. ``max_keepalive_connections`` limits the subset retained while idle and may be zero to disable idle retention. Both count fields accept - exact integers or ASCII decimal strings for environment-derived settings. - ``keepalive_expiry_seconds`` limits how long an idle connection remains - reusable and may be zero for immediate expiry. The defaults preserve HTTPX's - documented finite baseline without importing HTTPX's private + exact integers or exact ASCII decimal strings for environment-derived + settings. ``keepalive_expiry_seconds`` limits how long an idle connection + remains reusable and may be zero for immediate expiry. The defaults preserve + HTTPX's documented finite baseline without importing HTTPX's private ``DEFAULT_LIMITS`` object. """ From e1a01a1ad9d592aeaeb886db515c166e6f107caa Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 15 Aug 2026 19:13:20 +0900 Subject: [PATCH 7/8] docs(security): document exact pool-count strings --- .../connection-pool-resource-limits.md | 34 ++++++++++--------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/research/connection-pool-resource-limits.md b/docs/research/connection-pool-resource-limits.md index e730d172..d37788e3 100644 --- a/docs/research/connection-pool-resource-limits.md +++ b/docs/research/connection-pool-resource-limits.md @@ -18,15 +18,16 @@ an exact `EgressConnectionPoolPolicy` with different documented field values instead. This boundary does not claim EgressWeave sandboxes arbitrary Python code already executing inside the embedding process. -`max_connections` must be an exact built-in `int` greater than zero or an ASCII -decimal string. `max_keepalive_connections` accepts the same reviewed forms, -may be zero to retain no idle connections, and must not exceed total capacity. -Integer subclasses are rejected before normalization so caller-defined numeric -behavior cannot cross the trusted configuration boundary. A caller using an -integer subclass must migrate by converting its validated value to an exact -built-in integer or an approved ASCII decimal string before constructing the -policy. `keepalive_expiry_seconds` must be a finite non-negative real number and -may be zero for immediate expiry. Booleans, fractional counts, signed or +`max_connections` must be an exact built-in `int` greater than zero or an exact +built-in `str` containing only ASCII decimal digits. +`max_keepalive_connections` accepts the same reviewed forms, may be zero to +retain no idle connections, and must not exceed total capacity. Integer and +string subclasses are rejected before normalization so caller-defined numeric +or text-protocol behavior cannot cross the trusted configuration boundary. A +caller using either subclass form must migrate by converting its validated value +to an exact built-in integer or exact ASCII decimal string before constructing +the policy. `keepalive_expiry_seconds` must be a finite non-negative real number +and may be zero for immediate expiry. Booleans, fractional counts, signed or non-ASCII count text, negative values, non-finite expiry values, unrelated objects, and contradictory capacities fail during trusted policy construction. @@ -58,8 +59,9 @@ and portable across standalone and modular integrations. 1. Both public `EgressPolicy` constructors accept the same immutable pool policy. 2. Trusted construction accepts only the exact `EgressConnectionPoolPolicy` type; subclasses are rejected before transport pool values are read. -3. Count fields accept only exact built-in integers or reviewed ASCII decimal - strings; integer subclasses and booleans are rejected. +3. Count fields accept only exact built-in integers or exact built-in ASCII + decimal strings; integer subclasses, string subclasses, and booleans are + rejected before numeric or text protocol methods are invoked. 4. Total connection capacity is always positive and finite. 5. Idle capacity is finite, may be zero, and cannot exceed total capacity. 6. Idle expiry is finite and non-negative; `None` cannot disable reclamation. @@ -69,7 +71,7 @@ and portable across standalone and modular integrations. 9. The normalized pool policy participates in deterministic policy and decision fingerprints without recording live connection state. 10. Defaults, valid environment-style count text, invalid configuration, - relational invariants, exact policy-type and count-type enforcement, + relational invariants, exact policy-type and scalar-type enforcement, sync/async delegation, public API exposure, and fingerprint drift are covered by offline regression tests with complete production statement and branch coverage. @@ -87,10 +89,10 @@ assuming it is universally safer. Applications that previously subclassed `EgressConnectionPoolPolicy` must migrate to an exact instance and configure the supported finite fields directly. -Applications that supplied integer subclasses for either count must convert the -validated count to an exact built-in `int` or an approved ASCII decimal string. -Both exact-type checks run during trusted startup, before a pool or request can -consume those values. +Applications that supplied integer or string subclasses for either count must +convert the validated count to an exact built-in `int` or exact built-in ASCII +decimal `str`. These exact-type checks run during trusted startup, before a pool +or request can consume those values. ## References From 9836caa81b3b49d2e6a965830cf9a96242b0a097 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 15 Aug 2026 19:13:34 +0900 Subject: [PATCH 8/8] test(docs): bind exact pool-count string guidance --- tests/test_connection_pool_count_value_documentation.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tests/test_connection_pool_count_value_documentation.py b/tests/test_connection_pool_count_value_documentation.py index 1daee8d8..56f85d3f 100644 --- a/tests/test_connection_pool_count_value_documentation.py +++ b/tests/test_connection_pool_count_value_documentation.py @@ -16,8 +16,9 @@ def test_connection_pool_guide_documents_exact_builtin_count_values() -> None: for fragment in ( "exact built-in `int`", - "Integer subclasses are rejected", + "exact built-in `str`", + "Integer and string subclasses are rejected", "must migrate", - "approved ASCII decimal string", + "exact built-in ASCII decimal `str`", ): assert fragment in guide