python-masakariclient — Rewrite pack

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

Branch stable/2026.2 @ 073cd2cca082 (8.9.0 + 2 commits) — repository https://opendev.org/openstack/python-masakariclient — analysed on 2026-11-01

This pack has two uses: keep these commands working against OpenKeel's Go Masakari, and allow a rewrite of the commands. Nothing here was run against a real Masakari: see § 5.

1. Contents of _rewrite/

Versions: python-masakariclient 8.9.1.dev2, openstacksdk 4.20.0, osc-lib 4.7.0, cliff 4.16.0, keystoneauth1 5.17.0, python-openstackclient 10.3.1, Python 3.13.

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

python -I -B _rewrite/extract_plugin_stable-2026.2.py <repo> python-masakariclient masakariclient _rewrite
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-404> --mode 404
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-200> --mode 200
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-1>/c.json <repo>/masakariclient/tests/unit <repo>
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-2>/c.json <repo>/masakariclient/tests/unit <repo>
python -I -B _rewrite/scenarios_stub_stable-2026.2.py <scenarios.json>
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 <run-1>/c.json <run-2>/c.json <scenarios.json> <scratch-dir>

All of these bind or contact 127.0.0.1 only.

The generic rewrite_pack.py and conformance_capture.py were not used: there are no functional tests, and no service in this repository.

2. What the commands require from a service

The client parses no message text and no error code. So any stable text will do, and only the statuses and keys above are contractual.

Where the client and the service could disagree (read, not run)

• --marker expects, in the service, the integer id (masakari:masakari/db/sqlalchemy/api.py:200).
• --limit 0 sends limit=0, since the string is truthy (masakariclient/common/utils.py:63). The service's answer was not tested.
• --filters failover_segment_id= is overwritten by the service (masakari:masakari/api/openstack/ha/hosts.py:59).
• --filters enabled= passes to the service (masakari:masakari/api/openstack/ha/segments.py:50) and is absent from the help.
• Host filters name and control_attributes exist on the service (masakari:masakari/api/openstack/ha/hosts.py:60), but the SDK filters name on the client side and does not forward it.

3. Operations

All 15 were observed at least once, listed in [api-surface_stable-2026.2.md](_rewrite/api-surface_stable-2026.2.md): /segments (5), /segments/{id}/hosts (5), /notifications (3), /notifications/{id}/vmoves (2). Service routes the CLI never calls: GET /, /v1/extensions, /v1/extensions/{id}. Static routes in the contract over-approximate: the extractor sees the hosts branch of get_uuid_by_name even in segment delete, which never takes it; the observed sequences are the reference.

4. For a rewrite of the commands

Recommendation: keep this Python plugin and make the service compatible. It is small, but it depends on openstacksdk for nearly all its behaviour, and it plugs into the Python openstack command.

5. Conformance: what was proved

Test coverage by command:

• with vectors, through the parser: notification show, segment create, segment update;
• tested without the parser, no vector: notification vmove show, segment host show, segment host update, segment host delete, segment show, segment delete;
• no test at all: segment host create, segment host list, notification create, notification list, segment list, notification vmove list.

The delete test does not see defect 1: it only checks the mock call (masakariclient/tests/unit/osc/v1/test_segment.py:214).

To close the gap (for you to run, since this work had to stay on the stub): point the scenarios at a real Masakari on stable/2026.2 and at openkeel-masakari, by replacing the Stub with an endpoint and keeping SCENARIOS; the inject entries need the stub, so keep those aside. Comparing exit codes and sequences between the two gives a compatibility verdict.

6. Gaps found while building the pack

• The generic stub had no GET /instance-ha/v1 and announced 2.100. Fixed in my copy of the probe.
• The extractor knew no ha proxy (with_rest=0) and no gate other than supports_microversion (gates=0). Fixed: 36 of 36 calls resolved, 8 gates.
• The capture tripled each call, because the tests set app = mock.Mock(). Fixed.
• README.rst:12 and doc/source/cli/commands.rst:13 are out of date.

7. Non-functional requirements

• Latency: each invocation authenticates and reads discovery. A name lookup lists a whole collection: GET /segments is on the hot path of 8 commands, and GET …/hosts on 3 more.
• Timeouts: no project-level timeout is set in the plugin [inferred from masakariclient/plugin.py:41].
• Secrets: no secret is specific to this plugin. The notification payload is printed as is.

8. Checklist for an OpenKeel service

• [ ] Catalog type instance-ha, with a public endpoint.
• [ ] GET /v1: version 1.3, min_version 1.0.
• [ ] All values from 1.0 to 1.3 honoured; no header means 1.0; JSON answered to Accept: */*.
• [ ] Unknown ID and non-UUID both give 404 on every member route.
• [ ] Collection keys always present, also when empty.
• [ ] uuid, notification_uuid and integer id in every representation.
• [ ] "True", "False" accepted for host booleans.
• [ ] limit and marker paginate to an empty page.
• [ ] generated-since, repeated sort_key and sort_dir accepted.
• [ ] Scenario suite: same exit codes and sequences as a real Masakari.

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