#!/usr/bin/env python3
"""opcache-check: is PHP's code cache (OPcache) big enough, for each PHP version on this server?

Read-only. Built for GridPane servers (Ubuntu, one PHP-FPM service per PHP version), and it works
on any server laid out the same way. Run it as root: PHP's sockets are readable by root and
www-data only. Python 3 standard library, nothing to install.

    python3 opcache-check.py              # every PHP version
    python3 opcache-check.py 8.3          # one version
    python3 opcache-check.py --sample 60  # also measure the hit rate over the next 60 seconds
    python3 opcache-check.py --clean      # remove the small file this script leaves behind

Why it asks through a socket: each PHP version's PHP-FPM holds one code cache, shared by every site
on that version, and only a request through one of that version's sockets can read it. The command
line (php -r, wp eval) has its own, separate cache. So the script writes a tiny read-only PHP file
outside every web root (/var/lib/opcache-check/probe.php), asks one site's socket to run it, and
prints what PHP says. It changes no setting and reloads nothing.

From https://jonphillips.dev/posts/gridpane-opcache
"""
import glob, json, os, re, socket, struct, sys, time

ETC = os.environ.get("OPCACHE_CHECK_ETC", "/etc/php")
WWW = os.environ.get("OPCACHE_CHECK_WWW", "/var/www")
PROBE_DIR = os.environ.get("OPCACHE_CHECK_DIR", "/var/lib/opcache-check")
PROBE = PROBE_DIR + "/probe.php"
MB = 1024 * 1024
MEMORY_STEPS = [128, 256, 384, 512, 768, 1024, 1536, 2048]
FILE_STEPS = [10000, 20000, 40000, 60000, 100000]
TEXT_STEPS = [16, 32, 64, 128]

PROBE_PHP = r"""<?php
// opcache-check: read-only. Prints this PHP version's code cache numbers as JSON.
// Safe to delete; opcache-check.py writes it again when it next runs.
header('Content-Type: application/json');
$out = array('php' => PHP_VERSION);
if (!function_exists('opcache_get_status')) { $out['err'] = extension_loaded('Zend OPcache') ? 'refused' : 'not_loaded'; echo json_encode($out); return; }
$s = @opcache_get_status(true);
if (!is_array($s)) { $out['err'] = ini_get('opcache.enable') ? 'refused' : 'off'; echo json_encode($out); return; }
$www = rtrim(isset($_SERVER['CHECK_WWW']) ? $_SERVER['CHECK_WWW'] : '/var/www', '/') . '/';
$n = strlen($www);
$by = array();
foreach ((isset($s['scripts']) ? $s['scripts'] : array()) as $path => $x) {
    $site = '';
    if (strncmp($path, $www, $n) === 0) {
        $e = strpos($path, '/', $n);
        if ($e !== false) { $site = substr($path, $n, $e - $n); }
    }
    if (!isset($by[$site])) { $by[$site] = array(0, 0); }
    $by[$site][0]++;
    $by[$site][1] += isset($x['memory_consumption']) ? (int) $x['memory_consumption'] : 0;
}
$m = isset($s['memory_usage']) ? $s['memory_usage'] : array();
$i = isset($s['interned_strings_usage']) ? $s['interned_strings_usage'] : array();
$t = isset($s['opcache_statistics']) ? $s['opcache_statistics'] : array();
$g = function ($a, $k) { return isset($a[$k]) ? (int) $a[$k] : null; };
$out += array(
    'enabled' => !empty($s['opcache_enabled']),
    'full' => !empty($s['cache_full']),
    'used' => $g($m, 'used_memory'), 'free' => $g($m, 'free_memory'), 'wasted' => $g($m, 'wasted_memory'),
    'str_size' => $g($i, 'buffer_size'), 'str_used' => $g($i, 'used_memory'),
    'keys' => $g($t, 'num_cached_keys'), 'max_keys' => $g($t, 'max_cached_keys'),
    'hits' => $g($t, 'hits'), 'misses' => $g($t, 'misses'),
    'oom' => $g($t, 'oom_restarts'), 'hash' => $g($t, 'hash_restarts'),
    'start' => $g($t, 'start_time'), 'last_restart' => $g($t, 'last_restart_time'),
    'by' => $by,
);
echo json_encode($out);
"""


