oxidecomputer / oxidecomputer/omicron

Tell clients the current API version so they can tell if they're out of date

Open
#10,493 10 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
572
Forks
97
Avg merge
2d 12h
Merged PRs (30d)
96

Description

Pulled out of #9425. The simplest way I can think of for this to work would be to include the current API version in a response header for all requests, and the console can figure out what to do with that. You could also imagine the CLI using this to print a warning to stderr or something.

The motivating scenario is:

  1. User loads the web console, then goes and takes a nap.
  2. A system update happens. The API version no longer matches what their loaded console expects. Nexus has a new copy of the console on hand but the user has not requested it yet.
  3. The user wakes up and comes back and navigates somewhere in their existing console session, e.g., by clicking a link.

Console navigations happen client-side — they do not refresh the page. Assuming their session is still valid (idle timeout is 8 hours) a few things could happen here:

  • The navigation could trigger the background fetch of a JS file the user does not have cached, and this file is no longer on Nexus because the console files have changed. The background fetch 404s, which I think bubbles up to a page-level Something Went Wrong. The user refreshes and gets the latest console.
    • It's possible that this fetch does not 404, because there can overlap in the list of JS chunks between releases, though this basically never happens. But if it does, we fall through to the next possibility.
  • The JS loads fine and an API request goes through that has removed a field the console relies on, so the console blows up with Something Went Wrong. The user refreshes and gets the latest console.
    • This should be extremely unlikely because of the API version translation machinery — the API knows how to receive old request and how to respond with a shape the old client can handle.
    • New fields shouldn't be a problem, they will just be ignored.
  • Everything works fine, they're just missing new stuff

After writing this all up, it seems to me the most likely failure case by far is actually the first one, which would not be helped by adding the API version to a response header unless the console is polling something in the background or using refetchOnWindowFocus: true (we have it off currently). That would mean that whatever "hey bud refresh the console" warning we set up would appear before the user chooses to do the nav that sets off the series of potential catastrophes outlined above.

Contributor guide

Open the contributing guide

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

The issue names no implementation files or tests. Start by tracing the existing API version translation machinery and the response paths used by the web console and CLI, then clarify the intended version signal and warning behavior. Done should be an agreed approach that lets clients detect when their API version is out of date.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.