crazy-workers 1.4.2__tar.gz → 1.5.1__tar.gz

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crazy-workers
-Version: 1.4.2
+Version: 1.5.1
 Summary: A Python library for managing background worker processes with persistent state, automatic recovery, and a CLI.
 Author: GioVanni Colasanto
 License: MIT
@@ -76,9 +76,11 @@ pip install .
 
 ```python
 # workers/my_worker.py
-import json, sys, time
+import time
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+from crazy_workers import parse_params
+
+params = parse_params()
 duration = params.get('duration', 60)
 
 for _ in range(duration):
@@ -176,15 +178,28 @@ Closes the database connection and clears internal process references. Does **no
 
 ## Worker Script Contract
 
-A worker receives its parameters as a JSON string in `sys.argv[1]`:
+A worker receives its parameters as a JSON string in `sys.argv[1]`. Use
+`parse_params` instead of decoding it by hand:
 
 ```python
-import json, sys
+from crazy_workers import parse_params
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+params = parse_params()
 # ... do work ...
 ```
 
+Without arguments it is lenient: a worker launched with no parameters gets
+`{}`. Pass `required=` to abort before any real work when a parameter the
+worker cannot run without is missing or empty — the worker exits with code 1
+and a message on stderr:
+
+```python
+params = parse_params(required=('device_id', 'output_dir'))
+```
+
+`parse_params(argv=...)` accepts an explicit argv list, which makes the
+parsing trivially testable without patching `sys.argv`.
+
 A worker is a separate process, so it cannot be handed a live object (e.g. a DB
 connection). Pass **configuration** instead: the manager's `worker_env` (and any
 per-call `env`) is injected as environment variables, so a worker reads, say,

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/README.md

@@ -41,9 +41,11 @@ pip install .
 
 ```python
 # workers/my_worker.py
-import json, sys, time
+import time
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+from crazy_workers import parse_params
+
+params = parse_params()
 duration = params.get('duration', 60)
 
 for _ in range(duration):
@@ -141,15 +143,28 @@ Closes the database connection and clears internal process references. Does **no
 
 ## Worker Script Contract
 
-A worker receives its parameters as a JSON string in `sys.argv[1]`:
+A worker receives its parameters as a JSON string in `sys.argv[1]`. Use
+`parse_params` instead of decoding it by hand:
 
 ```python
-import json, sys
+from crazy_workers import parse_params
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+params = parse_params()
 # ... do work ...
 ```
 
+Without arguments it is lenient: a worker launched with no parameters gets
+`{}`. Pass `required=` to abort before any real work when a parameter the
+worker cannot run without is missing or empty — the worker exits with code 1
+and a message on stderr:
+
+```python
+params = parse_params(required=('device_id', 'output_dir'))
+```
+
+`parse_params(argv=...)` accepts an explicit argv list, which makes the
+parsing trivially testable without patching `sys.argv`.
+
 A worker is a separate process, so it cannot be handed a live object (e.g. a DB
 connection). Pass **configuration** instead: the manager's `worker_env` (and any
 per-call `env`) is injected as environment variables, so a worker reads, say,

crazy_workers-1.5.1/crazy_workers/__init__.py

@@ -0,0 +1,24 @@
+__all__ = ['WorkerManager', 'WorkerClient', 'WorkerStatus', 'DesiredStatus', 'parse_params']
+
+
+# Resolve exports lazily (PEP 562) so a worker doing `from crazy_workers import
+# parse_params` only imports the lightweight params module — not the control
+# plane (WorkerClient/WorkerManager) and its heavy SQLAlchemy dependencies.
+def __getattr__(name):
+  if name == 'parse_params':
+    from .params import parse_params
+
+    return parse_params
+  if name == 'WorkerManager':
+    from .core.manager import WorkerManager
+
+    return WorkerManager
+  if name == 'WorkerClient':
+    from .client import WorkerClient
+
+    return WorkerClient
+  if name in ('DesiredStatus', 'WorkerStatus'):
+    from .database import schema
+
+    return getattr(schema, name)
+  raise AttributeError(f'module {__name__!r} has no attribute {name!r}')

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/crazy_workers/cli/commands/status.py

