python-barbicanclient — Rewrite pack

Client contract (rewrite pack) — python-barbicanclient — branch stable/2026.2

Branch stable/2026.2 @ 8162006e8677 — repository https://opendev.org/openstack/python-barbicanclient — analysed on 2026-11-01

This pack serves two purposes:

• Keep this client working against a re-implemented key manager, by stating what it requires from the service.
• Re-implement the commands, with the machine-readable catalogue.

No replay against the real Barbican was done. The client ran against a local stub only. A stub answering what it is told cannot show that a service conforms: see § 5.

1. Contents of _rewrite/

The generic rewrite_pack.py and conformance_capture.py were not used: they need an in-process service or functional tests, and functionaltests/ needs a live deployment (etc/functional_tests.conf:5).

Versions: python-barbicanclient 7.6.1.dev2 (setup-time version at this commit), python-openstackclient 10.3.1, osc-lib 4.7.0, cliff 4.16.0, keystoneauth1 5.17.0, requests-mock 1.12.1, Python 3.13.

To regenerate, from the report directory, with HOME set to an empty directory and OS_* unset:

python -I -B _rewrite/extract_plugin_stable-2026.2.py <repo> python-barbicanclient barbicanclient _rewrite
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-404> --mode 404 --repo <repo>
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-200> --mode 200 --repo <repo>
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-shape> --mode shape --repo <repo>
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-1>/c.json <repo>/barbicanclient/tests <repo>
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-2>/c.json <repo>/barbicanclient/tests <repo>
python -I -B _rewrite/repro_defects_stable-2026.2.py <repro.json> --repo <repo>
python -I -B _rewrite/build_contract_stable-2026.2.py . <dir-404>/wire-probe_stable-2026.2.json <dir-200>/wire-probe_stable-2026.2.json <dir-shape>/wire-probe_stable-2026.2.json <run-1>/c.json <run-2>/c.json <repro.json> <reverse-spec-barbican>/_rewrite/routes_stable-2026.2.json <generated-dir>

2. What the client requires from a key manager

These are hard requirements on any service that must work with this client unchanged. "Crash" means the client fails with a bare Python message [observed]. Every row is client behaviour; whether a real Barbican satisfies it was read, not run.

Discovery

Requests to accept

Responses

Lists may omit the collection key without failing (barbicanclient/v1/secrets.py:680). total is read only by .total() (barbicanclient/base.py:75).

Decisions for a rewrite of the service

• Additive changes are not free. Requirements 17 to 20 mean a new field needs a new client, or a microversion that this client never asks for: it asks for at most 1.2.
• **/cas**: not in Barbican stable/2026.2, so ca get and ca list should already fail; a rewrite need not add it.
• **POST /secrets/{id}/metadata/{key}** is refused with 405 by Barbican, while the client sends it (D24). Staying faithful keeps the bug; adding the route would be harmless, and make add_secret_metadata work. This needs a decision.
• Secret delete at 1.2: the 400 with the fixed text is a requirement, including for castellan through the same code.

3. Coverage of the service

From [api-surface_stable-2026.2.md](_rewrite/api-surface_stable-2026.2.md): 32 operations, of which 29 have a handler in the Barbican route table. The client never calls 26 service operations, among them transport keys, quotas, project quotas, secret stores, PATCH on ACLs, GET …/consumers/{id}, POST and DELETE on /containers/{id}/secrets, and container consumer listing. A rewrite that serves only this client could postpone those. castellan and the other callers were not surveyed for them.

4. For a rewrite of the CLI or library

Recommendation [inferred]: keep the Python client, and make the service conform. The CLI is thin, but castellan needs the library, and its strictness on fields is what constrains the service. If the client can be patched, D5 (ignore unknown fields) and D1 (.get('title')) are the two fixes that buy the most.

5. Conformance: what was proved

"Replay is mandatory" is not met. Nothing here ran against Barbican. The barbican: cross-checks are readings of source code.

To close the gap: run probe_plugin_stable-2026.2.py with a real deployment in place of the stub, or run functionaltests/ against both the Python service and a rewrite. Those tests need a real deployment (etc/functional_tests.conf:5). Turn the shape mode into assertions only after that comparison.

6. Gaps found while building the pack

• 7 operations of the Python API are reached by no command. They ran only through a small Python driver, in the pyapi-* cases.
• GET /secrets/{id}/consumers has 0 unit vectors: its tests mock _api.get (barbicanclient/tests/v1/test_consumers.py:133).
• Not every option combination ran: --os-key-manager-api-version other than 1 and the listed variants did, TLS options did not.
• The stub has no state, so a read after a write returns the fixed document. acl-add-duplicate shows the body sent, not a stored ACL.

7. Non-functional requirements

• Latency: each process sends 2 identity and 2 discovery requests before its first business request [observed]. Discovery documents are on the hot path.
• Request volume: unnamed secrets multiply reads by 10 (D8). A service with many unnamed secrets sees secret list as up to about 100 GET for one page of 10 [inferred from the 21 for 2].
• Secrets in transit: the payload travels in the POST body, base64 or plain; TLS comes from the deployment. --debug logs it (D14).

8. Checklist for a compatible service

• [ ] key-manager in the catalog, public interface.
• [ ] Version documents depend on the requested microversion: stable for 1.0 or no header, CURRENT with min_version and max_version otherwise; 300 on the root.
• [ ] POST routes accept the trailing slash.
• [ ] DELETE on consumers reads a JSON body.
• [ ] Every 4xx and 5xx JSON body has title, and description; 401 included.
• [ ] The refusal to delete holds the exact text; force=1 works at 1.2.
• [ ] No field beyond the lists of § 2 in secrets, consumers, orders and meta.
• [ ] POST answers JSON with the ref; PUT …/acl answers JSON.
• [ ] GET …/acl gives a default read when nothing is set.
• [ ] Decision taken on /cas and on POST /secrets/{id}/metadata/{key}.
• [ ] The probe, pointed at the service, gives the same routes, and exit 0 with real resources.

Source: reverse-spec-python-barbicanclient/07-rewrite-pack_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.