def write_probe():
    os.makedirs(PROBE_DIR, mode=0o755, exist_ok=True)
    os.chmod(PROBE_DIR, 0o755)
    try:
        if open(PROBE).read() == PROBE_PHP:
            return
    except OSError:
        pass
    with open(PROBE + ".new", "w") as f:
        f.write(PROBE_PHP)
    os.chmod(PROBE + ".new", 0o644)
    os.replace(PROBE + ".new", PROBE)


def settings(ver):
    """The opcache lines as written: php.ini, then conf.d in order. The last one read wins, as in PHP."""
    files = [f"{ETC}/{ver}/fpm/php.ini"] + sorted(glob.glob(f"{ETC}/{ver}/fpm/conf.d/*.ini"))
    out = {}
    for path in files:
        try:
            for line in open(path, errors="replace"):
                m = re.match(r"^\s*opcache\.(\w+)\s*=\s*\"?([^\";\s]*)", line)
                if m:
                    out[m.group(1)] = m.group(2)
        except OSError:
            pass
    return out


def pools(ver):
    """Each pool's socket, and the site folder it serves (GridPane names pools after the site)."""
    found = []
    for conf in sorted(glob.glob(f"{ETC}/{ver}/fpm/pool.d/*.conf")):
        text = "".join(l for l in open(conf, errors="replace") if not l.lstrip().startswith((";", "#")))
        m = re.search(r"^\s*listen\s*=\s*(\S+)", text, re.M)
        if not m:
            continue
        folders = re.findall(re.escape(WWW) + r"/([^/\s]+)/", text)
        name = os.path.basename(conf)[:-5]
        site = max(set(folders), key=folders.count) if folders else (name if os.path.isdir(f"{WWW}/{name}") else None)
        found.append({"listen": m.group(1), "site": site})
    return found


def ask(listen, timeout=5):
    """Run the probe through one FastCGI socket. Returns (dict, None) or (None, reason)."""
    def rec(kind, body):
        return struct.pack("!BBHHBx", 1, kind, 1, len(body), 0) + body

    def pair(k, v):
        k, v = k.encode(), v.encode()
        head = b""
        for n in (len(k), len(v)):
            head += struct.pack("!B", n) if n < 128 else struct.pack("!I", n | 0x80000000)
        return head + k + v

    params = b"".join(pair(k, v) for k, v in (
        ("SCRIPT_FILENAME", PROBE), ("SCRIPT_NAME", "/probe.php"), ("REQUEST_URI", "/probe.php"),
        ("DOCUMENT_ROOT", PROBE_DIR), ("REQUEST_METHOD", "GET"), ("QUERY_STRING", ""),
        ("SERVER_PROTOCOL", "HTTP/1.1"), ("GATEWAY_INTERFACE", "CGI/1.1"), ("REMOTE_ADDR", "127.0.0.1"),
        ("SERVER_NAME", "localhost"), ("SERVER_PORT", "0"), ("CHECK_WWW", WWW)))
    try:
        if listen.startswith("/"):
            s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
            target = listen
        else:
            host, _, port = listen.rpartition(":")
            s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
            target = (host or "127.0.0.1", int(port))
        s.settimeout(timeout)
        s.connect(target)
        s.sendall(rec(1, struct.pack("!HB5x", 1, 0)) + rec(4, params) + rec(4, b"") + rec(5, b""))
        buf = b""
        while len(buf) < 8 * MB:
            chunk = s.recv(65536)
            if not chunk:
                break
            buf += chunk
        s.close()
    except Exception as e:
        return None, f"PHP did not answer on {listen} ({type(e).__name__})"
    out, err, i = b"", b"", 0
    while i + 8 <= len(buf):
        _, kind, _, length, pad = struct.unpack("!BBHHB", buf[i:i + 7])
        body = buf[i + 8:i + 8 + length]
        i += 8 + length + pad
        if kind == 6:
            out += body
        elif kind == 7:
            err += body
    body = out.partition(b"\r\n\r\n")[2]
    try:
        data = json.loads(body.decode("utf-8", "replace"))
        if isinstance(data, dict) and "php" in data:
            return data, None
    except ValueError:
        pass
    said = re.sub(r"\s+", " ", (err or out).decode("utf-8", "replace")).strip()[:160]
    return None, f"PHP would not run the probe: {said}"


