/** * What makes a release one to publish or to use * (docs/design/package-manager.md, "Validating releases"). The same rules * are checked by `zena pkg publish` before it uploads anything, by a package * host before it records a release, since it trusts no client, and by * `zena pkg fetch`, since a package can be kept on any PDS, where nothing * checked what was written. * * `checkSource` checks a release against its source archive: that the * archive is the artifact the release names and unpacks, and that the * manifest in it agrees with the release. `checkDependencies` checks that * each dependency is a release that exists and is not retracted, which a * fetch need not repeat, since resolving fails on a missing one. * `validateRelease` is both, for publishing, and also requires the * manifest's `description` and `license`, which releases published before * that rule may lack. Each returns every problem it finds, so one attempt * reports them all. */ import {Future} from 'zena:async'; import {HashSet} from 'zena:collections'; import {Cid} from 'atproto/cid'; import {IdentityResolver} from 'atproto/identity'; import {SourceFile, unpackSource} from './archive.zena'; import {PublishedFiles} from './files.zena'; import {Manifest, readManifest} from './manifest.zena'; import {Dependency, Release, SOURCE, isValidLicenseExpression} from './records.zena'; import {Version} from 'zena-lang:semver'; import {listVersions} from './registry.zena'; import {Versions} from './resolve.zena'; import {MANIFEST} from './workspace.zena'; /** The MIME type of a source archive, a CAR file. */ export let SOURCE_MIME_TYPE = 'application/vnd.ipld.car'; /** * The MIME types an artifact's blobs have: a source archive, a component * or core module, a component's WIT, and the parts of a large artifact * (package-manager.md, "Large artifacts"). */ export let ARTIFACT_MIME_TYPES: Array = [SOURCE_MIME_TYPE, 'application/wasm', 'text/plain', 'application/octet-stream']; /** * The artifact MIME type a `Content-Type` names, without its parameters * and in lowercase; null when it is not one of `ARTIFACT_MIME_TYPES`. */ export function artifactMimeType(contentType: String): String | null { let type = contentType.split(';')[0].trim().asciiLowerCase(); for (let allowed in ARTIFACT_MIME_TYPES) { if (type == allowed) { return type; } } return null; } /** * The problems with `release`, a release of the package `did`, and * `source`, the bytes of its source artifact: empty when there are none. * `profileName`, given when publishing, is the name the package's profile * gives, which its manifest must have too. A fetch leaves it out, since a * package renamed later keeps its older releases. `publishing` also * requires the manifest's `description` and an SPDX `license`. */ export function checkSource(release: Release, did: String, source: FixedArray, profileName: String | null = null, publishing: boolean = false): GrowableArray { let problems = new GrowableArray(); let version = release.version.toString(); let artifact = release.artifact(SOURCE); if (artifact == null) { problems.push(`release ${version} has no source artifact`); return problems; } if (artifact.size != source.length as i64) { problems.push(`the source artifact is ${artifact.size} bytes, but the archive is ${source.length}`); } if (!Cid.forBlob(source).equals(artifact.cid)) { problems.push(`the archive is not the source artifact ${artifact.cid.toString()}`); } let blob = artifact.blob; if (blob != null && blob.mimeType != SOURCE_MIME_TYPE) { problems.push(`the source artifact is ${blob.mimeType}, not ${SOURCE_MIME_TYPE}`); } let files = unpacked(source, problems); if (files == null) { return problems; } var text: String | null = null; for (let file in files) { if (file.path == MANIFEST) { text = String.fromBytes(file.contents as ByteArray); } } if (text == null) { problems.push(`the archive has no ${MANIFEST}`); return problems; } let manifest = try { readManifest(text) } catch (e) { problems.push(`the archive's ${MANIFEST} cannot be read: ${e.message}`); null }; if (manifest == null) { return problems; } let manifestVersion = manifest.version; if (manifestVersion == null) { problems.push(`the archive's ${MANIFEST} has no version`); } else if (manifestVersion.compareTo(release.version) != 0) { problems.push(`the archive's ${MANIFEST} is version ${manifestVersion.toString()}, not ${version}`); } let manifestDid = manifest.did; if (manifestDid != null && manifestDid != did) { problems.push(`the archive's ${MANIFEST} is the package ${manifestDid}, not ${did}`); } if (profileName != null && (manifest.name == null || manifest.name as String != profileName)) { problems.push(`the archive's ${MANIFEST} names ${manifest.name ?? 'no package'}, not ${profileName}`); } manifest.wits.forEach((name, wit) => { problems.push(`the archive depends on the WIT in ${wit}, as ${name}, which a published package cannot`); }); // A new release says what the package is and on what terms it may be // used. Releases published before this rule are fetched all the same. if (publishing) { for (let problem in checkMetadata(manifest, `the archive's ${MANIFEST}`)) { problems.push(problem); } // The archive holds what its manifest publishes, the file of every // library it exports among them (package-manifest.md, "files"). let published = PublishedFiles.of(manifest); let held = new HashSet(); for (let file in files) { held.add(file.path); if (!published.includes(file.path)) { problems.push(`the archive holds ${file.path}, which its ${MANIFEST} does not publish`); } } for (let path in manifest.exportFiles) { let relative = if (path.startsWith('./')) path.sliceBytes(2, path.length) else path; if (!held.has(relative)) { problems.push(`the archive has no ${relative}, which its ${MANIFEST} exports`); } } // A package that lists no exports has its main library in its source // directory too, or no import of its name works. let mainFile = manifest.mainFile; if (mainFile != null && !held.has(mainFile)) { problems.push(`the archive has no ${mainFile}, the library its ${MANIFEST}'s main names`); } } // The release's dependencies are the manifest's, each by its local name: // a path dependency appears in the release as the DID it has. let declared = new HashSet(); for (let name in manifest.requirements.keys()) { declared.add(name); } for (let name in manifest.paths.keys()) { declared.add(name); } let listed = new HashSet(); for (let dependency in release.dependencies) { listed.add(dependency.name); if (!declared.has(dependency.name)) { problems.push(`the release depends on ${dependency.name}, which the archive's ${MANIFEST} does not`); } } for (let name in declared) { if (!listed.has(name)) { problems.push(`the archive's ${MANIFEST} depends on ${name}, which the release does not list`); } } return problems; } /** The files in `source`, or null, with why added to `problems`. */ function unpacked(source: FixedArray, problems: GrowableArray): FixedArray | null { try { return unpackSource(source); } catch (e) { problems.push(`the archive does not unpack: ${e.message}`); return null; } } /** * The problems with `dependencies`: each range must have a version in it * that its package has published and not retracted, or the release that * names it could never be resolved. Empty when there are none. With `explain`, a dependency that * cannot be found says why in full; without, only whether its DID or its * PDS failed, as a host answers. */ export async function checkDependencies(dependencies: Array, resolver: IdentityResolver, explain: boolean = true): Future> { let problems = new GrowableArray(); for (let dependency in dependencies) { let named = `${dependency.name} ${dependency.range.text} (${dependency.did})`; let found = await versionsOf(dependency, resolver, explain); if (found is String) { problems.push(`${named} cannot be found: ${found}`); } else { var published = false; var usable = false; for (let version in found.releases) { if (dependency.range.includes(version)) { published = true; if (!found.retracted.has(version.toString())) { usable = true; } } } if (!published) { problems.push(`${named} is not published: no version in the range is; publish one first, or depend on a range that has one`); } else if (!usable) { problems.push(`${named} is retracted: every published version in the range is; depend on another range`); } } } return problems; } /** * The versions `dependency`'s package lists, or why they could not be * read: whether its DID does not resolve or its PDS cannot be read, and * with `explain`, the error. A host leaves the error out, since its * answer would tell a refused connection from a timeout from a status, * on whatever network a DID document points it at. */ async function versionsOf(dependency: Dependency, resolver: IdentityResolver, explain: boolean) : Future { let document = try { await resolver.resolveDid(dependency.did) } catch (e) { return if (explain) `its DID does not resolve: ${e.message}` else 'its DID does not resolve'; }; try { return await listVersions(document); } catch (e) { return if (explain) `its PDS cannot be read: ${e.message}` else 'its PDS cannot be read'; } } /** * What publishing requires of `manifest`, called `where` in the problems: * a description, and a license as an SPDX expression. */ export function checkMetadata(manifest: Manifest, where: String): GrowableArray { let problems = new GrowableArray(); let description = manifest.description; if (description == null || description.trim() == '') { problems.push(`${where} has no description`); } let license = manifest.license; if (license == null) { problems.push(`${where} has no license: give an SPDX expression, such as "MIT"`); } else if (!isValidLicenseExpression(license)) { problems.push(`${where} license '${license}' is not an SPDX expression`); } return problems; } /** * Every problem with publishing `release` of the package `did`, with * `source` as its source archive and `profileName` as its profile's name: * `checkSource`'s and `checkDependencies`', the errors behind a dependency * that cannot be found included unless `explain` is false. */ export async function validateRelease(release: Release, did: String, source: FixedArray, profileName: String, resolver: IdentityResolver, explain: boolean = true): Future> { let problems = checkSource(release, did, source, profileName, true); for (let problem in await checkDependencies(release.dependencies, resolver, explain)) { problems.push(problem); } return problems; }