oxidecomputer / oxidecomputer/dropshot-api-manager
Clarify when `operation_id` is required, or always require it
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 5
- Forks
- 3
- Avg merge
- 8h 49m
- Merged PRs (30d)
- 2
Description
Issue distilled from Matrix chat starting here.
In the external API in omicron, most endpoints with two versions present include an operation_id that allows the tooling to associate the two versions as versions of the same thing. instance_ephemeral_ip_detach does not, though, and it didn't seem to be a problem.
After some discussion, it sounds like this works because the old version's schema is already blessed, so that schema doesn't get regenerated (if it did, it would have the v12341234_ prefix in the operation ID). The apparent addition of a new endpoint is fine because the user ran generate to tell the tooling that it's fine.
I find it pretty confusing that this is fine. Looking at the endpoints file, you'd reasonably conclude that operation_id is required on these old versioned functions. If it's not required or only required sometimes, I'd rather we only do it when it's required, but I think it would be better to find a way to make it required.
This is related to a broader worry I have that the tooling seems to demand this workflow:
- Change the code
- Run
check - Think about what
checkis telling you the schema mismatch consists in - Only run
generateonce you agree, on reflection, that the expected changes are what you want
Historically, this is not how we have used the schema generator. What we have done is:
- Change the code
- Generate the schema. (If it fails, fix the code.)
- Make sure the schema looks right
So if the other workflow is now what's expected, that's a new muscle we need to try to build. My sense was that that is not really the intention with the new tooling, and what we really want is for generate to just do the right thing virtually all the time but error out when the situation requires disambiguation.
Contributor guide
No contributing guide indexed for this repository
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 versioned endpoint definitions in nexus/external-api/src/lib.rs, especially instance_ephemeral_ip_detach, and trace how the schema tooling handles operation_id during check and generate. Compare the documented behavior with the existing workflow; done means the requirement or omission rule and the expected schema-generation workflow are unambiguous.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- api, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100