hfhost 0.2.1__tar.gz → 0.4.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. {hfhost-0.2.1 → hfhost-0.4.2}/NOTICE +16 -8
  2. {hfhost-0.2.1 → hfhost-0.4.2}/PKG-INFO +1 -1
  3. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/__init__.py +1 -1
  4. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/client.py +57 -5
  5. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/ptc.py +2 -1
  6. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/wire.py +1 -1
  7. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost.egg-info/PKG-INFO +1 -1
  8. {hfhost-0.2.1 → hfhost-0.4.2}/pyproject.toml +3 -1
  9. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_client.py +56 -2
  10. {hfhost-0.2.1 → hfhost-0.4.2}/LICENSE +0 -0
  11. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/ardop.py +0 -0
  12. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/audio.py +0 -0
  13. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/cbor.py +0 -0
  14. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/config.py +0 -0
  15. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/hostapi.py +0 -0
  16. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/kiwi.py +0 -0
  17. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/link.py +0 -0
  18. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/rig.py +0 -0
  19. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/supervisor.py +0 -0
  20. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/testing/__init__.py +0 -0
  21. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/testing/bridge.py +0 -0
  22. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/testing/fakehostapi.py +0 -0
  23. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/testing/fakemodem.py +0 -0
  24. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/testing/hostapi_bridge.py +0 -0
  25. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost/transcript.py +0 -0
  26. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost.egg-info/SOURCES.txt +0 -0
  27. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost.egg-info/dependency_links.txt +0 -0
  28. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost.egg-info/requires.txt +0 -0
  29. {hfhost-0.2.1 → hfhost-0.4.2}/hfhost.egg-info/top_level.txt +0 -0
  30. {hfhost-0.2.1 → hfhost-0.4.2}/setup.cfg +0 -0
  31. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_ardop.py +0 -0
  32. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_audio.py +0 -0
  33. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_cbor.py +0 -0
  34. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_client_against_host.py +0 -0
  35. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_config_ports.py +0 -0
  36. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_hostapi.py +0 -0
  37. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_kiwi.py +0 -0
  38. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_ptc.py +0 -0
  39. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_rig.py +0 -0
  40. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_supervisor.py +0 -0
  41. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_transcript.py +0 -0
  42. {hfhost-0.2.1 → hfhost-0.4.2}/tests/test_wire.py +0 -0
@@ -3,19 +3,27 @@ Copyright (C) 2026 Saul St John (W9SSJ)
3
3
 
4
4
  The code is free software: you can redistribute it and/or modify it under the
5
5
  terms of the GNU Affero General Public License as published by the Free Software
6
- Foundation, version 3. See LICENSE for the full text.
7
-
8
- The documentation, the images and the project site are under the Creative
9
- Commons Attribution 4.0 International licence instead -- everything under docs/
10
- and site/, the protocol descriptions in docs/protocols/ included. See
11
- LICENSE-CC-BY-4.0 for the full text and
12
- https://creativecommons.org/licenses/by/4.0/ for the deed. Attribution is the
13
- whole of what it asks.
6
+ Foundation, version 3. See LICENSE for the full text. The documentation of the
7
+ software -- installing, configuring and operating it, its architecture, and the
8
+ implementation notes in docs/implementation/ -- is under the same licence.
9
+
10
+ The protocol descriptions and the project site are under the Creative Commons
11
+ Attribution 4.0 International licence instead: the waveforms, wire formats and
12
+ link behaviour set out in docs/protocols/, the illustrated guides in docs/viz/,
13
+ the notes in evidence/, and the pages under site/ (its build code stays AGPL).
14
+ Each file names its licence in its first lines, or in REUSE.toml when it cannot
15
+ carry one. See LICENSE-CC-BY-4.0 for the full
16
+ text and https://creativecommons.org/licenses/by/4.0/ for the deed. Attribution
17
+ is the whole of what it asks.
14
18
 
15
19
  That licence reaches this project's expression of the protocols it describes and
