~ 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
Merged chadtmiller.com asked to merge into main from chadtmiller.com/knotless:serve/swift-registry

knotless-serve now runs a Swift package registry for each repository. SwiftPM and Xcode can resolve .package(id: "<scope>.<Name>", from: …) from https://knotless.dev/swift/<did>/<repo key>/, and swift package-registry publish publishes to it. HUD's HUDKit is the first user. The new swift object in dev.knotless.release needs 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:

  • the list of a package's releases, with a Link to latest-version; a yanked release is listed with a 410 problem;
  • a release's metadata, with the archive's SHA-256 as its checksum and Links to the successor and predecessor versions;
  • Package.swift, and ?swift-version= for a version-specific manifest, falling back to 303 as the spec says, with alternate links carrying each manifest's swift-tools-version;
  • the source archive, with its Digest;
  • identifiers?url=, which answers for the repository's own address (by DID or handle) and for the URLs a release's metadata lists in repositoryURLs;
  • the multipart/form-data publish that swift package-registry publish sends;
  • the login that swift package-registry login posts to the registry's own address.

Every answer carries Content-Version: 1, and an Accept asking 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 gets 401 with a Basic challenge.

A release gains an optional swift object:

  • identifier: the identifier in the case it was published in;
  • manifests: Package.swift and each Package@swift-*.swift read from the archive;
  • metadata: what the publish said about the release, as JSON.

The release's package is 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.md has a new Swift packages section. docs/reference/api.md lists 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.

  • Identifiers are lowercased into package. The spec treats identifiers case-insensitively, and a release's name has to be lowercase. The published case is kept for the answers.
  • The archive must have one top-level directory. This is how swift package archive-source lays 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.
  • Signed publishes are refused. A signature and its certificate have nowhere to go in the record. Keeping the release without them would make it read as unsigned.
  • A yank is a problem. The spec has no other way to say a release shouldn't be used.

How it was checked

a_swift_registry in tests/web.rs speaks the protocol as SwiftPM does, against a served registry and the PDS:

  • login: none, wrong, another account's, Bearer;
  • three publishes, one with metadata;
  • the record's shape;
  • the release list in any case and with .json;
  • the 415 for another API version;
  • release metadata and its links;
  • both manifests and the 303;
  • the archive and its Digest;
  • identifier lookups by scp, .git, handle and DID URLs;
  • a yank, read as a 410 problem;
  • every refusal;
  • records no publish would make (a bad archive gives 502, a missing Package.swift gives 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 and Digest. Run locally: those tests, clippy and fmt for knotless-serve, and harness/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.0 and 1.1.0 published, with an app password from a netrc file;
  • publishing 1.1.0 again got 409 … is published already;
  • in a consumer with .package(id: "mona.LinkedList", from: "1.0.0"), after swift package-registry set --scope mona, swift package resolve pinned 1.1.0, and swift run printed the library's answer;
  • xcodebuild -resolvePackageDependencies resolved it and xcodebuild build built it;
  • after knotless release yank of 1.1.0, a fresh resolve took 1.0.0. A resolve with 1.1.0 pinned in Package.resolved moved the pin to 1.0.0, which the docs now say.

That run used plain http (--allow-insecure-http). swift package-registry login itself always posts over https, so it was not run there; its route is covered by the test.

Shortcomings

  • No signed releases.
  • As with crates and npm packages: public repositories only, and no commit or check on a release made this way.
  • The app password, which can do far more than publish, sits in the keychain or .netrc.
  • Nothing checks a repositoryURLs claim to another host: it is the owner's word, and only those who point a scope at this registry read it.
  • Asynchronous publishing (202) is not offered. Publishes answer 201 at once.
  • The releases page doesn't show how to use a Swift package yet.

Review

The lexicon first, then crates/knotless-serve/src/web/swift.rs's publish, manifests_of and parts.

Approved

This 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_of accepts digit runs of any length, so a manifest name such as Package@swift-<very long number>.swift can exceed the lexicon's 64-byte name limit. 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);
review.knotless.dev

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.

Approved

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)>) for Link, Digest and Content-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_publish became the closure-returning refused_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 the is_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.

Merged as 6a61307