Open sbosnick opened 4 years ago
The latest commits (specifically https://github.com/hyperium/http/pull/419/commits/6364f795fb860e959d7133688f2e797be148ae57) make an opinionated change to marking from_maybe_shared_unchecked
as an unsafe
function. Specifically it removes the unsafe
from the function definition.
As described in more detail in in the commit message for https://github.com/hyperium/http/pull/419/commits/6364f795fb860e959d7133688f2e797be148ae57, this is both sound and is not a breaking change.
This change is taking the design view that unsafe
function in the public API should be restricted to functions where the caller bears responsibility for preventing undefined behaviour and not as a general means of indicating caller responsibility for ensuring that API constraints unrelated to undefined behaviour are met.
I am making this change to have a concrete proposal for consideration. If there are reasons to prefer the other approach to unsafe
functions in the public API then I can change this back and explain the constraints (and their relationship to avoiding undefined behaviour) through comments.
Reorganized the
Debug
impl forHeaderValue
to make the invariants that its use ofunsafe
rely upon for soundness more obvious. This also adds a few more test cases for edges cases of theDebug
impl. This also adds comments to all of the uses ofunsafe
in header/value.rs to explain and document their soundness.One of the uses of
unsafe
in this file is in the functionfrom_maybe_shared_unchecked()
which is part of the public API of this crate. Currently this function is anunsafe
function, but ifunsafe
functions are intended to signify caller responsibility for preventing undefined behaviour then this function is safe. There are no parameters you can pass tofrom_maybe_shared_unchecked()
that will cause undefined behaviour.There are, however, parameters you can pass to
from_maybe_shared_unchecked()
that would create aHeaderValue
that did not comply with RFC 7230 (section 3.2). That is, aHeaderValue
that contained (for example) a NUL byte (0x00). Ifunsafe
functions are intended to signify caller responsibility for maintaining some precondition (not just avoiding undefined behaviour) then it may make sense to keepfrom_maybe_shared_unchecked()
as anunsafe
function.Removing
unsafe
fromfrom_maybe_shared_unchecked()
is an API change but it does not appear to be a breaking change.Before this is merged we have to make a decision on the approach to
unsafe
functions to use and ~may~ make further changes tofrom_maybe_shared_unchecked()
(I can at least improve the doc comments if theunsafe
should remain).This is part of #412.