[yujiyokoo]

Summary

The Python SDK's thread and interrupt rules are now tested through the public API. Several threads can use one Cipher at once, and they share one connection to CipherStash. A Ctrl-C during a call waits for the call to finish, and the Cipher still works afterwards. The README now describes these rules for users.

Changes

• Request counts by endpoint: the ZeroKMS connection now counts each request it sends, by endpoint. ZeroKMS is CipherStash's key service.
  • _engine.requests() returns the counts, for example {"load-keyset": 1, "retrieve-key": 3}.
  • _engine.request_count() is now their sum.
  • A request counts when it is sent. A failed request counts too. The tests of a refused call rely on this.
• Shared test helpers: tests/_sync_contract.py has the test model, the thread runner, and the interrupt helpers.
  • pytest now puts tests/ on the path. So the deterministic tests can import the module.
  • The gate test for interrupts now uses the same helpers.
• First call from 8 threads: tests/_first_call.py runs in a new Python process. Its 8 threads start their first encrypt together, behind a threading.Barrier. The live test checks that the process built one client, and loaded the keyset once.
• Calls from 8 threads: 8 threads each make 100 encrypt calls on one Cipher. One decrypt then opens all 800 rows, and each row must equal its model.
  • This test runs live, in tests/test_concurrency_live.py.
  • It also runs on the deterministic test build, in tests_deterministic/test_concurrency.py. So it runs on every pull request, with no credentials.
• Ctrl-C during encrypt: tests/_interrupt.py runs in a new Python process.
  • It times a reference call first: the fastest of three. It starts at 5000 values, and doubles them until a call takes 0.4 seconds, up to 80,000.
  • It then sends SIGINT a quarter of the way into one more call.
  • The live test checks that exactly one KeyboardInterrupt arrives, after at least half the reference time. A call cut short would raise at the quarter.
  • The call returns all its rows or none, and the next encrypt works.
• Two Cipher instances: the existing live test now also checks that the second Cipher adds no keyset load.
• README: a new section, "Use it from several threads". It covers these points:
  • The calls are synchronous, and each one releases the GIL.
  • A process has one connection. Every Cipher uses it.
  • Make one Cipher for each model, not one for each web request.
  • A Ctrl-C arrives after the call returns.
  • The timeouts: 10 seconds for each ZeroKMS request, and 30 seconds for each access token request.
• client.rs: one helper, locked(), now recovers a poisoned lock, in place of four copies.

Verification

• mise run test:cargo: all core and extension tests pass.
• clippy and cargo fmt --check: no findings, with and without all features.
• pytest on Python 3.14: 353 passed, 28 skipped. The skips are the live tests and 2 gate-probe tests.
• mise run test:deterministic: 19 passed, with the new concurrency test.
• The gate test on a gate-probe build: 2 passed, with the shared helpers.
• mypy: no findings in the new and changed test files.
• Both child scripts ran on the deterministic build, through a local wrapper:
  • In the interrupt script, the signal went at 0.17 seconds. The interrupt arrived at 0.66 seconds, at the end of the call.
  • The first-call script read 0 builds. That is correct, because the deterministic build never builds the live client.
• Python 3.9 was not run for this branch.
• The live tests have not run. This machine has no CipherStash credentials. The live job on this PR is their first run.
• pyright reports that it cannot resolve _sync_contract in the deterministic test. pyright does not read pytest's pythonpath setting. pytest itself imports it correctly.

Related

Closes #1394. Refs #1341.

Review notes

• Start with tests/_sync_contract.py, then the two child scripts.
• The interrupt test fails, and does not skip, if 80,000 values take less than 0.2 seconds. Then the signal cannot be sent inside the call, so the test would check nothing. A skip would fail mise run test:live anyway. Only a ZeroKMS on the same machine is that fast.
• Request counts include failed requests. A failed keyset load also fails the call that made it. So a test of the load count fails on that error first, not on the count.
• The spec says calls have no timeout. The README states the real timeouts, from stack-kms and stack-auth. A setting to change them is not in this PR.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Tip

🎯 Customize your risk assessments

Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.

✅ Automatic approvals, with your rules

Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d3de32e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR