Track CBOR wire format support (KEP-4222)

[doxxx93]

Would you like to work on this feature?

maybe

What problem are you trying to solve?

The Kubernetes API server is adding CBOR (RFC 8949) as an alternative wire format via KEP-4222, gated behind CBORServingAndStorage (alpha in v1.32).

client-go is tracking this with ClientsAllowCBOR (v1.32 alpha) and ClientsPreferCBOR (v1.33 beta).

Opening this to track upstream progress and discuss if/when kube-rs should support it.

Describe the solution you'd like

An optional feature flag on kube-client that enables CBOR content negotiation.

Since k8s-openapi types already have serde impls, a serde-compatible CBOR crate (e.g. ciborium, cbor4ii) should integrate without type changes.

Relevant content types:

• application/cbor (request/response)
• application/cbor-seq (watch streams, RFC 8742)
• application/apply-patch+cbor (SSA)

Describe alternatives you've considered

Continue with JSON only, or wait for Protobuf (#725). CBOR is complementary to both — simpler to integrate than Protobuf and more efficient than JSON.

Documentation, Adoption, Migration Strategy

• KEP-4222: CBOR Serializer kubernetes/enhancements#4222
• RFC 8949: https://www.rfc-editor.org/rfc/rfc8949.html
• RFC 8742: https://datatracker.ietf.org/doc/rfc8742/

Target crate for feature

kube-client, kube-core

[clux]

I like the idea of this.

The protobuf epic is struggling a bit because it's a different generation setup and probably necessitates a kind of big breaking change. On the other hand, CBOR could theoretically give us a subset of the same benefit in a much easier to adopt manner.

In theory anyway. It'll probably come down to the practice.

Crates

Did a quick check on the crates. Some quick notes on the potentially usable ones;

ciborium / docs

very small. no examples. short history. most adopted. There's basically only one fn on deser side; from_reader_with_buffer and one on the ser side into_writer. Which.. feels restrictive?

cbor4ii / docs

small. some benchmarks. also no examples. seems to be preparing for a 2.0. least adopted.

minicbor / docs

examples. separate minicbor-serde layer (also with docs). looks nice, but mostly by one guy. dtolnay has helped though. fast growing, but less adoption that ciborium, and big version spread in download graph (presumably since 2.0.0 is only 8mo old).

EDIT: licensing issues, see comment below.

Other thoughts

Any of these 3 could work, and there's clearly enough pull in the ecosystem that if one of these fail, we could probably switch to another, so maybe adopting one of them isn't too bad. I like the look of minicbor the most so far.

Interestingly, this format has a long history and there's two older crates attempting this, the serde cbor crate (archived with a scary warning) and BurntSushi's even older crate linking back to the now archived one.

[imp]

Are there any licensing considerations? I never heard of minicbor Blue Oak Model License Version 1.0.0 - is it compatible with the rest of the kube code base?

[clux]

Ah, yes good shout. We are beholden to CNCF's third-party-license-policy and enforced by cargo-deny.

Blue Oak probably needs an exception if we were to use it. Possibly difficult. IANAL, but it reads weirdly to me, and their license-faq positions themselves more as a "possibly GPL compatible" license, which is normally not allowed.

[doxxx93]

Some additional findings on ciborium vs cbor4ii from a kube-rs integration angle:

serde correctness

ciborium has some long-standing serde bugs that could bite us with K8s types — Option<()> roundtrip, nested Options, and #[serde(flatten)] with integer keys are all broken with open issues for 1-2 years.

cbor4ii avoids the Option issues by encoding unit types as empty arrays instead of null.

Watch streams (application/cbor-seq)

Probably the trickiest part of this. ciborium can't distinguish EOF from parse errors in its decoder, making CBOR sequence decoding fragile. cbor4ii's SliceReader can be checked for exhaustion between items.

Neither crate has async support, so we'd likely buffer complete CBOR items from the async byte stream then pass to synchronous from_slice — cbor4ii has from_slice with zero-copy, ciborium doesn't.

Tradeoffs

cbor4ii's main risk is single maintainer (quininer), but the codebase is small, MIT licensed, and actively maintained. Performance-wise, cbor4ii appears significantly faster based on rust_serialization_benchmark, though worth verifying with K8s-shaped payloads.

Based on this, leaning toward cbor4ii. Thoughts?