Rust equivalent for apimachinery's meta/v1.Duration

[hawkw]

Would you like to work on this feature?

yes

What problem are you trying to solve?

Some objects contain strings which represent durations. These strings are often parsed in the format implemented by the Go standard library's time.Duration type. For example, kubernetes-sigs/gateway-api#1997 adds duration fields to the Gateway API's HTTPRoute type, and explicitly specifies that they are formatted according to the Go time.Duration format:

// Timeout values are formatted like 1h/1m/1s/1ms as parsed by Golang time.ParseDuration
// and MUST BE >= 1ms or 0 to disable (no timeout).

(ref: https://github.com/kubernetes-sigs/gateway-api/blob/659d478ec039271a95429b133a999d1593808e96/geps/gep-1742.md?plain=1#L336-L337)

Describe the solution you'd like

In the Go apimachinery's meta package, there is a v1.Duration struct for representing durations, whose JSON representation is a string in the Go time.ParseDuration/time.Duration format: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration.
That type is used in the Go bindings for Kubernetes objects that include durations in this format, such as in the Gateway API proposal I mentioned above:

       // +kubebuilder:validation:Format=duration
       Request *metav1.Duration `json:"request,omitempty"`

(ref: https://github.com/kubernetes-sigs/gateway-api/blob/659d478ec039271a95429b133a999d1593808e96/geps/gep-1742.md?plain=1#L353-L354)

It would be nice if there was a similar type in the kube ecosystem.

Such a type should implement serde::Serialize/serde::Deserialize to and from JSON strings in the same format as Go's time.Duration. Since Go time.Durations are signed, and Rust's std::time::Durations are unsigned, the new type should also track whether the duration is positive or negative. Conversions to and from std::time::Duration should also be provided. Finally, we should be sure to check our implementation against the cases that the Go library tests to ensure that the same strings parse to equivalent duration values.

Describe alternatives you've considered

This doesn't technically need to be implemented in kube-core. We could say that users should represent duration fields as Strings, and user code should be responsible for parsing them. However, in my opinion, it's preferable to provide it in kube-core, because there is an equivalent in the Go apimachinery.

Also, if we don't provide a nice way to parse these duration types, folks may take the easy way out and use other Rust libraries for parsing durations, such as humantime. These crates implement a format that is similar to, but not identical to the Go standard library's format, leading to potential issues when the format is accepted by Go but rejected by Rust.

Documentation, Adoption, Migration Strategy

No response

Target crate for feature

kube-core

[hawkw]

I've already written an implementation of this for my own code, and I'm happy to open a PR upstreaming it to kube-core --- I wanted to make sure there was an open issue describing why this is desirable first, though.

[clux]

Thanks for writing this up. Agree with the reasoning and that we need to stay upstream with the Go format.
Would definitely be a good thing to have in kube-core, and am happy to look at a PR!

The format looks like a dict in their tests and while it could potentially be hackable through some complicated chrono+serde_with usage, I would be happier hiding this inside the de/serializer for the type so users always get the right thing.

Interestingly, the struct is not in present at all in k8s-openapi: Arnavion/k8s-openapi#141, but the type does generate from protobufs in k8s-pb (old version, but something has to handle casttype=time.Duration ultimately).