search

oxidecomputer / omicron

Omicron: Oxide control plane
Mozilla Public License 2.0
252 stars 40 forks source link

`source_error` should not be empty in the API spec #1746

Open zephraph opened 2 years ago

zephraph commented 2 years ago

The source_error type returned from SagaErrorInfo is an empty object in the openapi spec. I ran across this while working on the TypeScript generator. I haven't dug into why it's this way yet, but we should fix it.

https://github.com/oxidecomputer/omicron/blob/508906b5465aeb4a5e8dce4406fab0f708dbbd89/openapi/nexus.json#L10292

davepacheco commented 2 years ago

This endpoint is a pretty low-level one that exposes exactly what the underlying saga produced. Steno does not enforce any constraints on a saga's error type other than that it be serializeable. We could require JsonSchema and put something here...but the other piece is that this endpoint maybe shouldn't be in the spec at all. It's not intended to be used by the console or any other stable API. It's in the bucket of "things developers, support, and maybe sophisticated operators might want to inspect when something has gone badly". We had a discussion about what to do with these APIs but I don't remember where we landed?

We probably do want to make a first-class interface for viewing and managing sagas (e.g., list running sagas, list ones needing attention, pause a saga, abort a saga, abandon a saga). I'd expect it to be pretty niche -- only used after hitting a bug -- but still important.

We probably also want a first-class interface for better dealing with "create" operations that create sagas. RFD 4 talks about this.

david-crespo commented 2 years ago

Yep, I vote for solving this by taking the endpoint out of the spec.