Skip to content

fix(swagger-ui-build): harden curl download against transient CDN failures#1541

Open
dmitry-tokarev-nv wants to merge 1 commit intojuhaku:masterfrom
dmitry-tokarev-nv:harden-swagger-ui-curl-download
Open

fix(swagger-ui-build): harden curl download against transient CDN failures#1541
dmitry-tokarev-nv wants to merge 1 commit intojuhaku:masterfrom
dmitry-tokarev-nv:harden-swagger-ui-curl-download

Conversation

@dmitry-tokarev-nv
Copy link
Copy Markdown

Problem

utoipa-swagger-ui/build.rs downloads the Swagger UI archive at compile time using curl -sSL -o file URL. Without --fail, curl exits 0 on HTTP 4xx/5xx and writes the error response body to the output path. The build then hits ZipArchive::new, which panics with "Could not find EOCD" — leaving the user to figure out that the actual problem was a transient CDN error, not a malformed local archive.

We hit this in our CI when the GitHub Releases CDN started serving sustained 5xx for the swagger-ui release tarball. Job logs showed:

SWAGGER_UI_DOWNLOAD_URL: https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.zip
trying to download using `curl` system package
thread 'main' panicked at .../utoipa-swagger-ui-9.0.2/build.rs:219:51:
failed to open downloaded Swagger UI: InvalidArchive("Could not find EOCD")

Change

Add the standard set of curl resilience flags to the download_file_curl invocation:

flag purpose
--fail --show-error surface HTTP 4xx/5xx as a curl error with a useful message instead of silently writing HTML to the output
--retry 5 --retry-delay 2 ride out transient 5xx and connection failures from release CDNs
--connect-timeout 10 --max-time 120 bound the worst case so a stuck download cannot hang the build forever

All flags are present in every modern curl, including the curl.exe shipped via the Windows curl installer.

Notes

  • No behaviour change on the happy path.
  • Failing builds now report the actual HTTP status (e.g. `curl: (22) The requested URL returned error: 502 Bad Gateway`) instead of a confusing zip-format panic from later in the build script.
  • The `download_file_reqwest` path (under the `reqwest` feature) is left unchanged here — adding retries there would mean either a manual loop or a `reqwest-retry` dep, which felt outside the scope of "fix the silent-failure mode in the default code path." Happy to follow up if you would like that too.

…lures

The build script downloads the Swagger UI archive at compile time using
`curl -sSL -o file URL`. Without `--fail`, curl exits 0 on HTTP 4xx/5xx
and writes the error response body to the output path. The build then
proceeds to `ZipArchive::new`, which panics with the cryptic message
"Could not find EOCD" — leaving the user to figure out that the real
problem was a transient CDN error, not a malformed local archive.

This has been observed in CI when the GitHub Releases CDN serves a
sustained 5xx for the swagger-ui release tarball. Add:

  --fail / --show-error      surface HTTP errors with a clear message
  --retry 5 --retry-delay 2  ride out transient 5xx and connection
                              errors
  --connect-timeout 10
  --max-time 120             bound a stuck download so it can't hang
                              the build indefinitely

The flags used are supported on every curl release in current LTS
distros and on the curl.exe shipped via the Windows curl installer.

Signed-off-by: Dmitry Tokarev <dtokarev@nvidia.com>
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.

1 participant