chadtmiller.com/knotless
git that lives in your Atmosphere account
1
10
Maven metadata releases only what it names; the releases page shows Swift and Maven usage
.changeset/registries-on-the-pages.mdnew+7−0
| @@ -0,0 +1,7 @@ | ||
--- | ||
default: patch | ||
--- | ||
| ||
# The releases page says how to use a Swift package or a Maven artifact | ||
| ||
A Swift package's release shows the `swift package-registry set` and `.package(id:from:)` that use it, and a Maven artifact's the `maven { url = … }` and `implementation` that do. A Maven repository's `maven-metadata.xml` now releases only the versions it names, and keeps a version's uploaded files until its release is made, so a publish that fails can be run again. | ||
crates/knotless-serve/src/web/maven.rs+29−22
| @@ -297,26 +297,26 @@ impl Staging { | ||
files.iter().find(|f| f.file.name == name).cloned() | ||
} | ||
| ||
/// The versions of `of`'s artifact kept, taken out when `take`. | ||
fn versions(&self, of: &Publishing, take: bool) -> Vec<(String, Vec<Uploaded>)> { | ||
let mut versions = self.versions.lock().unwrap(); | ||
/// The versions of `of`'s artifact kept, each with its files. | ||
fn versions(&self, of: &Publishing) -> Vec<(String, Vec<Uploaded>)> { | ||
let versions = self.versions.lock().unwrap(); | ||
let same = |at: &Publishing| { | ||
(&at.did, &at.key, &at.group, &at.artifact) | ||
== (&of.did, &of.key, &of.group, &of.artifact) | ||
}; | ||
let ours: Vec<Publishing> = versions.keys().filter(|at| same(at)).cloned().collect(); | ||
let mut found = Vec::new(); | ||
for at in ours { | ||
let files = match take { | ||
true => versions.remove(&at).map(|(_, files)| files), | ||
false => versions.get(&at).map(|(_, files)| files.clone()), | ||
}; | ||
found.push((at.version, files.unwrap_or_default())); | ||
} | ||
let ours = versions.iter().filter(|(at, _)| same(at)); | ||
let mut found: Vec<_> = ours | ||
.map(|(at, (_, files))| (at.version.clone(), files.clone())) | ||
.collect(); | ||
found.sort_by(|a, b| a.0.cmp(&b.0)); | ||
found | ||
} | ||
| ||
/// Forgets the files kept for `at`, once its release is made. | ||
fn forget(&self, at: &Publishing) { | ||
self.versions.lock().unwrap().remove(at); | ||
} | ||
| ||
/// The session credentials of hash `kept` logged in to, if it is not | ||
/// too old. | ||
fn session(&self, kept: &str) -> Option<session::Session> { | ||
| @@ -554,19 +554,21 @@ impl Writing<'_> { | ||
Ok(created()) | ||
} | ||
| ||
/// `maven-metadata.xml`: the release of each version of the artifact | ||
/// whose files were uploaded, once every version it names is published | ||
/// or uploaded. | ||
/// `maven-metadata.xml`: the release of each version it names whose | ||
/// files were uploaded, once every version it names is published or | ||
/// uploaded. Each version's files are kept until its release is made, | ||
/// so a publish that fails can be run again. | ||
async fn publish(&self, xml: &[u8]) -> Answer { | ||
let (app, asked) = (self.app, &self.asked); | ||
let of = self.at(""); | ||
let staged = app.maven.versions(&of, false); | ||
let staged = app.maven.versions(&of); | ||
let published = versions(&self.opened.releases, asked); | ||
let xml = String::from_utf8_lossy(xml); | ||
let named = versions_in(&xml); | ||
let known = |v: &str| { | ||
published.iter().any(|r| r.version == v) || staged.iter().any(|(s, _)| s == v) | ||
}; | ||
let xml = String::from_utf8_lossy(xml); | ||
if let Some(lost) = versions_in(&xml).into_iter().find(|v| !known(v)) { | ||
if let Some(lost) = named.iter().find(|v| !known(v)) { | ||
let says = format!( | ||
"{}:{} {lost} was not uploaded here, or its upload was forgotten: publish it again", | ||
asked.group, asked.artifact | ||
| @@ -574,7 +576,10 @@ impl Writing<'_> { | ||
return Err(bad(says)); | ||
} | ||
let package = asked.package(); | ||
for (version, files) in app.maven.versions(&of, true) { | ||
let releasing = staged | ||
.into_iter() | ||
.filter(|(v, _)| named.contains(&v.as_str())); | ||
for (version, files) in releasing { | ||
let target = Target::open(&app.ctx, &self.opened.url, &package, &version).await; | ||
let target = target.map_err(refused_as(StatusCode::BAD_REQUEST))?; | ||
let hashes = files.iter().map(|f| f.hashes.clone()).collect(); | ||
| @@ -592,6 +597,7 @@ impl Writing<'_> { | ||
made.map_err(refused_as(StatusCode::BAD_GATEWAY))?; | ||
let rkey = knotless::keys::release_rkey(self.key, &package, &version); | ||
registry::indexed(app, &target, self.did, &rkey).await; | ||
app.maven.forget(&self.at(&version)); | ||
} | ||
Ok(created()) | ||
} | ||
| @@ -752,12 +758,13 @@ mod tests { | ||
assert!(staging.file(&at("d", "1.0.0"), "a-1.0.0.pom").is_some()); | ||
assert!(staging.file(&at("d", "1.0.0"), "a-1.0.0.aar").is_none()); | ||
assert!(staging.file(&at("d", "2.0.0"), "a-2.0.0.pom").is_none()); | ||
let kept = staging.versions(&at("d", ""), false); | ||
let kept = staging.versions(&at("d", "")); | ||
let versions: Vec<(&str, usize)> = | ||
kept.iter().map(|(v, f)| (v.as_str(), f.len())).collect(); | ||
assert_eq!(versions, [("0.9.0", 1), ("1.0.0", 1)]); | ||
assert_eq!(staging.versions(&at("d", ""), true).len(), 2); | ||
assert!(staging.versions(&at("d", ""), false).is_empty()); | ||
staging.forget(&at("d", "0.9.0")); | ||
staging.forget(&at("d", "1.0.0")); | ||
assert!(staging.versions(&at("d", "")).is_empty()); | ||
| ||
// A version of too many files is refused; past too many versions, | ||
// the oldest is forgotten. | ||
crates/knotless-serve/src/web/releases.rs+11−0
| @@ -44,6 +44,12 @@ pub struct ReleaseView { | ||
is_crate: bool, | ||
#[serde(skip_serializing_if = "std::ops::Not::not")] | ||
npm: bool, | ||
/// Its identifier, when it is a Swift package. | ||
#[serde(skip_serializing_if = "Option::is_none")] | ||
swift: Option<String>, | ||
/// `<group>:<artifact>`, when it is a Maven artifact. | ||
#[serde(skip_serializing_if = "Option::is_none")] | ||
maven: Option<String>, | ||
#[serde(skip_serializing_if = "Option::is_none")] | ||
commit: Option<String>, | ||
#[serde(skip_serializing_if = "Option::is_none")] | ||
| @@ -216,6 +222,11 @@ pub(super) async fn list_releases( | ||
image: image(&r), | ||
is_crate: r.cargo.is_some(), | ||
npm: r.npm.is_some(), | ||
swift: r.swift.as_ref().map(|s| s.identifier.clone()), | ||
maven: r | ||
.maven | ||
.as_ref() | ||
.map(|m| format!("{}:{}", m.group, m.artifact)), | ||
uri, | ||
package: r.package, | ||
version: r.version, | ||
crates/knotless-serve/tests/web.rs+25−0
| @@ -4427,6 +4427,14 @@ fn a_swift_registry() { | ||
let link = res.headers()["link"].to_str().unwrap().to_string(); | ||
assert!(link.contains("/1.0.0>; rel=\"latest-version\""), "{link}"); | ||
assert_eq!(says(get("Mona/LinkedList/1.1.0.zip")).0, 200); | ||
// The releases page knows each for a Swift package, by its identifier. | ||
let repo = format!("at://{did}/dev.knotless.repo/swiftpkgs"); | ||
let listed = site.json(&xrpc("listReleases", &[("repo", &repo)])); | ||
let listed = listed["releases"].as_array().unwrap(); | ||
assert!( | ||
listed.iter().all(|r| r["swift"] == "Mona.LinkedList"), | ||
"{listed:?}" | ||
); | ||
| ||
// Refused: what is there, who may not, and what SwiftPM never sends. | ||
let ok_body = || multipart(&[("source-archive", &archive("3.0.0"))]); | ||
| @@ -4733,6 +4741,14 @@ fn a_maven_repository() { | ||
wait_until(|| !get(metadata).1.contains("<version>1.1.0</version>")); | ||
assert!(get(metadata).1.contains("<latest>1.0.0</latest>")); | ||
assert_eq!(get("com/example/lib/1.1.0/lib-1.1.0.pom").0, 200); | ||
// The releases page knows each for a Maven artifact, by its coordinates. | ||
let at = format!("at://{did}/dev.knotless.repo/artifacts"); | ||
let listed = site.json(&xrpc("listReleases", &[("repo", &at)])); | ||
let listed = listed["releases"].as_array().unwrap(); | ||
assert!( | ||
listed.iter().all(|r| r["maven"] == "com.example:lib"), | ||
"{listed:?}" | ||
); | ||
| ||
// Refused: what is there, who may not, and what Gradle never sends. | ||
let refused = |path: &str, auth: &str, body: &[u8], status: u16, why: &str| { | ||
| @@ -4798,6 +4814,15 @@ fn a_maven_repository() { | ||
.count() | ||
}; | ||
assert_eq!(versions("com.example.lib"), 2); | ||
// Metadata releases only the versions it names; one not named stays | ||
// uploaded until metadata names it. | ||
let named = b"<versions><version>1.0.0</version></versions>"; | ||
assert_eq!(put(metadata, Some(&owners), named).0, 201); | ||
assert_eq!(versions("com.example.lib"), 2); | ||
let named = b"<versions><version>2.0.0</version></versions>"; | ||
assert_eq!(put(metadata, Some(&owners), named).0, 201); | ||
assert_eq!(versions("com.example.lib"), 3); | ||
refused(new, &owners, b"x", 409, "published already"); | ||
let large = vec![b' '; (64 << 20) + 1]; | ||
refused(new, &owners, &large, 413, "at most"); | ||
let nokey = format!("{}/maven/{did}/nokey/{metadata}", site.base); | ||
docs/design/packages.md+14−6
| @@ -496,11 +496,14 @@ then each one's `.sha1`, `.sha256`, `.sha512` and `.md5`, and last the | ||
artifact's `maven-metadata.xml`. A release is made once, with every file. | ||
So serve uploads each file to the owner's PDS as it lands, checks each | ||
hash sent beside it (but MD5, which it does not compute), and keeps the | ||
uploaded files for an hour, at most 64 versions at a time. The metadata | ||
makes the release of each version kept for that artifact, as Gradle and | ||
Maven send it after the files. Metadata naming a version neither | ||
published nor kept, as after a restart lost the files, is refused, so the | ||
publish fails and is run again. The credentials log in to the owner's PDS | ||
uploaded files for an hour, at most 64 versions at a time. The metadata, | ||
which Gradle and Maven send after the files, makes the release of each | ||
version it names that was kept, and the files are forgotten only once | ||
its release is made, so a publish that fails making one can be run | ||
again; a version kept that it does not name waits for metadata that | ||
does. Metadata naming a version neither published nor kept, as after a | ||
restart lost the files, is refused, so the publish fails and is run | ||
again. The credentials log in to the owner's PDS | ||
once for a publish's requests: the session is kept by their hash for ten | ||
minutes, and nowhere else. | ||
| ||
| @@ -549,7 +552,12 @@ its blobs, a crate the lines naming its repository's | ||
adds it, rather than its `.crate`, and an npm package the line of | ||
`.npmrc` sending its scope to its repository's | ||
[registry](#npm-packages) and the `npm install` that installs it, or for | ||
an unscoped package, the `npm install` of its tarball. | ||
an unscoped package, the `npm install` of its tarball; a Swift package | ||
the `swift package-registry set` sending its scope to its repository's | ||
[registry](#swift-packages) and the `.package(id:from:)` that depends on | ||
it, and a Maven artifact the `maven { url = … }` naming its repository's | ||
[Maven repository](#maven-artifacts) and the `implementation` that | ||
depends on it. | ||
| ||
Each file's name links to download it, from | ||
`/<owner>/<repo>/releases/download/<package>/<version>/<file>`. | ||
docs/reference/api.md+2−2
| @@ -649,7 +649,7 @@ minutes. | ||
| `GET <group path>/<artifact>/<version>/<file>.<hash>` | its SHA-256 from its record, or its SHA-1 or SHA-512 from the record's `maven`; 404 for MD5 | | ||
| `PUT <group path>/<artifact>/<version>/<file>` | a file of a version, at most 64 MiB, uploaded to the owner's PDS and kept for its release; 201. 409 for a version published already; 400 for a snapshot, a group, artifact or version a release does not take, a file not named `<artifact>-<version>` and then `-` or `.`, an empty one, or more than 64 | | ||
| `PUT <group path>/<artifact>/<version>/<file>.<hash>` | its hash, checked against the file kept; 201, MD5 unchecked. 404 for a file not kept, 400 for a hash not its | | ||
| `PUT <group path>/<artifact>/maven-metadata.xml` | the release of each version of the artifact kept, with its files; 201. 400 when it names a version neither published nor kept | | ||
| `PUT <group path>/<artifact>/maven-metadata.xml` | the release of each version it names that was kept, with its files, which are kept until it is made; 201. 400 when it names a version neither published nor kept | | ||
| `PUT <group path>/<artifact>/maven-metadata.xml.<hash>` | 201: the metadata is made as it is read | | ||
| ||
Errors are plain text. A write with no credentials is 401, with a `Basic` | ||
| @@ -712,7 +712,7 @@ name it has now. | ||
| `dev.knotless.getActorGists?actor=` | an account's gists, newest first, found as `getActorRepos` finds its repositories: each with the first ten `files` at the root of its default branch (`{name}`, ignoring case), `fileCount`, all of them, read from its mirror (none when it has none, or nothing was pushed), `starCount` and `forkCount` from the index (0 without one), and `commentCount`, how many comments `getGistComments` lists on it (none without an index); `ProfileNotFound` for an unknown account | | ||
| `dev.knotless.getGistComments?gist=` | what is said on a gist, oldest first: the comments whose `subject` is its record, each a `commentView` as `getThread` gives one, less those its owner hid, those by accounts it blocked, and those taken down; with an asker, `viewer.hide`, true for the gist's owner, who may hide them with `hideItem`. 404 `NotFound` for a repository that is not a gist, or with no index | | ||
| `dev.knotless.getRepo?repo=` | a repository: its owner, `kind: "gist"` for a gist, description, `links` (only http and https ones), `topics`, default branch, counts, languages, `collaborators` (the first twenty its record names, besides its owner) and `collaboratorCount`, `private` if it is, `archivedAt` if its owner archived it, and `site` if it has a website this server serves: its `url`, `deployedAt`, the `commit` its deployer named, and its `check` only when that check is from a runner the repository names; with an asker, `viewer`: its `star`, a `transfer` offered to it, the `labels` it may put on the repository's pulls and issues, and `admin: true` when it may change the repository's settings, as its owner or an admin who joined the organization that owns it | | ||
| `dev.knotless.listReleases?repo=&package=&limit=&cursor=` | its releases ([packages.md](../design/packages.md#on-the-pages)), newest first, 30 a page by default, of one `package` if given: each with `latest` when it is its package's latest, `yanked` when its owner withdrew it, `image` when its files are an OCI layout's, `crate` when it is a crate of the repository's Cargo registry, `npm` when it is a package of its npm registry, its notes as Markdown and as `html`, and its files' names, sizes and SHA-256; and every package it publishes, by name, with its latest version, how many releases it has and whether it is an image. None for a private repository or without an index | | ||
| `dev.knotless.listReleases?repo=&package=&limit=&cursor=` | its releases ([packages.md](../design/packages.md#on-the-pages)), newest first, 30 a page by default, of one `package` if given: each with `latest` when it is its package's latest, `yanked` when its owner withdrew it, `image` when its files are an OCI layout's, `crate` when it is a crate of the repository's Cargo registry, `npm` when it is a package of its npm registry, `swift`, its identifier, when it is a package of its Swift registry, `maven`, its `<group>:<artifact>`, when it is an artifact of its Maven repository, its notes as Markdown and as `html`, and its files' names, sizes and SHA-256; and every package it publishes, by name, with its latest version, how many releases it has and whether it is an image. None for a private repository or without an index | | ||
| `dev.knotless.getTree?repo=&ref=&path=` | a folder, its README and the newest checks of its last commit | | ||
| `dev.knotless.listPaths?repo=&ref=&limit=` | every folder and file at a revision, the shallowest first, at most 50,000, and `truncated` when the deepest were left out: for Go to file | | ||
| `dev.knotless.getLastCommits?repo=&ref=&path=` | the newest commit to change each entry of a folder, and at the root, how many commits the ref's history holds | | ||
lexicons/dev/knotless/defs.json+2−0
| @@ -374,6 +374,8 @@ | ||
"yanked": { "type": "boolean", "description": "True when its owner withdrew it, by a dev.knotless.releaseYank record: its files can still be read, but it is no one's latest." }, | ||
"crate": { "type": "boolean", "description": "True when it is a crate, added with Cargo from its repository's registry, at `/cargo/<owner's DID>/<repository's key>/`, rather than downloaded." }, | ||
"npm": { "type": "boolean", "description": "True when it is an npm package, installed with npm from its repository's registry, at `/npm/<owner's DID>/<repository's key>/`, rather than downloaded." }, | ||
"swift": { "type": "string", "description": "Its identifier, `<scope>.<name>` as it was published, when it is a Swift package, resolved with SwiftPM from its repository's registry, at `/swift/<owner's DID>/<repository's key>/`, rather than downloaded." }, | ||
"maven": { "type": "string", "description": "Its coordinates, `<group>:<artifact>`, when it is a Maven artifact, resolved with Gradle or Maven from its repository's Maven repository, at `/maven/<owner's DID>/<repository's key>/`, rather than downloaded." }, | ||
"commit": { "type": "string", "description": "The hex object ID of the commit its files were built from, if its record names one." }, | ||
"check": { "type": "string", "format": "at-uri", "description": "The dev.knotless.check of the run that built it, if its record names one." }, | ||
"notes": { "type": "string", "description": "What changed since the version before, in Markdown, as its record says." }, | ||
web/src/lib/organisms/ReleaseCard.svelte+37−4
| @@ -2,7 +2,15 @@ | ||
import type { ReleaseView } from '#lib/lexicons/dev/knotless/defs.ts'; | ||
import { page } from '$app/state'; | ||
import { ago, plural, repoHref, size } from '#lib/format.ts'; | ||
import { cargoUse, downloadHref, npmUse, pullCommand, releaseAnchor } from '#lib/releases.ts'; | ||
import { | ||
cargoUse, | ||
downloadHref, | ||
mavenUse, | ||
npmUse, | ||
pullCommand, | ||
releaseAnchor, | ||
swiftUse | ||
} from '#lib/releases.ts'; | ||
import Sha from '#lib/atoms/Sha.svelte'; | ||
import Time from '#lib/atoms/Time.svelte'; | ||
import Command from '#lib/molecules/Command.svelte'; | ||
| @@ -14,9 +22,9 @@ | ||
* commit, its notes, and its files, each with its size and SHA-256 and | ||
* linked to download; | ||
* or, for an image, the | ||
* command that pulls it rather than its blobs, and for a crate or an | ||
* npm package, how Cargo or npm adds it. A shared step's links to the | ||
* step's page. | ||
* command that pulls it rather than its blobs, and for a crate, an npm | ||
* package, a Swift package or a Maven artifact, how its tool adds it. A | ||
* shared step's links to the step's page. | ||
*/ | ||
let { owner, name, release: r }: { owner: string; name: string; release: ReleaseView } = $props(); | ||
const step = $derived(stepOf(r.package)); | ||
| @@ -25,6 +33,12 @@ | ||
r.crate ? cargoUse(page.url.origin, r.uri, name, r.package, r.version) : undefined | ||
); | ||
const npm = $derived(r.npm ? npmUse(page.url.origin, r.uri, r.package, r.version) : undefined); | ||
const swift = $derived( | ||
r.swift ? swiftUse(page.url.origin, r.uri, r.swift, r.version) : undefined | ||
); | ||
const maven = $derived( | ||
r.maven ? mavenUse(page.url.origin, r.uri, r.maven, r.version) : undefined | ||
); | ||
</script> | ||
| ||
<article class="box release" id={releaseAnchor(r)}> | ||
| @@ -65,6 +79,25 @@ | ||
package with npm.{:else}An npm package, installed from its tarball.{/if} | ||
</p> | ||
</div> | ||
{:else if swift} | ||
<div class="release-pull"> | ||
<Command text={swift.config} /> | ||
<Command text={swift.add} /> | ||
<p class="mute"> | ||
A Swift package. Send its scope to the registry, then depend on it in <code | ||
>Package.swift</code | ||
>. | ||
</p> | ||
</div> | ||
{:else if maven} | ||
<div class="release-pull"> | ||
<Command text={maven.config} /> | ||
<Command text={maven.add} /> | ||
<p class="mute"> | ||
A Maven artifact. Add the repository to Gradle's <code>repositories</code>, then depend on | ||
it. | ||
</p> | ||
</div> | ||
{:else} | ||
<ul class="list release-files" aria-label="Files"> | ||
{#each r.files as f (f.name)} | ||
web/src/lib/releases.ts+35−0
| @@ -72,6 +72,41 @@ export function npmUse( | ||
return { add: `npm install ${registry}${pkg}/-/${pkg}-${version}.tgz` }; | ||
} | ||
| ||
/** | ||
* What a Swift package's release, `uri`, of identifier `id`, says to | ||
* SwiftPM, served from `origin`: the command sending its scope to its | ||
* repository's registry, and the dependency that names it there. | ||
*/ | ||
export function swiftUse( | ||
origin: string, | ||
uri: string, | ||
id: string, | ||
version: string | ||
): { config: string; add: string } { | ||
const scope = id.split('.')[0]; | ||
return { | ||
config: `swift package-registry set --scope ${scope} ${origin}${registryPath('swift', uri)}`, | ||
add: `.package(id: "${id}", from: "${version}")` | ||
}; | ||
} | ||
| ||
/** | ||
* What a Maven artifact's release, `uri`, of coordinates `coordinates` | ||
* (`<group>:<artifact>`), says to Gradle, served from `origin`: the | ||
* repository naming its repository's, and the dependency on it. | ||
*/ | ||
export function mavenUse( | ||
origin: string, | ||
uri: string, | ||
coordinates: string, | ||
version: string | ||
): { config: string; add: string } { | ||
return { | ||
config: `maven { url = uri("${origin}${registryPath('maven', uri)}") }`, | ||
add: `implementation("${coordinates}:${version}")` | ||
}; | ||
} | ||
| ||
/** The id a release has on the releases page, for a link to land on it. */ | ||
export const releaseAnchor = (r: { package: string; version: string }) => | ||
`${r.package}@${r.version}`; | ||