From f1ea45452af31e8829db430545487202f38d91c8 Mon Sep 17 00:00:00 2001 From: Sander Date: Sat, 7 Nov 2026 10:57:06 +0100 Subject: [PATCH 1/2] fix(release): serialise staging with certification; recover unmarked shadows - stage-compatibility-release shares the certification concurrency group. Staging closes older staging PRs and deletes their branches; with a separate group it did that to a candidate that was still being certified (1.3.26: #71), wasting a full certification. - is_shadow_database accepts a database carrying exactly one shadow marker when the sidecar is missing. build_shadow_database moves the database before the sidecar, so an interrupted install left a shadow that every later start refused. A sidecar that is present must still match. Both files are in the pinned release trust surface; the next certified release needs a trust re-bootstrap. Co-Authored-By: Claude Opus 5.5 --- .../workflows/stage-compatibility-release.yml | 5 +- CHANGELOG.md | 4 ++ scripts/migrate_lib.sh | 10 +++- scripts/tests/test_shadow_marker.py | 57 +++++++++++++++++++ 4 files changed, 73 insertions(+), 3 deletions(-) create mode 100644 scripts/tests/test_shadow_marker.py diff --git a/.github/workflows/stage-compatibility-release.yml b/.github/workflows/stage-compatibility-release.yml index 6701d5bb..b1f620a6 100644 --- a/.github/workflows/stage-compatibility-release.yml +++ b/.github/workflows/stage-compatibility-release.yml @@ -19,8 +19,11 @@ on: type: string permissions: contents: read +# Shares the certification group: staging closes older staging PRs and +# deletes their branches, which must never happen while one of them is being +# certified. It now waits for a running certification to finish. concurrency: - group: compatibility-release-staging + group: compatibility-release-certification cancel-in-progress: false jobs: stage: diff --git a/CHANGELOG.md b/CHANGELOG.md index 13914a8d..57fb5772 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed +- A shadow database whose sidecar file is missing (installation interrupted between moving the database and its marker file) is recognised by its marker table instead of being refused as an unknown library. +- Release staging waits for a running certification instead of closing that candidate's pull request and deleting its branch mid-certification. + ## [1.3.26] - 2026-11-06 ### Fixed diff --git a/scripts/migrate_lib.sh b/scripts/migrate_lib.sh index 988085aa..b554f7fd 100644 --- a/scripts/migrate_lib.sh +++ b/scripts/migrate_lib.sh @@ -421,20 +421,26 @@ protect_sqlite_sources() { } is_shadow_database() { - [[ -f "$1" && -f "${1}.plex-pg-shadow" ]] || return 1 + [[ -f "$1" ]] || return 1 python3 - "$1" <<'PY' import pathlib import sqlite3 import sys path = pathlib.Path(sys.argv[1]) +sidecar = pathlib.Path(str(path) + '.plex-pg-shadow') try: connection = sqlite3.connect(path.resolve().as_uri() + '?mode=ro', uri=True) identity = connection.execute('SELECT identity FROM plex_pg_shadow_marker').fetchall() - expected = pathlib.Path(str(path) + '.plex-pg-shadow').read_text().strip() connection.close() + expected = sidecar.read_text().strip() if sidecar.exists() else None except (OSError, sqlite3.Error): sys.exit(1) +if expected is None: + # build_shadow_database installs the database before its sidecar; a crash + # in between leaves a marked shadow without one. Only that function + # creates the marker table, so one marker row identifies a shadow. + sys.exit(0 if len(identity) == 1 and identity[0][0] else 1) sys.exit(0 if identity == [(expected,)] and expected else 1) PY } diff --git a/scripts/tests/test_shadow_marker.py b/scripts/tests/test_shadow_marker.py new file mode 100644 index 00000000..bd6585c5 --- /dev/null +++ b/scripts/tests/test_shadow_marker.py @@ -0,0 +1,57 @@ +"""A shadow database is recognised by its marker, with or without its sidecar.""" +from contextlib import closing +import pathlib +import sqlite3 +import subprocess +import tempfile +import unittest + + +ROOT = pathlib.Path(__file__).resolve().parents[2] + + +def is_shadow(path): + return subprocess.run( + ['bash', '-c', 'source "$1"; is_shadow_database "$2"', 'shadow-test', + str(ROOT / 'scripts/migrate_lib.sh'), str(path)], + capture_output=True, text=True, timeout=30).returncode == 0 + + +class ShadowMarkerTests(unittest.TestCase): + def database(self, root, name, marker=None): + path = root / name + with closing(sqlite3.connect(path)) as connection, connection: + connection.execute('CREATE TABLE metadata_items(id INTEGER PRIMARY KEY)') + if marker is not None: + connection.execute('CREATE TABLE plex_pg_shadow_marker(identity TEXT NOT NULL)') + connection.execute('INSERT INTO plex_pg_shadow_marker VALUES (?)', (marker,)) + return path + + def test_marker_and_sidecar(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + matching = self.database(root, 'matching.db', 'identity-1') + pathlib.Path(str(matching) + '.plex-pg-shadow').write_text('identity-1\n') + self.assertTrue(is_shadow(matching)) + + mismatched = self.database(root, 'mismatched.db', 'identity-1') + pathlib.Path(str(mismatched) + '.plex-pg-shadow').write_text('identity-2\n') + self.assertFalse(is_shadow(mismatched)) + + def test_marker_without_sidecar_after_interrupted_install(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + self.assertTrue(is_shadow(self.database(root, 'shadow.db', 'identity-1'))) + + def test_real_library_is_never_a_shadow(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + library = self.database(root, 'library.db') + self.assertFalse(is_shadow(library)) + pathlib.Path(str(library) + '.plex-pg-shadow').write_text('identity-1\n') + self.assertFalse(is_shadow(library)) + self.assertFalse(is_shadow(root / 'missing.db')) + + +if __name__ == '__main__': + unittest.main() From 177df9f9f7525a060e79159c5d29f572942f68e9 Mon Sep 17 00:00:00 2001 From: Sander Date: Sat, 7 Nov 2026 11:02:28 +0100 Subject: [PATCH 2/2] fix(release): address review of staging and shadow changes Codex review of the previous commit: - Sharing the certification concurrency group let a later run replace the pending certification that staging had just dispatched. Keep the groups separate; staging instead skips closing older staging PRs while a certification is running or queued. - Accepting a marker-only database as a shadow could let a restored or reused real library be treated as disposable. Keep the strict sidecar check and explain the likely interrupted installation in the refusal. Co-Authored-By: Claude Opus 5.5 --- .../workflows/stage-compatibility-release.yml | 28 +++++++++------ CHANGELOG.md | 4 +-- scripts/migrate_lib.sh | 35 +++++++++++++----- scripts/tests/test_shadow_marker.py | 36 ++++++++++--------- 4 files changed, 66 insertions(+), 37 deletions(-) diff --git a/.github/workflows/stage-compatibility-release.yml b/.github/workflows/stage-compatibility-release.yml index b1f620a6..06e59d27 100644 --- a/.github/workflows/stage-compatibility-release.yml +++ b/.github/workflows/stage-compatibility-release.yml @@ -19,11 +19,8 @@ on: type: string permissions: contents: read -# Shares the certification group: staging closes older staging PRs and -# deletes their branches, which must never happen while one of them is being -# certified. It now waits for a running certification to finish. concurrency: - group: compatibility-release-certification + group: compatibility-release-staging cancel-in-progress: false jobs: stage: @@ -66,13 +63,22 @@ jobs: fi test "$(gh api "repos/$GITHUB_REPOSITORY/commits/${{ github.event.repository.default_branch }}" --jq .sha)" = "$SOURCE_SHA" git -c 'credential.helper=!gh auth git-credential' push origin "$branch" - # Only the newest staged leaf can be certified; close older ones. - gh pr list --repo "$GITHUB_REPOSITORY" --state open --json number,headRefName \ - --jq '.[] | select(.headRefName | startswith("automation/release-stage-")) | .number' | - while read -r number; do - gh pr close "$number" --repo "$GITHUB_REPOSITORY" --delete-branch \ - --comment "Superseded by staging run $GITHUB_RUN_ID." - done + # Only the newest staged leaf can be certified; close older ones, + # but never while a certification runs or waits: it may be + # certifying one of them (1.3.26 lost a finished certification + # that way). A later staging run closes them. + active_certifications=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow release-certification.yml \ + --limit 20 --json status --jq '[.[] | select(.status != "completed")] | length') + if [[ "$active_certifications" == 0 ]]; then + gh pr list --repo "$GITHUB_REPOSITORY" --state open --json number,headRefName \ + --jq '.[] | select(.headRefName | startswith("automation/release-stage-")) | .number' | + while read -r number; do + gh pr close "$number" --repo "$GITHUB_REPOSITORY" --delete-branch \ + --comment "Superseded by staging run $GITHUB_RUN_ID." + done + else + echo "A certification is running; older staging PRs stay open." >> "$GITHUB_STEP_SUMMARY" + fi gh pr create --repo "$GITHUB_REPOSITORY" --base '${{ github.event.repository.default_branch }}' --head "$branch" --title "Stage compatibility release $(cat VERSION)" --body 'Version and factual changelog frozen before full native certification. Preserve this leaf with a merge; squash/rebase or concurrent main changes require fresh staging and certification.' echo "Frozen candidate: $(git rev-parse HEAD)" >> "$GITHUB_STEP_SUMMARY" gh workflow run release-certification.yml --ref '${{ github.event.repository.default_branch }}' -f "source_sha=$(git rev-parse HEAD)" -f "upstream_profile_json=$PROFILE_JSON" -f "profile_id=$PROFILE_ID" -f mode=full diff --git a/CHANGELOG.md b/CHANGELOG.md index 57fb5772..a0d903a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Fixed -- A shadow database whose sidecar file is missing (installation interrupted between moving the database and its marker file) is recognised by its marker table instead of being refused as an unknown library. -- Release staging waits for a running certification instead of closing that candidate's pull request and deleting its branch mid-certification. +- A shadow database without its sidecar file (an interrupted installation) is still refused, since it may have been used as a real library since, but the error now explains that and how to recover. +- Release staging no longer closes older staging pull requests (and deletes their branches) while a certification is running or queued, which had discarded a finished 1.3.26 certification. ## [1.3.26] - 2026-11-06 diff --git a/scripts/migrate_lib.sh b/scripts/migrate_lib.sh index b554f7fd..6a671e01 100644 --- a/scripts/migrate_lib.sh +++ b/scripts/migrate_lib.sh @@ -421,36 +421,54 @@ protect_sqlite_sources() { } is_shadow_database() { - [[ -f "$1" ]] || return 1 + [[ -f "$1" && -f "${1}.plex-pg-shadow" ]] || return 1 python3 - "$1" <<'PY' import pathlib import sqlite3 import sys path = pathlib.Path(sys.argv[1]) -sidecar = pathlib.Path(str(path) + '.plex-pg-shadow') try: connection = sqlite3.connect(path.resolve().as_uri() + '?mode=ro', uri=True) identity = connection.execute('SELECT identity FROM plex_pg_shadow_marker').fetchall() + expected = pathlib.Path(str(path) + '.plex-pg-shadow').read_text().strip() connection.close() - expected = sidecar.read_text().strip() if sidecar.exists() else None except (OSError, sqlite3.Error): sys.exit(1) -if expected is None: - # build_shadow_database installs the database before its sidecar; a crash - # in between leaves a marked shadow without one. Only that function - # creates the marker table, so one marker row identifies a shadow. - sys.exit(0 if len(identity) == 1 and identity[0][0] else 1) sys.exit(0 if identity == [(expected,)] and expected else 1) PY } +# A database with a shadow marker but no sidecar is most likely left by an +# interrupted shadow installation (the database is moved before its sidecar). +# It is still refused: it may since have been used as a real library. +shadow_recovery_hint() { + [[ -f "$1" && ! -e "${1}.plex-pg-shadow" ]] || return 0 + python3 - "$1" <<'PY' || return 0 +import pathlib +import sqlite3 +import sys + +path = pathlib.Path(sys.argv[1]) +try: + connection = sqlite3.connect(path.resolve().as_uri() + '?mode=ro', uri=True) + rows = connection.execute('SELECT identity FROM plex_pg_shadow_marker').fetchall() + connection.close() +except (OSError, sqlite3.Error): + sys.exit(1) +sys.exit(0 if len(rows) == 1 else 1) +PY + echo " It carries a plex-postgresql shadow marker but no ${1}.plex-pg-shadow file, which usually means a" >&2 + echo " shadow installation was interrupted. If it was not used with plain Plex since, move it aside and start again." >&2 +} + protect_shadow_destinations() { local shadow_dir="$1" db_file protect_sqlite_sources "$shadow_dir" || return 1 for db_file in "$shadow_dir/com.plexapp.plugins.library.db" "$shadow_dir/com.plexapp.plugins.library.blobs.db"; do if [[ -e "$db_file" ]] && ! is_shadow_database "$db_file"; then echo "ERROR: Unmarked SQLite destination $db_file; preserve it as a separate source/backup before startup." >&2 + shadow_recovery_hint "$db_file" return 1 fi done @@ -726,6 +744,7 @@ build_shadow_database() ( protect_sqlite_sources "$(dirname "$db_file")" || return 1 if [[ -e "$db_file" ]] && ! is_shadow_database "$db_file"; then echo "ERROR: Unmarked SQLite destination $db_file; preserve it as a separate backup before rebuilding." >&2 + shadow_recovery_hint "$db_file" return 1 fi temporary=$(mktemp "${db_file}.new.XXXXXX") || return 1 diff --git a/scripts/tests/test_shadow_marker.py b/scripts/tests/test_shadow_marker.py index bd6585c5..f0362b76 100644 --- a/scripts/tests/test_shadow_marker.py +++ b/scripts/tests/test_shadow_marker.py @@ -1,4 +1,4 @@ -"""A shadow database is recognised by its marker, with or without its sidecar.""" +"""Shadow databases need their sidecar; a marker alone only earns a recovery hint.""" from contextlib import closing import pathlib import sqlite3 @@ -10,11 +10,11 @@ ROOT = pathlib.Path(__file__).resolve().parents[2] -def is_shadow(path): +def run(function, path): return subprocess.run( - ['bash', '-c', 'source "$1"; is_shadow_database "$2"', 'shadow-test', + ['bash', '-c', 'source "$1"; ' + function + ' "$2"', 'shadow-test', str(ROOT / 'scripts/migrate_lib.sh'), str(path)], - capture_output=True, text=True, timeout=30).returncode == 0 + capture_output=True, text=True, timeout=30) class ShadowMarkerTests(unittest.TestCase): @@ -27,30 +27,34 @@ def database(self, root, name, marker=None): connection.execute('INSERT INTO plex_pg_shadow_marker VALUES (?)', (marker,)) return path - def test_marker_and_sidecar(self): + def test_shadow_requires_matching_sidecar(self): with tempfile.TemporaryDirectory() as directory: root = pathlib.Path(directory) matching = self.database(root, 'matching.db', 'identity-1') pathlib.Path(str(matching) + '.plex-pg-shadow').write_text('identity-1\n') - self.assertTrue(is_shadow(matching)) + self.assertEqual(run('is_shadow_database', matching).returncode, 0) mismatched = self.database(root, 'mismatched.db', 'identity-1') pathlib.Path(str(mismatched) + '.plex-pg-shadow').write_text('identity-2\n') - self.assertFalse(is_shadow(mismatched)) + self.assertNotEqual(run('is_shadow_database', mismatched).returncode, 0) - def test_marker_without_sidecar_after_interrupted_install(self): - with tempfile.TemporaryDirectory() as directory: - root = pathlib.Path(directory) - self.assertTrue(is_shadow(self.database(root, 'shadow.db', 'identity-1'))) + # A marker without sidecar may since be a real library: refused. + unmarked = self.database(root, 'unmarked.db', 'identity-1') + self.assertNotEqual(run('is_shadow_database', unmarked).returncode, 0) - def test_real_library_is_never_a_shadow(self): + def test_recovery_hint_only_for_marker_without_sidecar(self): with tempfile.TemporaryDirectory() as directory: root = pathlib.Path(directory) + interrupted = self.database(root, 'interrupted.db', 'identity-1') + self.assertIn('shadow installation was interrupted', + run('shadow_recovery_hint', interrupted).stderr) + library = self.database(root, 'library.db') - self.assertFalse(is_shadow(library)) - pathlib.Path(str(library) + '.plex-pg-shadow').write_text('identity-1\n') - self.assertFalse(is_shadow(library)) - self.assertFalse(is_shadow(root / 'missing.db')) + self.assertEqual(run('shadow_recovery_hint', library).stderr, '') + + marked = self.database(root, 'marked.db', 'identity-1') + pathlib.Path(str(marked) + '.plex-pg-shadow').write_text('identity-1\n') + self.assertEqual(run('shadow_recovery_hint', marked).stderr, '') if __name__ == '__main__':