16
20
  not the facts of them, which are nobody's to license: an implementation written
17
21
  from these descriptions owes it nothing. See docs/protocols/LICENSE.md.
18
22
 
23
+ Recordings of on-air transmissions, this station's and other stations', and
24
+ data decoded from them, are listed in REUSE.toml as NOASSERTION. The project
25
+ claims no copyright in and assigns no licence to these files.
26
+
19
27
 
20
28
  ATTRIBUTION
21
29
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hfhost
3
- Version: 0.2.1
3
+ Version: 0.4.2
4
4
  Summary: Host clients for HF modems, including VARA-style TCP and Sabir framed CBOR
5
5
  License-Expression: AGPL-3.0-only
6
6
  Project-URL: Homepage, https://hfmodem.ssj.lol
@@ -3,4 +3,4 @@
3
3
 
4
4
  """hfhost — the host side of the VARA-style two-socket TCP modem interface."""
5
5
 
6
- __version__ = "0.2.1"
6
+ __version__ = "0.4.2"
@@ -127,14 +127,32 @@ class ModemClient:
127
127
  # -- attach / detach ---------------------------------------------------
128
128
 
129
129
  def attach(self, timeout: float | None = None) -> None:
130
+ """Obtain an acknowledged attachment within one shared deadline.
131
+
132
+ TCP connect alone can succeed while a prior probe's host session is
133
+ retiring. The server refuses that overlapping pair; retry only after
134
+ the failed pair has been closed, without extending the attach budget.
135
+ """
136
+ deadline = time.monotonic() + (self.attach_timeout_s if timeout is None
137
+ else timeout)
138
+ while True:
139
+ try:
140
+ self._attach_once(max(0., deadline - time.monotonic()))
141
+ return
142
+ except AttachError as exc:
143
+ remaining = deadline - time.monotonic()
144
+ if not isinstance(exc.__cause__, (ModemError, TimeoutError)) or remaining <= 0:
145
+ raise
146
+ time.sleep(min(.05, remaining))
147
+
148
+ def _attach_once(self, timeout: float) -> None:
130
149
  """Atomically connect both sockets, start readers, replay desired
131
150
  state. On any failure both sockets are closed — never a half-attach.
132
151
 
133
152
  Held across replay by _attaching (never by _life, which the reader
134
153
  threads need to detach) so that a concurrent caller seeing attached=True
135
154
  also sees the desired state landed, not MYCALL/BW still in flight."""
136
- deadline = time.monotonic() + (self.attach_timeout_s if timeout is None
137
- else timeout)
155
+ deadline = time.monotonic() + timeout
138
156
  with self._attaching:
139
157
  with self._life:
140
158
  if self._closed:
@@ -167,7 +185,14 @@ class ModemClient:
167
185
  daemon=True).start()
168
186
  self.transcript.state(self.name, "attached")
169
187
  try:
170
- self.replay(timeout=max(deadline - time.monotonic(), 1.0))
188
+ # VERSION does not alter configuration. Even an empty desired
189
+ # replay needs a round trip before attachment is ready.
190
+ remaining = deadline - time.monotonic()
191
+ if remaining <= 0:
192
+ raise TimeoutError(f"{self.name}: attach deadline exhausted")
193
+ if not self._acknowledge_attachment(remaining):
194
+ raise AttachError(f"{self.name}: attachment not acknowledged")
195
+ self.replay(_deadline=deadline)
171
196
  except (ModemError, TimeoutError) as exc:
172
197
  self._detach(gen, f"replay failed: {exc}", deliberate=True)
173
198
  self.attach_failures += 1
@@ -176,6 +201,30 @@ class ModemClient:
176
201
  if self.on_attach:
177
202
  self.on_attach(self)
178
203
 
204
+ def _acknowledge_attachment(self, timeout: float) -> bool:
205
+ """Prove a round trip without grading the target's VERSION grammar.
206
+
207
+ A target without VERSION support may answer WRONG. That still proves
208
+ this pair was admitted; conformance owns the version-shape verdict.
209
+ """
210
+ q = self.subscribe()
211
+ try:
212
+ self._send_cmd("VERSION")
213
+ deadline = time.monotonic() + timeout
214
+ while (remaining := deadline - time.monotonic()) > 0:
215
+ try:
216
+ item = q.get(timeout=remaining)
217
+ except queue.Empty:
218
+ return False
219
+ if item is _DETACHED:
220
+ return False
221
+ if (item.kind in (REPLY_OK, REPLY_WRONG)
222
+ or item.kind == NOTIFICATION and item.name == "VERSION"):
223
+ return True
224
+ return False
225
+ finally:
226
+ self.unsubscribe(q)
227
+
179
228
  def _dial(self, port: int, deadline: float) -> socket.socket:
180
229
  remaining = deadline - time.monotonic()
181
230
  if remaining <= 0:
@@ -338,7 +387,7 @@ class ModemClient:
338
387
  self._desired[slot] = text
339
388
  return self.command(text) if self.attached else None
340
389
 
341
- def replay(self, timeout: float = 5.0) -> None:
390
+ def replay(self, timeout: float = 5.0, *, _deadline: float | None = None) -> None:
342
391
  """Reissue all recorded desired state; attach() ends with this. A
343
392
  WRONG is transcribed as an error, not fatal — the responder's retry
344
393
  loop must not spin forever on a modem that rejects one setting."""
@@ -346,7 +395,10 @@ class ModemClient:
346
395
  text = self._desired.get(slot)
347
396
  if text is None:
348
397
  continue
349
- line = self.command(text, timeout)
398
+ remaining = timeout if _deadline is None else _deadline - time.monotonic()
399
+ if remaining <= 0:
400
+ raise TimeoutError(f"{self.name}: replay deadline exhausted")
401
+ line = self.command(text, remaining)
350
402
  if line.kind == REPLY_WRONG:
351
403
  self.transcript.error(self.name, f"replay rejected: {text}")
352
404
 
@@ -39,9 +39,10 @@ NACK_TIMEOUT = 0.25 # manual 10.9.3, a minimum
39
39
  # modem -> host response codes (manual 10.6 / WA8DED guide)
40
40
  OK, MSG, FAIL, LINK = 0, 1, 2, 3
41
41
  MON_HEADER, MON_HEADER_INFO, MON_INFO, DATA = 4, 5, 6, 7
42
+ SENT_ECHO = 8 # SCS %M1 expansion
42
43
 
43
44
  _STRING_CODES = (MSG, FAIL, LINK, MON_HEADER, MON_HEADER_INFO)
44
- _COUNTED_CODES = (MON_INFO, DATA)
45
+ _COUNTED_CODES = (MON_INFO, DATA, SENT_ECHO)
45
46
 
46
47
 
47
48
  class PtcError(Exception):
@@ -77,7 +77,7 @@ def _version(args: list[str]) -> dict | None:
77
77
 
78
78
 
79
79
  def _bitrate(args: list[str]) -> dict | None:
80
- # Spec §7.3: "BITRATE (N) x bps TX" / "... RX". Neither modem emits it yet.
80
+ # Spec §7.3: "BITRATE (N) x bps TX" / "... RX".
81
81
  if len(args) != 4:
82
82
  return None
83
83
  level, bps, unit, direction = args
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hfhost
3
- Version: 0.2.1
3
+ Version: 0.4.2
4
4
  Summary: Host clients for HF modems, including VARA-style TCP and Sabir framed CBOR
5
5
  License-Expression: AGPL-3.0-only
6
6
  Project-URL: Homepage, https://hfmodem.ssj.lol
@@ -1,10 +1,12 @@
1
+ # SPDX-License-Identifier: AGPL-3.0-only
2
+ # SPDX-FileCopyrightText: 2026 Saul St John (W9SSJ)
1
3
  [build-system]
2
4
  requires = ["setuptools>=77"]
3
5
  build-backend = "setuptools.build_meta"
