"""Settings descriptor: maps config keys to display metadata.

``get_settings_sections(config)`` returns an ordered list of sections, each
containing a list of field descriptors.  The template iterates this structure
generically, so adding editability later is a matter of:

  1. Setting ``"editable": True`` on a field.
  2. Adding the matching ``<input>``/``<select>`` in the template
     (guided by ``"type"``).
  3. Wiring a POST handler in http.py.

Field descriptor keys
---------------------
key         str   Config key (for future form POST matching)
label       str   Human-readable label
description str   One-line help text shown below the value
value       any   Sanitized display value (secrets replaced with "•••")
type        str   One of: text | number | port | boolean | path | duration |
                  list | secret | size | select
editable    bool  Reserved for future use — currently always False
sensitive   bool  True when the raw value must never be shown
"""

# Credential field names that should always be masked.
_SECRET_KEYS = frozenset({
    "password", "token", "user_key", "api_key", "secret",
    "smtp_password", "smtp_user",
})

_CHANNEL_TYPE_LABELS = {
    "pushover":   "Pushover",
    "email":      "E-mail",
    "signal":     "Signal",
    "mattermost": "Mattermost",
}


def _mask(value):
    """Return a masked placeholder for sensitive values."""
    if not value:
        return ""
    return "•••"


def _fmt_size(n):
    """Format a byte count as a human-readable string."""
    try:
        n = int(n)
    except (TypeError, ValueError):
        return str(n)
    for unit in ("B", "KB", "MB", "GB"):
        if n < 1024:
            return f"{n} {unit}"
        n //= 1024
    return f"{n} TB"


def _fmt_duration(seconds):
    """Format seconds into a human-readable duration string."""
    try:
        s = int(seconds)
    except (TypeError, ValueError):
        return str(seconds)
    if s < 60:
        return f"{s}s"
    if s < 3600:
        m, sec = divmod(s, 60)
        return f"{m}m {sec}s" if sec else f"{m}m"
    h, rem = divmod(s, 3600)
    m = rem // 60
    return f"{h}h {m}m" if m else f"{h}h"


def _sanitize_channel(name, cfg):
    """Return a sanitized copy of a notification channel config."""
    result = {}
    for k, v in cfg.items():
        if k in _SECRET_KEYS:
            result[k] = _mask(v)
        elif isinstance(v, list):
            result[k] = v
        else:
            result[k] = v
    return result


# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------

