"""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 # 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), ], ) 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", } 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_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