python-octaviaclient — Rewrite pack

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

Branch stable/2026.2 @ b37975ec8f2d (tag 3.15.0 + 2 commits) — repository https://opendev.org/openstack/python-octaviaclient — analysed on 2026-11-01

This pack states **what openstack loadbalancer … requires from a load-balancer service**, so that an OpenKeel replacement keeps working with the unmodified plugin. It is a client contract, not a plan to rewrite the plugin.

No real service was contacted. The CLI ran against a local stub on 127.0.0.1. Octavia's code and OpenAPI were read, not run. See § 5.

1. Contents of _rewrite/

Versions: python-octaviaclient 3.15.1.dev2 (installed files identical to the repository), osc-lib 4.7.0, cliff 4.16.0, python-openstackclient 10.3.1, openstacksdk 4.20.0, keystoneauth1 5.17.0, Python 3.13.

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

python -I -B _rewrite/extract_plugin_stable-2026.2.py <repo> python-octaviaclient octaviaclient _rewrite
for m in 404 200 typed; do python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-$m> --mode $m; done
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-options> --mode typed --options
python -I -B _rewrite/repro_defects_stable-2026.2.py <repro.json>
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-1>/c.json <repo>/octaviaclient/tests/unit
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-2>/c.json <repo>/octaviaclient/tests/unit
python -I -B _rewrite/build_contract_stable-2026.2.py . <repo> <dir-404>/wire-probe_stable-2026.2.json <dir-200>/wire-probe_stable-2026.2.json <dir-typed>/wire-probe_stable-2026.2.json <dir-options>/wire-probe_stable-2026.2.json <repro.json> <run-1>/c.json <run-2>/c.json <octavia-openapi.json> <tables-dir>

The generic rewrite_pack.py and conformance_capture.py were not used, because the plugin has no functional tests to record (octaviaclient/tests/functional/base.py:45).

2. What the CLI requires from a service

"Hard" means that the command fails without it. Items marked [observed] were seen on the stub, which shows the client's demand, not a service's answer.

Catalog and URL

Lookup

Response shape

Status, for --wait

What the service must accept

Errors and paging

3. Coverage of OpenKeel services

No OpenKeel service was probed: the request allowed only the local stub.

4. Rewriting the plugin itself

Not recommended now. The plugin is thin, and scripts depend on command and argument names, which cli-commands_stable-2026.2.json holds. A short list to keep, and to fix:

5. Conformance: what was proved

Replay against the original service: not done, and not possible under this request's rules. The usual "replay is mandatory" bar is not met. The vectors were not replayed against any rewrite either, since none exists.

Tag order: the PUT body varies from run to run (["t3","t4","t2","t1"], then ["t2","t4","t1","t3"]) [observed], so wire files are not byte-stable across runs on set --tag and unset --tag. The unit vectors were identical over 4 runs, but this does not show that the order is stable: their merged tag lists hold only 2 items.

To close the gap: point probe_plugin at a devstack on stable/2026.2, or at the OpenKeel lab, with the stub removed, and compare request sequences and exit codes with wire-probe-typed.

6. Gaps found while building the pack

• The shared probe's modes stop at the first lookup, since {} has no collection key and 404 ends the command. Hence typed mode. Its 10 unset commands send nothing with no option; they were reached through --options.
• The shared probe disabled logging, which hid every error text; this copy keeps it.
• ClientCache holds clients on the class (osc-lib:osc_lib/clientmanager.py:47), so in one process later commands kept the first endpoint. This made two catalog scenarios pass falsely until the probe reset it. Results before the reset were discarded.
• The extractor resolves SDK calls to routes only: with_rest is 3 of 197 calls. Octavia routes come from the OctaviaAPI table that build_contract reads, and from the wire.
• Client calls in cli-commands are static and over-approximate: amphora configure lists load_balancer_show, reached through a status_f argument. For routes, the wire wins.
• No functional tests exist in the repository, so no suite could be replayed.

7. Non-functional requirements

• Latency: each invocation authenticates, and each name adds one list request, or two for a child with a parent [observed]. A script of N commands sends N token requests.
• Polling: one GET per 3 s per --wait (octaviaclient/osc/v2/utils.py:793).
• Paging: the client requests no page size, so the service's limit decides. Its next page is requested at once.

8. Checklist for an OpenKeel service

• [ ] Types load-balancer and network are in the catalog; the URL does not end in /v2.
• [ ] Routes of api-surface_stable-2026.2.md exist under /v2.0, including GET /lbaas/quotas/defaults.
• [ ] Lists keep their key when empty; filters id and name work on every list.
• [ ] The wrapper is the first JSON key of a single-resource body.
• [ ] Decoding accepts connection_limit as a string, True/False in queries, repeated tag parameters, null as reset, and empty PUT objects.
• [ ] Both quota spellings are accepted.
• [ ] Writes leave ACTIVE before answering; failures end in ERROR; finished deletes give 404.
• [ ] Errors hold faultstring; responses carry x-openstack-request-id.
• [ ] next links carry the filters and stop at the end.
• [ ] Run probe_plugin against the service and compare with wire-probe-typed.

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