Skip to content

feat(papermc): migrate Paper source to v3 Fill API - #147

Merged
deniz-blue merged 1 commit into
deniz-blue:mainfrom
maldis018:feat/papermc-v3-fill-api
Jun 18, 2026
Merged

feat(papermc): migrate Paper source to v3 Fill API#147
deniz-blue merged 1 commit into
deniz-blue:mainfrom
maldis018:feat/papermc-v3-fill-api

Conversation

@maldis018

Copy link
Copy Markdown
Contributor

Migrate PaperMC source from the deprecated v2 API to the v3 Fill API

Closes #146

Problem

src/sources/papermc.rs resolves Paper builds through https://api.papermc.io/v2. PaperMC has frozen v2: its version list tops out at 1.21.11, and GET v2/projects/paper/versions/26.1.2/builds returns 404 {"error":"Version not found."}. Every modern Minecraft version (the 26.x scheme onward) lives only on the new Fill API at https://fill.papermc.io/v3, so mcman build cannot resolve a Paper jar for any current MC version. Full evidence in #146.

Change

Rewrites src/sources/papermc.rs to target the v3 Fill API. The v3 response shapes differ from v2, so the structs and resolve_source are reworked, not just the base URL:

  • Base URL api.papermc.io/v2fill.papermc.io/v3.
  • Builds are returned as a bare, newest-first JSON array (v2 wrapped them in an object, oldest-first). "latest" is now the first element; a pinned build hits the single-build endpoint /builds/{id} directly.
  • Build id moved from build (u64) to id (u64).
  • Server jar is keyed server:default in downloads (was application).
  • Download URL is provided directly as downloads["server:default"].url, so it's used verbatim instead of being hand-constructed from the API path.
  • Versions is now an ordered (newest-first) map of version-group → versions, deserialized into an IndexMap to preserve API order so "latest" is reliable. (Adds the serde feature to the existing indexmap dependency.)
  • ResolvedFile now carries size and the sha256 from the v3 downloads[...].checksums.sha256 (v2 left both empty).
  • Drops v2-only fields that v3 does not provide and the resolver never used: the PaperChannel enum, version_groups, promoted, and changes/commits. channel is retained as a plain String for forward-compat but is not used for filtering.
  • Adds a validate_segment() allowlist on the user-supplied project / version / build values before they are interpolated into request URLs.

Testing

  • cargo check passes.
  • cargo clippy --all-features produces no findings in papermc.rs. (The repo currently has pre-existing clippy errors on main in unrelated files - init/mod.rs, packwiz.rs, jenkins.rs. This PR doesn't touch those.)
  • End-to-end: mcman build against mc_version = "26.1.2" resolves the Paper jar and assembles a full 20-plugin server with correct loader-filtering. Verified in production on a live 26.1.2 server for several weeks.

Notes for the reviewer

  • Clean cutover, no v2 fallback. The Fill API serves the full historical version list, so legacy MC versions (≤ 1.21.11) resolve through v3 as well. Happy to add a v2 fallback path instead if you'd prefer to keep the old endpoint for older servers.
  • Single commit, based on current main (2665efb).

The legacy api.papermc.io/v2 service no longer receives new versions and
returns HTTP 404 for Minecraft releases above 1.21.11 (e.g. 26.1.2). The
builds exist only on the new "Fill" API at fill.papermc.io/v3.

Rewrite src/sources/papermc.rs to target v3:
- builds are returned as a bare, newest-first array; build ids live under
  `id`; the server jar is keyed `server:default` in `downloads`
- each download carries name/size/url/checksums.sha256, so the download URL
  is used directly instead of being constructed
- a project's `versions` is an ordered (newest-first) map of
  version-group -> versions, deserialized into an IndexMap to preserve order
- populate ResolvedFile size + sha256 (v2 left both empty)
- pinned builds use the direct /builds/{id} endpoint; "latest" takes the
  first element of the builds array
- validate project/version/build path segments before URL interpolation
- drop the v2-only PaperChannel enum, version_groups, promoted, and changes

Requires the indexmap `serde` feature for the versions map.

Verified end-to-end: `mcman build` resolves Paper 26.1.2 build deniz-blue#66
(sha256 2c2af90d…) and the full 20-plugin server with correct
loader-filtering restored.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@deniz-blue

Copy link
Copy Markdown
Owner

LGTM, thanks for contributing

@deniz-blue
deniz-blue merged commit 73d7e44 into deniz-blue:main Jun 18, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

PaperMC source uses the deprecated v2 API; fails to resolve any Minecraft 26.x+ build

2 participants