Skip to content

Commit 6e1fc79

Browse files
authored
fix: correct the nocopy reason and measure the reservation refusals (#123)
`nocopy` is not something podman cannot express: `-v vol:/data:nocopy` suppresses the copy-up (measured, 4.9.3), and compose2pod already emits that for a short-syntax entry. Only `--mount`, which the long form renders as, has no nocopy in its grammar, so the message now names the escape and the row moves to LIMITATIONS. The reservation refusals get the two table shapes their claims need: ABSENT_FLAGS for `cpus`, where podman run has no such flag, and STUB_FLAGS for `devices`, where `--gpus` exists, is hidden from --help, and accepts `nonsense` as readily as `all`. Closes #116
1 parent 80b370a commit 6e1fc79

7 files changed

Lines changed: 155 additions & 21 deletions

File tree

‎compose2pod/parsing.py‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -332,13 +332,20 @@ def _reject_subpath(name: str, vtype: str, added_in: str) -> None:
332332
def _validate_volume_type_options(name: str, options: dict[str, Any]) -> None:
333333
"""Check a long-form volume entry's `volume:` sub-map (measured, v5.1.2).
334334
335-
Both keys are real Docker keys that the runtime will not honour: podman's
336-
`--mount` cannot express `nocopy` at any version, and `subpath` on a named
337-
volume arrives in podman 5.4. Each is refused with a "not supported" message
338-
rather than folded into the generic unknown-key check the caller already ran.
335+
Both keys are real Docker keys this entry cannot carry: `--mount`, which a
336+
long-form volume renders as, has no `nocopy` in its grammar, and `subpath` on
337+
a named volume arrives in podman 5.4. Each is refused with a "not supported"
338+
message rather than folded into the generic unknown-key check the caller ran.
339+
340+
`nocopy` is a limitation of the spelling, not of podman: `-v vol:/data:nocopy`
341+
is honoured (measured, 4.9.3 -- it suppresses the copy-up), and compose2pod
342+
emits exactly that for a short-syntax entry, so the message names the escape.
339343
"""
340344
if "nocopy" in options:
341-
msg = f"service {name!r}: volume 'nocopy' is not supported (podman cannot express it)"
345+
msg = (
346+
f"service {name!r}: volume 'nocopy' is not supported here: the long form mounts with "
347+
"--mount, whose grammar has no nocopy (use the short syntax, which emits -v and podman honours)"
348+
)
342349
raise UnsupportedComposeError(msg)
343350
if "subpath" in options:
344351
_reject_subpath(name, "volume", "5.4")

‎compose2pod/resources.py‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,15 @@ def _validate_limits(name: str, svc: dict[str, Any], limits: Any) -> None: # no
4949
raise UnsupportedComposeError(msg)
5050

5151

52+
# Measured on podman 4.9.3: `--memory-reservation` is the only reservation flag
53+
# podman run has, and `--gpus` exists but is hidden and accepts `nonsense` as
54+
# readily as `all`, so emitting it would reserve nothing and say it had.
55+
_RESERVATION_REFUSALS = {
56+
"cpus": "podman run has no reservation flag for it",
57+
"devices": "podman run's --gpus accepts any value and reserves nothing",
58+
}
59+
60+
5261
def _validate_reservations(name: str, svc: dict[str, Any], reservations: Any) -> None: # noqa: ANN401 - Compose values are untyped
5362
# No `reservations is None` escape -- see `_validate_limits`.
5463
if not isinstance(reservations, dict):
@@ -59,9 +68,9 @@ def _validate_reservations(name: str, svc: dict[str, Any], reservations: Any) ->
5968
if unknown:
6069
msg = f"service {name!r}: deploy.resources.reservations: unsupported keys {sorted(unknown)}"
6170
raise UnsupportedComposeError(msg)
62-
for field in ("cpus", "devices"):
71+
for field, reason in _RESERVATION_REFUSALS.items():
6372
if field in reservations:
64-
msg = f"service {name!r}: deploy.resources.reservations.{field} is not supported (no podman equivalent)"
73+
msg = f"service {name!r}: deploy.resources.reservations.{field} is not supported ({reason})"
6574
raise UnsupportedComposeError(msg)
6675
if "memory" in reservations:
6776
_validate_memory_size(name, "deploy.resources.reservations.memory", reservations["memory"])

‎docs/adr/0006-docker-rejection-parity.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,13 @@ deferred to it. `tests/conformance/` runs both oracles for real over a probe mat
2424
from `SERVICE_KEYS | STRUCTURAL_KEYS | IGNORED_SERVICE_KEYS`, so a new key is probed the moment
2525
it is added, and `tests/integration/refusals.py` measures the other side, pairing each volume-family
2626
refusal above with the `--mount` that expresses what Docker says the document means, so a claim that
27-
podman cannot express something cannot go stale unnoticed either. It carries both verdicts:
28-
`REFUSALS` for the mounts podman will not make, `LIMITATIONS` for the ones it would, which is what
29-
keeps a limitation from quietly reading as rule two. A gate that every rule-two site has a row is
27+
podman cannot express something cannot go stale unnoticed either. It carries four verdicts, because
28+
four kinds of claim need four experiments: `REFUSALS` for the mounts podman will not make,
29+
`LIMITATIONS` for the ones it would (which is what keeps a limitation from quietly reading as rule
30+
two), and, where the claim is about podman's flag surface rather than a mount, `ABSENT_FLAGS` for a
31+
flag podman does not have and `STUB_FLAGS` for one it has that validates nothing -- a flag accepting
32+
`nonsense` is a worse reason to emit it than a flag that fails, since the script would report
33+
success for something it never did. A gate that every rule-two site has a row is
3034
[#109](https://github.com/modern-python/compose2pod/issues/109) phase 3, and it has to carry the
3135
exemptions first: not every refusal this document names turns out to be one podman makes.
3236
Verdicts are per version, and the supported range is stated rather than implied: the rulings here

‎tests/integration/refusals.py‎

Lines changed: 83 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,18 @@
1818
rather than for podman's inability to mount, which would make a row pass for the
1919
wrong reason and hide an emit bug behind a parity claim.
2020
21-
Not every refusal site can have a row. `network_mode` is refused under ADR-0003, not
22-
rule two, and podman honours it (#115); `nocopy` and `deploy.resources.reservations.*`
23-
do not fit this shape at all (#116). The gate that every *rule-two* site has a row is
24-
issue #109 phase 3, and it has to know about those exemptions before it can be written.
21+
Two more tables hold the refusals whose claim is about podman's *flag surface* rather
22+
than about a mount, which `Refusal` cannot express: its argv asserts that a flag fails,
23+
and here the claim is that no flag exists to try, or that one exists and checks nothing.
24+
25+
- `ABSENT_FLAGS` -- no such flag on `podman run`, checked by running it rather than by
26+
reading `--help`, because `--gpus` proves a flag can exist while staying out of it.
27+
- `STUB_FLAGS` -- the flag exists and accepts deliberate nonsense, so emitting it would
28+
exit 0 having done nothing, which is worse than refusing.
29+
30+
Four claims, four experiments. `network_mode` alone has no row: it is refused under
31+
ADR-0003, not rule two, and podman honours it (#115). The gate that every rule-two site
32+
has a row is issue #109 phase 3, and that is the exemption it has to know about.
2533
2634
A `subpath` row measures the floor, not podman as such: podman gained the option above
2735
the supported minimum (ADR-0006), so the row goes red on a runner newer than the floor,
@@ -53,14 +61,43 @@ class Limitation:
5361
5462
`host_dir` is created under the test's `tmp_path` first, because a bind whose
5563
source does not exist fails for that reason instead of the one being measured.
56-
`{host}` in `podman_argv` is substituted with its absolute path.
64+
`{host}` in `podman_argv` is substituted with its absolute path. A row whose
65+
counterfactual needs no host path leaves it empty.
5766
"""
5867

5968
id: str
6069
compose: dict[str, Any]
6170
refusal_match: str
62-
host_dir: str
6371
podman_argv: list[str]
72+
host_dir: str = ""
73+
74+
75+
@dataclass(frozen=True)
76+
class AbsentFlag:
77+
"""A refusal whose claim is that podman has no flag to emit for the key.
78+
79+
Each `unknown_argv` must be rejected by `podman run`. The row goes red the day
80+
podman grows one, which is the only thing keeping "no equivalent" from going stale.
81+
"""
82+
83+
id: str
84+
compose: dict[str, Any]
85+
refusal_match: str
86+
unknown_argv: list[list[str]]
87+
88+
89+
@dataclass(frozen=True)
90+
class StubFlag:
91+
"""A refusal whose claim is that podman's flag exists and validates nothing.
92+
93+
`nonsense_argv` is deliberate rubbish podman accepts anyway; the row goes red when
94+
a podman starts rejecting it, which is when the refusal deserves re-examining.
95+
"""
96+
97+
id: str
98+
compose: dict[str, Any]
99+
refusal_match: str
100+
nonsense_argv: list[str]
64101

65102

66103
def _one_volume(entry: "str | dict[str, Any]") -> dict[str, Any]:
@@ -156,7 +193,27 @@ def _one_volume(entry: "str | dict[str, Any]") -> dict[str, Any]:
156193
]
157194

158195

196+
def _reservation(field: str, value: object) -> dict[str, Any]:
197+
return {"services": {"app": {"image": "busybox:1.36", "deploy": {"resources": {"reservations": {field: value}}}}}}
198+
199+
159200
LIMITATIONS: list[Limitation] = [
201+
Limitation(
202+
# Measured: `-v vol:/etc:nocopy` leaves only podman's own hosts/hostname/resolv.conf
203+
# in the volume, so the image copy-up really is suppressed.
204+
id="volume-nocopy",
205+
compose={
206+
"services": {
207+
"app": {
208+
"image": "busybox:1.36",
209+
"volumes": [{"type": "volume", "source": "ncvol", "target": "/data", "volume": {"nocopy": True}}],
210+
}
211+
},
212+
"volumes": {"ncvol": {}},
213+
},
214+
refusal_match="use the short syntax, which emits -v",
215+
podman_argv=["-v", "c2p-nocopy-probe:/data:nocopy"],
216+
),
160217
Limitation(
161218
id="drive-qualified-bind",
162219
compose=_one_volume("C:\\data:/var"),
@@ -172,3 +229,23 @@ def _one_volume(entry: "str | dict[str, Any]") -> dict[str, Any]:
172229
podman_argv=["--mount", "type=bind,src={host},dst=/var"],
173230
),
174231
]
232+
233+
234+
ABSENT_FLAGS: list[AbsentFlag] = [
235+
AbsentFlag(
236+
id="reservations-cpus",
237+
compose=_reservation("cpus", "0.5"),
238+
refusal_match="podman run has no reservation flag for it",
239+
unknown_argv=[["--cpu-reservation", "1"], ["--cpus-reservation", "1"]],
240+
),
241+
]
242+
243+
244+
STUB_FLAGS: list[StubFlag] = [
245+
StubFlag(
246+
id="reservations-devices",
247+
compose=_reservation("devices", [{"capabilities": ["gpu"]}]),
248+
refusal_match="--gpus accepts any value and reserves nothing",
249+
nonsense_argv=["--gpus", "nonsense"],
250+
),
251+
]

‎tests/integration/test_podman_refusals.py‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,16 @@
1414

1515
from compose2pod.exceptions import UnsupportedComposeError
1616
from compose2pod.parsing import validate
17-
from tests.integration.refusals import LIMITATIONS, REFUSALS, Limitation, Refusal
17+
from tests.integration.refusals import (
18+
ABSENT_FLAGS,
19+
LIMITATIONS,
20+
REFUSALS,
21+
STUB_FLAGS,
22+
AbsentFlag,
23+
Limitation,
24+
Refusal,
25+
StubFlag,
26+
)
1827

1928

2029
def _resolve(argv: list[str], host: Path) -> list[str]:
@@ -46,9 +55,37 @@ def test_a_tracked_limitation_names_a_mount_podman_would_have_made(
4655
validate(limitation.compose)
4756

4857
source = tmp_path / limitation.host_dir
49-
source.mkdir(parents=True)
58+
source.mkdir(parents=True, exist_ok=True)
5059
argv = _resolve(limitation.podman_argv, source)
5160

5261
assert probe_podman(f"{limitation.id} [limitation]", argv) == 0, (
5362
"podman refuses this mount too, so it is rule two and belongs in REFUSALS"
5463
)
64+
65+
66+
@pytest.mark.parametrize("absent", ABSENT_FLAGS, ids=lambda absent: absent.id)
67+
def test_a_refusal_citing_no_flag_names_flags_podman_does_not_have(
68+
absent: AbsentFlag, probe_podman: Callable[[str, list[str]], int]
69+
) -> None:
70+
with pytest.raises(UnsupportedComposeError, match=absent.refusal_match):
71+
validate(absent.compose)
72+
73+
assert probe_podman(f"{absent.id} [control]", []) == 0, (
74+
"the bare control run failed, so every argv below would look absent whatever podman has"
75+
)
76+
for argv in absent.unknown_argv:
77+
assert probe_podman(f"{absent.id} {argv[0]}", argv) != 0, (
78+
"podman took this flag, so it has an equivalent and the refusal needs re-examining"
79+
)
80+
81+
82+
@pytest.mark.parametrize("stub", STUB_FLAGS, ids=lambda stub: stub.id)
83+
def test_a_refusal_citing_a_stub_flag_names_one_podman_does_not_validate(
84+
stub: StubFlag, probe_podman: Callable[[str, list[str]], int]
85+
) -> None:
86+
with pytest.raises(UnsupportedComposeError, match=stub.refusal_match):
87+
validate(stub.compose)
88+
89+
assert probe_podman(stub.id, stub.nonsense_argv) == 0, (
90+
"podman rejected deliberate nonsense, so the flag validates something after all"
91+
)

‎tests/test_parsing.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ def test_nested_option_rejects(self) -> None:
220220
),
221221
(
222222
{"type": "volume", "source": "v", "target": "/d", "volume": {"nocopy": True}},
223-
r"'nocopy' is not supported",
223+
r"use the short syntax, which emits -v",
224224
{"v": {}},
225225
),
226226
# per-option schema

‎tests/test_resources.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,11 +63,11 @@ def test_unsupported_limit_key_rejected(self) -> None:
6363
validate_deploy("app", _svc({"resources": {"limits": {"gpus": 1}}}))
6464

6565
def test_reservations_cpus_rejected(self) -> None:
66-
with pytest.raises(UnsupportedComposeError, match=r"reservations.cpus is not supported"):
66+
with pytest.raises(UnsupportedComposeError, match=r"podman run has no reservation flag for it"):
6767
validate_deploy("app", _svc({"resources": {"reservations": {"cpus": "0.5"}}}))
6868

6969
def test_reservations_devices_rejected(self) -> None:
70-
with pytest.raises(UnsupportedComposeError, match=r"reservations.devices is not supported"):
70+
with pytest.raises(UnsupportedComposeError, match=r"--gpus accepts any value and reserves nothing"):
7171
validate_deploy("app", _svc({"resources": {"reservations": {"devices": []}}}))
7272

7373
def test_limit_value_bool_rejected(self) -> None:

0 commit comments

Comments
 (0)