[29/n] [wicketd] add the commission API, client, and OpenAPI document#10857

Open

sunshowers wants to merge 28 commits into

mainfrom

sunshowers/spr/draft-11n-wicketd-add-the-commission-api-client-and-openapi-document

sunshowers commented Jul 17, 2026 •

edited

Loading

Contributor

This change implements v1 of the wicketd commission API, as described in RFD 710.

This is a pretty large change, so here's a short orientation and review guide.

What this PR is not

This PR does not change existing functionality. It is completely additive -- any behavior changes were made in prior commits in the stack.
This PR does not introduce a new security boundary. The way to access the commissioning API is exactly the same as the existing wicketd API.
This PR does not represent a customer commitment. The commissioning API is purely for rkdeploy. The extent to which we want to provide access to this API to customers will be determined in the future.

Review guide

The API surface matches what rkdeploy needs almost 1:1. I've paid attention to the type design and ensuring that any partial errors are properly reported to clients (something that was a bit lacking in the unstable API).

I would spend the most time looking at:

The API and type design -- I hope it is all generally self-explanatory.
The implementation in wicketd/src/commission/conversions.rs -- in particular, with extensive use of destructuring.
Wiring into existing code.
The tests.

Part of the review is going to be integrating with rkdeploy -- @JustinAzoff is taking care of this.

Note that while this API is server-side versioned, changing it does carry a substantial cost because such a change has to be coordinated with rkdeploy. So it's worth getting it right.

Depends on:

TODO:

test with rkdeploy on a racklette

sunshowers added 2 commits

July 17, 2026 11:39


          [spr] initial version

ca81f6f

Created using spr 1.3.6-beta.1


          [spr] changes to main this commit is based on

c9e80d9

Created using spr 1.3.6-beta.1

[skip ci]

JustinAzoff reviewed

View reviewed changes

wicketd-commission-types/versions/src/initial/update.rs Outdated

