Adopt SemVer 2.0.0 and promote release images by digest
This commit is contained in:
1 parent
2893685aef
commit
b312a50d37
7 files changed
+357
-2
No files matched your search
@@ -0,0 +1,99 @@
|
||||
import {spawnSync} from 'node:child_process';
|
||||
import {pathToFileURL} from 'node:url';
|
||||
|
||||
export const images = ['pageswiki-app', 'pageswiki-adaptor-gateway', 'pageswiki-excalidraw-viewer'];
|
||||
// SemVer 2.0.0: numeric prerelease identifiers cannot have leading zeroes.
|
||||
const number = '(0|[1-9][0-9]*)';
|
||||
const identifier = '(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)';
|
||||
const semver = new RegExp(`^${number}\\.${number}\\.${number}(?:-${identifier}(?:\\.${identifier})*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$`);
|
||||
|
||||
export function imageTag(ref) {
|
||||
if (!ref.startsWith('refs/tags/v')) throw new Error('Release must run on a refs/tags/v… Git tag');
|
||||
const tag = ref.slice('refs/tags/'.length);
|
||||
if (!semver.test(tag.slice(1)) || /\s/.test(tag)) throw new Error(`Invalid SemVer 2.0.0 tag: ${tag}`);
|
||||
// Gitea stores container tags case-insensitively; reject instead of silently
|
||||
// collapsing distinct SemVer identifiers. '+' is not a Docker tag character.
|
||||
if (/[A-Z]/.test(tag)) throw new Error('Release identifiers must be lowercase for the Gitea registry');
|
||||
const result = tag.replace('+', '_');
|
||||
if (result.length > 128) throw new Error('Container release tag exceeds 128 characters');
|
||||
return result;
|
||||
}
|
||||
|
||||
function run(command, args) {
|
||||
const result = spawnSync(command, args, {encoding: 'utf8', timeout: 120000, maxBuffer: 4 * 1024 * 1024});
|
||||
if (result.error) throw result.error;
|
||||
if (result.status !== 0) throw new Error(`${command} failed: ${result.stderr.trim()}`);
|
||||
return result.stdout.trim();
|
||||
}
|
||||
|
||||
export function dockerClient(execute = run) {
|
||||
function inspect(ref, field, optional = false) {
|
||||
try {
|
||||
return JSON.parse(execute('docker', ['buildx', 'imagetools', 'inspect', '--format', `{{json .${field}}}`, ref]));
|
||||
} catch (error) {
|
||||
// Only an explicit missing manifest is absence, never auth/TLS/timeouts.
|
||||
if (optional && (error.message.endsWith(`ERROR: ${ref}: not found`) || /\bmanifest unknown\b/i.test(error.message))) return null;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
return {
|
||||
digest(ref, optional = false) {
|
||||
const manifest = inspect(ref, 'Manifest', optional);
|
||||
if (manifest === null) return null;
|
||||
if (!/^sha256:[0-9a-f]{64}$/.test(manifest.digest)) throw new Error(`Invalid registry digest: ${ref}`);
|
||||
return manifest.digest;
|
||||
},
|
||||
revision(ref) {
|
||||
const config = inspect(ref, 'Image');
|
||||
if (config.os !== 'linux' || config.architecture !== 'amd64') throw new Error(`Expected linux/amd64 source: ${ref}`);
|
||||
return config.config?.Labels?.['org.opencontainers.image.revision'];
|
||||
},
|
||||
copy(source, destination) {
|
||||
execute('docker', ['buildx', 'imagetools', 'create', '--prefer-index=false', '--tag', destination, source]);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export function promote({ref, revision, prefix}, client = dockerClient(), log = console.log) {
|
||||
const tag = imageTag(ref);
|
||||
if (!/^[0-9a-f]{40}$/.test(revision)) throw new Error('Expected the release commit SHA');
|
||||
if (!/^[a-z0-9][a-z0-9.-]*(?::[0-9]+)?\/[a-z0-9][a-z0-9_-]*$/.test(prefix)) throw new Error('Invalid registry/owner prefix');
|
||||
// Resolve every source to a digest and check every destination before writes.
|
||||
const plan = images.map(image => {
|
||||
const repository = `${prefix}/${image}`;
|
||||
const digest = client.digest(`${repository}:sha-${revision}`);
|
||||
const source = `${repository}@${digest}`;
|
||||
if (client.revision(source) !== revision) throw new Error(`Image revision does not match Git tag: ${image}`);
|
||||
const destination = `${repository}:${tag}`;
|
||||
const existing = client.digest(destination, true);
|
||||
if (existing !== null && existing !== digest) throw new Error(`Refusing to overwrite released image: ${destination}`);
|
||||
return {source, destination, digest};
|
||||
});
|
||||
for (const item of plan) {
|
||||
// Recheck before writing. Registry tag protection/serialized releases are
|
||||
// still required: the registry does not offer a portable compare-and-swap.
|
||||
const existing = client.digest(item.destination, true);
|
||||
if (existing !== null && existing !== item.digest) throw new Error(`Release changed concurrently: ${item.destination}`);
|
||||
if (existing === null) client.copy(item.source, item.destination);
|
||||
if (client.digest(item.destination) !== item.digest) throw new Error(`Promoted digest mismatch: ${item.destination}`);
|
||||
log(`${item.destination} -> ${item.digest}`);
|
||||
}
|
||||
return plan;
|
||||
}
|
||||
|
||||
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
|
||||
try {
|
||||
const ref = process.env.RELEASE_REF || '';
|
||||
const tag = imageTag(ref);
|
||||
if (process.argv[2] === '--validate') {
|
||||
console.log(`Release ${ref.slice('refs/tags/'.length)}; container tag ${tag}`);
|
||||
} else if (process.argv.length !== 2) {
|
||||
throw new Error('Usage: node tools/ci/release-images.mjs [--validate]');
|
||||
} else {
|
||||
promote({ref, revision: run('git', ['rev-parse', 'HEAD^{commit}']), prefix: `${process.env.REGISTRY}/${process.env.IMAGE_OWNER}`});
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(error.message);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,116 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import {dockerClient, imageTag, images, promote} from './release-images.mjs';
|
||||
|
||||
test('SemVer release and prerelease tags', () => {
|
||||
for (const version of ['0.1.0', '1.0.0', '1.2.3-rc.1', '1.0.0-0', '1.0.0-01a', '1.0.0-x-y-z.--', '12345678901234567890.0.1']) {
|
||||
assert.equal(imageTag(`refs/tags/v${version}`), `v${version}`);
|
||||
}
|
||||
assert.equal(imageTag('refs/tags/v1.2.3-rc.1+build.001'), 'v1.2.3-rc.1_build.001');
|
||||
});
|
||||
|
||||
test('reject malformed SemVer and ambiguous registry tags', () => {
|
||||
for (const version of ['1', '1.2', '01.2.3', '1.02.3', '1.2.03', '1.2.3-01', '1.2.3-a.01', '1.2.3-', '1.2.3-a..b', '1.2.3+', '1.2.3+foo..bar', '1.2.3+foo+bar', '1.2.3_bad', '1.2.3\n', '1.2.3-RC.1', '1.2.3+BUILD', '1.2.3-'+ 'a'.repeat(128)]) {
|
||||
assert.throws(() => imageTag(`refs/tags/v${version}`));
|
||||
}
|
||||
assert.throws(() => imageTag('refs/heads/v1.2.3'));
|
||||
assert.throws(() => imageTag('refs/tags/1.2.3'));
|
||||
});
|
||||
|
||||
const revision = 'a'.repeat(40);
|
||||
const options = {ref: 'refs/tags/v0.1.0', revision, prefix: 'registry.example.test/anya'};
|
||||
function registry() {
|
||||
const entries = new Map(images.map((image, index) => [`${options.prefix}/${image}:sha-${revision}`, `sha256:${String(index + 1).repeat(64)}`]));
|
||||
const copies = [];
|
||||
const client = {
|
||||
digest(ref, optional = false) {
|
||||
if (entries.has(ref)) return entries.get(ref);
|
||||
if (optional) return null;
|
||||
throw new Error('source missing');
|
||||
},
|
||||
revision: () => revision,
|
||||
copy(source, destination) {
|
||||
copies.push({source, destination});
|
||||
entries.set(destination, source.split('@')[1]);
|
||||
},
|
||||
};
|
||||
return {client, entries, copies};
|
||||
}
|
||||
|
||||
test('promotes three sources by digest and retry does not rewrite', () => {
|
||||
const {client, copies} = registry();
|
||||
const plan = promote(options, client, () => {});
|
||||
assert.equal(copies.length, 3);
|
||||
for (const item of plan) assert.ok(item.source.endsWith(`@${item.digest}`));
|
||||
promote(options, client, () => {});
|
||||
assert.equal(copies.length, 3);
|
||||
});
|
||||
|
||||
test('missing source, wrong revision or existing release conflict prevents all writes', () => {
|
||||
for (const failure of ['missing', 'revision', 'conflict']) {
|
||||
const {client, entries, copies} = registry();
|
||||
const last = `${options.prefix}/${images[2]}`;
|
||||
if (failure === 'missing') entries.delete(`${last}:sha-${revision}`);
|
||||
if (failure === 'revision') client.revision = () => 'b'.repeat(40);
|
||||
if (failure === 'conflict') entries.set(`${last}:v0.1.0`, `sha256:${'f'.repeat(64)}`);
|
||||
assert.throws(() => promote(options, client));
|
||||
assert.equal(copies.length, 0);
|
||||
}
|
||||
});
|
||||
|
||||
test('partial promotion is safely resumable', () => {
|
||||
const {client, copies} = registry();
|
||||
const copy = client.copy;
|
||||
client.copy = (source, destination) => {
|
||||
if (copies.length === 1) throw new Error('registry unavailable');
|
||||
copy(source, destination);
|
||||
};
|
||||
assert.throws(() => promote(options, client, () => {}), /unavailable/);
|
||||
client.copy = copy;
|
||||
promote(options, client, () => {});
|
||||
assert.equal(copies.length, 3);
|
||||
});
|
||||
|
||||
test('destination digest mismatch and concurrent overwrite are failures', () => {
|
||||
const {client} = registry();
|
||||
client.copy = () => {};
|
||||
assert.throws(() => promote(options, client, () => {}));
|
||||
const other = registry();
|
||||
const get = other.client.digest;
|
||||
let reads = 0;
|
||||
other.client.digest = (ref, optional) => {
|
||||
if (ref.endsWith(':v0.1.0') && ++reads > 3) return `sha256:${'f'.repeat(64)}`;
|
||||
return get(ref, optional);
|
||||
};
|
||||
assert.throws(() => promote(options, other.client), /concurrently/);
|
||||
assert.equal(other.copies.length, 0);
|
||||
});
|
||||
|
||||
test('inspect distinguishes missing manifests from authorization and network errors', () => {
|
||||
const ref = 'registry.example.test/anya/image:v0.1.0';
|
||||
for (const message of [`docker failed: ERROR: ${ref}: not found`, 'docker failed: manifest unknown']) {
|
||||
const client = dockerClient(() => { throw new Error(message); });
|
||||
assert.equal(client.digest(ref, true), null);
|
||||
assert.throws(() => client.digest(ref));
|
||||
}
|
||||
for (const message of ['unauthorized', 'TLS handshake timeout', 'no such host', '404 page not found']) {
|
||||
const client = dockerClient(() => { throw new Error(message); });
|
||||
assert.throws(() => client.digest(ref, true));
|
||||
}
|
||||
});
|
||||
|
||||
test('Docker adapter preserves manifest format and validates metadata', () => {
|
||||
const calls = [];
|
||||
const client = dockerClient((command, args) => {
|
||||
calls.push([command, ...args]);
|
||||
if (args.includes('{{json .Manifest}}')) return JSON.stringify({digest: `sha256:${'a'.repeat(64)}`});
|
||||
if (args.includes('{{json .Image}}')) return JSON.stringify({os: 'linux', architecture: 'amd64', config: {Labels: {'org.opencontainers.image.revision': revision}}});
|
||||
return '';
|
||||
});
|
||||
assert.equal(client.revision('source'), revision);
|
||||
assert.equal(client.digest('source'), `sha256:${'a'.repeat(64)}`);
|
||||
client.copy('source@sha256:abc', 'destination:v0.1.0');
|
||||
assert.deepEqual(calls.at(-1), ['docker', 'buildx', 'imagetools', 'create', '--prefer-index=false', '--tag', 'destination:v0.1.0', 'source@sha256:abc']);
|
||||
assert.throws(() => dockerClient(() => '{}').digest('source'), /Invalid registry digest/);
|
||||
assert.throws(() => dockerClient(() => '{}').revision('source'), /linux\/amd64/);
|
||||
});
|
||||
Reference in new issue
Block a user