Say when a route needs the container PDP, document which proxied writes wait, send X-Wait-Timeout: 0

[zeevmoney]

Linear issues

• PER-16340: say "container PDP only" when a route only the container PDP serves is called on the cloud PDP.
• PER-16339: document which facts writes proxied through the PDP wait for sync.
• PER-16681: send X-Wait-Timeout when the facts sync timeout is 0.

Stacked on #141.

Why

• The cloud PDP serves the decision routes and /health only. It answers 404 for the /facts routes that proxy_facts_via_pdp sends facts to, for the /local routes of permit.pdp_api, and for /user-tenants. For the first two, the SDK raised a generic 404 API Error: {'details': ''}, which does not say that the route needs the container PDP.
• wait_for_sync(), facts_sync_timeout and proxy_facts_via_pdp read as if every proxied facts write waits for the PDP to have the change. The PDP waits on 11 routes and forwards every other facts request without waiting.
• facts_sync_timeout=0 and wait_for_sync(timeout=0) sent no X-Wait-Timeout header, because the SDK checked the value's truthiness. The PDP then waited its default of 10 seconds instead of not waiting.

What changed

Routes only the container PDP serves (PER-16340)

• permit/utils/cloud_pdp.py decides when a 404 on a container-only route is the cloud PDP's. It is when the pdp URL's host is cloudpdp.api.permit.io (any scheme, port, path or letter case), or when the 404 body is empty (zero bytes). Every other 404 keeps its current error and message: a container PDP's JSON 404, and the API's 404 that a container PDP's /facts routes pass on, such as for a missing tenant (PermitNotFoundError).
• SimpleHttpClient takes a keyword-only container_pdp_advice. Every facts client under proxy_facts_via_pdp and every permit.pdp_api client sets it. On the cloud PDP's 404, these clients raise a PermitApiError whose message names the route, followed by what to do and the PDP setup docs link. For example: The SDK got status code 404 from the PDP at https://cloudpdp.api.permit.io: only the container PDP serves POST /facts/users, and the cloud PDP does not. PermitApiError takes a keyword-only message.
• get_user_tenants() keeps the PermitConnectionError and the exact message it got in Add tenants.create_user and get_user_tenants #139. The message is now built by the same helper.
• Creating a client (async or blocking) with proxy_facts_via_pdp=True and a pdp on the cloud PDP host issues a UserWarning:
  • it is attributed to the line that created the client, for subclasses too;
  • it is issued on each creation, and Python's default filter shows it once per line;
  • clients that wait_for_sync() yields do not issue it;
  • both client docstrings document it in a Warns section.
• These docstrings now say "Container PDP only": the 47 facts methods that go to the PDP with the proxy on, pdp_api.role_assignments.list() and get_user_tenants(). The sync stub is regenerated.
• e2e:
  • The container_pdp skip fixture moves to tests/conftest.py. The five e2e tests that need a container PDP use it.
  • The e2e (cloud PDP) job gets two read-only tests that check the new 404 messages and the warning.

Which proxied writes wait for sync (PER-16339)

• These places list the 11 methods the PDP waits on: the wait_for_sync() docstring, the proxy_facts_via_pdp and facts_sync_timeout field descriptions, and a new README section, "Read-your-writes through the PDP". They also say that every other facts request is forwarded without waiting. The 11 methods are users.create, users.update, users.sync, users.assign_role, users.unassign_role, tenants.create, role_assignments.assign, role_assignments.unassign, resource_instances.create, resource_instances.update and relationship_tuples.create. The README also lists the 17 writes that are forwarded without waiting.
• tests/facts_methods.py holds a table of all 48 public facts methods, with the exact request each one sends under the proxy. tests/test_facts_sync_offline.py uses it to check that:
  • each method sends X-Wait-Timeout, or not, to the PDP route the table gives;
  • the synced routes equal the /facts operations in the committed PDP spec (.github/api-specs/pdp.json);
  • each of the four documented lists equals the set of methods whose route is synced.
• API coverage allowlist: 5 PDP "untested" entries that the new tests cover are removed. 19 sdk_only entries (PER-16338) are added for proxied routes that the PDP forwards without listing them in its spec.

Timeout 0 (PER-16681)

• The SDK now sends X-Wait-Timeout whenever facts_sync_timeout is not None, 0 included. X-Timeout-Policy is unchanged, because none of its values is falsy.

Behaviour changes

1. Container-only routes on the cloud PDP. On the cloud PDP's 404, facts methods under proxy_facts_via_pdp=True and every permit.pdp_api method still raise PermitApiError, but with a new message that names the route and says it needs the container PDP.
   • err.details changes from {'details': ''} to {'details': '', 'message': <message>}.
   • err.__cause__ is now None; it was aiohttp.ContentTypeError.
   • Other 404s, other statuses and get_user_tenants() are unchanged.
2. New UserWarning at client creation when proxy_facts_via_pdp=True and pdp is on the cloud PDP host. With warnings turned into errors, creating such a client raises.
3. A facts sync timeout of 0 now means do not wait. facts_sync_timeout=0 sends X-Wait-Timeout: 0.0, and wait_for_sync(timeout=0) sends X-Wait-Timeout: 0. Before, no header was sent, and the PDP waited its default: 10 seconds, unless PDP_LOCAL_FACTS_WAIT_TIMEOUT sets another.

Additions to the API that existing callers don't need to change for: PermitApiError(..., message=...) and SimpleHttpClient(..., container_pdp_advice=...).

How it was tested

• Offline suite: 1166 passed, 3 skipped, 0 warnings on both the pydantic-v2 and pydantic-v1 lanes. The base has 787 passed, 3 skipped. The new tests are in tests/test_container_pdp_only_offline.py (251) and tests/test_facts_sync_offline.py (128).

• How the wire tests work: each one runs on the async and the blocking client against a local pytest-httpserver. It asserts the exact method, path, query, headers and body, and that the other server got nothing. Clients are closed after each call.

• Mutation checks: 26 mutants of the code these tests guard were run at the final head, covering:

  • the 404 rule and the host check;
  • the advice wiring and the error details;
  • the warning's condition, category and line;
  • the timeout check and wait_for_sync;
  • a docstring note, the README list and an SDK route;
  • the e2e skip.

  25 were caught. The one survivor is equivalent to the original: it starts the frame walk one frame further out, which the __init__ skip makes identical.

• e2e: 44 tests collect. They need keys and run in CI. With a dummy key and unreachable services, the five container-only e2e tests skip with their reason.

• Other checks:

  • mypy passes on both lanes and the typing-surface tests pass on both (4 passed);
  • all pre-commit hooks pass;
  • the CI script tests pass (223);
  • the API coverage report exits 0 (PDP GA: 17 covered, 15 excluded, 1 deferred, 0 untested);
  • actionlint and zizmor report nothing.

Owner actions before merge

• Run CI, including e2e and e2e (cloud PDP). The cloud PDP job now runs 8 tests, two of them new. If one of the new ones fails, the cloud PDP answered GET /local/role_assignments or GET /facts/users/<key> with something other than a 404.

🤖 Generated with Claude Code

[linear-code]

PER-16340

PER-16339

PER-16681

[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.