#!/usr/bin/env python3
"""List and check a TouchUp backup folder, with the Python standard library only (Python 3.8 or later).

Usage:
    python3 read_backup.py <backup-folder>            list and check every file
    python3 read_backup.py <backup-folder> --show files/PICK.LS    also print one text file, decoded

Exit code: 0 when every file of the manifest is present with the size and the sha256 it lists,
1 when a file is missing or differs, 2 when the manifest is missing, malformed or of a version this script
does not read, or when --show names a file that cannot be shown.
The format is described at https://underautomation.com/touchup/documentation/backup-format.
"""
import argparse
import hashlib
import json
import os
import re
import stat
import sys

MANIFEST = "touchup-backup.json"
SUPPORTED_SCHEMA = 1
SHOW_LIMIT = 1 << 20  # --show prints at most 1 MiB

# C0 and C1 control characters (a backup can come from anywhere: no terminal escape sequence reaches the screen)
CONTROL = re.compile("[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]")
CONTROL_LINE = re.compile("[\x00-\x1f\x7f-\x9f]")


class Malformed(Exception):
    """The manifest has a field of the wrong type: the message names the field."""


def clean(value):
    """A manifest value for a one-line listing, control characters replaced by U+FFFD."""
    return CONTROL_LINE.sub("�", str(value))


def sha256_of(path):
    digest = hashlib.sha256()
    with open(path, "rb") as stream:
        for block in iter(lambda: stream.read(1 << 20), b""):
            digest.update(block)
    return digest.hexdigest()