def step_up(value, steps, need=None):
    """The smallest step above the current value (and at least the need). None when already at the top."""
    return next((s for s in steps if s > value and s >= (need or 0)), None)


def mem_advice(ver, target):
    if target:
        print(f"     gp stack php {ver} -opcache-memory {target}    (the cache comes out of RAM: check free -m first)")
    else:
        print(f"     It is already at {MEMORY_STEPS[-1]} MB or more. Fewer sites on PHP {ver}, or a server with more RAM, is the fix.")


def pct(a, b):
    return 100.0 * a / b if b else 0.0


def check(ver, sample):
    ini = settings(ver)
    plist = pools(ver)
    sites = sorted({p["site"] for p in plist if p["site"]})
    print(f"\nPHP {ver}: {len(sites)} site{'s' if len(sites) != 1 else ''} with a pool")
    print(f"  settings file: memory {ini.get('memory_consumption', '?')} MB, files {ini.get('max_accelerated_files', '?')}, "
          f"text buffer {ini.get('interned_strings_buffer', '?')} MB, revalidate_freq {ini.get('revalidate_freq', '?')}")
    if ini.get("enable", "").lower() in ("0", "off", "false", "no"):
        print("  CODE CACHE OFF: opcache.enable is 0, so every request compiles its PHP from scratch.")
        return
    # a site's own pool first; GridPane's stock pools may not be running
    order = [p for p in plist if p["site"]] + [p for p in plist if not p["site"]]
    data, why = None, "no pool has a socket"
    for p in order[:4]:
        if p["listen"].startswith("/") and not os.path.exists(p["listen"]):
            why = f"socket {p['listen']} does not exist"
            continue
        found, why = ask(p["listen"])
        if found and found.get("err") in ("refused", "not_loaded"):
            data = data or found  # remember it, but another pool may allow the read
            why = None
            continue
        if found:
            data, answered = found, p["listen"]
            break
    if not data:
        print(f"  CANNOT SEE the live numbers: {why}. That is not the same as fine.")
        return
    if data.get("err") or not data.get("enabled"):
        if not data.get("err"):
            print("  CODE CACHE OFF: PHP says the cache is not enabled for this version.")
            return
        print({"not_loaded": "  CANNOT SEE: this PHP runs without the OPcache extension, so nothing is cached.",
               "refused": "  CANNOT SEE: PHP refused (opcache.restrict_api, or opcache_get_status is disabled).",
               "off": "  CODE CACHE OFF for this PHP version."}.get(data["err"], f"  CANNOT SEE: {data['err']}"))
        return

    used, free, wasted = data["used"] or 0, data["free"] or 0, data["wasted"] or 0
    total = used + free + wasted
    if not total:
        print("  CANNOT SEE: PHP gave no memory numbers for its cache. That is not the same as fine.")
        return
    taken = pct(used + wasted, total)
    keys, max_keys = data["keys"] or 0, data["max_keys"] or 0
    str_used, str_size = data["str_used"] or 0, data["str_size"] or 0
    hits, misses = data["hits"] or 0, data["misses"] or 0
    started = max(data.get("start") or 0, data.get("last_restart") or 0)
    age_h = (time.time() - started) / 3600 if started else 0
    print(f"  running PHP {data['php']}, cache started {age_h:.1f} hours ago")
    print(f"  memory       {(used + wasted) / MB:6.0f} of {total / MB:.0f} MB taken ({taken:.0f}%), {wasted / MB:.1f} MB of it wasted")
    print(f"  file slots   {keys:6,} of {max_keys:,} ({pct(keys, max_keys):.0f}%)")
    print(f"  text buffer  {str_used / MB:6.1f} of {str_size / MB:.0f} MB ({pct(str_used, str_size):.0f}%)")
    print(f"  hit rate     {pct(hits, hits + misses):.1f}% since the cache started ({hits + misses:,} file loads)")
    if data.get("oom") or data.get("hash"):
        print(f"  emptied for lack of room {data.get('oom') or 0} times, for lack of file slots {data.get('hash') or 0} times")

    recent = None
    if sample and sites:
        time.sleep(sample)
        again, _ = ask(answered)
        if again and not again.get("err") and again.get("start") == data.get("start") and again.get("last_restart") == data.get("last_restart"):
            dh, dm = (again["hits"] or 0) - hits, (again["misses"] or 0) - misses
            if dh + dm >= 500:
                recent = pct(dh, dh + dm)
                print(f"  hit rate     {recent:.1f}% over the last {sample} seconds ({dh + dm:,} file loads)")
            else:
                print(f"  hit rate     too few file loads in {sample} seconds to judge ({dh + dm:,}; 500 needed)")

    by = {(k or "(outside the site folders)"): v for k, v in (data.get("by") or {}).items()}
    cached_bytes = sum(v[1] for v in by.values()) or 1
    print("  cached code by site folder, largest first:")
    for site, (n, b) in sorted(by.items(), key=lambda kv: -kv[1][1]):
        tag = "  <- staging" if site.startswith("staging.") else ""
        print(f"    {site:40.40s} {b / MB:7.1f} MB {pct(b, cached_bytes):4.0f}% {n:7,} files{tag}")
    empty = [s for s in sites if s not in by]
    for s in empty:
        print(f"    {s:40.40s}   nothing cached{'  <- staging' if s.startswith('staging.') else ''}")

    # verdicts, worst first
    mem_now = round(total / MB)
    fitted = [s for s in sites if by.get(s, (0, 0))[1] >= 5 * MB]
    said = False
    if data.get("full") or taken >= 95:
        if sites and len(fitted) < len(sites) and fitted:
            code = max(used - str_size, 0) / MB
            need = code * len(sites) / len(fitted) + str_size / MB
            target = step_up(mem_now, MEMORY_STEPS, need)
            print(f"  -> FULL. Only {len(fitted)} of {len(sites)} sites {'has' if len(fitted) == 1 else 'have'} code in the cache; the rest did not fit.")
            if target:
                print(f"     Raise it to about {target} MB (a guess scaled from the sites that fit), then check again a day later.")
        else:
            target = step_up(mem_now, MEMORY_STEPS, (used / MB) / 0.6)
            print(f"  -> FULL. New PHP files are not cached and are compiled again on every request.")
        mem_advice(ver, target)
        said = True
    elif taken >= 85:
        print("  -> NEARLY FULL. One plugin update or one more site could fill it.")
        mem_advice(ver, step_up(mem_now, MEMORY_STEPS))
        said = True
    elif data.get("oom"):
        print("  -> It has room now, but PHP has emptied it for lack of room before.")
        mem_advice(ver, step_up(mem_now, MEMORY_STEPS))
        said = True
    if (max_keys and pct(keys, max_keys) >= 75) or data.get("hash"):
        target = next((s for s in FILE_STEPS if s >= keys * 1.5), FILE_STEPS[-1])
        print(f"  -> FILE SLOTS {'REACHED' if pct(keys, max_keys) >= 90 else 'CLOSE'}. gp stack php {ver} -opcache-max-accel-files {target}")
        said = True
    if str_size and pct(str_used, str_size) >= 85:
        target = step_up(round(str_size / MB), TEXT_STEPS)
        print(f"  -> TEXT BUFFER {'FULL' if pct(str_used, str_size) >= 95 else 'NEARLY FULL'}.", end=" ")
        if not target:
            print("It is already at the largest step this script suggests; look at what fills it.")
        else:
            print(f"Raise it to {target} MB. GridPane has no command for it; edit the live line by hand.")
            print(f"     It comes out of the cache's own {mem_now} MB, so raise memory by at least as much in the same pass.")
            print(f"     grep -n interned_strings_buffer {ETC}/{ver}/fpm/php.ini    (the line starting with ; is not the live one)")
            print(f"     sed -i 's/^opcache.interned_strings_buffer *=.*/opcache.interned_strings_buffer={target}/' {ETC}/{ver}/fpm/php.ini")
            print(f"     grep -n interned_strings_buffer {ETC}/{ver}/fpm/php.ini    (check the live line changed)")
            print(f"     then reload PHP {ver}: any gp stack php {ver} -opcache-... command does it, so make the memory change last")
        said = True
    staging = sum(b for s, (n, b) in by.items() if s.startswith("staging."))
    if staging and pct(staging, cached_bytes) >= 25 and taken >= 70:
        print(f"  -> STAGING holds {pct(staging, cached_bytes):.0f}% of this cache, in the same cache the live sites use.")
        print("     Move staging to a PHP version of its own, or delete it when the work is done.")
        said = True
    if total and pct(wasted, total) >= 15 and taken < 95:
        print(f"  -> {pct(wasted, total):.0f}% is held by old copies of changed files. PHP clears it only when the cache fills or PHP reloads.")
        said = True
    low = recent if recent is not None else (pct(hits, hits + misses) if hits + misses >= 10000 else None)
    if low is not None and low < 90 and age_h >= 0.5:
        print(f"  -> Many requests miss the cache ({low:.0f}%; healthy is above 99%).")
        said = True
    if not sites:
        print("  -> No site runs on this PHP version. GridPane keeps it running for its own tools; nothing to do.")
    elif not said:
        print(f"  -> Healthy: {100 - taken:.0f}% of the memory and {100 - pct(keys, max_keys):.0f}% of the file slots are free.")


