flight-alloc 0.0.1__py3-none-any.whl

src/web/api/runs.py

@@ -0,0 +1,102 @@
+"""Starting a Plan / Allocate / Reset, and polling what's in flight.
+
+A run is kicked off on a worker thread and the UI polls
+``/api/run/status`` — the POST returns as soon as the run is accepted,
+so a slow solve never holds a request open.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date as date_t
+
+from ...state import STATE
+from .. import runner
+from ..core.responses import Response, bad_request, conflict, json_response
+from ..core.router import Request, Router
+
+logger = logging.getLogger("src.web")
+
+#: Sub-commands ``/api/run`` will accept.
+RUN_STEPS = {"all", "plan", "step1", "step2", "step3", "reset"}
+
+
+def parse_date(raw: str | None) -> date_t | None:
+    if not raw:
+        return None
+    try:
+        return date_t.fromisoformat(raw)
+    except ValueError:
+        return None
+
+
+def register(router: Router) -> None:
+
+    @router.get("/api/run/status")
+    def status(_req: Request) -> Response:
+        return json_response(runner.status())
+
+    @router.post("/api/run")
+    def run(req: Request) -> Response:
+        body = req.json()
+        step = body.get("step") if isinstance(body.get("step"), str) else "all"
+        if step not in RUN_STEPS:
+            return bad_request(f"step={step!r} not allowed")
+        if step == "reset":
+            return _reset()
+
+        d_day = parse_date(body.get("date"))
+        if d_day is None:
+            return bad_request("body.date required (YYYY-MM-DD)")
+
+        missing = STATE.missing_inputs()
+        if missing:
+            from ...state import INPUT_LABELS
+            names = ", ".join(INPUT_LABELS[k] for k in missing)
+            return conflict({
+                "error": f"upload the missing input file(s) first: {names}",
+                "missing": missing,
+            })
+
+        # Belt-and-suspenders: the dashboard is expected to grey out
+        # Allocate until P2F handlers are sorted (see plan.js /
+        # handlers.js), but a direct API call — or a stale tab — could
+        # still reach here. Only blocks when Plan has already run for
+        # this date (same date requested) with a real gap; never blocks
+        # the "all" step's own Plan phase when nothing's been planned
+        # yet, since that will surface the same gap in the Warnings tab
+        # after the solve.
+        if step in ("all", "step3") and d_day == STATE.run_date:
+            from .. import readback
+            handlers_state = readback.read_handlers(STATE)
+            if handlers_state.get("plan_has_run") and not handlers_state.get("ready"):
+                missing_shifts = handlers_state.get("missing_p2f_shifts", [])
+                return conflict({
+                    "error": (
+                        "P2F handler nomination missing or invalid for "
+                        f"shift(s): {', '.join(missing_shifts)}. Fix it in "
+                        "the Override drawer, then Plan again before "
+                        "Allocate."
+                    ),
+                    "missing_p2f_shifts": missing_shifts,
+                    "issues": handlers_state.get("issues", []),
+                })
+
+        STATE.run_date = d_day
+        if not runner.trigger(STATE, d_day, step):
+            return conflict({"error": "another run is in progress"})
+        return json_response({"started": True, "step": step})
+
+
+def _reset() -> Response:
+    runner.cancel()
+    cleared = STATE.reset_results()
+    # The drawer promises "defaults restore on Reset" for the
+    # per-(shift, role) bands, so clear those too.
+    from ...allocator import caps as _caps
+    _caps.reset_overrides()
+    logger.info("[reset] cleared %s", cleared)
+    return json_response({"reset": True, "cleared": cleared})
+
+
+__all__ = ["RUN_STEPS", "parse_date", "register"]

src/web/api/settings.py

@@ -0,0 +1,201 @@
+"""Drawer settings that write through past the session.
+
+Shift limits are per-iteration and cleared by Reset. The airport-code,
+break-length and extraction-filter edits go into ``configs/config.yml``, and
+the per-staff flight caps into ``configs/shift_limits.json``, so they
+outlive the process and the engine sees them on the next run.
+"""
+
+from __future__ import annotations
+
+from .. import overrides as override_ops
+from .. import runner
+from ..core.responses import (
+    Response,
+    bad_request,
+    conflict,
+    json_response,
+    server_error,
+)
+from ..core.router import Request, Router
+
+#: Shift codes and roles a band override may name.
+BAND_SHIFTS = ("M", "A", "N", "M1", "A1")
+BAND_ROLES = ("STAFF", "ZC")
+
+
+def register(router: Router) -> None:
+
+    @router.post("/api/shift_limits")
+    def shift_limits(req: Request) -> Response:
+        """Drawer "Edit shift limits": a per-iteration band override for
+        one (shift, role) bucket. Cleared by Reset."""
+        body = req.json()
+        shift = body.get("shift")
+        role = body.get("role")
+        try:
+            min_v = int(body.get("min"))
+            target_v = int(body.get("target"))
+            max_v = int(body.get("max"))
+        except (TypeError, ValueError):
+            return bad_request("min, target, max must be integers")
+        if shift not in BAND_SHIFTS:
+            allowed = "/".join(BAND_SHIFTS)
+            return bad_request(f"shift must be {allowed}, got {shift!r}")
+        if role not in BAND_ROLES:
+            allowed = " or ".join(BAND_ROLES)
+            return bad_request(f"role must be {allowed}, got {role!r}")
+        from ...allocator import caps as _caps
+        from ...schemas import Role as _Role
+        try:
+            saved = _caps.set_iteration_band(
+                shift, _Role.STAFF if role == "STAFF" else _Role.ZC,
+                min_v=min_v, target_v=target_v, max_v=max_v,
+            )
+        except ValueError as exc:
+            return bad_request(str(exc))
+        return json_response({"saved": saved})
+
+    def _break_payload(minutes: int) -> dict[str, int]:
+        from ...config import BREAK_MINUTES_HIGHEST, BREAK_MINUTES_LOWEST
+        return {
+            "length_minutes": minutes,
+            "min": BREAK_MINUTES_LOWEST,
+            "max": BREAK_MINUTES_HIGHEST,
+        }
+
+    @router.get("/api/break_length")
+    def get_break_length(_req: Request) -> Response:
+        """Setup sidebar "Shift break length" — the value the next
+        Allocate run will use, plus the allowed range."""
+        try:
+            minutes = override_ops.get_break_length()
+        except Exception as exc:  # noqa: BLE001
+            return server_error(exc, context="get_break_length failed")
+        return json_response(_break_payload(minutes))
+
+    @router.post("/api/break_length")
+    def set_break_length(req: Request) -> Response:
+        """Writes ``break_pass.length_minutes`` to configs/config.yml so
+        the next Allocate run uses it."""
+        try:
+            minutes = override_ops.set_break_length(
+                req.json().get("length_minutes"),
+            )
+        except ValueError as exc:
+            return bad_request(str(exc))
+        return json_response(_break_payload(minutes))
+
+    def _caps_payload() -> dict[str, object]:
+        from ...allocator import caps as _caps
+        overrides = _caps.snapshot_iteration_overrides()["shift_role"]
+        return {
+            "caps": _caps.default_caps(),
+            "overrides": {key: band["max"] for key, band in overrides.items()},
+        }
+
+    @router.get("/api/hard_caps")
+    def get_hard_caps(_req: Request) -> Response:
+        """Setup sidebar "Max flights per staff" table — the saved cap
+        per shift and role, plus the cap of any per-run shift-limits
+        override that shadows one until Reset."""
+        return json_response(_caps_payload())
+
+    @router.post("/api/hard_caps")
+    def set_hard_caps(req: Request) -> Response:
+        """Writes the caps to configs/shift_limits.json. Refused while a
+        run is in flight, since the engine reads the caps all the way
+        through one."""
+        caps = req.json().get("caps")
+        if not isinstance(caps, dict):
+            return bad_request("body.caps must be an object of {shift: {role: cap}}")
+        if runner.is_running():
+            return conflict({"error": "a run is in progress — wait for it to finish"})
+        from ...allocator import caps as _caps
+        try:
+            notes = _caps.set_default_caps(caps)
+        except ValueError as exc:
+            return bad_request(str(exc))
+        return json_response({**_caps_payload(), "notes": notes})
+
+    @router.get("/api/extraction_filters")
+    def list_filters(_req: Request) -> Response:
+        try:
+            filters = override_ops.list_extraction_filters()
+        except Exception as exc:  # noqa: BLE001
+            return server_error(exc, context="list_extraction_filters failed")
+        return json_response({"filters": filters})
+
+    @router.get("/api/intl_airports")
+    def list_airports(_req: Request) -> Response:
+        """Setup sidebar's international airport list, as configured in
+        configs/config.yml."""
+        try:
+            airports = override_ops.list_intl_airports()
+        except Exception as exc:  # noqa: BLE001
+            return server_error(exc, context="list_intl_airports failed")
+        return json_response({"airports": airports})
+
+    @router.post("/api/intl_airports")
+    def add_airport(req: Request) -> Response:
+        """Setup sidebar "Add international airport code" — writes through
+        to configs/config.yml so the engine sees it on the next run."""
+        body = req.json()
+        code = body.get("code")
+        name = body.get("name")
+        if not isinstance(code, str):
+            return bad_request("body.code must be a string")
+        try:
+            payload = override_ops.add_intl_airport_code(
+                code, name if isinstance(name, str) else None,
+            )
+        except ValueError as exc:
+            return bad_request(str(exc))
+        return json_response({
+            "added": payload, "airports": override_ops.list_intl_airports(),
+        })
+
+    @router.post("/api/intl_airports/remove")
+    def remove_airport(req: Request) -> Response:
+        """Setup sidebar's remove button on an airport chip — deletes the
+        code from configs/config.yml; the next run treats flights from
+        that airport as domestic."""
+        code = req.json().get("code")
+        if not isinstance(code, str):
+            return bad_request("body.code must be a string")
+        try:
+            removed = override_ops.remove_intl_airport_code(code)
+        except ValueError as exc:
+            return bad_request(str(exc))
+        return json_response({
+            "removed": removed, "airports": override_ops.list_intl_airports(),
+        })
+
+    @router.post("/api/extraction_filters/add")
+    def add_filter(req: Request) -> Response:
+        try:
+            norm = override_ops.add_extraction_filter(req.json())
+        except ValueError as exc:
+            return bad_request(str(exc))
+        except Exception as exc:  # noqa: BLE001
+            return server_error(exc, context="add_extraction_filter failed")
+        return json_response({
+            "filter": norm, "filters": override_ops.list_extraction_filters(),
+        })
+
+    @router.post("/api/extraction_filters/remove")
+    def remove_filter(req: Request) -> Response:
+        try:
+            idx = int(req.json().get("index", 0))
+        except (TypeError, ValueError):
+            return bad_request("body.index must be an integer (1-based)")
+        try:
+            removed = override_ops.remove_extraction_filter(idx)
+        except IndexError as exc:
+            return bad_request(str(exc))
+        return json_response({
+            "removed": removed, "filters": override_ops.list_extraction_filters(),
+        })
+
+
+__all__ = ["BAND_ROLES", "BAND_SHIFTS", "register"]

src/web/api/zc.py

@@ -0,0 +1,117 @@
+"""Zone Controller list: read, add, remove — one list per date.
+
+The list lives in ``zc_store`` (saved on disk, carried over from the
+previous day until edited). Every change is applied to the working data
+straight away, so the dashboard reflects it before Allocate is clicked;
+the next Plan re-applies it from the store.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date as date_t
+
+from ... import zc_store
+from ...state import STATE
+from .. import runner
+from ..core.responses import Response, bad_request, conflict, json_response
+from ..core.router import Request, Router
+from .runs import parse_date
+
+logger = logging.getLogger("src.web")
+
+
+def _payload(d_day: date_t, **extra: object) -> dict[str, object]:
+    names, source, carried_from = zc_store.effective(d_day)
+    return {
+        "date": d_day.isoformat(),
+        "names": names,
+        # saved   = this date has its own list
+        # carried = inherited from an earlier date until edited
+        # none    = nothing saved on or before this date
+        "source": source,
+        "carried_from": carried_from.isoformat() if carried_from else None,
+        **extra,
+    }
+
+
+def _rebuild(d_day: date_t) -> dict[str, object]:
+    """Re-derive today's availability from the rosters and re-apply the
+    staged rows plus the ZC list.
+
+    A rebuild (rather than patching roles in place) is what makes
+    *removing* a ZC work: the roster row is the only place that still
+    knows whether that person is STAFF or AM. Only done when the date
+    being edited is the one that has been planned; otherwise the list is
+    simply saved and applied by the next Plan for that date.
+    """
+    with STATE.lock:
+        planned = bool(STATE.availability) and STATE.run_date == d_day
+    if not planned:
+        return {"applied": False, "reason": "not planned yet"}
+
+    from ...step2_extract_roster import run as run_step2
+
+    # step2 replaces state.warnings; the ones on screen belong to the
+    # last Plan / Allocate, so put them back afterwards.
+    with STATE.lock:
+        saved_warnings = list(STATE.warnings)
+    try:
+        counts = run_step2(STATE, d_day, runner.CONFIG_PATH)
+    except Exception as exc:  # noqa: BLE001 — list is saved; say why it didn't apply
+        logger.warning("[zc] roster re-read failed: %s", exc)
+        return {"applied": False, "reason": f"{type(exc).__name__}: {exc}"}
+    finally:
+        with STATE.lock:
+            STATE.warnings = saved_warnings
+    if counts.get("ABORTED"):
+        return {"applied": False, "reason": "roster check failed — see warnings"}
+    return {"applied": True}
+
+
+def _date_or_error(raw: str | None) -> tuple[date_t | None, Response | None]:
+    d_day = parse_date(raw)
+    if d_day is None:
+        return None, bad_request("date required (YYYY-MM-DD)")
+    return d_day, None
+
+
+def register(router: Router) -> None:
+
+    @router.get("/api/zc")
+    def get_zc(req: Request) -> Response:
+        d_day, err = _date_or_error((req.query.get("date") or [""])[0])
+        if err:
+            return err
+        return json_response(_payload(d_day))
+
+    @router.post("/api/zc/add")
+    def add_zc(req: Request) -> Response:
+        body = req.json()
+        d_day, err = _date_or_error(body.get("date"))
+        if err:
+            return err
+        name = str(body.get("name") or "").strip()
+        if not name:
+            return bad_request("name required")
+        if runner.is_running():
+            return conflict({"error": "a run is in progress — wait for it to finish"})
+        zc_store.add(d_day, name)
+        return json_response(_payload(d_day, **_rebuild(d_day)))
+
+    @router.post("/api/zc/remove")
+    def remove_zc(req: Request) -> Response:
+        body = req.json()
+        d_day, err = _date_or_error(body.get("date"))
+        if err:
+            return err
+        name = str(body.get("name") or "").strip()
+        if not name:
+            return bad_request("name required")
+        if runner.is_running():
+            return conflict({"error": "a run is in progress — wait for it to finish"})
+        zc_store.remove(d_day, name)
+        return json_response(_payload(d_day, **_rebuild(d_day)))
+
+
+__all__ = ["register"]

