134 lines
5.6 KiB
JavaScript
134 lines
5.6 KiB
JavaScript
// scripts/ci/lib/immutable-package-guard.mjs
|
|
// 버전별(immutable) generic package 경로 보호 정책.
|
|
//
|
|
// Forgejo generic registry는 HEAD를 405로 거부하고 파일 해시도 헤더로 주지 않는다
|
|
// (docs/deployment/unsigned-distribution.md §1). HEAD로 존재 여부를 보던 예전 가드는
|
|
// 항상 "없음"으로 판정해 죽어 있었고, 업로드가 409를 받으면 DELETE 후 재PUT으로
|
|
// 이미 게시된 버전의 바이트를 조용히 바꿨다.
|
|
//
|
|
// 이 모듈은
|
|
// 1) 순수 정책: 로컬 sha256과 원격 sha256을 비교해 업로드/건너뜀/충돌을 분류
|
|
// 2) IO 어댑터: 패키지 파일 목록 API(sha256 제공)를 읽는 함수 (fetch 주입)
|
|
// 3) 유스케이스: 불변 경로에 한 파일을 올리는 절차 (DELETE를 절대 하지 않는다)
|
|
// 를 분리해 publisher가 같은 버전 재실행을 안전하게 처리하게 한다.
|
|
|
|
/**
|
|
* @typedef {{ name: string, sha256: string }} LocalAssetDigest
|
|
* @typedef {ReadonlyMap<string, string>} RemoteDigests 원격 파일명 → sha256(hex, 소문자)
|
|
* @typedef {(url: string, init?: RequestInit) => Promise<Response>} FetchLike
|
|
*/
|
|
|
|
/**
|
|
* @param {string | null | undefined} value
|
|
* @returns {string}
|
|
*/
|
|
function normalizeDigest(value) {
|
|
return String(value ?? "").trim().toLowerCase();
|
|
}
|
|
|
|
/**
|
|
* 순수 정책: 버전별 경로에 올릴 파일을 분류한다.
|
|
* - 원격에 없음 → upload
|
|
* - 원격 sha256 == 로컬 sha256 → identical (재실행/재시도: 건너뜀)
|
|
* - 원격 sha256 != 로컬 sha256 → conflicting (불변 위반: 중단해야 함)
|
|
*
|
|
* @param {{ localFiles: readonly LocalAssetDigest[], remoteDigests: RemoteDigests }} input
|
|
* @returns {{ upload: LocalAssetDigest[], identical: LocalAssetDigest[], conflicting: Array<LocalAssetDigest & { remoteSha256: string }> }}
|
|
*/
|
|
export function classifyImmutableAssets({ localFiles, remoteDigests }) {
|
|
const upload = [];
|
|
const identical = [];
|
|
const conflicting = [];
|
|
for (const file of localFiles) {
|
|
if (!remoteDigests.has(file.name)) {
|
|
upload.push(file);
|
|
continue;
|
|
}
|
|
const remoteSha256 = normalizeDigest(remoteDigests.get(file.name));
|
|
if (remoteSha256 === normalizeDigest(file.sha256)) identical.push(file);
|
|
else conflicting.push({ ...file, remoteSha256 });
|
|
}
|
|
return { upload, identical, conflicting };
|
|
}
|
|
|
|
/**
|
|
* 불변 위반이 있으면 fail-closed 예외를 던진다.
|
|
* @param {{ tag: string, conflicting: ReadonlyArray<LocalAssetDigest & { remoteSha256: string }> }} input
|
|
*/
|
|
export function assertNoImmutableConflicts({ tag, conflicting }) {
|
|
if (conflicting.length === 0) return;
|
|
const details = conflicting
|
|
.map((file) => `${file.name}: remote sha256 ${file.remoteSha256 || "(unknown)"}, local sha256 ${file.sha256}`)
|
|
.join("; ");
|
|
throw new Error(
|
|
`${tag} is already published with different bytes (${details}). Releases are immutable — ` +
|
|
"lift the version and publish a new tag instead of re-publishing this one.",
|
|
);
|
|
}
|
|
|
|
/**
|
|
* IO 어댑터: 패키지 버전의 파일 목록 API에서 파일별 sha256을 읽는다.
|
|
* GET {origin}/api/v1/packages/{owner}/generic/{package}/{version}/files
|
|
* - 404 → 빈 Map (아직 게시되지 않은 버전)
|
|
* - 200 → 파일명 → sha256
|
|
* - 그 외 HTTP/네트워크 오류 → 예외 (fail-closed: 판단할 수 없으면 게시하지 않는다)
|
|
*
|
|
* @param {{ filesApiUrl: string, fetchImpl: FetchLike }} deps
|
|
* @returns {Promise<Map<string, string>>}
|
|
*/
|
|
export async function readRemotePackageDigests({ filesApiUrl, fetchImpl }) {
|
|
const response = await fetchImpl(filesApiUrl, { cache: "no-store" });
|
|
if (response.status === 404) return new Map();
|
|
if (!response.ok) {
|
|
throw new Error(
|
|
`Cannot list published package files (${filesApiUrl}): HTTP ${response.status}. ` +
|
|
"Refusing to publish without knowing what the immutable version path already holds.",
|
|
);
|
|
}
|
|
const payload = await response.json();
|
|
if (!Array.isArray(payload)) {
|
|
throw new Error(`Unexpected package files payload from ${filesApiUrl}: expected an array.`);
|
|
}
|
|
const digests = new Map();
|
|
for (const entry of payload) {
|
|
if (entry && typeof entry.name === "string" && typeof entry.sha256 === "string") {
|
|
digests.set(entry.name, normalizeDigest(entry.sha256));
|
|
}
|
|
}
|
|
return digests;
|
|
}
|
|
|
|
/**
|
|
* 유스케이스: 불변(버전별) 경로에 파일 하나를 올린다.
|
|
* - PUT 성공 → "uploaded"
|
|
* - 409(동시 실행 등으로 그 사이 누가 올림) → 원격 sha256을 다시 읽어 같으면 "verified-existing",
|
|
* 다르거나 확인할 수 없으면 예외. **DELETE는 절대 하지 않는다.**
|
|
* - 그 외 실패 → 예외
|
|
*
|
|
* @param {{
|
|
* url: string,
|
|
* name: string,
|
|
* sha256: string,
|
|
* body: BodyInit,
|
|
* fetchImpl: FetchLike,
|
|
* readRemoteDigest: () => Promise<string | undefined>,
|
|
* }} input
|
|
* @returns {Promise<"uploaded" | "verified-existing">}
|
|
*/
|
|
export async function uploadImmutableAsset({ url, name, sha256, body, fetchImpl, readRemoteDigest }) {
|
|
const response = await fetchImpl(url, {
|
|
method: "PUT",
|
|
headers: { "Content-Type": "application/octet-stream" },
|
|
body,
|
|
});
|
|
if (response.ok) return "uploaded";
|
|
if (response.status === 409) {
|
|
const remote = normalizeDigest(await readRemoteDigest());
|
|
if (remote && remote === normalizeDigest(sha256)) return "verified-existing";
|
|
throw new Error(
|
|
`registry upload refused for immutable ${name}: HTTP 409 and remote sha256 ` +
|
|
`${remote || "(unknown)"} != local ${sha256}. Published versions are never overwritten.`,
|
|
);
|
|
}
|
|
throw new Error(`registry upload failed for ${name}: HTTP ${response.status} ${await response.text()}`);
|
|
}
|