4
6
 
5
7
  [project]
6
8
  name = "hfhost"
7
- version = "0.2.1"
9
+ version = "0.4.2"
8
10
  description = "Host clients for HF modems, including VARA-style TCP and Sabir framed CBOR"
9
11
  license = "AGPL-3.0-only"
10
12
  license-files = ["LICENSE", "NOTICE"]
@@ -7,6 +7,7 @@ desired-state replay, epoch fencing, cancellation, staleness."""
7
7
  import queue
8
8
  import threading
9
9
  import time
10
+ from types import SimpleNamespace
10
11
 
11
12
  import pytest
12
13
 
@@ -92,7 +93,60 @@ def test_attach_replays_desired_state(fake, client):
92
93
  assert client.attached
93
94
  assert fake.wait_attached()
94
95
  assert fake.session_log[0] == [
95
- "MYCALL N0CAL", "BW2300", "COMPRESSION OFF", "LISTEN ON"]
96
+ "VERSION", "MYCALL N0CAL", "BW2300", "COMPRESSION OFF", "LISTEN ON"]
97
+
98
+
99
+ def test_empty_replay_retries_a_refused_attachment(fake, client):
100
+ """A connected TCP pair can be refused while a probe is retiring."""
101
+ def refuse_first(cmd):
102
+ if fake.attach_count == 1:
103
+ fake.drop()
104
+ return []
105
+ return None
106
+
107
+ fake.on_command = refuse_first
108
+ client.attach()
109
+ assert fake.attach_count == 2
110
+ assert client.attached
111
+ assert fake.session_log == [["VERSION"], ["VERSION"]]
112
+
113
+
114
+ def test_attach_requires_acknowledgement_within_its_budget(fake, tr):
115
+ fake.on_command = lambda cmd: []
116
+ c = make_client(fake, tr, attach_timeout_s=.2)
117
+ try:
118
+ with pytest.raises(AttachError, match="not acknowledged"):
119
+ c.attach()
120
+ assert not c.attached
121
+ assert c._cmd_sock is None and c._data_sock is None
122
+ finally:
123
+ c.close()
124
+
125
+
126
+ @pytest.mark.parametrize("reply", ["OK", "WRONG"])
127
+ def test_attach_acknowledgement_does_not_grade_version_grammar(fake, client, reply):
128
+ fake.on_command = lambda cmd: reply
129
+ client.attach()
130
+ assert client.attached
131
+ assert fake.session_log[0] == ["VERSION"]
132
+
133
+
134
+ def test_attach_replay_spends_one_deadline(monkeypatch):
135
+ clock = [0.0]
136
+ seen = []
137
+
138
+ def command(text, timeout):
139
+ seen.append((text, timeout))
140
+ clock[0] += .6
141
+ return SimpleNamespace(kind=wire.REPLY_OK)
142
+
143
+ client = SimpleNamespace(name="deadline", _REPLAY_ORDER=("a", "b", "c"),
144
+ _desired={"a": "A", "b": "B", "c": "C"},
145
+ command=command)
146
+ monkeypatch.setattr("hfhost.client.time.monotonic", lambda: clock[0])
147
+ with pytest.raises(TimeoutError, match="deadline exhausted"):
148
+ ModemClient.replay(client, _deadline=1.0)
149
+ assert seen == [("A", 1.0), ("B", .4)]
96
150
 
97
151
 
98
152
  def test_attach_failure_leaves_no_half_attach(tr):
@@ -354,7 +408,7 @@ def test_concurrent_attach_waits_for_replay(fake, tr):
354
408
  gate.set()
355
409
  first.join(3.0)
356
410
  later.join(3.0)
357
- assert seen["log"] == ["MYCALL N0CAL", "BW2300", "LISTEN ON"]
411
+ assert seen["log"] == ["VERSION", "MYCALL N0CAL", "BW2300", "LISTEN ON"]
358
412
  finally:
359
413
  gate.set()
360
414
  c.close()
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes