synackd / ochami / 41886189620

93%

Build Type

push

github

Committed by web-flow

Commit Message

docs!: document patch flag limits, rename rfc7386 (#240)

* docs(client): note keyval patch encoding limits

NewKeyValPatchData picks the patch encoding from whether add or remove
items are present, and set and unset behave differently in the two
encodings. Nothing in its doc comment says so, so a caller can't tell
that adding an array operation makes a previously valid set or unset
fail.

Describe both behaviors, including that a null value is stored by an
RFC 6902 patch rather than deleting the key. State why the function
doesn't reconcile them: doing so needs the current document, which it
has no way to read.

Signed-off-by: Devon Bautista <17506592+synackd@users.noreply.github.com>

* docs(man): describe strict --set/--unset handling

ochami-boot(1) and ochami-metadata(1) say --set creates a key that
doesn't exist, without saying that passing --add or --remove turns the
whole command into an RFC 6902 JSON Patch. That encoding rejects a set
whose parent key is missing and an unset whose key is missing, so
commands that follow the man page can fail with a 422 from the service.

Explain in each patch section which encoding is sent, that an RFC 6902
patch applies as a whole, and that empty fields count as missing
because the services omit them from the stored spec. Otherwise, an
unset of an empty field that works alone would look like a service bug
once --add is added.

Give the restrictions on --set and --unset their own paragraphs, and
state the merge patch behavior they differ from: missing parent keys
are created and absent keys are ignored. Point to --unset for removing
a key, since --set with a null value keeps a map key under RFC 6902
where a merge patch deletes it.

Signed-off-by: Devon Bautista <17506592+synackd@users.noreply.github.com>

* docs(cmd): warn of strict --set/--unset handling

The patch commands' help describes the key/value flags as one method,
but passing --add or --remove changes how --set and --unset are sent
and when the ser... (continued)

Coverage Stats

57 of 57 new or added lines in 8 files covered. (100.0%)

248 existing lines in 28 files now uncovered.

13626 of 14624 relevant lines covered (93.18%)

762.16 hits per line