sunshowers changed the title ~~[draft] [11/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [12/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers changed the title ~~[draft] [12/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [13/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers changed the title ~~[draft] [13/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [14/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers mentioned this pull request

[15/n] [update-engine] use oxide-update-engine from crates.io, delete the vendored copy #10868

Merged

1 task

sunshowers added 2 commits

July 20, 2026 13:44


          a bunch of updates

ed5bbcf

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

48679e0

Created using spr 1.3.6-beta.1

[skip ci]

sunshowers changed the title ~~[draft] [14/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [15/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers changed the title ~~[draft] [15/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [16/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers added 2 commits

July 20, 2026 17:05


          rebase

081b310

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

06703f2

Created using spr 1.3.6-beta.1

[skip ci]

sunshowers changed the title ~~[draft] [16/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [17/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers added 2 commits

July 20, 2026 19:59


          more updates

7fcfa59

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

40dfffb

Created using spr 1.3.6-beta.1

[skip ci]

sunshowers changed the title ~~[draft] [17/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [18/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers changed the title ~~[draft] [18/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [19/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers mentioned this pull request

[19/n] [wicketd] add the commission API, client, and OpenAPI document #10879

Closed

1 task

sunshowers added 2 commits

July 21, 2026 10:24


          rebase

9b48da1

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

15a8287

Created using spr 1.3.6-beta.1

[skip ci]

sunshowers changed the title ~~[draft] [19/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [20/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers mentioned this pull request

[20/n] [wicketd] make GetInventoryError::InvalidSpIdentifier carry the id #10885

Merged

sunshowers changed the title ~~[draft] [20/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [21/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers added 3 commits

July 21, 2026 13:48


          rebase, transceiver stuff

f24509c

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

747bcc8

Created using spr 1.3.6-beta.1

[skip ci]


          rustfmt

fe7c221

Created using spr 1.3.6-beta.1

sunshowers added a commit that referenced this pull request


          [15/n] [update-engine] use oxide-update-engine from crates.io, delete…

4e690b1

… the vendored copy (#10868)

I moved these crates to crates.io a while ago, and they have a few
important bugfixes and features that smoothen the process of integrating
#10857.

There aren't any wire protocol changes, so this can be landed without
breaking rkdeploy.

This was referenced Jul 21, 2026

[21/n] [wicketd] compute transceiver staleness at read time, per switch #10888

Merged

[22/n] [wicket-common] move bgp auth key set types to wicketd-commission-types #10890

Merged

sunshowers changed the title ~~[draft] [21/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [xx/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers added a commit that referenced this pull request


          [20/n] [wicketd] make GetInventoryError::InvalidSpIdentifier carry th…

3b28548

…e id (#10885)

Identified during #10857 review.

Also map it to a 400 (client-side error) rather than a 503 (server-side
error).

sunshowers added 2 commits

July 22, 2026 21:26


          lots more updates

a516281

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

0b0907d

Created using spr 1.3.6-beta.1

[skip ci]

sunshowers added a commit that referenced this pull request


          [21/n] [wicketd] compute transceiver staleness at read time, per swit…

6fc9c0a

…ch (#10888)

Found while reviewing
#10857.

Currently, for transceivers:

1. There's a single `last_seen` across both switches.
2. The `last_seen` is snapshotted at update time, which means that it
would only measure how long the update was in the mpsc channel for.

Both of these seem incorrect, and in particular the second one would
show up as wicket always reporting <1s.

<img width="1584" height="332" alt="image"
src="https://github.com/user-attachments/assets/c203a9f6-5760-4ec0-a146-e33e550a048a"
/>

Fix both these issues.

To maintain the same wire shape, for point 1 we pick `max`. (The
commissioning API will publish per-switch last seen values.) For point 2
there will be a behavior change visible in wicket, but that seems
correct.

sunshowers added 6 commits

July 23, 2026 11:39


          more fixes

1aeab59

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

538d2ab

Created using spr 1.3.6-beta.1

[skip ci]


          more fixes

b23fe78

Created using spr 1.3.6-beta.1


          rustfmt

65e92d6

Created using spr 1.3.6-beta.1


          a few more fixes

3c0c201

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

ff4ec90

Created using spr 1.3.6-beta.1

[skip ci]

sunshowers changed the title ~~[draft] [xx/n] [wicketd] add the commission API, client, and OpenAPI document~~ [28/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers marked this pull request as ready for review

July 23, 2026 20:06

sunshowers requested review from JustinAzoff and andrewjstone

July 23, 2026 20:06


          openapi

9c94c5f

Created using spr 1.3.6-beta.1

andrewjstone reviewed

View reviewed changes

andrewjstone left a comment

Contributor

@sunshowers this looks great so far. I did a preliminary review. I mostly skipped conversions.rs and I still need to look at the integration tests and the http handler and progress files.

wicketd-commission-api/src/lib.rs Outdated

wicketd-commission-api/src/lib.rs

wicketd-commission-api/src/lib.rs Outdated

wicketd-commission-types/versions/src/initial/inventory.rs Outdated

wicketd-commission-types/versions/src/initial/inventory.rs Outdated

wicketd-commission-types/versions/src/initial/inventory.rs Outdated

wicketd-commission-types/versions/src/initial/inventory.rs Outdated

wicketd-commission-types/versions/src/initial/inventory.rs Outdated

wicketd-commission-types/versions/src/initial/inventory.rs

wicketd-commission-types/versions/src/initial/rack_setup.rs Outdated

andrewjstone reviewed

View reviewed changes

wicketd/src/commission/http_entrypoints.rs

sunshowers added a commit that referenced this pull request


          [22/n] [wicket-common] move bgp auth key set types to wicketd-commiss…

d1faf20

…ion-types (#10890)

Found while reviewing #10857.

rkdeploy doesn't need these today, but there's a decent likelihood it'll
need them at some point because BGP auth keys are part of RSS.

sunshowers added 3 commits

July 23, 2026 16:17


          start addressing review feedback

78a19a5

Created using spr 1.3.6-beta.1


          [spr] changes introduced through rebase

de2ef61

Created using spr 1.3.6-beta.1

[skip ci]


          accidentally dropped a line

962c5fd

Created using spr 1.3.6-beta.1

andrewjstone approved these changes

View reviewed changes

andrewjstone left a comment

Contributor

Truly amazing work @sunshowers. Thank you so much for getting us out of this jam.

Approved pending resolution of #10857 (comment)

sunshowers changed the base branch from sunshowers/spr/main.draft-11n-wicketd-add-the-commission-api-client-and-openapi-document to main

July 24, 2026 23:31

sunshowers changed the title ~~[28/n] [wicketd] add the commission API, client, and OpenAPI document~~ [29/n] [wicketd] add the commission API, client, and OpenAPI document

sunshowers added 2 commits

July 24, 2026 16:52


          rebase on main, review feedback from andrew and opus

4c7248d

Created using spr 1.3.6-beta.1


          wording tweaks

76020a8

Created using spr 1.3.6-beta.1

sunshowers requested a review from andrewjstone

July 24, 2026 23:58

andrewjstone approved these changes

View reviewed changes

andrewjstone left a comment

Contributor

Changes look good. Thanks again Rain.

wicketd-commission-types/versions/src/impls/inventory.rs Outdated

wicketd-commission-types/versions/src/initial/inventory.rs

+                  ///
+                  /// `None` means wicketd was started without baseboard information, or was
+                  /// given a baseboard it could not identify.
+                  pub sled_baseboard: Option<BaseboardId>,

andrewjstone Jul 25, 2026

Contributor

Luckily, this won't be possible in with #10518, so we can remove the Option then.


          hopefully the final version

5b5abbd

Created using spr 1.3.6-beta.1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet