openapi manager should support multiple documents for versioned APIs #7564
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
sunshowers
reviewed
Feb 25, 2025
Comment on lines
+199
to
+201
| * If there is a blessed file for that version, then the version is blessed. The generated file must exactly match the blessed one. If not, the tool cannot fix this. You have to undo whatever changes you made that affected the blessed version. (See above on how to make changes to the API trait without affecting older versions.) | ||
| * If there is no blessed file for that version, then the version is locally-added. There should be exactly one local file for it and it should exactly match the generated file. The tool can fix any problems here by removing all local files and generating a new one based on the generated one. | ||
| * The tool also ensures that a "latest" symlink exists and points to the highest-numbered OpenAPI document. |
There was a problem hiding this comment.
Thoughts on putting a Mermaid flowchart here?
There was a problem hiding this comment.
I took a swing at adding one in 62a416d. Let me know what you think.
|
|
||
| for api in apis.iter_apis() { | ||
| if api.is_lockstep() { | ||
| for version in api.iter_versions_semver() { |
There was a problem hiding this comment.
There's just one version here, right?
There was a problem hiding this comment.
We have the exactly-once iterator now, would it make sense to use it here?
sunshowers
reviewed
Feb 26, 2025
|
Yeah, some local experimentation shows this is really fantastic. All the important error cases are taken care of -- this is so great and I'm excited we're going to get this into the hands of folks. With my comments above this is good to go. |
Final manual testingTesting from: Fresh clone: Basic lockstep workflow (file missing, file stale, file up-to-date): Basic versioned workflow (add version, make change; file missing, file stale, file up-to-date) Error case: cannot change a blessed version |
Final manual testing (continued)Retiring an old supported version: From the same state as above, removing INITIAL: Error case: remove local document for a blessed version that hasn't been retired: Error cases: hash mismatch, corrupt document for a blessed version. It's a little tricky to corrupt the file in a way that really exercises something interesting. If you just change its contents, you get a hash mismatch: So I renamed the file with the right hash and tried again: |
Final manual testing (continued)Warning (not error) for unexpected files: Error for files that look more like mistakes: Error case: parse error: Error case: invalid OpenAPI: Error case: Oxide-specific OpenAPI lint: Error: stale or missing "extra" file (nexus_tags.txt): Stale: |
Final manual testing (continued)Missing symlink: Error case: hand-crafted bogus symlink: |
Final manual testing (continued)Lastly I tested every possible merge problem I could think of. It's a little harder to show the transcript. First, I created a I created branches:
Then I created In a successful merge, the only expected steps are:
I also tested a bunch of cases where I intentionally botched the Merging with v3 (older version than mine)
Merging with v4 (same version as mine)I skipped several error cases that were identical to the ones covered above.
Merging with v5 (newer version than mine)I skipped several error cases that were identical to the ones covered above.
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Goal: update the openapi-manager (
cargo xtask openapi) to support multiple versions of OpenAPI documents. This is aimed at supporting client-side and server-side-only versioning as described in RFD 432 ("Versioning for internal HTTP APIs"). Critically, we want this workflow to be as simple as possible and as close as possible to the existing one for non-versioned APIs. And it should be really hard to accidentally mess things up (e.g., break compatibility with an older version that's supposed to be supported).Status: I think this is basically ready for review. There's still some work left (see below) but I don't expect it to change the shape of this all that much and it'd be nice to parallelize here.
This change includes:
I realize this is a big change. (At least it's mostly new code?) But I didn't see a way to break it up well. If there's anything I can do to help review (e.g., video chat walkthrough), let me know. I'd suggest looking at stuff in this order:
dns-server-api/ clients/dns-service-client`: shows what the changes to a versioned API look likeIf you want to see this in action: I demo'd this at last Friday's demo day. It's somewhat anti-climactic because the workflow is almost the same for versioned APIs as it was for APIs before (those are now called lockstep APIs). If you want to see exactly what's changed, check out the
dns-server-api/clients/dns-service-clientchanges. This is also described in the README.Work I plan to do before landing this (but don't want to block review on):
XXX-dap-last-step: these are all basically the same thing. To reduce the risk of mismerge with other changes to src/spec.rs upstream, I have kept the API definitions in src/spec.rs in roughly the same format as they were before. But before I land this, I intend to replace all those with literal definitions ofManagedApiConfiginstead and rip outsrc/spec.rsaltogether.Work to do after landing this: