golang
crypto/rand: Documentation for errors
The 3 exported funcs Int, Prime, Read return an error, but the current documentation doesn't say why and when errors might occur. Also their is no guidance about how to deal with a non-nil error: would a caller-side retry policy make sense?
I suggest we write a short explanation about why errors are part of the API at all, what such errors would look like, and how to deal with them.
Prime does mention that its errors comes from rand.Read.
It may be confusing to figure out if we're likely to have errors "because CSPRNGs inherently use system calls that may fail", or "because we're accepting any custom io.Reader in Int and Prime", or if "Reader cannot return errors, but we still want to stick to the io.Reader interface".
would a caller-side retry policy make sense?
In general, there is no safe non-nil error result from rand.Reader or rand.Read.
I would be in favour of having crypto/rand.[Reader.]Read never return an error, and completely fill the provided slice. (And have it panic if the underlying system call errors.)
Change https://go.dev/cl/602497 mentions this issue: crypto/rand: crash program if Read would return an error