def is_link(path):
    """A symbolic link, or a Windows junction or other reparse point (os.path.islink is False for a junction)."""
    if os.path.islink(path):
        return True
    try:
        return bool(getattr(os.lstat(path), "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT)
    except OSError:
        return False


def locate(folder, rel, prefix):
    """The real path of a manifest entry, or None when it is not a plain file below `prefix` (no ".." and no link)."""
    parts = rel.split("/")
    if not rel.startswith(prefix) or any(p in ("", ".", "..") for p in parts) or "\\" in rel or ":" in rel:
        return None
    path = folder
    for part in parts:  # a link anywhere on the way is refused, as TouchUp does
        path = os.path.join(path, part)
        if is_link(path):
            return None
    if not os.path.isfile(path):
        return None
    root = os.path.realpath(os.path.join(folder, prefix.rstrip("/")))
    try:
        if os.path.commonpath([root, os.path.realpath(path)]) != root:
            return None
    except ValueError:  # another drive
        return None
    return path


def need(value, kind, field):
    # bool is an int in Python: a size of true is not a size
    if not isinstance(value, kind) or (kind is int and isinstance(value, bool)):
        raise Malformed(field)
    return value


def validate(manifest):
    """False for a schemaVersion this script does not read; raises Malformed for a field of the wrong type.
    Unknown fields are ignored (the format only adds fields)."""
    need(manifest, dict, "manifest")
    if type(manifest.get("schemaVersion")) is not int or manifest["schemaVersion"] != SUPPORTED_SCHEMA:
        return False
    need(manifest.get("files"), list, "files")
    for name in ("controller", "profile", "normalization"):
        if manifest.get(name) is not None:
            need(manifest[name], dict, name)
    for name in ("files", "binary", "skipped"):
        if manifest.get(name) is None:
            continue
        for item in need(manifest[name], list, name):
            need(item, dict, name + "[]")
            need(item.get("path"), str, name + "[].path")
            if name == "skipped":
                need(item.get("reason", ""), str, "skipped[].reason")
            else:
                need(item.get("size"), int, name + "[].size")
                need(item.get("sha256"), str, name + "[].sha256")
                if item.get("encoding") is not None:
                    need(item["encoding"], str, name + "[].encoding")
    return True


def check(folder, entries, prefix, out):
    """Prints one line per entry and returns the number of problems."""
    problems = 0
    for entry in entries:
        rel = entry["path"]
        path = locate(folder, rel, prefix)
        if path is None:
            status = "MISSING"
        elif os.path.getsize(path) != entry["size"]:
            status = "SIZE MISMATCH"
        elif sha256_of(path) != entry["sha256"].lower():
            status = "HASH MISMATCH"
        else:
            status = "OK"
        # encoding is the label of the text files that are not utf-8; a text file with no label is utf-8
        if "normalizedSha256" in entry:
            note = "  text, encoding " + clean(entry.get("encoding") or "utf-8")
        elif prefix == "binary/":
            note = "  binary, compared by hash only"
        else:
            note = "  binary"
        if status != "OK":
            problems += 1
        out.append("  %-14s %s  (%s bytes)%s" % (status, clean(rel), entry["size"], note))
    return problems


def show_file(folder, manifest, rel):
    """Prints one text file of the manifest, decoded. Returns an exit code (0, or 2 when it cannot be shown)."""
    entry = next((f for f in manifest["files"] if f["path"] == rel), None)
    path = locate(folder, rel, "files/") if entry else None
    if path is None:
        print("--show: %s is not a file of the manifest" % clean(rel))
        return 2
    if "normalizedSha256" not in entry:
        print("--show: %s is a binary file, not shown" % clean(rel))
        return 2
    with open(path, "rb") as stream:
        data = stream.read(SHOW_LIMIT + 1)
    try:
        text = data[:SHOW_LIMIT].decode(entry.get("encoding") or "utf-8", errors="replace")
    except (LookupError, TypeError, ValueError):
        print("--show: unknown encoding %s" % clean(entry.get("encoding")))
        return 2
    print("---- %s" % clean(rel))
    print(CONTROL.sub("�", text))
    if len(data) > SHOW_LIMIT:
        print("(truncated)")
    return 0


def main(argv):
    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
    parser = argparse.ArgumentParser(description="List and check a TouchUp backup folder.")
    parser.add_argument("folder", help="the backup folder (it holds touchup-backup.json)")
    parser.add_argument("--show", metavar="PATH", help="also print one text file of the manifest, decoded, for example files/PICK.LS")
    options = parser.parse_args(argv[1:])
    folder = os.path.abspath(options.folder)
    try:
        with open(os.path.join(folder, MANIFEST), "r", encoding="utf-8-sig") as stream:
            manifest = json.load(stream)
    except (OSError, ValueError, RecursionError) as error:
        print("No readable %s in %s: %s" % (MANIFEST, clean(folder), clean(error)))
        return 2
    try:
        if not validate(manifest):
            print("Unsupported manifest: schemaVersion %s (this script reads %d)" % (clean(manifest.get("schemaVersion")), SUPPORTED_SCHEMA))
            return 2
        controller = manifest.get("controller") or {}
        profile = manifest.get("profile") or {}
        norm = manifest.get("normalization") or {}
        print("Backup of %s (%s %s) taken %s by %s with TouchUp %s" % (
            clean(controller.get("name")), clean(controller.get("brand")), clean(controller.get("model") or ""), clean(manifest.get("takenAt")),
            clean(manifest.get("takenBy")), clean(manifest.get("touchupVersion"))))
        # no profile: the backup is older than the profiles, it reads as the default profile of the brand
        print("Profile: %s" % (("%s (id %s)" % (clean(profile.get("name")), clean(profile.get("id")))) if profile else "none recorded (the default profile of the brand)"))
        print("Normalization: %s" % (("rules %s, version %s" % (clean(norm.get("rules")), clean(norm.get("version")))) if norm else "none"))
        if manifest.get("summary"):
            print("Summary: %s" % clean(manifest["summary"]))

        out = []
        problems = check(folder, manifest["files"], "files/", out)
        print("Files (%d):" % len(manifest["files"]))
        print("\n".join(out))
        binary = manifest.get("binary") or []
        if binary:
            out = []
            problems += check(folder, binary, "binary/", out)
            print("Binary (%d):" % len(binary))
            print("\n".join(out))
        skipped = manifest.get("skipped") or []
        if skipped:
            print("Skipped by the controller (%d), not in the backup:" % len(skipped))
            for item in skipped:
                print("  %s: %s" % (clean(item["path"]), clean(item.get("reason", ""))))
        if os.path.isfile(os.path.join(folder, "mastering.json")):
            print("mastering.json: present (not in the manifest)")
        print("%d files checked, %d problem(s)" % (len(manifest["files"]) + len(binary), problems))
        if options.show is not None:
            code = show_file(folder, manifest, options.show)
            if code:
                return code
    except Malformed as error:
        print("Malformed manifest: %s" % error)
        return 2
    return 1 if problems else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))
