chadtmiller.com/knotless
git that lives in your Atmosphere account
knotless-serve answers the Swift Package Registry for a repository's packages
MergedThis adds a per-repository Swift Package Registry (SE-0292) to knotless-serve, with an optional swift object on dev.knotless.release. I found nothing that must change.
The lexicon is consistent with the code. The 141-byte identifier limit matches a 39-byte scope, a dot and a 100-byte name. The manifests limits of 32 entries and 100,000 bytes each match MOST_MANIFESTS and MOST_KEPT. The new object is optional, so existing records still validate. The Made and Target::create plumbing and the record structs follow the cargo and npm pattern. The change file is present.
publish checks, in order:
- the session is the repository's owner;
- the identifier is valid and the version is not already published (409);
- the archive has exactly one top-level directory and a
Package.swift.
The zip reader bounds its inflation (take(size + 1), with the size capped at MOST_KEPT) and refuses 64-bit and malformed entries. Multipart parsing and the 64 MiB body cap look sound.
Minor, not worth holding the pull:
swift_version_ofaccepts digit runs of any length, so a manifest name such asPackage@swift-<very long number>.swiftcan exceed the lexicon's 64-bytenamelimit. The PDS would then refuse the record and the publish would answer 502 rather than 422. Only the publisher is affected.- A swift release and an npm or cargo release whose package names lowercase to the same string share a record key, so the second publish gets a 409. That is acceptable, but it may be worth a line in
packages.md.
I did not read the second half of the unit tests in swift.rs (from about line 900), tests/web.rs, docs/design/packages.md or docs/reference/api.md. The test check's 100% coverage gate will catch what the tests miss. I read everything else the pull changes.
crates/knotless-serve/src/web/swift.rsline 308Outdated
let mut links = Vec::from_iter(asked.latest()); | |
let mut next = |to: Option<&&ReleaseRecord>, rel: &str| { | |
let to = to.map(|r| format!("<{}/{}>; rel=\"{rel}\"", asked.at, r.version)); | |
links.extend(to); |
Digit runs of any length pass here, so a manifest name can exceed the lexicon's 64-byte swiftManifest.name limit. The PDS would refuse the record and the publish would answer 502 instead of 422. Capping the name's length in manifests_of would turn that into a clean refusal.
I read the change since the approved commit, and my earlier approval still stands. It is a small refactor and one added test line.
- Header setting now goes through
headers_mut().extend(Option<(name, value)>)forLink,DigestandContent-Disposition. It sets the same headers as before. The names it sets (Link,Digest,Content-Disposition) are not already present on those responses, so append versus replace makes no difference. refused_publishbecame the closure-returningrefused_as(status). It keeps the same 409 on "is published already" and the same status otherwise, and the tests were updated to match.- The new
entries(&[0; 30])assertion and theis_ok()simplification are fine.
My two earlier minor notes (the unbounded digit run in swift_version_of, and the shared record key across package kinds) are not changed by this diff. Neither blocks the pull.
10 passed, 1 skipped
knotless-serve now runs a Swift package registry for each repository. SwiftPM and Xcode can resolve
.package(id: "<scope>.<Name>", from: …)fromhttps://knotless.dev/swift/<did>/<repo key>/, andswift package-registry publishpublishes to it. HUD's HUDKit is the first user. The newswiftobject indev.knotless.releaseneeds a look, because a lexicon can only grow once it is published.Claude Opus 5.5 · high
What changes
knotless-serve runs a Swift package registry for each repository at
/swift/<did>/<repo key>/, as the Swift Package Registry Service spec (SE-0292) lays it out:Linktolatest-version; a yanked release is listed with a410problem;checksumandLinks to the successor and predecessor versions;Package.swift, and?swift-version=for a version-specific manifest, falling back to303as the spec says, withalternatelinks carrying each manifest'sswift-tools-version;Digest;identifiers?url=, which answers for the repository's own address (by DID or handle) and for the URLs a release's metadata lists inrepositoryURLs;multipart/form-datapublish thatswift package-registry publishsends;swift package-registry loginposts to the registry's own address.Every answer carries
Content-Version: 1, and anAcceptasking for another API version gets 415. Errors are problem details. Credentials are Basic<handle>:<app password>, or that string as a Bearer token. A publish or login without credentials gets401with aBasicchallenge.A release gains an optional
swiftobject:identifier: the identifier in the case it was published in;manifests:Package.swiftand eachPackage@swift-*.swiftread from the archive;metadata: what the publish said about the release, as JSON.The release's
packageis the identifier lowercased, and its one file is<Name>-<version>.zip. The manifests are kept in the record so that resolution reads no blob until it downloads.docs/design/packages.mdhas a new Swift packages section.docs/reference/api.mdlists the routes. There is a change file.Why
HUD is becoming an SDK. Its iOS half, HUDKit, has to be a versioned Swift package that Grain can depend on, instead of a copied
vendor/hud. This follows the Cargo and npm registries' choices, for the same reasons: one registry per repository, an address that holds a DID and a key, reads served from what the index has (so a takedown holds), and the client's own format kept in the record.package. The spec treats identifiers case-insensitively, and a release's name has to be lowercase. The published case is kept for the answers.swift package archive-sourcelays it out, and SwiftPM strips that level when it extracts. An archive with files at its root would extract wrong, so it is refused at publish.problem. The spec has no other way to say a release shouldn't be used.How it was checked
a_swift_registryintests/web.rsspeaks the protocol as SwiftPM does, against a served registry and the PDS:.json;303;Digest;.git, handle and DID URLs;410problem;Package.swiftgives 404, a missing file gives 404).Unit tests cover identifier rules, the zip reader (stored and deflated, broken entries), multipart parsing including base64 parts, the metadata, the token,
Accept, URL normalising andDigest. Run locally: those tests, clippy and fmt for knotless-serve, andharness/lexicons.mjs.End to end, against a local knotless-serve over the harness PDS, with Swift 6.3.3 and Xcode 26.6:
swift package-registry publish mona.LinkedList 1.0.0and1.1.0published, with an app password from a netrc file;409 … is published already;.package(id: "mona.LinkedList", from: "1.0.0"), afterswift package-registry set --scope mona,swift package resolvepinned1.1.0, andswift runprinted the library's answer;xcodebuild -resolvePackageDependenciesresolved it andxcodebuild buildbuilt it;knotless release yankof 1.1.0, a fresh resolve took 1.0.0. A resolve with 1.1.0 pinned inPackage.resolvedmoved the pin to 1.0.0, which the docs now say.That run used plain http (
--allow-insecure-http).swift package-registry loginitself always posts over https, so it was not run there; its route is covered by the test.Shortcomings
commitorcheckon a release made this way..netrc.repositoryURLsclaim to another host: it is the owner's word, and only those who point a scope at this registry read it.202) is not offered. Publishes answer201at once.Review
The lexicon first, then
crates/knotless-serve/src/web/swift.rs'spublish,manifests_ofandparts.