oxidecomputer / oxidecomputer/dropshot-api-manager

Clarify when `operation_id` is required, or always require it

Open
#47 2 comments 1 reaction 0 assignees View on GitHub

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:

  1. Change the code
  2. Run check
  3. Think about what check is telling you the schema mismatch consists in
  4. Only run generate once 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:

  1. Change the code
  2. Generate the schema. (If it fails, fix the code.)
  3. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.