Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
feat(linux): add standard AppImage update metadata
Satwik Sharmae3bde938a9bb
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 8eb4938f9..eff4443b6 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -658,9 +658,9 @@ jobs:# bsdtar (libarchive-tools) is fpm's mtree generator for the pacman target.# rpmbuild (rpm) is what fpm shells out to for the rpm target; without it the- # build fails at packaging, not at config parse.+ # build fails at packaging, not at config parse. zsync generates AppImageUpdate sidecars.- name: Install Linux packaging dependencies- run: sudo apt-get update && sudo apt-get install -y libarchive-tools rpm+ run: sudo apt-get update && sudo apt-get install -y libarchive-tools rpm zsync# patchelf is what build-linux-compositor-addon.mjs renames the ffmpeg symbols# with, so the addon cannot bind to Chromium's bundled ffmpeg — an unconditional@@ -715,6 +715,21 @@ jobs:exit 1fi+ - name: Verify AppImage update information and sidecars+ run: |+ VERSION="$(node -p 'require("./package.json").version')"+ EXPECTED='gh-releases-zsync|getopenscreen|openscreen|latest|Openscreen-Linux-*.AppImage.zsync'+ # Helper-only prereleases can be selected by AppImageUpdate's latest-all channel.+ # RCs keep using electron-updater; their .zsync is available by its explicit URL.+ if [[ "$VERSION" == *-* ]]; then EXPECTED=''; fi+ while IFS= read -r -d '' IMAGE; do+ test -s "${IMAGE}.zsync" \+ || { echo "::error::${IMAGE}.zsync missing — external AppImage updates have no sidecar"; exit 1; }+ INFO="$("$IMAGE" --appimage-updateinformation)"+ [[ "$INFO" == "$EXPECTED" ]] \+ || { echo "::error::Unexpected AppImage update information in ${IMAGE}: ${INFO}"; exit 1; }+ done < <(find release -type f -name '*.AppImage' -print0)+# The Linux counterpart of the Windows job's "Verify native binaries load under# package identity", added for the same reason and after the same kind of miss:# 1.9.1 shipped three sonames that nothing declared and nothing bundled — libgbm.so.1@@ -754,16 +769,12 @@ jobs:name: openscreen-linuxpath: |release/**/*.AppImage+ release/**/*.AppImage.zsyncrelease/**/*.debrelease/**/*.pacmanrelease/**/*.rpmrelease/**/latest-linux.yml- # Still no *.zsync, and there never will be: zsync was electron-updater's old delta- # format and app-builder-lib 26.x dropped it in favour of the block map it embeds- # directly in the AppImage. That glob had matched nothing since the dependency bump,- # silently — `if-no-files-found: error` evaluates the union of these patterns, so one- # dead glob among live ones never fails. Hence the explicit assertion below.- #+ # .zsync serves external AppImage tools; electron-updater uses the embedded blockmap.# latest-linux.yml serves all four formats from one file: each updater picks its own# extension out of the `files:` list. app-update.yml and the `package-type` marker are# already inside the deb/rpm/pacman payloads — only this feed was missing.diff --git a/electron-builder.json5 b/electron-builder.json5index c5733ff9e..ff890bdec 100644--- a/electron-builder.json5+++ b/electron-builder.json5@@ -47,6 +47,9 @@// (unknown scene fields are #[serde(default)]) rather than erroring. See the script header// and technical-documentation/engineering/build-and-packaging.md."beforePack": "scripts/before-pack.cjs",+ // Standard AppImage updates need .upd_info and a .zsync alongside electron-updater's blockmap.+ "artifactBuildCompleted": "scripts/appimage-updates.cjs",+ "afterAllArtifactBuild": "scripts/appimage-updates.cjs","npmRebuild": true,// sharp ships ABI-stable (napi) prebuilt binaries with bundled libvips. Building it from source// needs a system libvips we don't provide and breaks on CI/local ("vips-cpp.42 not found"), so wediff --git a/scripts/appimage-updates.cjs b/scripts/appimage-updates.cjsnew file mode 100644index 000000000..f4a1a6e8d--- /dev/null+++ b/scripts/appimage-updates.cjs@@ -0,0 +1,131 @@+// Standard AppImage update information complements electron-updater's embedded blockmap.+// artifactBuildCompleted runs before artifactCreated, where electron-builder schedules the feed+// and upload. Mutating the file after that point would leave latest-linux.yml's hashes stale.+const childProcess = require("node:child_process");+const fs = require("node:fs");+const path = require("node:path");++const REPOSITORY = "getopenscreen/openscreen";+const ASSET_PATTERN = "Openscreen-Linux-*.AppImage.zsync";++function readBuffer(fd, offset, length, limit) {+ if (+ !Number.isSafeInteger(offset) ||+ !Number.isSafeInteger(length) ||+ offset < 0 ||+ length < 0 ||+ offset + length > limit+ ) {+ throw new Error("AppImage ELF section extends beyond the artifact");+ }+ const buffer = Buffer.alloc(length);+ let read = 0;+ while (read < length) {+ const count = fs.readSync(fd, buffer, read, length - read, offset + read);+ if (count === 0) throw new Error("AppImage ELF section is truncated");+ read += count;+ }+ return buffer;+}++function findUpdateSection(fd, payloadSize) {+ const header = readBuffer(fd, 0, 64, payloadSize);+ if (+ header.subarray(0, 4).toString("hex") !== "7f454c46" ||+ header.subarray(8, 11).toString("hex") !== "414902" ||+ ![1, 2].includes(header[4]) ||+ header[5] !== 1+ ) {+ throw new Error("Expected a little-endian ELF32 or ELF64 type-2 AppImage");+ }+ const is64 = header[4] === 2;+ const tableOffset = is64 ? Number(header.readBigUInt64LE(40)) : header.readUInt32LE(32);+ const entrySize = header.readUInt16LE(is64 ? 58 : 46);+ const entryCount = header.readUInt16LE(is64 ? 60 : 48);+ const namesIndex = header.readUInt16LE(is64 ? 62 : 50);+ if (entrySize !== (is64 ? 64 : 40) || namesIndex >= entryCount) {+ throw new Error("AppImage ELF section table is invalid");+ }+ const table = readBuffer(fd, tableOffset, entrySize * entryCount, payloadSize);+ const section = (index) => {+ const offset = index * entrySize;+ return {+ name: table.readUInt32LE(offset),+ offset: is64 ? Number(table.readBigUInt64LE(offset + 24)) : table.readUInt32LE(offset + 16),+ size: is64 ? Number(table.readBigUInt64LE(offset + 32)) : table.readUInt32LE(offset + 20),+ };+ };+ const namesSection = section(namesIndex);+ const names = readBuffer(fd, namesSection.offset, namesSection.size, payloadSize);+ for (let index = 0; index < entryCount; index++) {+ const entry = section(index);+ const end = names.indexOf(0, entry.name);+ if (end < 0) throw new Error("AppImage ELF section name is invalid");+ if (names.subarray(entry.name, end).toString("utf8") === ".upd_info") {+ // Validate the complete reserved range before changing any bytes.+ readBuffer(fd, entry.offset, entry.size, payloadSize);+ return entry;+ }+ }+ throw new Error("AppImage runtime has no reserved .upd_info section");+}++exports.artifactBuildCompleted = async function artifactBuildCompleted(event) {+ if (event.target?.name !== "appImage" || !event.file?.endsWith(".AppImage")) return;+ const version = event.packager.appInfo.version;+ // Stable installs discover stable releases. AppImageUpdate's latest-all / latest-pre+ // choose a release before matching assets, so helper-only prereleases such as+ // v0.0.0-stt-models would break RC discovery. Leave RCs without automatic discovery;+ // their tagged .zsync still supports an explicitly selected update.+ const information = version.includes("-")+ ? Buffer.alloc(0)+ : Buffer.from(`gh-releases-zsync|${REPOSITORY.replace("/", "|")}|latest|${ASSET_PATTERN}`);+ const blockMapSize = event.updateInfo?.blockMapSize;+ const fd = fs.openSync(event.file, "r+");+ try {+ const size = fs.fstatSync(fd).size;+ if (!Number.isSafeInteger(blockMapSize) || blockMapSize <= 0 || blockMapSize + 4 >= size) {+ throw new Error("AppImage embedded blockmap size is invalid");+ }+ const trailer = readBuffer(fd, size - 4, 4, size);+ if (trailer.readUInt32BE(0) !== blockMapSize) {+ throw new Error("AppImage embedded blockmap trailer disagrees with update metadata");+ }+ const payloadSize = size - blockMapSize - 4;+ const section = findUpdateSection(fd, payloadSize);+ if (information.length >= section.size) {+ throw new Error("AppImage update information does not fit in .upd_info");+ }+ const padded = Buffer.alloc(section.size);+ information.copy(padded);+ fs.ftruncateSync(fd, payloadSize);+ fs.writeSync(fd, padded, 0, padded.length, section.offset);+ } finally {+ fs.closeSync(fd);+ }+ // This internal helper is verified against app-builder-lib 26.15.3. Recheck its return+ // shape and artifactBuildCompleted ordering when upgrading electron-builder.+ const { appendBlockmap } = require("app-builder-lib/out/targets/differentialUpdateInfoBuilder");+ event.updateInfo = await appendBlockmap(event.file);+ const filename = path.basename(event.file);+ childProcess.execFileSync(+ "zsyncmake",+ [+ "-e",+ "-f",+ filename,+ "-u",+ `https://github.com/${REPOSITORY}/releases/download/v${version}/${encodeURIComponent(filename)}`,+ "-o",+ `${event.file}.zsync`,+ event.file,+ ],+ { stdio: "inherit" },+ );+};++exports.afterAllArtifactBuild = function afterAllArtifactBuild(result) {+ return result.artifactPaths+ .filter((file) => file.endsWith(".AppImage"))+ .map((file) => `${file}.zsync`);+};diff --git a/scripts/appimage-updates.test.mjs b/scripts/appimage-updates.test.mjsnew file mode 100644index 000000000..dc47adf58--- /dev/null+++ b/scripts/appimage-updates.test.mjs@@ -0,0 +1,199 @@+import childProcess from "node:child_process";+import { createHash } from "node:crypto";+import fs from "node:fs";+import { createRequire } from "node:module";+import os from "node:os";+import path from "node:path";+import { inflateRawSync } from "node:zlib";+import { afterEach, describe, expect, it, vi } from "vitest";++const require = createRequire(import.meta.url);+const { blake2b } = require("@noble/hashes/blake2.js");+const { appendBlockmap } = require("app-builder-lib/out/targets/differentialUpdateInfoBuilder");+const { artifactBuildCompleted, afterAllArtifactBuild } = require("./appimage-updates.cjs");+const temporaryDirectories = [];+const UPDATE_OFFSET = 1536;+const UPDATE_SIZE = 1024;++afterEach(() => {+ vi.restoreAllMocks();+ for (const directory of temporaryDirectories.splice(0)) {+ fs.rmSync(directory, { recursive: true, force: true });+ }+});++// A small ELF header, section table and reserved runtime area, followed by payload bytes.+// Real legacy/static runtimes use these same ELF32/64 layouts; no Linux executable is needed.+function runtimeFixture({+ is64 = true,+ sectionName = ".upd_info",+ sectionSize = UPDATE_SIZE,+ updateInformation = "",+} = {}) {+ const buffer = Buffer.alloc(4096, 0x5a);+ buffer.fill(0, 0, 64);+ Buffer.from("7f454c46", "hex").copy(buffer);+ buffer[4] = is64 ? 2 : 1;+ buffer[5] = 1;+ Buffer.from("414902", "hex").copy(buffer, 8);+ const tableOffset = 512;+ const entrySize = is64 ? 64 : 40;+ if (is64) buffer.writeBigUInt64LE(BigInt(tableOffset), 40);+ else buffer.writeUInt32LE(tableOffset, 32);+ buffer.writeUInt16LE(entrySize, is64 ? 58 : 46);+ buffer.writeUInt16LE(3, is64 ? 60 : 48);+ buffer.writeUInt16LE(1, is64 ? 62 : 50);+ buffer.fill(0, tableOffset, tableOffset + entrySize * 3);+ const names = Buffer.from(`\0.shstrtab\0${sectionName}\0`);+ names.copy(buffer, 1024);+ const setSection = (index, name, offset, size) => {+ const at = tableOffset + index * entrySize;+ buffer.writeUInt32LE(name, at);+ if (is64) {+ buffer.writeBigUInt64LE(BigInt(offset), at + 24);+ buffer.writeBigUInt64LE(BigInt(size), at + 32);+ } else {+ buffer.writeUInt32LE(offset, at + 16);+ buffer.writeUInt32LE(size, at + 20);+ }+ };+ setSection(1, 1, 1024, names.length);+ setSection(2, 11, UPDATE_OFFSET, sectionSize);+ buffer.fill(0, UPDATE_OFFSET, UPDATE_OFFSET + UPDATE_SIZE);+ Buffer.from(updateInformation).copy(buffer, UPDATE_OFFSET);+ return buffer;+}++async function artifact({ version = "2.0.1", filename, ...fixtureOptions } = {}) {+ const directory = fs.mkdtempSync(path.join(os.tmpdir(), "openscreen-appimage-update-"));+ temporaryDirectories.push(directory);+ const file = path.join(directory, filename ?? `Openscreen-Linux-${version}.AppImage`);+ fs.writeFileSync(file, runtimeFixture(fixtureOptions));+ const updateInfo = await appendBlockmap(file);+ return {+ file,+ target: { name: "appImage" },+ packager: { appInfo: { version } },+ updateInfo,+ };+}++describe("AppImage standard update information", () => {+ it.each([+ true,+ false,+ ])("preserves payload and refreshes all update hashes (ELF64=%s)", async (is64) => {+ const event = await artifact({ is64 });+ const before = fs.readFileSync(event.file);+ const beforeInfo = event.updateInfo;+ const payloadSize = before.length - beforeInfo.blockMapSize - 4;+ const zsync = vi.spyOn(childProcess, "execFileSync").mockImplementation(() => {+ const finalBytes = fs.readFileSync(event.file);+ expect(event.updateInfo.sha512).toBe(+ createHash("sha512").update(finalBytes).digest("base64"),+ );+ fs.writeFileSync(`${event.file}.zsync`, "generated from final bytes");+ });++ await artifactBuildCompleted(event);++ const after = fs.readFileSync(event.file);+ expect(after.subarray(0, UPDATE_OFFSET)).toEqual(before.subarray(0, UPDATE_OFFSET));+ expect(after.subarray(UPDATE_OFFSET + UPDATE_SIZE, payloadSize)).toEqual(+ before.subarray(UPDATE_OFFSET + UPDATE_SIZE, payloadSize),+ );+ const information = after.subarray(UPDATE_OFFSET, UPDATE_OFFSET + UPDATE_SIZE);+ const end = information.indexOf(0);+ expect(information.subarray(0, end).toString()).toBe(+ "gh-releases-zsync|getopenscreen|openscreen|latest|Openscreen-Linux-*.AppImage.zsync",+ );+ expect(information.subarray(end).every((byte) => byte === 0)).toBe(true);+ expect(event.updateInfo).not.toBe(beforeInfo);+ expect(event.updateInfo.sha512).not.toBe(beforeInfo.sha512);+ expect(event.updateInfo.size).toBe(after.length);+ expect(after.readUInt32BE(after.length - 4)).toBe(event.updateInfo.blockMapSize);+ const map = JSON.parse(+ inflateRawSync(after.subarray(payloadSize, after.length - 4)).toString(),+ );+ expect(map.files[0].sizes).toEqual([payloadSize]);+ expect(map.files[0].checksums).toEqual([+ Buffer.from(blake2b(after.subarray(0, payloadSize), { dkLen: 18 })).toString("base64"),+ ]);+ expect(zsync).toHaveBeenCalledWith(+ "zsyncmake",+ [+ "-e",+ "-f",+ "Openscreen-Linux-2.0.1.AppImage",+ "-u",+ "https://github.com/getopenscreen/openscreen/releases/download/v2.0.1/Openscreen-Linux-2.0.1.AppImage",+ "-o",+ `${event.file}.zsync`,+ event.file,+ ],+ { stdio: "inherit" },+ );+ expect(+ afterAllArtifactBuild({+ artifactPaths: [event.file, path.join(path.dirname(event.file), "other.deb")],+ }),+ ).toEqual([`${event.file}.zsync`]);+ });++ it("leaves RC discovery empty while generating a tagged zsync URL", async () => {+ const event = await artifact({+ version: "2.1.0-rc.2",+ filename: "Openscreen-Linux-2.1.0-rc.2 beta.AppImage",+ updateInformation: "gh-releases-zsync|getopenscreen|openscreen|latest-all|*.AppImage.zsync",+ });+ const zsync = vi.spyOn(childProcess, "execFileSync").mockImplementation(() => undefined);+ await artifactBuildCompleted(event);+ const after = fs.readFileSync(event.file);+ // latest-all / latest-pre may select a helper-only release without an AppImage asset.+ expect(+ after.subarray(UPDATE_OFFSET, UPDATE_OFFSET + UPDATE_SIZE).every((byte) => byte === 0),+ ).toBe(true);+ expect(event.updateInfo.size).toBe(after.length);+ expect(event.updateInfo.sha512).toBe(createHash("sha512").update(after).digest("base64"));+ expect(zsync.mock.calls[0][1]).toContain(+ "https://github.com/getopenscreen/openscreen/releases/download/v2.1.0-rc.2/Openscreen-Linux-2.1.0-rc.2%20beta.AppImage",+ );+ });++ it.each([+ ["a missing reserved section", { sectionName: ".other" }, /no reserved .upd_info/],+ ["an undersized reserved section", { sectionSize: 8 }, /does not fit/],+ ["an out-of-range reserved section", { sectionSize: 4096 }, /beyond the artifact/],+ ])("rejects %s before changing any bytes", async (_label, fixtureOptions, message) => {+ const event = await artifact(fixtureOptions);+ const before = fs.readFileSync(event.file);+ const zsync = vi.spyOn(childProcess, "execFileSync");+ await expect(artifactBuildCompleted(event)).rejects.toThrow(message);+ expect(fs.readFileSync(event.file)).toEqual(before);+ expect(zsync).not.toHaveBeenCalled();+ });++ it.each([+ undefined,+ -1,+ 0,+ 1,+ Number.MAX_SAFE_INTEGER,+ ])("rejects invalid or stale blockmap size %s before changing any bytes", async (blockMapSize) => {+ const event = await artifact();+ event.updateInfo.blockMapSize = blockMapSize;+ const before = fs.readFileSync(event.file);+ await expect(artifactBuildCompleted(event)).rejects.toThrow(/blockmap/);+ expect(fs.readFileSync(event.file)).toEqual(before);+ });++ it.each([+ { target: null },+ { target: { name: "deb" }, file: "missing.deb" },+ { target: { name: "appImage" }, file: "missing.blockmap" },+ ])("ignores an unrelated artifact %j", async (event) => {+ const zsync = vi.spyOn(childProcess, "execFileSync");+ await artifactBuildCompleted(event);+ expect(zsync).not.toHaveBeenCalled();+ });+});diff --git a/technical-documentation/engineering/build-and-packaging.md b/technical-documentation/engineering/build-and-packaging.mdindex d7608ff0e..11aea19e0 100644--- a/technical-documentation/engineering/build-and-packaging.md+++ b/technical-documentation/engineering/build-and-packaging.md@@ -23,6 +23,14 @@ OpenScreen builds its renderer, Electron main process, preload bridge, native he`vite.config.ts` uses `vite-plugin-electron` to compile `electron/main.ts` and `electron/preload.ts` into `dist-electron/` while Vite emits the renderer to `dist/`. The main `tsconfig.json` is strict, covers `src` and `electron`, and has `noEmit`; TypeScript is therefore a check while Vite performs emission. `build-vite` is the renderer/Electron-bundle build used when an installer is not needed, whereas `build` continues through electron-builder.+## AppImage updates++Linux packaging also requires `zsync` (`sudo apt-get install zsync`), which supplies `zsyncmake`. Each AppImage ships a `.zsync` sidecar for external tools such as AppImageUpdate, alongside the embedded blockmap and `latest-linux.yml` used by electron-updater.++`scripts/appimage-updates.cjs` fills the runtime's reserved `.upd_info` section without moving its appended filesystem. The `artifactBuildCompleted` hook removes the old blockmap, writes the update information, rebuilds the blockmap and replaces the artifact's update metadata **before** electron-builder schedules publication. It then generates `.zsync` from the final bytes; `afterAllArtifactBuild` includes that sidecar when publishing directly. Recheck the internal `appendBlockmap` helper and hook ordering when upgrading electron-builder from 26.15.3.++Stable builds use `gh-releases-zsync` with the upstream repository's `latest` channel. RCs still produce sidecars with explicit tagged download URLs, but leave external discovery empty: AppImageUpdate's `latest-all` can select a helper-only prerelease with no AppImage asset. RC updates continue through electron-updater. CI checks both policies and uploads the sidecars as release assets.+## Native artifactsA usable full package depends on generated artifacts that are not committed: