flight-alloc 0.0.1__py3-none-any.whl

src/web/runner.py

@@ -0,0 +1,168 @@
+"""Runs Plan / Allocate on a background thread for the web UI.
+
+State lives in this process, so the stages run in-thread rather than in
+a subprocess — there is no workbook to hand off through. The UI fires
+POST /api/run and then polls GET /api/run/status until it settles.
+
+Run state is module-level: the server is single-process and serves one
+assigner.
+"""
+
+from __future__ import annotations
+
+import threading
+import traceback
+from dataclasses import dataclass, field
+from datetime import date as date_t
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+from ..state import AppState
+
+RunState = Literal["idle", "running", "ok", "failed"]
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CONFIG_PATH = REPO_ROOT / "configs" / "config.yml"
+
+
+@dataclass
+class _Run:
+    state: RunState = "idle"
+    step: str = ""
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    error: str = ""
+    counts: dict[str, int] = field(default_factory=dict)
+    cancelled: bool = False
+    """Set by Reset while a run is in flight. The worker checks it before
+    committing results, so a cancelled run leaves the freshly-cleared
+    state alone instead of repopulating it."""
+
+
+_run = _Run()
+_lock = threading.Lock()
+
+
+def status() -> dict[str, object]:
+    """Snapshot for ``GET /api/run/status``."""
+    with _lock:
+        elapsed = None
+        if _run.started_at:
+            end = _run.finished_at or datetime.now()
+            elapsed = round((end - _run.started_at).total_seconds(), 1)
+        return {
+            "state": _run.state,
+            "step": _run.step,
+            "started_at": _run.started_at.isoformat(timespec="seconds")
+            if _run.started_at else None,
+            "finished_at": _run.finished_at.isoformat(timespec="seconds")
+            if _run.finished_at else None,
+            "elapsed_s": elapsed,
+            "error": _run.error,
+            "counts": dict(_run.counts),
+        }
+
+
+def is_running() -> bool:
+    with _lock:
+        return _run.state == "running"
+
+
+def cancel() -> bool:
+    """Ask an in-flight run to discard its results. Returns True when a
+    run was actually in flight.
+
+    The solver runs under its own ``max_seconds`` ceiling, so the thread
+    finishes on its own shortly; marking it cancelled means whatever it
+    produces is thrown away rather than written over the state the
+    operator just reset.
+    """
+    with _lock:
+        if _run.state != "running":
+            return False
+        _run.cancelled = True
+        return True
+
+
+def trigger(state: AppState, d_day: date_t, sub_command: str) -> bool:
+    """Start a run on a background thread. Returns False when one is
+    already in flight."""
+    with _lock:
+        if _run.state == "running":
+            return False
+        _run.state = "running"
+        _run.step = sub_command
+        _run.started_at = datetime.now()
+        _run.finished_at = None
+        _run.error = ""
+        _run.counts = {}
+        _run.cancelled = False
+
+    thread = threading.Thread(
+        target=_worker, args=(state, d_day, sub_command),
+        name=f"flight-alloc-{sub_command}", daemon=True,
+    )
+    thread.start()
+    return True
+
+
+def _worker(state: AppState, d_day: date_t, sub_command: str) -> None:
+    counts: dict[str, int] = {}
+    error = ""
+    try:
+        counts = _dispatch(state, d_day, sub_command)
+    except FileNotFoundError as exc:
+        # A missing upload is an operator problem, not a crash — say so
+        # plainly rather than dumping a traceback into the UI.
+        error = str(exc)
+        print(f"[run] {sub_command} blocked: {error}")
+    except Exception as exc:  # noqa: BLE001
+        error = f"{type(exc).__name__}: {exc}"
+        traceback.print_exc()
+
+    with _lock:
+        cancelled = _run.cancelled
+        _run.finished_at = datetime.now()
+        _run.error = "" if cancelled else error
+        _run.counts = {} if cancelled else counts
+        _run.state = "ok" if (cancelled or not error) else "failed"
+        _run.cancelled = False
+
+    if cancelled:
+        # Results are discarded; the state the operator reset stands.
+        state.reset_results()
+        print(f"[run] {sub_command} finished but was cancelled — results dropped")
+
+
+def _dispatch(state: AppState, d_day: date_t, sub_command: str) -> dict[str, int]:
+    """Run one stage and return its counts."""
+    from ..plan import run as run_plan
+    from ..step1_clean_flights import run as run_step1
+    from ..step2_extract_roster import run as run_step2
+    from ..step3_allocate_flights import run as run_allocate
+
+    if sub_command == "plan":
+        run_plan(state, d_day, CONFIG_PATH)
+        return {"FLIGHTS": len(state.allocatable_cleaned()),
+                "STAFF": len(state.availability)}
+
+    if sub_command == "step1":
+        return {k.value: v for k, v in run_step1(state, d_day, CONFIG_PATH).items()}
+
+    if sub_command == "step2":
+        return run_step2(state, d_day, CONFIG_PATH)
+
+    if sub_command in ("step3", "allocate"):
+        return run_allocate(state, d_day, CONFIG_PATH, mode_label="Allocate")
+
+    if sub_command == "all":
+        # Plan first so cleaned flights + availability are rebuilt from
+        # the uploads, then solve on top of them.
+        run_plan(state, d_day, CONFIG_PATH)
+        return run_allocate(
+            state, d_day, CONFIG_PATH,
+            append_warnings=True, mode_label="Allocate",
+        )
+
+    raise ValueError(f"unknown run step: {sub_command!r}")

src/web/server.py

@@ -0,0 +1,185 @@
+"""The request loop and the launcher.
+
+Everything about *what* an endpoint does lives in ``api``; this module
+only knows how to get bytes off the socket, hand them to the router,
+and put the Response back on the wire. Adding an endpoint never touches
+this file.
+
+Served from stdlib http.server — no FastAPI / Flask / external deps, so
+it fits IT allow-list constraints and ships in the same PyInstaller
+bundle as the engine.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from .api import build_router
+from .core.responses import Response, bad_request
+from .core.router import Router
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+
+# Guard against an accidental multi-hundred-MB POST filling memory.
+MAX_UPLOAD_BYTES = 64 * 1024 * 1024
+
+logger = logging.getLogger("src.web")
+
+#: Built once at import; every request thread reads from it.
+ROUTER: Router = build_router()
+
+
+class Handler(BaseHTTPRequestHandler):
+    """One instance per request. Holds no state of its own — the shared
+    state is the module-level ``STATE`` singleton the handlers reach."""
+
+    server_version = "FlightAllocWeb/2.0"
+
+    # HTTP/1.1 keep-alive. The default HTTP/1.0 + Connection: close
+    # means a new TCP connection per request, and on Windows the
+    # loopback handshake (plus Defender's inspection of it) is slow
+    # enough that 5-6 cold connections on page load are noticeable.
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+        # DEBUG, not INFO: the console handler is set to INFO so the
+        # operator sees what happened ([upload], [reset], ...) without a
+        # line per request. On Windows every console write goes through
+        # the console driver, and one per request bottlenecks the loop.
+        logger.debug("%s - %s", self.client_address[0], format % args)
+
+    def address_string(self) -> str:
+        # The default can do a reverse DNS lookup on the client IP,
+        # which on some Windows setups adds 30s+ per request.
+        return self.client_address[0]
+
+    # ------------ the four verbs, all the same shape ------------
+
+    def do_GET(self) -> None:  # noqa: N802
+        self._handle("GET")
+
+    def do_POST(self) -> None:  # noqa: N802
+        self._handle("POST")
+
+    def do_PUT(self) -> None:  # noqa: N802
+        self._handle("PUT")
+
+    def do_DELETE(self) -> None:  # noqa: N802
+        self._handle("DELETE")
+
+    # ------------ plumbing ------------
+
+    def _handle(self, method: str) -> None:
+        try:
+            body = self._read_body()
+        except ValueError as exc:
+            self._send(bad_request(str(exc)))
+            return
+        self._send(ROUTER.dispatch(method, self.path, self.headers, body))
+
+    def _read_body(self) -> bytes:
+        length = int(self.headers.get("Content-Length", "0") or "0")
+        if length <= 0:
+            return b""
+        if length > MAX_UPLOAD_BYTES:
+            raise ValueError(
+                f"payload too large ({length / 1e6:.0f} MB); "
+                f"limit is {MAX_UPLOAD_BYTES / 1e6:.0f} MB"
+            )
+        return self.rfile.read(length)
+
+    def _send(self, response: Response) -> None:
+        try:
+            self.send_response(response.status)
+            self.send_header("Content-Type", response.content_type)
+            self.send_header("Content-Length", str(len(response.body)))
+            self.send_header("Cache-Control", "no-store")
+            for key, value in response.headers.items():
+                self.send_header(key, value)
+            self.end_headers()
+            self.wfile.write(response.body)
+        except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError):
+            # Browser bailed mid-response — common when the operator
+            # navigates or hits Reset while a poll is in flight. Don't
+            # flood stderr with the stack trace.
+            pass
+
+
+class WebServer(ThreadingHTTPServer):
+    """Threading so one slow request (a Reset, an in-flight poll) doesn't
+    block the others — a single page load fires 5-6 API calls in
+    parallel. ``daemon_threads`` so a hung handler doesn't keep the
+    process alive after Ctrl+C."""
+
+    daemon_threads = True
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Send this package's log to stdout.
+
+    The operational lines ([upload], [reset], [staged-form], ...) are the
+    only feedback an operator gets in the launcher window, so they need a
+    handler. Per-request access logs sit at DEBUG and stay off.
+    """
+    if logger.handlers:
+        return
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(level)
+    logger.propagate = False
+
+
+def serve(
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_PORT,
+    *,
+    open_browser: bool = True,
+) -> None:
+    """Run the server in the foreground. Ctrl+C exits cleanly."""
+    configure_logging()
+    from ..state import STATE
+    restored = STATE.load_persisted_rosters()
+    if restored:
+        logger.info("[rosters] restored %d saved roster file(s)", restored)
+    server = WebServer((host, port), Handler)
+    url = f"http://{host}:{port}/"
+    print(f"Flight Allocation console - {url}")
+    print("  Upload today's flight schedule from the dashboard;")
+    print("  the two roster files live in the Setup sidebar and are")
+    print("  remembered between runs (saved under data/rosters/).")
+    print("  Ctrl+C to stop.")
+    logger.debug("routes: %s", ", ".join(ROUTER.routes))
+
+    if open_browser:
+        threading.Timer(0.6, lambda: webbrowser.open(url)).start()
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nstopping...")
+    finally:
+        server.server_close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    p = argparse.ArgumentParser(prog="flight-alloc-web")
+    p.add_argument("--host", default=DEFAULT_HOST)
+    p.add_argument("--port", type=int, default=DEFAULT_PORT)
+    p.add_argument("--no-browser", action="store_true",
+                   help="do not auto-open the browser")
+    args = p.parse_args(argv)
+    serve(host=args.host, port=args.port, open_browser=not args.no_browser)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/zc_store.py

@@ -0,0 +1,221 @@
+"""On-disk Zone Controller list, one list per operating date.
+
+The rosters no longer carry ``/ZC`` in their cells; the assigner picks
+the Zone Controllers on the dashboard instead. That choice has to
+outlive a restart and has to be *updatable day to day* rather than
+re-entered from scratch every morning, so it is kept here.
+
+Rules
+-----
+* Each date has its own list. Editing a date never touches another one.
+* A date with no list of its own **inherits** the list of the most
+  recent earlier date ("carried over"). The assigner opens the day,
+  sees yesterday's ZCs pre-filled, and only adds / removes what changed.
+* The list a day is actually planned with is frozen onto that day (see
+  ``freeze``), so later edits to an earlier date cannot rewrite history.
+* A date whose list was deliberately emptied stays empty — it does not
+  fall back to an older date.
+* Removing someone also records them as *removed* for that date only.
+  That is what lets the assigner take a ZC off who was marked ``/ZC`` in
+  the roster file: they are not in the saved list, so without the record
+  there would be nothing to say "not a ZC today". Removals never carry
+  over, because a roster ``/ZC`` is a fact about one specific day.
+
+Layout::
+
+    data/zc_lists.json
+        {"2026-09-19": {"names": ["NAME ONE", "NAME TWO"],
+                        "removed": ["NAME THREE"]}, ...}
+
+(An older file that stores a bare list per date is still read.)
+
+Names are stored as displayed and matched case- and whitespace-
+insensitively, the same way override rows match names.
+
+Persistence is best-effort, like ``roster_store``: if the folder is
+read-only the lists keep working from memory and a warning is logged.
+Override the location with ``FLIGHT_ALLOC_DATA_DIR``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import tempfile
+import threading
+from datetime import date as date_t
+from pathlib import Path
+
+from .roster_store import data_dir
+
+logger = logging.getLogger("src.web")
+
+_lock = threading.RLock()
+_cache: dict[str, dict[str, list[str]]] | None = None
+_cache_path: Path | None = None
+
+
+def _path() -> Path:
+    return data_dir() / "zc_lists.json"
+
+
+def _norm(name: str) -> str:
+    return re.sub(r"\s+", " ", str(name or "")).strip().upper()
+
+
+def _clean(names: list[str]) -> list[str]:
+    """Trim, drop blanks, drop duplicates (case-insensitive), keep order."""
+    seen: set[str] = set()
+    out: list[str] = []
+    for n in names:
+        display = re.sub(r"\s+", " ", str(n or "")).strip()
+        key = _norm(display)
+        if not key or key in seen:
+            continue
+        seen.add(key)
+        out.append(display)
+    return out
+
+
+def _load() -> dict[str, dict[str, list[str]]]:
+    """The whole store, read from disk once per path (and again if
+    ``FLIGHT_ALLOC_DATA_DIR`` changes)."""
+    global _cache, _cache_path
+    path = _path()
+    with _lock:
+        if _cache is not None and _cache_path == path:
+            return _cache
+        data: dict[str, dict[str, list[str]]] = {}
+        if path.exists():
+            try:
+                raw = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as exc:
+                logger.warning("[zc] cannot read %s: %s", path, exc)
+                raw = {}
+            if isinstance(raw, dict):
+                for k, v in raw.items():
+                    try:
+                        date_t.fromisoformat(str(k))
+                    except ValueError:
+                        continue
+                    if isinstance(v, list):          # older format
+                        data[str(k)] = {"names": _clean([str(x) for x in v]), "removed": []}
+                    elif isinstance(v, dict):
+                        data[str(k)] = {
+                            "names": _clean([str(x) for x in v.get("names", [])]),
+                            "removed": _clean([str(x) for x in v.get("removed", [])]),
+                        }
+        _cache, _cache_path = data, path
+        return data
+
+
+def _write(data: dict[str, dict[str, list[str]]]) -> None:
+    """Atomic replace, so a crash mid-write can't leave a torn file."""
+    path = _path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                json.dump(dict(sorted(data.items())), fh, indent=2)
+            os.replace(tmp, path)
+        except OSError:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except OSError as exc:
+        logger.warning(
+            "[zc] could not persist the ZC list (%s) — it stays in memory only",
+            exc,
+        )
+
+
+def effective(d: date_t) -> tuple[list[str], str, date_t | None]:
+    """The list to use for ``d``.
+
+    Returns ``(names, source, carried_from)`` where ``source`` is
+    ``"saved"`` (the date has its own list), ``"carried"`` (inherited
+    from ``carried_from``) or ``"none"`` (nothing saved on or before
+    ``d``).
+    """
+    with _lock:
+        data = _load()
+        own = data.get(d.isoformat())
+        if own is not None:
+            return list(own["names"]), "saved", None
+        earlier = [k for k in data if k < d.isoformat()]
+        if earlier:
+            latest = max(earlier)
+            return list(data[latest]["names"]), "carried", date_t.fromisoformat(latest)
+        return [], "none", None
+
+
+def removed(d: date_t) -> list[str]:
+    """People explicitly taken off ZC on ``d`` (this date only, never
+    carried over)."""
+    with _lock:
+        own = _load().get(d.isoformat())
+        return list(own["removed"]) if own else []
+
+
+def set_list(
+    d: date_t, names: list[str], *, removed_names: list[str] | None = None,
+) -> list[str]:
+    """Save ``names`` as the list for ``d`` (an empty list is a real,
+    deliberate answer and is kept). ``removed_names`` replaces the day's
+    removal record; left as ``None`` the existing one is kept, minus
+    anyone who is being put on the list."""
+    with _lock:
+        data = _load()
+        cleaned = _clean(names)
+        on_list = {_norm(n) for n in cleaned}
+        base = data.get(d.isoformat(), {}).get("removed", []) if removed_names is None else removed_names
+        data[d.isoformat()] = {
+            "names": cleaned,
+            "removed": [n for n in _clean(base) if _norm(n) not in on_list],
+        }
+        _write(data)
+        return list(cleaned)
+
+
+def add(d: date_t, name: str) -> list[str]:
+    """Add one person to ``d``'s list, starting from what ``d`` already
+    resolves to (so a carried-over list is seeded, then saved)."""
+    with _lock:
+        names, _, _ = effective(d)
+        return set_list(d, names + [name])
+
+
+def remove(d: date_t, name: str) -> list[str]:
+    """Take one person off ``d``'s list, and record them as removed for
+    that date so a roster ``/ZC`` for them is overridden too."""
+    with _lock:
+        names, _, _ = effective(d)
+        key = _norm(name)
+        return set_list(
+            d, [n for n in names if _norm(n) != key],
+            removed_names=removed(d) + [name],
+        )
+
+
+def freeze(d: date_t) -> bool:
+    """Pin an inherited list onto ``d`` itself. Called when the list is
+    actually applied to a plan, so tomorrow's carry-over starts from
+    what today really ran with. Returns True when something was written."""
+    with _lock:
+        names, source, _ = effective(d)
+        if source != "carried":
+            return False
+        set_list(d, names)
+        return True
+
+
+def _reset_for_tests() -> None:
+    """Drop the in-memory cache (tests point the store at a temp dir)."""
+    global _cache, _cache_path
+    with _lock:
+        _cache, _cache_path = None, None