import os

from quart import Blueprint, jsonify

api = Blueprint("api", __name__, url_prefix="/api")


@api.route("/health")
async def health():
    return jsonify({"status": "ok"})


def build_version_payload() -> dict:
    """What build is this, separated into the values that answer different
    questions (rule 149).

    UNTIL 2026-08-31 THIS RETURNED THE CHANNEL. `BUILD_VERSION` in CI was
    literally "dev" / "main" / the tag, so a running instance reported
    `{"version": "main"}` — a channel name sitting where a build identifier
    belongs. The cost was concrete: with a deploy misbehaving, nothing on the
    instance could say which commit was serving it, and the one endpoint whose
    job that is answered with the name of a branch.

    The three values, and why they are three:

    - `version` — the NAME, `YYYY.MM.DD.HHMM` from COMMIT time. Answers "is
      this the same code?", so two channels carrying one commit report the
      same string.
    - `build` — the ORDERING KEY, minutes since 2020-01-01 from BUILD time.
      Answers "may this be installed over that?". The ONLY value anything may
      compare; it is monotonic by construction, which neither a commit count
      (branches diverge) nor a commit time (rebuilds go backwards) is.
    - `channel` — its own field, never folded into the name.

    Plus `commit`, so the artifact's claim about itself can be checked against
    the `:<sha>` it was published under (rule 145).

    ABSENT RATHER THAN EMPTY when unknown. A local build has no ordering key
    and no channel, and saying so is honest; emitting `""` or a placeholder
    would let it claim a position in an update order it is not part of. A
    reader must treat a missing `build` as "cannot be ordered", not as zero.
    """
    payload: dict = {"version": os.environ.get("APP_VERSION", "dev")}

    # Reported verbatim, never validated against an enum — a build claiming
    # something unexpected is better shown than dropped (rule 149).
    for key, env in (("channel", "APP_CHANNEL"), ("commit", "APP_COMMIT")):
        value = (os.environ.get(env) or "").strip()
        if value:
            payload[key] = value

    raw_key = (os.environ.get("APP_BUILD_KEY") or "").strip()
    if raw_key:
        try:
            # An INTEGER, not a string. A string ordering key is how a
            # comparison silently becomes lexicographic — "9" > "10" — which
            # is the same class of fault as folding the channel in: it reads
            # fine and orders wrong.
            payload["build"] = int(raw_key)
        except ValueError:
            # A malformed key is omitted rather than passed through: a reader
            # that cannot order is correct, one that orders on garbage is not.
            pass

    return payload


@api.route("/version")
async def version():
    return jsonify(build_version_payload())
