oxidecomputer / oxidecomputer/omicron
openapi-manager is confused when a lockstep API has a version change
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 572
- Forks
- 97
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 96
Description
Currently we bump the Nexus external OpenAPI version with each release (as seen in #7870).
When running cargo xtask openapi generate after bumping the version in the openapi-manager crate we end up in a bizarre state:
Generating OpenAPI documents from API definitions ...
Loading local OpenAPI documents from "/home/iliana/git/worktree/tuf-repo-depot/openapi" ...
Loading blessed OpenAPI documents from git revision "origin/main" path "openapi"
-------
Updating 14 OpenAPI documents...
Unchanged bootstrap-agent (lockstep v0.0.1): Bootstrap Agent API
Unchanged clickhouse-admin-keeper (lockstep v0.0.1): ClickHouse Cluster Admin Keeper API
Unchanged clickhouse-admin-server (lockstep v0.0.1): ClickHouse Cluster Admin Server API
Unchanged clickhouse-admin-single (lockstep v0.0.1): ClickHouse Single-Node Admin Server API
Unchanged cockroach-admin (lockstep v0.0.1): CockroachDB Cluster Admin API
Unchanged dns-server (versioned v1.0.0 (blessed)): Internal DNS
Unchanged dns-server "latest" symlink
Unchanged gateway (lockstep v0.0.1): Oxide Management Gateway Service API
Unchanged installinator (lockstep v0.0.1): Installinator API
Stale nexus (lockstep v20250409.0.0): Oxide Region API
Fixed updated /home/iliana/git/worktree/tuf-repo-depot/openapi/nexus.json: Updated
Unchanged nexus-internal (lockstep v0.0.1): Nexus internal API
Unchanged oximeter (lockstep v0.0.1): Oxide Oximeter API
Unchanged repo-depot (lockstep v0.0.1): Oxide TUF Repo Depot API
Unchanged sled-agent (lockstep v0.0.1): Oxide Sled Agent API
Unchanged wicketd (lockstep v0.0.1): Oxide Technician Port Control Service
Fixed removed /home/iliana/git/worktree/tuf-repo-depot/openapi/nexus.json
Loading local OpenAPI documents from "/home/iliana/git/worktree/tuf-repo-depot/openapi" ...
Rechecking all local files
found unexpected problem with API nexus version 20250409.0.0 (this is a bug)
problem: No local OpenAPI document was found for this lockstep API. This is only expected if you're adding a new lockstep API. This tool can
generate the file for you.
fix: will rewrite lockstep file nexus.json from generated
failure: ERROR: found problems after successfully fixing everything (this is a BUG!)
The ultimate result of this is that nexus.json is deleted. A workaround for this bug is to simply run the generate command again, as it will then regenerate nexus.json from scratch.
Output of cargo xtask openapi check in the original state:
Generating OpenAPI documents from API definitions ...
Loading local OpenAPI documents from "/home/iliana/git/worktree/tuf-repo-depot/openapi" ...
Loading blessed OpenAPI documents from git revision "origin/main" path "openapi"
-------
Checking 14 OpenAPI documents...
Fresh bootstrap-agent (lockstep v0.0.1): Bootstrap Agent API
Fresh clickhouse-admin-keeper (lockstep v0.0.1): ClickHouse Cluster Admin Keeper API
Fresh clickhouse-admin-server (lockstep v0.0.1): ClickHouse Cluster Admin Server API
Fresh clickhouse-admin-single (lockstep v0.0.1): ClickHouse Single-Node Admin Server API
Fresh cockroach-admin (lockstep v0.0.1): CockroachDB Cluster Admin API
Fresh dns-server (versioned v1.0.0 (blessed)): Internal DNS
Fresh dns-server "latest" symlink
Fresh gateway (lockstep v0.0.1): Oxide Management Gateway Service API
Fresh installinator (lockstep v0.0.1): Installinator API
Stale nexus (lockstep v20250409.0.0): Oxide Region API
problem: No local OpenAPI document was found for this lockstep API. This is only expected if you're adding a new lockstep API. This tool can
generate the file for you.
fix: will rewrite lockstep file nexus.json from generated
Fresh nexus-internal (lockstep v0.0.1): Nexus internal API
Fresh oximeter (lockstep v0.0.1): Oxide Oximeter API
Fresh repo-depot (lockstep v0.0.1): Oxide TUF Repo Depot API
Fresh sled-agent (lockstep v0.0.1): Oxide Sled Agent API
Fresh wicketd (lockstep v0.0.1): Oxide Technician Port Control Service
Other problems not associated with a specific supported API version:
problem: A local OpenAPI document was found that does not correspond to a supported version of this API: nexus.json. This is unusual, but it could
happen if you're either retiring an older version of this API or if you created this version in this branch and later merged with upstream
and had to change your local version number. In either case, this tool can remove the unused file for you.
fix: will delete file: nexus.json
Note API nexus version 20250212.0.0: formerly blessed version has been removed. This version will no longer be supported! This will break upgrade
from software that still uses this version. If this is unexpected, check the list of supported versions in Rust for a possible mismerge.
-------
Stale 14 documents checked: 14 fresh, 1 stale, 0 failed, 1 other problem
(run cargo xtask openapi generate to update)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the cargo xtask openapi generate and cargo xtask openapi check entry points, then inspect the openapi-manager crate and the openapi/nexus.json handling described in the report. Reproduce the version bump scenario and verify that generation does not delete the local document and that a subsequent check reports the API as fresh.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- api
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100