Convert an envelope to the old four-field shape

Deprecated. Scheduled for removal in 0.3.0.

Translates an envelope() into the four-field shape a hand-rolled HTTP layer commonly returns:

list(ok = TRUE, status = 200L, data = <parsed>, error = NULL)

detail is carried through as a fifth field, because call sites that log it would otherwise break on adoption.

Usage

as_legacy_envelope(res)

Arguments

res

An envelope from perform() or one of the convenience wrappers.

Value

A list with ok, status (the HTTP code), data, error, and detail.

Why this is deprecated on arrival

The old shape cannot express two things the new one can. It has no way to say "skipped because the host's breaker was open" as distinct from "failed", and it collapses the user-facing sentence and the log detail into one field. Both are load-bearing, and neither can be reconstructed once a call site is written against the old shape.

Note the collision in the word status: here it is the HTTP code, an integer, and in an envelope() it is the enum. That is exactly the ambiguity the new contract removes.

Removal

Scheduled for removal in 0.3.0. Use it to land a migration with a reviewable diff, then delete the call sites and delete this.

Warns once per session, not once per call, so a migration loop stays readable.

Examples

old <- as_legacy_envelope(status_ok(data = list(n = 1), source = "MyGene"))
#> Warning: as_legacy_envelope() is deprecated and will be removed in biohttp 0.3.0. Branch on res$status instead; see vignette("biohttp").
old$ok
#> [1] TRUE
old$status
#> [1] 200