def get_settings_sections(config: dict) -> list:
    """Return ordered list of setting sections for the settings page.

    Each section:
        {
            "title": str,
            "description": str,
            "fields": [ field_descriptor, ... ]
        }

    Each field_descriptor:
        {
            "key":         str,
            "label":       str,
            "description": str,
            "value":       display_value,
            "raw":         raw_config_value,   # None for sensitive
            "type":        str,
            "editable":    bool,
            "sensitive":   bool,
        }
    """
    def field(key, label, ftype, description="", editable=False, sensitive=False):
        raw = config.get(key)
        if sensitive:
            display = _mask(raw)
            raw_out = None
        elif ftype == "size":
            display = _fmt_size(raw)
            raw_out = raw
        elif ftype == "duration":
            display = _fmt_duration(raw)
            raw_out = raw
        elif ftype == "boolean":
            display = bool(raw)
            raw_out = raw
        elif ftype == "list":
            val = raw or []
            display = list(val) if not isinstance(val, list) else val
            raw_out = display
        else:
            display = raw if raw is not None else ""
            raw_out = raw
        return {
            "key": key,
            "label": label,
            "description": description,
            "value": display,
            "raw": raw_out,
            "type": ftype,
            "editable": editable,
            "sensitive": sensitive,
        }

    # ---- Notification channels (complex, built separately) ----------------
    notif_channels = []
    for ch_name, ch_cfg in (config.get("notification_channels") or {}).items():
        if not isinstance(ch_cfg, dict):
            continue
        ch_type = ch_cfg.get("type", "")
        fields = []
        for k, v in ch_cfg.items():
            if k == "type":
                continue
            sensitive = k in _SECRET_KEYS
            fields.append({
                "key": k,
                "label": k.replace("_", " ").title(),
                "value": _mask(v) if sensitive else (
                    ", ".join(v) if isinstance(v, list) else str(v)
                ),
                "sensitive": sensitive,
            })
        notif_channels.append({
            "name": ch_name,
            "type": ch_type,
            "type_label": _CHANNEL_TYPE_LABELS.get(ch_type, ch_type.title()),
            "fields": fields,
        })

    # ---- Users (show metadata only, never password hashes) ----------------
    users_list = []
    for username, attrs in (config.get("users") or {}).items():
        if not isinstance(attrs, dict):
            continue
        users_list.append({
            "username": username,
            "full_name": attrs.get("full_name", ""),
            "admin": bool(attrs.get("admin", False)),
            "avatar": attrs.get("avatar", ""),
            "notification_channels": attrs.get("notification_channels", []),
        })

    # ---- Hosts summary ----------------------------------------------------
    hosts_list = []
    for hname, hcfg in (config.get("hosts") or {}).items():
        if not isinstance(hcfg, dict):
            continue
        hosts_list.append({
            "name": hname,
            "watch": bool(hcfg.get("watch", False)),
            "dyndns": bool(hcfg.get("dyndns", False)),
            "owner": hcfg.get("owner", ""),
            "managers": hcfg.get("managers", []),
            "monitors": hcfg.get("monitors", []),
            "threshold_config": hcfg.get("threshold_config", ""),
            "notification_channels": hcfg.get("notification_channels", []),
        })

    return [
        {
            "id": "network",
            "title": "Network",
            "description": "Ports and bind addresses for all server sockets.",
            "fields": [
                field("hb_port",  "Heartbeat UDP port",  "port",
                      "UDP port the server listens on for heartbeat datagrams."),
                field("hbd_host", "HTTP bind address",   "text",
                      "Interface to bind the HTTP server to. Empty = all interfaces."),
                field("hbd_port", "HTTP API port",       "port",
                      "TCP port for the HTTP API and web UI."),
                field("ws_port",  "WebSocket port",      "port",
                      "TCP port for the plain WebSocket server."),
                field("wss_port", "Secure WebSocket port", "port",
                      "TCP port for WSS (TLS WebSocket). Leave empty to disable."),
            ],
        },
        {
            "id": "tls",
            "title": "TLS / WebSocket Security",
            "description": "Certificate paths used when wss_port is set.",
            "fields": [
                field("cert_path", "Certificate directory", "path",
                      "Directory containing the TLS certificate and key files."),
                field("wss_pem",   "Certificate file",     "text",
                      "Filename of the TLS certificate chain (PEM format)."),
                field("wss_key",   "Key file",             "text",
                      "Filename of the TLS private key (PEM format)."),
            ],
        },
        {
            "id": "monitoring",
            "title": "Monitoring",
            "description": "Heartbeat timing and alert re-notification behaviour.",
            "fields": [
                field("interval",  "Heartbeat interval", "duration",
                      "Expected time between heartbeat messages from each client."),
                field("grace",     "Grace multiplier",   "number",
                      "A host is marked overdue after interval × grace seconds of silence."),
                field("threshold_renotify_interval", "Re-notify interval", "duration",
                      "How often to re-send notifications for ongoing threshold alerts."),
                field("autosave_interval", "Autosave interval", "duration",
                      "How often the server saves its state to disk."),
            ],
        },
        {
            "id": "persistence",
            "title": "Persistence & Logging",
            "description": "State file and event log settings.",
            "fields": [
                field("pickfile", "State file",   "path",
                      "Path to the pickle file used to persist host state across restarts."),
                field("logfile",  "Event log",    "path",
                      "Path to the event log file."),
                field("logfmt",   "Log format",   "select",
                      "Format for event log entries: text, msg, or json."),
            ],
        },
        {
            "id": "journal",
            "title": "Message Journal",
            "description": "All received heartbeat and plugin messages are journalled here.",
            "fields": [
                field("journal_enabled",     "Enabled",          "boolean",
                      "Turn journalling on or off."),
                field("journal_dir",         "Journal directory","path",
                      "Directory where journal files are written."),
                field("journal_file",        "Journal filename", "text",
                      "Base filename for the journal (rotated copies get a numeric suffix)."),
                field("journal_max_size",    "Max file size",    "size",
                      "Rotate the journal when it exceeds this size."),
                field("journal_max_backups", "Backup count",     "number",
                      "Number of rotated journal files to keep."),
            ],
        },
        {
            "id": "dns",
            "title": "Dynamic DNS",
            "description": "nsupdate-based DNS registration for dynamic hosts.",
            "fields": [
                field("nsupdate_bin", "nsupdate binary", "path",
                      "Full path to the nsupdate executable."),
                field("dyndomains",   "Dynamic domains", "list",
                      "DNS zones managed by nsupdate for dynamic hosts."),
                field("drophosts",    "Drop hosts",      "list",
                      "Hostnames to silently ignore — no state, no alerts."),
            ],
        },
        {
            "id": "users",
            "title": "Users",
            "description": "Accounts defined in the config file. Password hashes are never shown.",
            "users": users_list,
            "fields": [
                field("default_owner", "Default owner", "text",
                      "Username that owns hosts with no explicit owner. "
                      "Falls back to the first admin user."),
            ],
        },
        {
            "id": "channels",
            "title": "Notification Channels",
            "description": "Named notification providers. Credentials are masked.",
            "channels": notif_channels,
            "fields": [
                field("default_notification_channels", "Default channels", "list",
                      "Channels used when a host does not specify its own."),
            ],
        },
        {
            "id": "hosts",
            "title": "Hosts",
            "description": "Host definitions loaded from the config file.",
            "hosts": hosts_list,
            "fields": [],
        },
        {
            "id": "runtime",
            "title": "Runtime",
            "description": "Flags set at startup (require restart to change).",
            "fields": [
                field("foreground", "Foreground mode", "boolean",
                      "Run in the foreground instead of daemonising."),
                field("verbose",    "Verbose logging",  "boolean",
                      "Enable verbose log output."),
                field("debug",      "Debug level",      "number",
                      "0 = off. Higher values increase log verbosity."),
            ],
        },
    ]