"""The exit-code table of DESIGN.md §1.6. These are frozen: agents branch on them. The test states the table in full so a change to it is a change to this file. """ from __future__ import annotations import pytest from hhstream_session.client import ClientError, reply_exit_code from hhstreamd.protocol import EXIT_CODE_FOR_ERROR, ExitCode, exit_code_for def test_the_frozen_numbers(): assert ExitCode.OK == 0 assert ExitCode.USAGE == 2 assert ExitCode.NO_SUCH_SESSION == 3 assert ExitCode.BAD_STATE == 4 assert ExitCode.DAEMON_UNREACHABLE == 5 assert ExitCode.POLICY == 6 assert ExitCode.TIMEOUT == 7 assert ExitCode.BUSY == 8 assert ExitCode.NO_LEASE == 9 assert ExitCode.COMPOSITOR == 10 # 1 is deliberately absent: it is the shell's "something went wrong", and # reusing it would make an unhandled crash indistinguishable from a # documented outcome. assert 1 not in set(ExitCode) @pytest.mark.parametrize( "error,code", [ # 2 — usage ("bad_request", 2), ("unknown_op", 2), ("unsupported_version", 2), ("message_too_large", 2), ("invalid_argument", 2), # 3 — no such session ("no_such_session", 3), ("no_such_process", 3), # 4 — not in a usable state ("session_exited", 4), ("session_killed", 4), ("session_reaped", 4), ("session_starting", 4), ("compositor_lost", 4), ("bad_state", 4), ("pid_reuse_detected", 4), ("identity_unknown", 4), # 5 — daemon unreachable ("daemon_unreachable", 5), # 6 — refused by policy ("not_allowlisted", 6), ("argument_refused", 6), ("session_cap_reached", 6), ("refused", 6), # 7 — timed out ("timeout", 7), ("readiness_timeout", 7), # 8 — busy ("busy", 8), ("already_managed", 8), ("pointer_busy", 8), # 9 — the verb needs the lease and this session does not hold it ("no_lease", 9), # 10 — the compositor side failed; the session itself survives ("compositor", 10), ("compositor_unavailable", 10), ("no_container", 10), ("driver_unavailable", 10), ("driver_refused", 10), # 6 — the container band is full: a budget, not a compositor failure ("container_budget", 6), ], ) def test_every_error_name_maps_to_its_documented_code(error, code): assert exit_code_for(error) == code def test_the_table_has_no_entries_this_test_does_not_know_about(): """Adding an error name must mean adding it to the test above.""" documented = { "bad_request", "unknown_op", "unsupported_version", "message_too_large", "invalid_argument", "no_such_session", "no_such_process", "session_exited", "session_killed", "session_reaped", "session_starting", "compositor_lost", "bad_state", "pid_reuse_detected", "identity_unknown", "daemon_unreachable", "not_allowlisted", "argument_refused", "session_cap_reached", "refused", "timeout", "readiness_timeout", "busy", "already_managed", "pointer_busy", "container_budget", "no_lease", "compositor", "compositor_unavailable", "no_container", "driver_unavailable", "driver_refused", } assert set(EXIT_CODE_FOR_ERROR) == documented def test_success_is_zero(): assert exit_code_for(None) == 0 assert exit_code_for("") == 0 def test_losing_the_compositor_is_not_the_same_as_losing_the_session(): """Code 10 exists precisely so these two cannot be confused (PLAN §8.2). A session whose container could not be built is still running; one that exited is not. An agent that saw the same code for both would kill a healthy application to recover from a compositor hiccup. """ assert exit_code_for("compositor") == ExitCode.COMPOSITOR assert exit_code_for("session_exited") == ExitCode.BAD_STATE assert ExitCode.COMPOSITOR != ExitCode.BAD_STATE def test_a_missing_lease_and_a_held_one_are_different_codes(): """8 means "wait", 9 means "acquire". One code could not say both.""" assert exit_code_for("pointer_busy") == ExitCode.BUSY assert exit_code_for("no_lease") == ExitCode.NO_LEASE def test_an_unknown_error_degrades_to_not_usable_rather_than_to_success(): """A caller that does not recognise the failure must still not see a 0.""" assert exit_code_for("something_invented_next_year") == ExitCode.BAD_STATE def test_reply_exit_code_reads_a_decoded_reply(): assert reply_exit_code({"ok": True, "id": "a"}) == 0 assert reply_exit_code({"ok": False, "error": "no_such_session"}) == 3 assert reply_exit_code({"ok": False}) == ExitCode.BAD_STATE def test_client_errors_carry_their_own_code(): assert ClientError("daemon_unreachable", "no socket").exit_code == 5 assert ClientError("timeout", "no reply").exit_code == 7