Files
jellyfin_vr_web_plugin/pack.py
T
cat-shark 5279f3929a plugin: fix zip reproducibility and legacy-tag log spam
Two issues found while verifying the live install:

1. pack.py produced a different zip MD5 for identical content, because zip
   records file mtimes. Re-running pack.py would have rewritten the manifest
   checksum while the already-published asset stayed the same, and Jellyfin
   would then refuse the install with "The checksum of the received data
   doesn't match." The zip entry now carries a fixed 1980-01-01 timestamp, and
   --publish downloads the published asset back and compares its MD5 with the
   manifest checksum before reporting success.

2. The legacy deploy.py tag lives in the on-disk index.html, so it was stripped
   from every single response and logged at INFO each time (6 lines and counting
   per boot on the live server). The message is now emitted once, and says what
   it actually means: the tag is still on disk, run deploy.py rollback to clean
   it up.

Verified: 21/21 rewrite checks pass, including a regression case built from the
tag actually present on the server.
2026-10-17 23:33:06 +08:00

452 lines
16 KiB
Python

#!/usr/bin/env python3
"""
Build the JFVR Jellyfin plugin, package it the way Jellyfin expects, and
(optionally) publish it to the Gitea repo that doubles as the plugin catalog.
What it does, in order:
1. build.py src/*.js -> dist/jfvr.js
2. dotnet build plugin/Jellyfin.Plugin.JFVR -> Jellyfin.Plugin.JFVR.dll
(the bundle is embedded straight from dist/jfvr.js)
3. verify the DLL really contains the bytes we just built
4. zip one DLL, named <assembly>_<targetAbi>.zip
5. manifest.json add/replace this version's entry (MD5 = the zip's MD5,
which Jellyfin re-checks at install time)
6. --publish create the Gitea release, upload the zip, push the
manifest so Jellyfin can see it
Usage:
python3 pack.py # build + package + update manifest.json
python3 pack.py --bump # same, after bumping the last version field
python3 pack.py --version 0.2.0.0 # same, with an explicit version
python3 pack.py --publish # ... and publish to Gitea
python3 pack.py --print-urls # just show the catalog URL
Env:
GITEA_TOKEN required by --publish. Scope: write:repository.
Falls back to a GITEA_TOKEN line in secrets.local.md.
GITEA_URL default https://git.cat-shark.xyz
GITEA_REPO default cat-shark/jellyfin_vr_web_plugin
GITEA_BRANCH default main
DOTNET path to the dotnet binary (default: $PATH, then ~/.dotnet/dotnet)
"""
import argparse
import hashlib
import json
import os
import re
import shutil
import subprocess
import sys
import urllib.error
import urllib.request
import uuid
import zipfile
from datetime import datetime, timezone
import yaml
HERE = os.path.dirname(os.path.abspath(__file__))
PLUGIN_DIR = os.path.join(HERE, "plugin")
BUILD_YAML = os.path.join(PLUGIN_DIR, "build.yaml")
PROJECT = os.path.join(PLUGIN_DIR, "Jellyfin.Plugin.JFVR", "Jellyfin.Plugin.JFVR.csproj")
BUNDLE = os.path.join(HERE, "dist", "jfvr.js")
OUT_DIR = os.path.join(HERE, "dist", "plugin")
MANIFEST = os.path.join(HERE, "manifest.json")
SECRETS = os.path.join(HERE, "secrets.local.md")
ASSEMBLY = "Jellyfin.Plugin.JFVR"
MAX_VERSIONS = 20
GITEA_URL = os.environ.get("GITEA_URL", "https://git.cat-shark.xyz").rstrip("/")
GITEA_REPO = os.environ.get("GITEA_REPO", "cat-shark/jellyfin_vr_web_plugin")
GITEA_BRANCH = os.environ.get("GITEA_BRANCH", "main")
# ---------------------------------------------------------------- helpers
def run(cmd, **kw):
"""Run a command, echo it, and abort on failure."""
print("$ " + " ".join(cmd))
r = subprocess.run(cmd, capture_output=True, text=True, **kw)
if r.stdout.strip():
print(r.stdout.rstrip())
if r.returncode != 0:
print(r.stderr.rstrip(), file=sys.stderr)
sys.exit("command failed: %s" % cmd[0])
if r.stderr.strip():
print(r.stderr.rstrip(), file=sys.stderr)
return r
def dotnet_bin():
explicit = os.environ.get("DOTNET")
if explicit:
return explicit
found = shutil.which("dotnet")
if found:
return found
local = os.path.expanduser("~/.dotnet/dotnet")
if os.path.exists(local):
return local
sys.exit("dotnet not found. Install the .NET 10 SDK, or set DOTNET=/path/to/dotnet")
def md5_of(path):
h = hashlib.md5()
with open(path, "rb") as fh:
for chunk in iter(lambda: fh.read(1 << 20), b""):
h.update(chunk)
return h.hexdigest().upper()
def bundle_version():
"""The 6-char version the in-page HUD reports (build.py uses the same rule)."""
with open(BUNDLE, "rb") as fh:
return hashlib.md5(fh.read()).hexdigest()[:6]
def read_build_yaml():
with open(BUILD_YAML, encoding="utf-8") as fh:
return yaml.safe_load(fh)
def bump(version):
parts = version.split(".")
while len(parts) < 4:
parts.append("0")
parts[-1] = str(int(parts[-1]) + 1)
return ".".join(parts)
def write_build_yaml_version(version):
with open(BUILD_YAML, encoding="utf-8") as fh:
text = fh.read()
text = re.sub(r'^version:\s*".*?"', 'version: "%s"' % version, text, count=1, flags=re.M)
with open(BUILD_YAML, "w", encoding="utf-8") as fh:
fh.write(text)
def catalog_url():
return "%s/%s/raw/branch/%s/manifest.json" % (GITEA_URL, GITEA_REPO, GITEA_BRANCH)
def source_url(tag, asset):
return "%s/%s/releases/download/%s/%s" % (GITEA_URL, GITEA_REPO, tag, asset)
# ---------------------------------------------------------------- gitea
def gitea_token():
token = os.environ.get("GITEA_TOKEN")
if token:
return token.strip()
if os.path.exists(SECRETS):
with open(SECRETS, encoding="utf-8") as fh:
for line in fh:
m = re.match(r"^\s*GITEA_TOKEN\s*[:=]\s*(\S+)", line)
if m:
return m.group(1)
sys.exit(
"--publish needs a Gitea token.\n"
"Create one at %s/user/settings/applications (scope: write:repository)\n"
"then export GITEA_TOKEN=... or add a 'GITEA_TOKEN: ...' line to secrets.local.md"
% GITEA_URL
)
def gitea_request(method, path, token, body=None, ctype="application/json"):
url = "%s/api/v1%s" % (GITEA_URL, path)
data = json.dumps(body).encode() if body is not None else None
req = urllib.request.Request(url, data=data, method=method)
req.add_header("Authorization", "token " + token)
req.add_header("Content-Type", ctype)
try:
with urllib.request.urlopen(req, timeout=60) as resp:
raw = resp.read()
return resp.status, (json.loads(raw) if raw else None)
except urllib.error.HTTPError as e:
raw = e.read()
try:
return e.code, json.loads(raw)
except Exception:
return e.code, raw.decode("utf-8", "replace")
def multipart(fields, files):
boundary = "----JFVR" + uuid.uuid4().hex
out = bytearray()
for key, value in fields.items():
out += ('--%s\r\nContent-Disposition: form-data; name="%s"\r\n\r\n%s\r\n'
% (boundary, key, value)).encode()
for key, (filename, data, ctype) in files.items():
out += ('--%s\r\nContent-Disposition: form-data; name="%s"; filename="%s"\r\n'
'Content-Type: %s\r\n\r\n' % (boundary, key, filename, ctype)).encode()
out += data + b"\r\n"
out += ("--%s--\r\n" % boundary).encode()
return bytes(out), "multipart/form-data; boundary=%s" % boundary
def publish(tag, meta, zip_path, asset_name, changelog, token):
path = "/repos/%s/releases/tags/%s" % (GITEA_REPO, tag)
status, release = gitea_request("GET", path, token)
if status == 200:
print("release %s already exists (id %s)" % (tag, release["id"]))
else:
status, release = gitea_request("POST", "/repos/%s/releases" % GITEA_REPO, token, {
"tag_name": tag,
"name": "%s %s" % (meta["name"], tag),
"body": changelog,
"draft": False,
"prerelease": False,
})
if status not in (200, 201):
sys.exit("creating release %s failed (%s): %s" % (tag, status, release))
print("created release %s (id %s)" % (tag, release["id"]))
release_id = release["id"]
for asset in release.get("assets") or []:
if asset["name"] == asset_name:
gitea_request("DELETE",
"/repos/%s/releases/%s/assets/%s" % (GITEA_REPO, release_id, asset["id"]),
token)
print("replaced existing asset %s" % asset_name)
with open(zip_path, "rb") as fh:
payload, ctype = multipart({}, {"attachment": (asset_name, fh.read(), "application/zip")})
url = "%s/api/v1/repos/%s/releases/%s/assets?name=%s" % (GITEA_URL, GITEA_REPO, release_id, asset_name)
req = urllib.request.Request(url, data=payload, method="POST")
req.add_header("Authorization", "token " + token)
req.add_header("Content-Type", ctype)
try:
with urllib.request.urlopen(req, timeout=300) as resp:
json.loads(resp.read())
except urllib.error.HTTPError as e:
sys.exit("uploading %s failed (%s): %s" % (asset_name, e.code, e.read().decode("utf-8", "replace")))
print("uploaded %s" % asset_name)
def head_ok(url):
"""A draft release 404s on its download URL; verify the asset is really live."""
req = urllib.request.Request(url, method="HEAD")
try:
with urllib.request.urlopen(req, timeout=60) as resp:
return resp.status, resp.headers.get("Content-Length")
except urllib.error.HTTPError as e:
return e.code, None
def fetch_md5(url):
"""Download the published asset and hash it -- exactly what Jellyfin does.
This is the check that catches a manifest whose checksum no longer matches the
uploaded zip (a real failure mode: the install then dies with
"The checksum of the received data doesn't match.").
"""
h = hashlib.md5()
req = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(req, timeout=300) as resp:
while True:
chunk = resp.read(1 << 20)
if not chunk:
break
h.update(chunk)
return h.hexdigest().upper()
# ---------------------------------------------------------------- steps
def build_bundle():
run([sys.executable, os.path.join(HERE, "build.py")], cwd=HERE)
def build_plugin(version):
env = dict(os.environ)
dotnet = dotnet_bin()
env["DOTNET_ROOT"] = os.path.dirname(dotnet)
env["DOTNET_CLI_TELEMETRY_OPTOUT"] = "1"
env["DOTNET_NOLOGO"] = "1"
run([dotnet, "build", PROJECT, "-c", "Release", "-p:Version=" + version], cwd=HERE, env=env)
dll = os.path.join(os.path.dirname(PROJECT), "bin", "Release", "net10.0", ASSEMBLY + ".dll")
if not os.path.exists(dll):
sys.exit("expected build output missing: %s" % dll)
return dll
def verify_embedded(dll):
"""Guard against shipping a DLL whose embedded bundle is not what we built."""
with open(dll, "rb") as fh:
blob = fh.read()
with open(BUNDLE, "rb") as fh:
bundle = fh.read()
at = blob.find(bundle)
if at < 0:
sys.exit("the built DLL does not contain dist/jfvr.js -- refusing to package")
if int.from_bytes(blob[at - 4:at], "little") != len(bundle):
sys.exit("embedded bundle length prefix mismatch -- refusing to package")
print("verified: DLL embeds %d bytes of dist/jfvr.js (md5 %s)" % (len(bundle), bundle_version()))
def make_zip(dll, target_abi):
"""Package the DLL the way Jellyfin expects: one file, named after the assembly.
The entry gets a fixed timestamp on purpose. zip stores mtimes, so packaging
the same DLL twice would otherwise produce different bytes, a different MD5,
and a manifest checksum that no longer matches the already-uploaded asset.
"""
os.makedirs(OUT_DIR, exist_ok=True)
asset = "%s_%s.zip" % (ASSEMBLY, target_abi)
path = os.path.join(OUT_DIR, asset)
info = zipfile.ZipInfo(ASSEMBLY + ".dll", date_time=(1980, 1, 1, 0, 0, 0))
info.compress_type = zipfile.ZIP_DEFLATED
info.external_attr = 0o644 << 16
with open(dll, "rb") as fh:
payload = fh.read()
with zipfile.ZipFile(path, "w") as zf:
zf.writestr(info, payload)
print("packaged %s (%d bytes)" % (path, os.path.getsize(path)))
return path, asset
def update_manifest(meta, version, asset, checksum, changelog):
if os.path.exists(MANIFEST):
with open(MANIFEST, encoding="utf-8") as fh:
manifest = json.load(fh)
else:
manifest = []
package = next((p for p in manifest if p.get("guid") == meta["guid"]), None)
if package is None:
package = {
"name": meta["name"],
"guid": meta["guid"],
"overview": meta["overview"],
"description": meta["description"],
"owner": meta["owner"],
"category": meta["category"],
"versions": [],
}
if meta.get("imageUrl"):
package["imageUrl"] = meta["imageUrl"]
manifest.append(package)
for key in ("name", "overview", "description", "owner", "category"):
package[key] = meta[key]
entry = {
"version": version,
"targetAbi": meta["targetAbi"],
"changelog": changelog,
"sourceUrl": source_url("v" + version, asset),
"checksum": checksum,
"timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S"),
}
package["versions"] = [v for v in package["versions"] if v.get("version") != version]
package["versions"].insert(0, entry)
package["versions"] = package["versions"][:MAX_VERSIONS]
with open(MANIFEST, "w", encoding="utf-8") as fh:
json.dump(manifest, fh, indent=2, ensure_ascii=False)
fh.write("\n")
return entry
def main():
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--version", help="plugin version, e.g. 0.2.0.0")
ap.add_argument("--bump", action="store_true", help="bump the last version component")
ap.add_argument("--publish", action="store_true", help="create the Gitea release and upload the zip")
ap.add_argument("--no-push", action="store_true", help="with --publish: skip git commit/push")
ap.add_argument("--print-urls", action="store_true", help="print the catalog URL and exit")
args = ap.parse_args()
if args.print_urls:
print("Jellyfin plugin repository URL:")
print(" " + catalog_url())
return
meta = read_build_yaml()
if args.version:
version = args.version
write_build_yaml_version(version)
elif args.bump:
version = bump(meta["version"])
write_build_yaml_version(version)
meta = read_build_yaml()
else:
version = meta["version"]
print("=" * 72)
print("JFVR plugin %s (targetAbi %s)" % (version, meta["targetAbi"]))
print("=" * 72)
build_bundle()
js_ver = bundle_version()
dll = build_plugin(version)
verify_embedded(dll)
zip_path, asset = make_zip(dll, meta["targetAbi"])
checksum = md5_of(zip_path)
print("zip md5: %s" % checksum)
changelog = (meta.get("changelog") or "").strip()
changelog = "Bundle version: `%s`\n\n%s" % (js_ver, changelog)
entry = update_manifest(meta, version, asset, checksum, changelog)
print("manifest.json updated: %s" % entry["sourceUrl"])
if args.publish:
token = gitea_token()
publish("v" + version, meta, zip_path, asset, changelog, token)
status, length = head_ok(entry["sourceUrl"])
print("asset check: HTTP %s, %s bytes" % (status, length))
if status != 200:
sys.exit("the asset is not downloadable -- is the release a draft?")
# What Jellyfin will do at install time: download it and compare MD5.
live = fetch_md5(entry["sourceUrl"])
if live != checksum:
sys.exit("published asset md5 %s != manifest checksum %s -- install would fail"
% (live, checksum))
print("asset md5 matches the manifest checksum (%s)" % live)
if not args.no_push:
run(["git", "add", "manifest.json", "plugin/build.yaml"], cwd=HERE)
dirty = subprocess.run(
["git", "diff", "--cached", "--quiet", "--", "manifest.json", "plugin/build.yaml"],
cwd=HERE,
).returncode != 0
if dirty:
run(["git", "commit", "-m", "plugin: publish %s (bundle %s)" % (version, js_ver)], cwd=HERE)
else:
print("manifest.json unchanged -- nothing to commit")
run(["git", "push", "origin", GITEA_BRANCH], cwd=HERE)
else:
print("--no-push: push manifest.json yourself, Jellyfin reads it from the branch")
print()
print("=" * 72)
print("Jellyfin plugin repository URL:")
print(" " + catalog_url())
print()
print("Bundle (in-page HUD version): %s" % js_ver)
print("Install: Dashboard > Plugins > Catalog > gear > + > paste the URL above.")
if not args.publish:
print("Then: python3 pack.py --publish (creates the release and pushes the manifest)")
if __name__ == "__main__":
main()