@@ -6,12 +6,13 @@ from datetime import datetime
 from rich.panel import Panel
 from rich.table import Table
 
+from ...core.engine import resolve_system_pid
 from ..ui import console
 
 
 def show_status(client, workers_dir, json_mode=False):
   """Observability hub: the target state store plus the worker table (desired vs actual)."""
-  workers = _merge_with_filesystem(client.list(), workers_dir)
+  workers = _with_system_pids(_merge_with_filesystem(client.list(), workers_dir))
 
   if json_mode:
     sys.stdout.write(json.dumps({'workers': workers}) + '\n')
@@ -70,6 +71,25 @@ def _merge_with_filesystem(db_workers, workers_dir):
   return results
 
 
+def _with_system_pids(workers):
+  results = []
+  for worker in workers:
+    enriched = dict(worker)
+    enriched['system_pid'] = resolve_system_pid(enriched.get('pid'), worker_key=enriched.get('worker_key'))
+    results.append(enriched)
+  return results
+
+
+def _format_pid(worker):
+  pid = worker.get('pid')
+  system_pid = worker.get('system_pid')
+  if not pid:
+    return '-'
+  if system_pid and system_pid != pid:
+    return f'{system_pid} [dim](ns {pid})[/dim]'
+  return str(pid)
+
+
 def _build_table(workers):
   table = Table(
     title='[bold cyan]Workers — desired vs actual[/bold cyan]', border_style='cyan', header_style='bold magenta'
@@ -114,7 +134,7 @@ def _build_table(workers):
       w['worker_type'],
       f'[{desired_style}]{desired}[/{desired_style}]',
       f'[{status_style}]{status}[/{status_style}]',
-      str(w['pid']) if w['pid'] else '-',
+      _format_pid(w),
       last_action,
       params_str,
     )

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/crazy_workers/core/engine.py

@@ -1,4 +1,5 @@
 import logging
+import os
 import psutil
 import subprocess
 
@@ -64,6 +65,81 @@ def is_process_running(pid):
     return False
 
 
+def resolve_system_pid(pid, worker_key=None):
+  """Return the most-native PID visible for ``pid``.
+
+  ``pid`` remains the control PID used by the current process namespace. On
+  Linux, ``CRAZY_WORKERS_HOST_PROC`` can point at a read-only host procfs mount
+  (for example /host/proc in Docker) so status can show the host PID. Without
+  that mount, /proc exposes NSpid when PID namespaces are visible; its first
+  value is the PID in the outermost namespace visible to this procfs mount. On
+  Windows and ordinary Linux hosts this is just ``pid``.
+  """
+  if pid is None:
+    return None
+  if os.name != 'posix':
+    return pid
+
+  host_pid = _resolve_from_host_proc(pid, worker_key=worker_key)
+  if host_pid is not None:
+    return host_pid
+
+  try:
+    with open(f'/proc/{pid}/status', encoding='utf-8') as f:
+      for line in f:
+        if line.startswith('NSpid:'):
+          values = [int(value) for value in line.split()[1:]]
+          return values[0] if values else pid
+  except (OSError, ValueError):
+    return pid
+
+  return pid
+
+
+def _resolve_from_host_proc(pid, worker_key=None):
+  host_proc = os.environ.get('CRAZY_WORKERS_HOST_PROC')
+  if not host_proc:
+    return None
+  if not os.path.isdir(host_proc):
+    return None
+
+  for entry in os.listdir(host_proc):
+    if not entry.isdigit():
+      continue
+
+    status_path = os.path.join(host_proc, entry, 'status')
+    try:
+      with open(status_path, encoding='utf-8') as f:
+        nspid = _read_nspid(f)
+    except (OSError, ValueError):
+      continue
+
+    if not nspid or nspid[-1] != pid:
+      continue
+    if worker_key and not _host_proc_cmdline_matches(host_proc, entry, worker_key):
+      continue
+    return nspid[0]
+
+  return None
+
+
+def _read_nspid(lines):
+  for line in lines:
+    if line.startswith('NSpid:'):
+      return [int(value) for value in line.split()[1:]]
+  return None
+
+
+def _host_proc_cmdline_matches(host_proc, host_pid, worker_key):
+  try:
+    with open(os.path.join(host_proc, host_pid, 'cmdline'), 'rb') as f:
+      raw = f.read()
+  except OSError:
+    return False
+  parts = [part.decode(errors='ignore') for part in raw.split(b'\0') if part]
+  return worker_key_token(worker_key) in parts
+
+
 def terminate_process(pid, timeout=5, popen_process=None, exclude_pids=None):
   """Gracefully terminates a process and its non-managed children.
 

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/crazy_workers/core/manager/__init__.py

@@ -107,8 +107,8 @@ class WorkerManager:
     else:
       self.storage = None
 
-  def start_worker(self, worker_type, worker_key=None, parameters=None, env=None):
-    return start_worker(self, worker_type, worker_key, parameters, env)
+  def start_worker(self, worker_type, worker_key=None, parameters=None, env=None, reset_backoff=True):
+    return start_worker(self, worker_type, worker_key, parameters, env, reset_backoff)
 
   def stop_worker(self, worker_key):
     return stop_worker(self, worker_key)

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/crazy_workers/core/manager/starter.py

@@ -19,7 +19,7 @@ logger = logging.getLogger('crazy_workers')
 _SAFE_NAME = re.compile(r'[A-Za-z0-9_-]+')
 
 
-def start_worker(manager, worker_type, worker_key=None, parameters=None, env=None):
+def start_worker(manager, worker_type, worker_key=None, parameters=None, env=None, reset_backoff=True):
   if not manager.storage:
     return False, 'System not initialized (database missing)'
 
@@ -43,7 +43,7 @@ def start_worker(manager, worker_type, worker_key=None, parameters=None, env=Non
       worker.status = WorkerStatus.STOPPED
       return False, f'Worker file {worker_type}.py not found'
 
-    return _spawn_worker_process(manager, worker, worker_path, parameters, env, session)
+    return _spawn_worker_process(manager, worker, worker_path, parameters, env, session, reset_backoff)
 
 
 def _validate_inputs(worker_type, worker_key):
@@ -107,7 +107,7 @@ def _get_worker_script_path(manager, worker_type):
   return worker_path
 
 
-def _spawn_worker_process(manager, worker, worker_path, parameters, env, session):
+def _spawn_worker_process(manager, worker, worker_path, parameters, env, session, reset_backoff=True):
   log_file_path = os.path.join(manager.logs_dir, f'{worker.worker_key}.log')
 
   # The manager's worker_env is the baseline for every worker (e.g. the host
@@ -132,8 +132,13 @@ def _spawn_worker_process(manager, worker, worker_path, parameters, env, session
   worker.pid = handle.pid
   worker.status = WorkerStatus.RUNNING
   worker.last_started_at = func.now()
-  # A clean start clears the crash backoff so the next failure starts over.
-  worker.restart_count = 0
+  # A clean start (CLI/client/manual restart) clears the crash backoff so the
+  # next failure starts over. An automatic reconciler restart passes
+  # reset_backoff=False: a fast crash-loop must keep accumulating restart_count
+  # across respawns, otherwise the exponential backoff can never escalate. The
+  # reconciler instead resets the counter once the worker is observed healthy.
+  if reset_backoff:
+    worker.restart_count = 0
   session.commit()
 
   manager._active_processes[worker.worker_key] = handle

crazy_workers-1.5.1/crazy_workers/daemon/reconciler.py

@@ -0,0 +1,181 @@
+import logging
+import time
+from datetime import datetime, timedelta, timezone
+
+from ..database.schema import DesiredStatus, Worker, WorkerStatus
+
+
+logger = logging.getLogger('crazy_workers')
+
+_BACKOFF_BASE_SECONDS = 1
+_BACKOFF_MAX_SECONDS = 60
+# Cap the exponent so a long-crashed worker doesn't compute an astronomically
+# large intermediate before min() clamps it.
+_BACKOFF_MAX_EXPONENT = 16
+
+
+class Reconciler:
+  """Single-owner loop: drives actual worker state toward desired state.
+
+  Owns every worker process for one workers_dir/DB. Clients never spawn; they
+  only set desired_status in the shared DB and this loop makes it so.
+
+  | desired  | alive | observed        | action                                     |
+  |----------|-------|-----------------|--------------------------------------------|
+  | RUNNING  | no    | RUNNING         | record crash (mark CRASHED, +restart_count)|
+  | RUNNING  | no    | other           | start (skipped while in backoff)           |
+  | RUNNING  | yes   | RUNNING         | noop (reset backoff once proven healthy)   |
+  | RUNNING  | yes   | other           | heal observed status to RUNNING            |
+  | STOPPED  | yes   | -               | stop                                       |
+  | STOPPED  | no    | RUNNING/CRASHED | heal stale observed status to STOPPED      |
+  | STOPPED  | no    | STOPPED         | noop                                       |
+
+  Crash detection is split from the restart on purpose. A worker that dies the
+  instant it starts comes back from ``start_worker`` marked RUNNING; if the same
+  pass that noticed the dead PID respawned it, its status would flip to RUNNING
+  again before the backoff branch ever saw CRASHED, and an instantly-crashing
+  worker would respawn at full loop speed forever. Instead the first pass records
+  the death (CRASHED + a bumped restart_count), and a later pass restarts it once
+  the exponential backoff has elapsed.
+  """
+
+  def __init__(self, manager, interval=2.0):
+    self.manager = manager
+    self.interval = interval
+    self._stop = False
+
+  def run_forever(self):
+    logger.info('Reconciler started (interval=%ss)', self.interval)
+    while not self._stop:
+      try:
+        self.reconcile_once()
+      except Exception:
+        logger.exception('Reconcile pass failed; continuing.')
+      # Sleep in small slices so a SIGTERM-triggered stop is honoured promptly
+      # instead of after a full interval.
+      self._interruptible_sleep(self.interval)
+    logger.info('Reconciler stopped.')
+
+  def stop(self):
+    self._stop = True
+
+  def _interruptible_sleep(self, seconds):
+    deadline = time.monotonic() + seconds
+    while not self._stop and time.monotonic() < deadline:
+      time.sleep(min(0.2, deadline - time.monotonic()))
+
+  def reconcile_once(self):
+    """One pass over every worker. Returns the actions taken (for tests/observability)."""
+    actions = []
+    for row in self._load_snapshot():
+      action = self._reconcile_worker(row)
+      if action:
+        actions.append((row['worker_key'], action))
+    return actions
+
+  def _load_snapshot(self):
+    # Read everything we need into plain dicts and release the session before
+    # touching processes — start/stop open their own short-lived sessions.
+    with self.manager.storage.session_scope() as session:
+      return [
+        {
+          'worker_key': w.worker_key,
+          'worker_type': w.worker_type,
+          'parameters': w.parameters,
+          'pid': w.pid,
+          'desired': w.desired_status,
+          'status': w.status,
+          'restart_count': w.restart_count,
+          'last_exit_at': w.last_exit_at,
+        }
+        for w in session.query(Worker).all()
+      ]
+
+  def _reconcile_worker(self, row):
+    alive = self.manager.backend.is_alive(pid=row['pid'], worker_key=row['worker_key'])
+
+    if row['desired'] == DesiredStatus.RUNNING and not alive:
+      if row['status'] == WorkerStatus.RUNNING:
+        # We last saw it RUNNING but the process is gone: it crashed. Record the
+        # death now and let a later pass restart it — see the class docstring for
+        # why detection and restart are split across passes.
+        logger.warning('Reconcile: worker %s died; recording crash', row['worker_key'])
+        self._record_crash(row['worker_key'])
+        return 'crashed'
+      if self._in_backoff(row):
+        return None
+      logger.info('Reconcile: starting %s', row['worker_key'])
+      # reset_backoff=False: an automatic restart must not wipe the crash history
+      # a fast crash-loop is accumulating, or the backoff could never escalate.
+      self.manager.start_worker(row['worker_type'], row['worker_key'], row['parameters'], reset_backoff=False)
+      return 'start'
+    if row['desired'] == DesiredStatus.STOPPED:
+      if alive:
+        logger.info('Reconcile: stopping %s', row['worker_key'])
+        self.manager.stop_worker(row['worker_key'])
+        return 'stop'
+      if row['status'] not in (WorkerStatus.STOPPED, WorkerStatus.NEVER_STARTED):
+        # Desired down and the process is already gone, but the observed status is
+        # stale — RUNNING left by the last spawn, or CRASHED. Nothing kills the
+        # process (it is dead) and stop_worker only handles a RUNNING worker, so
+        # converge the observed status here, or the table shows a phantom
+        # RUNNING/CRASHED with a dead PID forever.
+        self._mark_stopped(row['worker_key'])
+        return 'mark_stopped'
+      return None
+    if row['desired'] == DesiredStatus.RUNNING and alive:
+      if row['status'] != WorkerStatus.RUNNING:
+        # Process is up but the observed status drifted (e.g. left STARTING). Heal it.
+        self._mark_running(row['worker_key'])
+        return 'mark_running'
+      if row['restart_count']:
+        # Alive a full pass after its last spawn — proven healthy. Clear the crash
+        # backoff so a future crash starts counting (and backing off) from zero.
+        self._reset_backoff(row['worker_key'])
+        return 'reset_backoff'
+    return None
+
+  def _in_backoff(self, row):
+    if not row['last_exit_at'] or row['status'] != WorkerStatus.CRASHED:
+      return False
+    exponent = min(row['restart_count'], _BACKOFF_MAX_EXPONENT)
+    delay = min(_BACKOFF_BASE_SECONDS * (2**exponent), _BACKOFF_MAX_SECONDS)
+    last_exit = row['last_exit_at']
+    # last_exit_at is stored as UTC wall-clock; coerce naive values read back
+    # from the DB to aware UTC so the comparison never mixes naive and aware.
+    if last_exit.tzinfo is None:
+      last_exit = last_exit.replace(tzinfo=timezone.utc)
+    return datetime.now(timezone.utc) < last_exit + timedelta(seconds=delay)
+
+  def _mark_running(self, worker_key):
+    with self.manager.storage.session_scope() as session:
+      worker = session.query(Worker).filter_by(worker_key=worker_key).first()
+      if worker:
+        worker.status = WorkerStatus.RUNNING
+
+  def _record_crash(self, worker_key):
+    # Persist the death so the next pass's backoff gate can see it: mark CRASHED,
+    # bump the restart counter and stamp the exit time in UTC (Python-side, so the
+    # backoff math does not depend on the DB dialect's now()/timezone semantics).
+    # pid is cleared so we stop probing a dead (and potentially reused) PID.
+    with self.manager.storage.session_scope() as session:
+      worker = session.query(Worker).filter_by(worker_key=worker_key).first()
+      if worker:
+        worker.status = WorkerStatus.CRASHED
+        worker.last_exit_at = datetime.now(timezone.utc)
+        worker.restart_count = (worker.restart_count or 0) + 1
+        worker.pid = None
+
+  def _reset_backoff(self, worker_key):
+    with self.manager.storage.session_scope() as session:
+      worker = session.query(Worker).filter_by(worker_key=worker_key).first()
+      if worker:
+        worker.restart_count = 0
+
+  def _mark_stopped(self, worker_key):
+    with self.manager.storage.session_scope() as session:
+      worker = session.query(Worker).filter_by(worker_key=worker_key).first()
+      if worker:
+        worker.status = WorkerStatus.STOPPED
+        worker.pid = None
+        worker.last_stopped_at = datetime.now(timezone.utc)

crazy_workers-1.5.1/crazy_workers/params.py

@@ -0,0 +1,45 @@
+"""Worker-side parsing of the JSON parameters the daemon passes on argv.
+
+The manager spawns every worker as ``python -m crazy_workers._bootstrap
+<worker_path> <json_params>`` and the bootstrap restores ``sys.argv`` to
+``[worker_path, json_params]``. This module is the worker-side counterpart of
+that contract: call :func:`parse_params` at the top of a worker's ``main()``
+instead of re-implementing the argv/JSON boilerplate in every worker script.
+"""
+
+import json
+import sys
+
+
+def parse_params(argv=None, required=()):
+  """Return the parameters dict the daemon passed to this worker.
+
+  Without ``required`` a worker launched with no parameters gets ``{}`` — the
+  lenient mode for workers whose parameters are all optional. With ``required``
+  a missing argv, malformed JSON, or a missing/empty required key aborts the
+  worker with a message on stderr (``SystemExit``, exit code 1) before it does
+  any real work. A key counts as missing when it is absent, ``None``, or an
+  empty string; a falsy-but-present value like ``0`` or ``False`` is kept.
+
+  ``argv`` defaults to ``sys.argv``; pass a list explicitly in tests.
+  """
+  argv = sys.argv if argv is None else argv
+
+  if len(argv) < 2:
+    if required:
+      raise SystemExit(f'Missing required parameters: {", ".join(required)}')
+    return {}
+
+  try:
+    params = json.loads(argv[1])
+  except json.JSONDecodeError as error:
+    raise SystemExit(f'Invalid JSON parameters: {error}')
+
+  if not isinstance(params, dict):
+    raise SystemExit('Invalid JSON parameters: expected a JSON object')
+
+  missing = [key for key in required if key not in params or params[key] in (None, '')]
+  if missing:
+    raise SystemExit(f'Missing required parameters: {", ".join(missing)}')
+
+  return params

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/crazy_workers.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crazy-workers
-Version: 1.4.2
+Version: 1.5.1
 Summary: A Python library for managing background worker processes with persistent state, automatic recovery, and a CLI.
 Author: GioVanni Colasanto
 License: MIT
@@ -76,9 +76,11 @@ pip install .
 
 ```python
 # workers/my_worker.py
-import json, sys, time
+import time
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+from crazy_workers import parse_params
+
+params = parse_params()
 duration = params.get('duration', 60)
 
 for _ in range(duration):
@@ -176,15 +178,28 @@ Closes the database connection and clears internal process references. Does **no
 
 ## Worker Script Contract
 
-A worker receives its parameters as a JSON string in `sys.argv[1]`:
+A worker receives its parameters as a JSON string in `sys.argv[1]`. Use
+`parse_params` instead of decoding it by hand:
 
 ```python
-import json, sys
+from crazy_workers import parse_params
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+params = parse_params()
 # ... do work ...
 ```
 
+Without arguments it is lenient: a worker launched with no parameters gets
+`{}`. Pass `required=` to abort before any real work when a parameter the
+worker cannot run without is missing or empty — the worker exits with code 1
+and a message on stderr:
+
+```python
+params = parse_params(required=('device_id', 'output_dir'))
+```
+
+`parse_params(argv=...)` accepts an explicit argv list, which makes the
+parsing trivially testable without patching `sys.argv`.
+
 A worker is a separate process, so it cannot be handed a live object (e.g. a DB
 connection). Pass **configuration** instead: the manager's `worker_env` (and any
 per-call `env`) is injected as environment variables, so a worker reads, say,

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/crazy_workers.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 crazy_workers/__init__.py
 crazy_workers/_bootstrap.py
 crazy_workers/client.py
+crazy_workers/params.py
 crazy_workers.egg-info/PKG-INFO
 crazy_workers.egg-info/SOURCES.txt
 crazy_workers.egg-info/dependency_links.txt
@@ -45,4 +46,5 @@ crazy_workers/database/schema.py
 crazy_workers/database/storage.py
 crazy_workers/testing/__init__.py
 crazy_workers/testing/backends.py
-crazy_workers/testing/polling.py
+crazy_workers/testing/polling.py
+tests/test_params.py

{crazy_workers-1.4.2 → crazy_workers-1.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crazy-workers"
-version = "1.4.2"
+version = "1.5.1"
 description = "A Python library for managing background worker processes with persistent state, automatic recovery, and a CLI."
 readme = "README.md"
 authors = [{ name = "GioVanni Colasanto" }]
@@ -63,7 +63,7 @@ omit = ["*/venv/*", "*/build/*", "tests/*"]
 [tool.coverage.report]
 show_missing = true
 skip_covered = false
-fail_under = 95
+fail_under = 90
 
 [tool.ruff]
 line-length = 120

crazy_workers-1.5.1/tests/test_params.py

@@ -0,0 +1,51 @@
+import unittest
+from unittest.mock import patch
+
+from crazy_workers import parse_params
+
+
+class TestParseParams(unittest.TestCase):
+  def test_no_argv_returns_empty_dict(self):
+    self.assertEqual(parse_params(['worker.py']), {})
+
+  def test_no_argv_with_required_exits(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py'], required=('device_id', 'output_dir'))
+    self.assertEqual(ctx.exception.code, 'Missing required parameters: device_id, output_dir')
+
+  def test_invalid_json_exits(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py', 'not json'])
+    self.assertIn('Invalid JSON parameters', str(ctx.exception.code))
+
+  def test_non_object_json_exits(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py', '[1, 2, 3]'])
+    self.assertEqual(ctx.exception.code, 'Invalid JSON parameters: expected a JSON object')
+
+  def test_returns_parsed_params(self):
+    self.assertEqual(parse_params(['worker.py', '{"device_id": "7"}']), {'device_id': '7'})
+
+  def test_required_present_returns_params(self):
+    argv = ['worker.py', '{"device_id": "7", "output_dir": "/out"}']
+    params = parse_params(argv, required=('device_id', 'output_dir'))
+    self.assertEqual(params, {'device_id': '7', 'output_dir': '/out'})
+
+  def test_required_missing_exits_naming_keys(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py', '{"device_id": "7"}'], required=('device_id', 'output_dir'))
+    self.assertEqual(ctx.exception.code, 'Missing required parameters: output_dir')
+
+  def test_required_empty_value_counts_as_missing(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py', '{"device_id": ""}'], required=('device_id',))
+    self.assertEqual(ctx.exception.code, 'Missing required parameters: device_id')
+
+  def test_required_falsy_but_present_value_is_kept(self):
+    argv = ['worker.py', '{"retries": 0, "verbose": false}']
+    params = parse_params(argv, required=('retries', 'verbose'))
+    self.assertEqual(params, {'retries': 0, 'verbose': False})
+
+  def test_defaults_to_sys_argv(self):
+    with patch('sys.argv', ['worker.py', '{"interval": 5}']):
+      self.assertEqual(parse_params(), {'interval': 5})

crazy_workers-1.4.2/crazy_workers/__init__.py

@@ -1,6 +0,0 @@
-from .client import WorkerClient
-from .core.manager import WorkerManager
-from .database.schema import DesiredStatus, WorkerStatus
-
-
-__all__ = ['WorkerManager', 'WorkerClient', 'WorkerStatus', 'DesiredStatus']

crazy_workers-1.4.2/crazy_workers/daemon/reconciler.py

@@ -1,118 +0,0 @@
-import logging
-import time
-from datetime import datetime, timedelta, timezone
-
-from ..database.schema import DesiredStatus, Worker, WorkerStatus
-
-
-logger = logging.getLogger('crazy_workers')
-
-_BACKOFF_BASE_SECONDS = 1
-_BACKOFF_MAX_SECONDS = 60
-# Cap the exponent so a long-crashed worker doesn't compute an astronomically
-# large intermediate before min() clamps it.
-_BACKOFF_MAX_EXPONENT = 16
-
-
-class Reconciler:
-  """Single-owner loop: drives actual worker state toward desired state.
-
-  Owns every worker process for one workers_dir/DB. Clients never spawn; they
-  only set desired_status in the shared DB and this loop makes it so.
-
-  | desired  | alive | action                              |
-  |----------|-------|-------------------------------------|
-  | RUNNING  | no    | start (skipped while in backoff)    |
-  | RUNNING  | yes   | noop (reconcile observed status)    |
-  | STOPPED  | yes   | stop                                |
-  | STOPPED  | no    | noop                                |
-  """
-
-  def __init__(self, manager, interval=2.0):
-    self.manager = manager
-    self.interval = interval
-    self._stop = False
-
-  def run_forever(self):
-    logger.info('Reconciler started (interval=%ss)', self.interval)
-    while not self._stop:
-      try:
-        self.reconcile_once()
-      except Exception:
-        logger.exception('Reconcile pass failed; continuing.')
-      # Sleep in small slices so a SIGTERM-triggered stop is honoured promptly
-      # instead of after a full interval.
-      self._interruptible_sleep(self.interval)
-    logger.info('Reconciler stopped.')
-
-  def stop(self):
-    self._stop = True
-
-  def _interruptible_sleep(self, seconds):
-    deadline = time.monotonic() + seconds
-    while not self._stop and time.monotonic() < deadline:
-      time.sleep(min(0.2, deadline - time.monotonic()))
-
-  def reconcile_once(self):
-    """One pass over every worker. Returns the actions taken (for tests/observability)."""
-    actions = []
-    for row in self._load_snapshot():
-      action = self._reconcile_worker(row)
-      if action:
-        actions.append((row['worker_key'], action))
-    return actions
-
-  def _load_snapshot(self):
-    # Read everything we need into plain dicts and release the session before
-    # touching processes — start/stop open their own short-lived sessions.
-    with self.manager.storage.session_scope() as session:
-      return [
-        {
-          'worker_key': w.worker_key,
-          'worker_type': w.worker_type,
-          'parameters': w.parameters,
-          'pid': w.pid,
-          'desired': w.desired_status,
-          'status': w.status,
-          'restart_count': w.restart_count,
-          'last_exit_at': w.last_exit_at,
-        }
-        for w in session.query(Worker).all()
-      ]
-
-  def _reconcile_worker(self, row):
-    alive = self.manager.backend.is_alive(pid=row['pid'], worker_key=row['worker_key'])
-
-    if row['desired'] == DesiredStatus.RUNNING and not alive:
-      if self._in_backoff(row):
-        return None
-      logger.info('Reconcile: starting %s', row['worker_key'])
-      self.manager.start_worker(row['worker_type'], row['worker_key'], row['parameters'])
-      return 'start'
-    if row['desired'] == DesiredStatus.STOPPED and alive:
-      logger.info('Reconcile: stopping %s', row['worker_key'])
-      self.manager.stop_worker(row['worker_key'])
-      return 'stop'
-    if row['desired'] == DesiredStatus.RUNNING and alive and row['status'] != WorkerStatus.RUNNING:
-      # Process is up but the observed status drifted (e.g. left STARTING). Heal it.
-      self._mark_running(row['worker_key'])
-      return 'mark_running'
-    return None
-
-  def _in_backoff(self, row):
-    if not row['last_exit_at'] or row['status'] != WorkerStatus.CRASHED:
-      return False
-    exponent = min(row['restart_count'], _BACKOFF_MAX_EXPONENT)
-    delay = min(_BACKOFF_BASE_SECONDS * (2**exponent), _BACKOFF_MAX_SECONDS)
-    last_exit = row['last_exit_at']
-    # last_exit_at is stored as UTC wall-clock; coerce naive values read back
-    # from the DB to aware UTC so the comparison never mixes naive and aware.
-    if last_exit.tzinfo is None:
-      last_exit = last_exit.replace(tzinfo=timezone.utc)
-    return datetime.now(timezone.utc) < last_exit + timedelta(seconds=delay)
-
-  def _mark_running(self, worker_key):
-    with self.manager.storage.session_scope() as session:
-      worker = session.query(Worker).filter_by(worker_key=worker_key).first()
-      if worker:
-        worker.status = WorkerStatus.RUNNING