src/web/core/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP plumbing shared by every API module.
+
+Deliberately knows nothing about flights, rosters or the solver — it is
+the transport layer the ``api`` package plugs handlers into.
+"""

src/web/core/responses.py

@@ -0,0 +1,91 @@
+"""What a handler hands back.
+
+A handler returns a ``Response``; the request loop is what knows how to
+put it on the wire. Keeping the two apart means a handler is a plain
+function of ``Request -> Response``, testable without a socket.
+"""
+
+from __future__ import annotations
+
+import json
+import traceback
+from dataclasses import dataclass, field
+from typing import Any
+
+JSON_CONTENT_TYPE = "application/json"
+XLSX_CONTENT_TYPE = (
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+)
+XML_CONTENT_TYPE = "application/xml"
+
+
+@dataclass(slots=True)
+class Response:
+    """One HTTP response. ``headers`` carries anything beyond the
+    Content-Type / Content-Length / Cache-Control the sender always
+    sets — a Content-Disposition on a download, for instance."""
+
+    status: int = 200
+    body: bytes = b""
+    content_type: str = JSON_CONTENT_TYPE
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+def json_response(payload: Any, status: int = 200) -> Response:
+    return Response(
+        status=status,
+        body=json.dumps(payload, default=str).encode("utf-8"),
+        content_type=JSON_CONTENT_TYPE,
+    )
+
+
+def bad_request(message: str) -> Response:
+    return json_response({"error": message}, status=400)
+
+
+def not_found(message: str = "not found") -> Response:
+    return json_response({"error": message}, status=404)
+
+
+def conflict(payload: dict[str, Any]) -> Response:
+    return json_response(payload, status=409)
+
+
+def server_error(exc: BaseException, *, context: str = "") -> Response:
+    """500 with the exception text and traceback in the body.
+
+    Sending it as JSON rather than letting the exception bubble matters:
+    an escaped exception closes the connection mid-response and the
+    browser shows a bare ERR_EMPTY_RESPONSE with nothing to act on.
+    """
+    label = f"{context}: " if context else ""
+    return json_response(
+        {
+            "error": f"{label}{type(exc).__name__}: {exc}",
+            "traceback": traceback.format_exc(),
+        },
+        status=500,
+    )
+
+
+def attachment(body: bytes, content_type: str, filename: str) -> Response:
+    return Response(
+        status=200,
+        body=body,
+        content_type=content_type,
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+__all__ = [
+    "JSON_CONTENT_TYPE",
+    "Response",
+    "XLSX_CONTENT_TYPE",
+    "XML_CONTENT_TYPE",
+    "attachment",
+    "bad_request",
+    "conflict",
+    "json_response",
+    "not_found",
+    "server_error",
+]

src/web/core/router.py

@@ -0,0 +1,167 @@
+"""A pattern -> handler table, so adding an endpoint is a registration
+rather than another branch in a growing if/elif chain.
+
+Patterns are literal paths with optional ``{name}`` segments:
+
+    @router.get("/api/dashboard")
+    def dashboard(req): ...
+
+    @router.post("/api/inputs/{kind}")
+    def upload(req): ...            # req.params["kind"]
+
+    @router.get("/static/{path*}")
+    def asset(req): ...             # trailing * spans "/" too
+
+Literal routes are matched by dict lookup; only the handful of
+parameterised ones fall through to the regex list, so dispatch cost
+doesn't grow with the number of plain endpoints.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from .responses import Response, not_found, server_error
+
+#: A route handler. Takes the request, returns the response.
+Handler = Callable[["Request"], Response]
+
+#: ``{name}`` matches one path segment; ``{name*}`` matches the rest of
+#: the path, slashes included.
+_PARAM_RE = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)(\*?)\}")
+
+
+@dataclass(slots=True)
+class Request:
+    """One inbound request, already parsed enough for a handler to use.
+
+    ``body`` is read by the request loop before dispatch so a handler
+    never touches the socket — it is the raw bytes for an upload and
+    the JSON source for everything else.
+    """
+
+    method: str
+    path: str
+    headers: Any = None
+    body: bytes = b""
+    params: dict[str, str] = field(default_factory=dict)
+    query: dict[str, list[str]] = field(default_factory=dict)
+
+    def json(self) -> dict[str, Any]:
+        """The body as a dict. A malformed or non-object body reads as
+        ``{}`` — handlers validate the fields they need and return a
+        400 naming the missing one, which is a better error than a
+        generic parse failure."""
+        if not self.body:
+            return {}
+        try:
+            data = json.loads(self.body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def header(self, name: str, default: str = "") -> str:
+        if self.headers is None:
+            return default
+        return self.headers.get(name, default) or default
+
+
+def _compile(pattern: str) -> re.Pattern[str]:
+    parts: list[str] = []
+    last = 0
+    for m in _PARAM_RE.finditer(pattern):
+        parts.append(re.escape(pattern[last:m.start()]))
+        body = ".+" if m.group(2) else "[^/]+"
+        parts.append(f"(?P<{m.group(1)}>{body})")
+        last = m.end()
+    parts.append(re.escape(pattern[last:]))
+    return re.compile("^" + "".join(parts) + "$")
+
+
+class Router:
+    """Route table. One instance per server; built once at start-up."""
+
+    def __init__(self) -> None:
+        self._literal: dict[tuple[str, str], Handler] = {}
+        self._patterned: list[tuple[str, re.Pattern[str], Handler]] = []
+
+    # -- registration ------------------------------------------------
+
+    def add(self, method: str, pattern: str, handler: Handler) -> None:
+        method = method.upper()
+        if _PARAM_RE.search(pattern):
+            self._patterned.append((method, _compile(pattern), handler))
+        else:
+            self._literal[(method, pattern)] = handler
+
+    def route(self, method: str, pattern: str) -> Callable[[Handler], Handler]:
+        def decorator(fn: Handler) -> Handler:
+            self.add(method, pattern, fn)
+            return fn
+        return decorator
+
+    def get(self, pattern: str) -> Callable[[Handler], Handler]:
+        return self.route("GET", pattern)
+
+    def post(self, pattern: str) -> Callable[[Handler], Handler]:
+        return self.route("POST", pattern)
+
+    def put(self, pattern: str) -> Callable[[Handler], Handler]:
+        return self.route("PUT", pattern)
+
+    def delete(self, pattern: str) -> Callable[[Handler], Handler]:
+        return self.route("DELETE", pattern)
+
+    # -- dispatch ----------------------------------------------------
+
+    def resolve(self, method: str, path: str) -> tuple[Handler, dict[str, str]] | None:
+        handler = self._literal.get((method, path))
+        if handler is not None:
+            return handler, {}
+        for route_method, regex, fn in self._patterned:
+            if route_method != method:
+                continue
+            m = regex.match(path)
+            if m:
+                return fn, m.groupdict()
+        return None
+
+    def dispatch(self, method: str, raw_path: str, headers: Any, body: bytes) -> Response:
+        """Find the handler for this request and run it.
+
+        Any exception a handler lets escape becomes a 500 carrying the
+        traceback, so one broken endpoint can't take the console down.
+        """
+        parsed = urllib.parse.urlparse(raw_path)
+        match = self.resolve(method, parsed.path)
+        if match is None:
+            return not_found()
+        handler, params = match
+        request = Request(
+            method=method,
+            path=parsed.path,
+            headers=headers,
+            body=body,
+            params=params,
+            query=urllib.parse.parse_qs(parsed.query),
+        )
+        try:
+            return handler(request)
+        except Exception as exc:  # noqa: BLE001 — see docstring
+            return server_error(exc, context=f"{method} {parsed.path}")
+
+    @property
+    def routes(self) -> list[str]:
+        """``"GET /api/dashboard"`` for each registered route — handy in
+        a log line at start-up and when checking a new blueprint
+        actually registered."""
+        literal = [f"{m} {p}" for (m, p) in self._literal]
+        patterned = [f"{m} {r.pattern}" for (m, r, _) in self._patterned]
+        return sorted(literal + patterned)
+
+
+__all__ = ["Handler", "Request", "Router"]