~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/knotless

git that lives in your Atmosphere account

knotless.dev
1 collaborator

knotless 0.17.0 Latest 2 packages, 1 image

1
10

Maven metadata releases only what it names; the releases page shows Swift and Maven usage

Merged chadtmiller.com asked to merge into main from chadtmiller.com/knotless:serve/registries-pages
.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}`;