def main():
    args = sys.argv[1:]
    if any(a in ("-h", "--help") for a in args):
        print(__doc__.strip())
        return
    if "--clean" in args:
        for p in (PROBE, PROBE + ".new"):
            if os.path.exists(p):
                os.remove(p)
        if os.path.isdir(PROBE_DIR) and not os.listdir(PROBE_DIR):
            os.rmdir(PROBE_DIR)
        print("removed", PROBE)
        return
    sample = 0
    if "--sample" in args:
        i = args.index("--sample")
        if i + 1 >= len(args) or not args[i + 1].isdigit():
            sys.exit("--sample needs a number of seconds, e.g. --sample 60")
        sample = int(args[i + 1])
        del args[i:i + 2]
    bad = [a for a in args if not re.match(r"^\d+\.\d+$", a)]
    if bad:
        sys.exit(f"unknown argument {bad[0]}; try --help")
    if hasattr(os, "geteuid") and os.geteuid() != 0 and "OPCACHE_CHECK_ETC" not in os.environ:
        sys.exit("run this as root: PHP's sockets on GridPane are readable by root and www-data only")
    versions = sorted((os.path.basename(os.path.dirname(d)) for d in glob.glob(f"{ETC}/*/fpm")
                       if re.match(r"^\d+\.\d+$", os.path.basename(os.path.dirname(d)))),
                      key=lambda v: [int(x) for x in v.split(".")], reverse=True)
    if args:
        versions = [v for v in versions if v in args]
    if not versions:
        sys.exit(f"no PHP-FPM versions found under {ETC}")
    write_probe()
    try:
        mem = dict(re.findall(r"^(\w+):\s+(\d+) kB", open("/proc/meminfo").read(), re.M))
        print(f"Server memory: {int(mem['MemAvailable']) // 1024:,} MB available of {int(mem['MemTotal']) // 1024:,} MB")
    except (OSError, KeyError):
        pass
    for ver in versions:
        check(ver, sample)
    print(f"\nEvery PHP version's cache is its own block of RAM. Leave room for the database and PHP's workers.")
    print(f"This script left one file, {PROBE}; remove it with --clean.")


if __name__ == "__main__":
    main()
