~ 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

knotless-serve answers the Swift Package Registry for a repository's packages

Merged chadtmiller.com asked to merge into main from chadtmiller.com/knotless:serve/swift-registry
.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
lexicons/dev/knotless/release.json+20−0