chadtmiller.com/knotless
git that lives in your Atmosphere account
1
10
knotless-serve answers the Swift Package Registry for a repository's packages
.changeset/swift-registry.mdnew+7−0
| @@ -0,0 +1,7 @@ | ||
--- | ||
default: minor | ||
--- | ||
| ||
# A repository's Swift packages can be published and resolved with SwiftPM | ||
| ||
knotless-serve answers the Swift Package Registry protocol for each repository, so with `swift package-registry set https://knotless.dev/swift/<did>/<repo key>/`, `swift package-registry login` (your handle and an app password) and `swift package-registry publish` work, and SwiftPM and Xcode resolve `.package(id: "<scope>.<Name>", from: "1.0.0")`. `knotless release yank` takes a version out of what they resolve to. | ||
crates/knotless/src/records.rs+26−0
| @@ -1046,6 +1046,10 @@ pub struct ReleaseRecord { | ||
/// What npm's registry says of it, if it is an npm package. | ||
#[serde(default, skip_serializing_if = "Option::is_none")] | ||
pub npm: Option<NpmPackage>, | ||
/// What the Swift Package Registry says of it, if it is a Swift | ||
/// package. | ||
#[serde(default, skip_serializing_if = "Option::is_none")] | ||
pub swift: Option<SwiftPackage>, | ||
/// Whether its owner yanked it: read from its | ||
/// [`nsid::RELEASE_YANK`] record, and no part of this one. | ||
#[serde(skip)] | ||
| @@ -1070,6 +1074,28 @@ pub struct NpmPackage { | ||
pub manifest: String, | ||
} | ||
| ||
/// A release as a Swift package: its file is `<name>-<version>.zip`, its | ||
/// source archive, and its package's name is its identifier, | ||
/// `<scope>.<name>`, lowercased. | ||
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)] | ||
pub struct SwiftPackage { | ||
/// Its identifier as it was published, `<scope>.<name>` in its case. | ||
pub identifier: String, | ||
/// `Package.swift` and each `Package@swift-<version>.swift` beside it | ||
/// in the archive. | ||
pub manifests: Vec<SwiftManifest>, | ||
/// What the publish said of the release, as JSON, if it said anything. | ||
#[serde(default, skip_serializing_if = "Option::is_none")] | ||
pub metadata: Option<String>, | ||
} | ||
| ||
/// A manifest of a Swift package's release, by its file's name. | ||
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)] | ||
pub struct SwiftManifest { | ||
pub name: String, | ||
pub content: String, | ||
} | ||
| ||
/// That its owner yanked a release, keyed as the release is, which never | ||
/// changes: deleting this undoes it. | ||
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)] | ||
crates/knotless/src/release.rs+3−0
| @@ -187,6 +187,7 @@ pub struct Made { | ||
pub notes: Option<String>, | ||
pub cargo: Option<records::CargoCrate>, | ||
pub npm: Option<records::NpmPackage>, | ||
pub swift: Option<records::SwiftPackage>, | ||
} | ||
| ||
/// Where a version of a package is to be published: a public repository, | ||
| @@ -253,6 +254,7 @@ impl Target { | ||
created_at: records::now(), | ||
cargo: made.cargo, | ||
npm: made.npm, | ||
swift: made.swift, | ||
yanked: false, | ||
}; | ||
let typed = records::typed(nsid::RELEASE, &record); | ||
| @@ -502,6 +504,7 @@ mod tests { | ||
created_at: "2026-10-27T00:00:00.000Z".into(), | ||
cargo: None, | ||
npm: None, | ||
swift: None, | ||
yanked: false, | ||
} | ||
} | ||
crates/knotless-serve/src/web/cargo.rs+1−0
| @@ -519,6 +519,7 @@ mod tests { | ||
created_at: String::new(), | ||
cargo, | ||
npm: None, | ||
swift: None, | ||
yanked, | ||
}; | ||
(String::new(), record) | ||
crates/knotless-serve/src/web/npm.rs+1−0
| @@ -517,6 +517,7 @@ mod tests { | ||
npm: manifest.map(|m| NpmPackage { | ||
manifest: m.to_string(), | ||
}), | ||
swift: None, | ||
yanked, | ||
}; | ||
(String::new(), record) | ||
crates/knotless-serve/src/web/releases.rs+1−0
| @@ -328,6 +328,7 @@ mod tests { | ||
created_at: "2026-10-01T00:00:00Z".into(), | ||
cargo: None, | ||
npm: None, | ||
swift: None, | ||
yanked: false, | ||
}; | ||
( | ||
crates/knotless-serve/src/web/steps.rs+1−0
| @@ -270,6 +270,7 @@ mod tests { | ||
created_at: String::new(), | ||
cargo: None, | ||
npm: None, | ||
swift: None, | ||
yanked: false, | ||
}; | ||
(v.into(), record, Value::Null) | ||
crates/knotless-serve/src/web/swift.rsnew+1060−0
1060 lines changed: not loaded until asked for.
crates/knotless-serve/src/web.rs+16−0
| @@ -78,6 +78,7 @@ pub(crate) use settings::Counts; | ||
mod stars; | ||
mod steps; | ||
mod subscriptions; | ||
mod swift; | ||
mod themes; | ||
mod threads; | ||
mod views; | ||
| @@ -339,6 +340,21 @@ pub fn routes() -> Router<Arc<App>> { | ||
"/npm/{did}/{key}/{name}/-rev/{rev}", | ||
axum::routing::put(npm::unpublish).delete(npm::unpublish), | ||
) | ||
// `swift package-registry login` posts to the registry's own | ||
// address. | ||
.route("/swift/{did}/{key}", post(swift::login)) | ||
.route("/swift/{did}/{key}/", post(swift::login)) | ||
.route("/swift/{did}/{key}/login", post(swift::login)) | ||
.route("/swift/{did}/{key}/identifiers", get(swift::identifiers)) | ||
.route("/swift/{did}/{key}/{scope}/{name}", get(swift::list)) | ||
.route( | ||
"/swift/{did}/{key}/{scope}/{name}/{version}", | ||
get(swift::release).put(swift::publish), | ||
) | ||
.route( | ||
"/swift/{did}/{key}/{scope}/{name}/{version}/Package.swift", | ||
get(swift::manifest), | ||
) | ||
.route("/{authority}/{repo}/archive/{*rest}", get(archive::archive)) | ||
.merge(compressed) | ||
.layer(middleware::from_fn(renamed)) | ||
crates/knotless-serve/tests/web.rs+478−0
478 lines changed: not loaded until asked for.
docs/design/packages.md+73−1
| @@ -386,6 +386,77 @@ is lowercase, no version with build metadata is taken, as `npm publish` | ||
drops it, and neither `commit` nor `check` is set. `npm publish | ||
--provenance` is refused, as its Sigstore bundle has nowhere to go. | ||
| ||
## Swift packages | ||
| ||
A Swift package is a release too, and knotless-serve answers the Swift | ||
Package Registry Service protocol (SE-0292) from those records, one | ||
registry for each repository, as for [crates](#crates) and for the same | ||
reasons. A scope, or every scope, is pointed at it, and a package names its | ||
dependency by identifier: | ||
| ||
```sh | ||
swift package-registry set --scope mona https://knotless.dev/swift/<did>/<repo key>/ | ||
``` | ||
| ||
```swift | ||
.package(id: "mona.LinkedList", from: "1.0.0") | ||
``` | ||
| ||
Xcode 15 and later resolves such a dependency too, from the same | ||
`.swiftpm/configuration/registries.json`. Reads need no login. | ||
`swift package-registry login https://knotless.dev/swift/<did>/<repo key>/` | ||
takes the owner's handle as its user and an app password, which SwiftPM | ||
keeps in the keychain, or in `.netrc`, and sends with each publish as Basic | ||
credentials. It posts them to the registry's own address, which checks them | ||
against the owner's PDS, as each publish does again; serve keeps nothing. | ||
Then `swift package-registry publish mona.LinkedList 1.0.0` archives the | ||
package with `swift package archive-source` and publishes it. | ||
| ||
**An identifier is lowercase in the record.** An identifier is | ||
`<scope>.<name>`, the same in any case, so a release's `package` is it | ||
lowercased, which a release's name takes, and the `swift` object keeps it | ||
as it was published, `mona.LinkedList`, which the registry answers. A | ||
scope is letters, digits and single hyphens, at most 39; a name letters, | ||
digits and single hyphens or underscores, at most 100. The one file is the | ||
source archive, `<name>-<version>.zip`. | ||
| ||
**The manifests are in the record.** SwiftPM reads a release's | ||
`Package.swift`, and asks for each `Package@swift-<version>.swift` it | ||
names, before it downloads anything. A publish reads them out of the | ||
archive, from the one directory every file is under, as `swift package | ||
archive-source` lays it out and as SwiftPM strips it, and keeps them in | ||
the `swift` object, each at most 100,000 bytes and at most 32, so no blob | ||
is read to answer them. An archive with files outside that directory, or | ||
no `Package.swift` in it, is refused. What the publish said of the release, | ||
its `metadata`, is kept too, as the JSON it is, and answered with the | ||
release; its `checksum` is the archive's SHA-256, the record's. | ||
| ||
**A yank is a problem.** The spec has no yank, but lists a release that | ||
should not be used with a `problem`, which a client resolves to no more. | ||
A [yanked](#yanking) version is listed with one, `410`, and is no one's | ||
`latest-version`. Its metadata, manifests and archive are still read by | ||
its version, but SwiftPM resolves to it no more even where | ||
`Package.resolved` pins it: it moves the pin to the highest version left | ||
that the requirement takes, unlike a Cargo lockfile. `knotless release | ||
yank` yanks one. | ||
| ||
**Signatures are refused.** A signed release's signature and the | ||
certificate it names have nowhere to go in a record, and a release kept | ||
without them would read as unsigned, so a signed publish is refused: | ||
publish unsigned. The record is signed in the owner's account, as every | ||
release is. | ||
| ||
**Looking an identifier up by URL.** SwiftPM asks which identifiers a | ||
repository's URL has, to use a registry in place of a git dependency. This | ||
repository's own address on this server, by its owner's DID or handle, | ||
names every package it publishes; another address, those whose metadata | ||
names it in `repositoryURLs`. A claim to another's address is the owner's | ||
word, read only by those who point a scope at this registry. | ||
| ||
As with crates and npm packages, what it reads is what the index has, a | ||
publish puts its record in the index itself, and neither `commit` nor | ||
`check` is set. | ||
| ||
## On the pages | ||
| ||
knotless-serve indexes release records as it indexes the rest, so a | ||
| @@ -458,7 +529,8 @@ one record per version, two publishes of different versions never touch | ||
the same record. | ||
| ||
A registry beside the release records, in knotless-serve, needs nothing of | ||
the PDS, as [crates](#crates), [npm packages](#npm-packages) and | ||
the PDS, as [crates](#crates), [npm packages](#npm-packages), | ||
[Swift packages](#swift-packages) and | ||
[images](#images) show. | ||
| ||
## How knotless versions itself | ||
docs/reference/api.md+27−0
| @@ -601,6 +601,33 @@ password>`, which logs in to the owner's PDS. | ||
Errors are npm's, `{"error"}`. A write, a login or `whoami` with no token, a | ||
token not of that form, one the PDS refuses or another account's is 403. | ||
| ||
## Swift packages | ||
| ||
A Swift package registry of the packages a repository publishes as releases | ||
([packages.md](../design/packages.md#swift-packages)), under | ||
`/swift/<did>/<repo key>/`, where `<did>` is its owner's, as the Swift Package | ||
Registry Service specification has it. A package is `<scope>/<name>` in a | ||
path, in any case. What it reads is what the index has: with none, or for a | ||
repository the index lacks or has taken down, all of it is 404. Credentials, | ||
in `Authorization`, are `Basic` of `<handle>:<app password>`, or that as a | ||
`Bearer` token, which logs in to the owner's PDS. Every answer says | ||
`Content-Version: 1`, and one asked for by another version in `Accept` is | ||
415. | ||
| ||
| Route | | | ||
| --- | --- | | ||
| `GET <scope>/<name>`, or `.json` | `{releases}`, each version's `url` here, and a yanked one's `problem`, 410; a `Link` to the `latest-version`; `no-cache`, with an `ETag`; 404 for none | | ||
| `GET <scope>/<name>/<version>`, or `.json` | `{id, version, resources, metadata, publishedAt}`: `id` as it was published, the `source-archive` and its SHA-256 as `checksum`, and `metadata` as the publish said it, or `{}`; `Link`s to the `latest-version`, `successor-version` and `predecessor-version` | | ||
| `GET <scope>/<name>/<version>/Package.swift?swift-version=` | the manifest, `text/x-swift`, with a `Link` to each `Package@swift-<version>.swift` with its `swift-tools-version`; with `swift-version`, that one, or 303 to `Package.swift` | | ||
| `GET <scope>/<name>/<version>.zip` | the source archive, `application/zip`, as a release's files are sent, with its `Digest` | | ||
| `GET identifiers?url=` | `{identifiers}`: every package when `url` is this repository's address on this server, by its owner's DID or handle, else those whose metadata names it in `repositoryURLs`; 404 for none, 400 without a `url` | | ||
| `PUT <scope>/<name>/<version>` | as `swift package-registry publish`: `multipart/form-data` of a `source-archive` and optionally `metadata`, at most 64 MiB, the archive uploaded to the owner's PDS and its release made; 201 with its `Location`. 409 for a version published already; 400 for an identifier or version a release does not take, or a body that is not multipart; 422 for no archive, a signed one, an archive whose files are not all under one directory or that has no `Package.swift` there, a manifest over 100,000 bytes, more than 32, or `metadata` that is not a JSON object of at most 100,000 bytes | | ||
| `POST /`, `POST login` | as `swift package-registry login`: 200 for the owner's credentials | | ||
| ||
Errors are problem details, `{"detail"}` as `application/problem+json`. A | ||
publish or a login with no credentials is 401, with a `Basic` challenge; | ||
credentials the PDS refuses or another account's are 403. | ||
| ||
## Images | ||
| ||
An OCI registry of the images repositories publish as releases, with | ||