make the decode / decrypt pipeline non-allocating (groundwork)

[japaric]

this PR lays the groundwork for making the decoding - decryption - decoding pipeline "non-allocating" AKA removing as many allocations as possible

at a very high level that is enabled by these changes

• MessageDeframer::pop performs decoding - decryption in-place and yields borrowed data (slices) to the next layer
• Codec gains a lifetime parameter 'a to allow its read method to return maximally borrowed data (&'a) from Reader<'a> -- this lets the post-decryption decoding to also be non-allocating
• Payload becomes a std::Cow-like enum to support carrying either borrowed or owned data -- HandshakePayload and other types indirectly become Cow-like as well
• State::handle is tweaked to allow its return type hold borrowed data contained in the message parameter

to showcase how this enables the removal of allocations from the pipeline, this PR makes decoding & decryption of application-data as well as certificates (CertificateChain) non-allocating

removing the rest of the allocations that exist in the pipeline will be done in a subsequent PR

breaking changes:

• this change the signature of MessageDecrypter::decrypt. actual implementations don't have to change much, as you can see in the diff, but a breaking change is still a breaking change.

this PR builds on top of #1595

---

I think it's worthwhile to explain why Payload and many of the State implementers need to become Cow-like and cannot contain just references.

In very simplified terms, you can think of the process of advancing Connection's internal state machine as the following function: (this applies to both the buffered Connection and UnbufferedConnection APIs)

struct Connection {
    state: Option<Box<dyn State +'static>>,
    deframer: MessageDeframer,
    // ..
}

// in impl Connection
fn process_tls_records<'a>(&mut self, buffer: &mut DeframerSliceBuffer<'a>) {
    let mut current = self.state.take().unwrap();

    while let Some(message) = deframer.pop(buffer);{
        // message has type BorrowedPlainMessage<'a>
        let next = current.handle(state, message);
        current = next;
    }

    self.state = Some(current.into_owned());
}

each time this function is called, several records are decoded and decrypted from the buffered incoming TLS data (the buffer parameter in the above snippet). as mentioned above, Deframer::pop now yields slices with lifetime 'a. each messages that's fed into the state machine through the State::handle method can change the concrete state type behind the current trait object; each of those intermediate states can hold the 'a borrowed data in message thanks to the State::handle change done in this PR.

eventually, the deframer is exhausted (e.g. the user may need to read data from the socket and append it to buffer) and it's time to return from the function. however, just after exiting the while loop current may contain borrowed 'a content. it's not possible to store that borrowed content in Connection because its state field has a 'static constraint. that's where we are forced to erase the 'a lifetime by switching the true state behind current into its owned variant; this heap allocates any borrowed content. it's worth noting that into_owned it's a no-operation in the case the state type does not contain any borrowed data.

so yes, there's still one potential allocation in this function call but all of the many decoding and decryption events that happen within this function call becoming non-allocating; it also becomes possible to move between states -- within a single function call -- without needing to allocate borrowed content.

[codecov]

Codecov Report

Attention: 73 lines in your changes are missing coverage. Please review.

Comparison is base (962814e) 96.16% compared to head (35e4117) 95.96%.
Report is 6 commits behind head on main.

Files	Patch %	Lines
rustls/src/client/tls12.rs	85.35%	29 Missing ⚠️
rustls/src/server/server_conn.rs	25.00%	9 Missing ⚠️
rustls/src/server/tls13.rs	90.12%	8 Missing ⚠️
rustls/src/msgs/handshake.rs	88.88%	6 Missing ⚠️
rustls/src/crypto/cipher.rs	0.00%	5 Missing ⚠️
rustls/src/client/hs.rs	88.46%	3 Missing ⚠️
rustls/src/client/tls13.rs	97.00%	3 Missing ⚠️
rustls/src/msgs/base.rs	94.64%	3 Missing ⚠️
rustls/src/msgs/deframer.rs	97.93%	3 Missing ⚠️
rustls/src/msgs/message.rs	97.27%	3 Missing ⚠️
... and 1 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1597      +/-   ##
==========================================
- Coverage   96.16%   95.96%   -0.20%     
==========================================
  Files          80       80              
  Lines       17337    18138     +801     
==========================================
+ Hits        16672    17407     +735     
- Misses        665      731      +66     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[japaric]

@cpu @ctz @djc could I get a quick sanity check on the direction here? the main commits that affect the end-user and/or internal interfaces are:

• make Reader work on mutable slices
• make MessageDecrypter::decrypt operate on slices (:warning: this is a semver breaking change)
• make Deframer::pop return a slice (+)
• prepare Codec for non-allocating decoding
• add a Borrowed variant to Payload
• prepare State trait to handle slice fields

TL;DR make things std::Cow-like and add a bunch of lifetimes everywhere

the bulk of commits that will reduce allocations will be fairly mechanical like the 'reduce allocs around ServerCertDetails ' one

thoroughly minimizing the internal API in an incremental fashion is going to take a lot of commits but I'll break out a smaller PR out of this one that only does the interface changes

now, I mainly did this to enable in-place (non-allocating) decoding / decryption in the UnbufferedConnection API but this PR also improves the performance of the existing Connection API.

so far, I have only removed allocations from -- what my uneducated guess of what the biggest contributors are like -- application-data and certificates and I'm seeing improvements of this magnitude (ran these locally; I've filtered out the noisy aws_lc_rs benchmarks)

Scenario	Baseline	Candidate	Diff
handshake_tickets_ring_1.2_rsa_aes_client	4615881	4548840	✅ -67041 (-1.45%)
handshake_session_id_ring_1.2_rsa_aes_server	4327962	4267674	✅ -60288 (-1.39%)
handshake_tickets_ring_1.2_rsa_aes_server	4776473	4715679	✅ -60794 (-1.27%)
handshake_session_id_ring_1.3_ecdsa_chacha_client	41598210	41489715	✅ -108495 (-0.26%)
handshake_tickets_ring_1.3_ecdsa_chacha_client	41796305	41688683	✅ -107622 (-0.26%)
handshake_tickets_ring_1.3_rsa_chacha_client	42040674	41932666	✅ -108008 (-0.26%)
handshake_tickets_ring_1.3_rsa_aes_client	42083707	41975702	✅ -108005 (-0.26%)
handshake_tickets_ring_1.3_ecdsa_aes_client	41837011	41731569	✅ -105442 (-0.25%)
handshake_session_id_ring_1.3_ecdsa_aes_client	41651062	41546453	✅ -104609 (-0.25%)
handshake_session_id_ring_1.3_rsa_aes_client	41899822	41798231	✅ -101591 (-0.24%)
handshake_session_id_ring_1.3_rsa_chacha_client	41845117	41743759	✅ -101358 (-0.24%)

---

(+) I intend to use this RawSlice type in Context to make the UnbufferedConnection truly not-allocating when it comes to decrypting app-data and it'll probably also become instrumental to allowing caller-side certificate verification with the UnbufferedConnection API for future compatibility with async cert verifiers

[cpu]

@cpu @ctz @djc could I get a quick sanity check on the direction here?

ACK'ing this but wanted to mention it might be a little bit. We're focused on 0.22 release prep and Ctz is AFK for a little bit. The high-level vision sounds good to me, but I think input from Djc and Ctz will be most valuable here. My experience in this domain is more limited.

[japaric]

but I'll break out a smaller PR out of this one that only does the interface changes

I, instead, trimmed down this PR and it's ready for review. I have added a high level description of the changes in the PR description. removing the bulk of the allocations will be need in a separate / subsequent PR.

(the MSRV seems to not like the function/struct update syntax used in this PR 😢 )

[ctz]

@rustls-benchmarking bench

[rustls-benchmarking]

Benchmark results

Instruction counts

Significant differences

⚠️ There are significant instruction count differences

Click to expand

Scenario	Baseline	Candidate	Diff	Threshold
handshake_session_id_ring_1.2_rsa_aes_server	4415500	4376696	✅ -38804 (-0.88%)	0.20%
handshake_tickets_ring_1.2_rsa_aes_client	4729758	4689542	✅ -40216 (-0.85%)	0.20%
handshake_tickets_ring_1.2_rsa_aes_server	4855552	4822179	✅ -33373 (-0.69%)	0.20%
handshake_tickets_aws_lc_rs_1.2_rsa_aes_client	4505817	4477243	✅ -28574 (-0.63%)	0.20%
handshake_session_id_aws_lc_rs_1.2_rsa_aes_client	4168044	4148933	✅ -19111 (-0.46%)	0.20%
handshake_session_id_ring_1.2_rsa_aes_client	4441024	4424276	✅ -16748 (-0.38%)	0.20%
handshake_session_id_aws_lc_rs_1.3_rsa_aes_client	31164218	31069947	✅ -94271 (-0.30%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsa_aes_client	30967639	30890647	✅ -76992 (-0.25%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsa_chacha_client	31135139	31058081	✅ -77058 (-0.25%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsa_chacha_client	30959008	30883042	✅ -75966 (-0.25%)	0.20%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha_client	31335208	31260091	✅ -75117 (-0.24%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsa_aes_client	31146513	31074320	✅ -72193 (-0.23%)	0.20%
handshake_tickets_ring_1.3_ecdsa_aes_client	42235925	42149554	✅ -86371 (-0.20%)	0.20%
handshake_tickets_aws_lc_rs_1.3_rsa_aes_client	31353594	31289789	✅ -63805 (-0.20%)	0.20%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha_client	31115445	31052152	✅ -63293 (-0.20%)	0.20%

Other differences

Click to expand

Scenario	Baseline	Candidate	Diff	Threshold
handshake_tickets_aws_lc_rs_1.2_rsa_aes_server	4587695	4609787	22092 (0.48%)	3.23%
handshake_session_id_aws_lc_rs_1.3_rsa_aes_server	33228429	33344572	116143 (0.35%)	0.43%
handshake_session_id_aws_lc_rs_1.2_rsa_aes_server	4106087	4118716	12629 (0.31%)	4.42%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha_server	33597776	33517700	-80076 (-0.24%)	1.16%
handshake_tickets_ring_1.3_ecdsa_chacha_client	42202504	42118487	-84017 (-0.20%)	0.20%
handshake_session_id_ring_1.3_ecdsa_aes_client	42056296	41980012	-76284 (-0.18%)	0.20%
handshake_session_id_ring_1.3_ecdsa_chacha_client	42011736	41941769	-69967 (-0.17%)	0.20%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes_server	12368324	12348462	-19862 (-0.16%)	1.49%
handshake_tickets_ring_1.3_rsa_chacha_client	42381390	42318492	-62898 (-0.15%)	0.20%
handshake_tickets_ring_1.3_rsa_aes_client	42416520	42353709	-62811 (-0.15%)	0.20%
handshake_session_id_ring_1.3_rsa_chacha_client	42189094	42128053	-61041 (-0.14%)	0.20%
handshake_session_id_ring_1.3_rsa_aes_client	42236027	42175043	-60984 (-0.14%)	0.20%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes_server	57116413	57184665	68252 (0.12%)	0.43%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_aes_client	5210846	5205277	-5569 (-0.11%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes_server	12739686	12727162	-12524 (-0.10%)	0.96%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes_client	3377334	3374533	-2801 (-0.08%)	0.20%
handshake_tickets_ring_1.3_ecdsa_aes_server	43901049	43866268	-34781 (-0.08%)	0.20%
handshake_tickets_ring_1.3_ecdsa_chacha_server	43860763	43826220	-34543 (-0.08%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha_client	3388081	3385604	-2477 (-0.07%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsa_chacha_server	33541219	33518193	-23026 (-0.07%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha_server	12764202	12755461	-8741 (-0.07%)	1.63%
handshake_tickets_aws_lc_rs_1.3_ecdsa_aes_server	33528571	33506453	-22118 (-0.07%)	0.20%
handshake_no_resume_ring_1.3_rsa_aes_client	4538318	4535361	-2957 (-0.07%)	0.20%
handshake_no_resume_ring_1.3_rsa_chacha_client	4548330	4545382	-2948 (-0.06%)	0.20%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes_client	3173418	3171442	-1976 (-0.06%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes_client	57978948	57952647	-26301 (-0.05%)	0.20%
handshake_no_resume_ring_1.2_rsa_aes_client	4441922	4440054	-1868 (-0.04%)	0.20%
transfer_no_resume_ring_1.2_rsa_aes_server	56966872	56989927	23055 (0.04%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_aes_server	2052332	2051575	-757 (-0.04%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_aes_server	57175923	57154970	-20953 (-0.04%)	0.20%
transfer_no_resume_ring_1.3_ecdsa_aes_client	57930780	57949517	18737 (0.03%)	0.20%
transfer_no_resume_ring_1.3_ecdsa_chacha_client	92366469	92394844	28375 (0.03%)	0.20%
handshake_tickets_ring_1.3_rsa_aes_server	43892611	43879508	-13103 (-0.03%)	0.20%
handshake_tickets_ring_1.3_rsa_chacha_server	43852415	43839568	-12847 (-0.03%)	0.20%
handshake_tickets_aws_lc_rs_1.3_rsa_aes_server	33560159	33550505	-9654 (-0.03%)	0.53%
handshake_no_resume_ring_1.3_ecdsa_chacha_client	14417622	14413741	-3881 (-0.03%)	0.20%
handshake_session_id_ring_1.3_ecdsa_aes_server	43675535	43664517	-11018 (-0.03%)	0.20%
handshake_session_id_ring_1.3_ecdsa_chacha_server	43609358	43598577	-10781 (-0.02%)	0.20%
transfer_no_resume_ring_1.2_rsa_aes_client	57845049	57831566	-13483 (-0.02%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_chacha_server	2056076	2055602	-474 (-0.02%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha_server	91353837	91334403	-19434 (-0.02%)	0.21%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha_client	92435510	92454985	19475 (0.02%)	0.20%
transfer_no_resume_ring_1.3_rsa_aes_client	57945135	57933501	-11634 (-0.02%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes_server	57152119	57161162	9043 (0.02%)	0.33%
handshake_no_resume_ring_1.3_ecdsa_aes_client	14417142	14415095	-2047 (-0.01%)	0.20%
transfer_no_resume_ring_1.3_rsa_chacha_client	92383652	92372955	-10697 (-0.01%)	0.20%
handshake_no_resume_ring_1.3_rsa_chacha_server	12250480	12249257	-1223 (-0.01%)	0.20%
handshake_no_resume_ring_1.3_rsa_aes_server	12240337	12239168	-1169 (-0.01%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_aes_client	57969238	57974596	5358 (0.01%)	0.20%
transfer_no_resume_ring_1.3_ecdsa_aes_server	57082032	57086985	4953 (0.01%)	0.20%
transfer_no_resume_ring_1.3_rsa_aes_server	57102823	57107694	4871 (0.01%)	0.20%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes_client	68413663	68419061	5398 (0.01%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_chacha_client	92444457	92450800	6343 (0.01%)	0.20%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha_server	33248321	33246198	-2123 (-0.01%)	0.88%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_chacha_server	91340692	91335126	-5566 (-0.01%)	0.20%
transfer_no_resume_ring_1.3_ecdsa_chacha_server	91246162	91251407	5245 (0.01%)	0.20%
transfer_no_resume_ring_1.3_rsa_chacha_server	91267191	91272091	4900 (0.01%)	0.20%
handshake_no_resume_ring_1.2_rsa_aes_server	12044574	12043989	-585 (-0.00%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsa_chacha_server	33257444	33258553	1109 (0.00%)	0.20%
handshake_no_resume_ring_1.3_ecdsa_aes_server	2132792	2132723	-69 (-0.00%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsa_aes_server	33275570	33274498	-1072 (-0.00%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_chacha_client	5211108	5211251	143 (0.00%)	0.20%
handshake_session_id_ring_1.3_rsa_aes_server	43668394	43668979	585 (0.00%)	0.20%
handshake_session_id_ring_1.3_rsa_chacha_server	43602388	43602941	553 (0.00%)	0.20%
handshake_no_resume_ring_1.3_ecdsa_chacha_server	2135714	2135703	-11 (-0.00%)	0.20%

Wall-time

Significant differences

⚠️ There are significant wall-time differences

Click to expand

Scenario	Baseline	Candidate	Diff	Threshold
handshake_session_id_ring_1.3_rsa_chacha	7.43 ms	7.51 ms	⚠️ 0.09 ms (1.15%)	1.14%
handshake_tickets_ring_1.3_rsa_chacha	7.45 ms	7.53 ms	⚠️ 0.08 ms (1.06%)	1.05%

Other differences

Click to expand

Scenario	Baseline	Candidate	Diff	Threshold
handshake_session_id_ring_1.3_ecdsa_chacha	7.56 ms	7.65 ms	0.09 ms (1.18%)	1.43%
handshake_session_id_ring_1.3_rsa_aes	7.47 ms	7.55 ms	0.08 ms (1.13%)	1.21%
handshake_tickets_ring_1.3_ecdsa_chacha	7.58 ms	7.66 ms	0.08 ms (1.08%)	1.41%
handshake_session_id_ring_1.3_ecdsa_aes	7.60 ms	7.68 ms	0.08 ms (1.07%)	1.23%
handshake_tickets_ring_1.3_ecdsa_aes	7.62 ms	7.70 ms	0.08 ms (1.01%)	1.50%
handshake_tickets_ring_1.3_rsa_aes	7.50 ms	7.57 ms	0.07 ms (0.97%)	1.15%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_aes	5.12 ms	5.16 ms	0.05 ms (0.95%)	6.43%
transfer_no_resume_ring_1.3_ecdsa_aes	7.47 ms	7.54 ms	0.07 ms (0.90%)	4.25%
transfer_no_resume_ring_1.3_rsa_aes	7.29 ms	7.36 ms	0.06 ms (0.88%)	4.35%
handshake_no_resume_ring_1.3_ecdsa_chacha	1.27 ms	1.28 ms	0.01 ms (0.87%)	1.60%
transfer_no_resume_ring_1.2_rsa_aes	7.21 ms	7.27 ms	0.06 ms (0.86%)	4.49%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes	5.88 ms	5.92 ms	0.05 ms (0.82%)	5.82%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes	5.87 ms	5.92 ms	0.05 ms (0.81%)	5.33%
handshake_no_resume_ring_1.3_ecdsa_aes	1.27 ms	1.28 ms	0.01 ms (0.78%)	1.30%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_chacha	653.67 µs	657.80 µs	4.12 µs (0.63%)	2.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_aes	655.14 µs	659.25 µs	4.11 µs (0.63%)	3.06%
handshake_tickets_aws_lc_rs_1.2_rsa_aes	2.26 ms	2.25 ms	-0.01 ms (-0.49%)	2.45%
transfer_no_resume_ring_1.3_rsa_chacha	14.00 ms	14.06 ms	0.06 ms (0.43%)	2.25%
handshake_tickets_ring_1.2_rsa_aes	1.79 ms	1.79 ms	0.01 ms (0.43%)	2.06%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_chacha	13.59 ms	13.65 ms	0.06 ms (0.42%)	2.63%
handshake_tickets_aws_lc_rs_1.3_ecdsa_aes	5.58 ms	5.60 ms	0.02 ms (0.40%)	1.22%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha	14.35 ms	14.41 ms	0.06 ms (0.39%)	2.34%
transfer_no_resume_ring_1.3_ecdsa_chacha	14.18 ms	14.24 ms	0.06 ms (0.39%)	2.47%
handshake_no_resume_ring_1.3_rsa_aes	1.08 ms	1.09 ms	0.00 ms (0.38%)	1.92%
handshake_session_id_aws_lc_rs_1.2_rsa_aes	2.08 ms	2.07 ms	-0.01 ms (-0.31%)	2.37%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha	1.40 ms	1.40 ms	0.00 ms (0.29%)	1.54%
handshake_tickets_aws_lc_rs_1.3_rsa_aes	6.39 ms	6.41 ms	0.02 ms (0.26%)	1.30%
handshake_session_id_aws_lc_rs_1.3_ecdsa_aes	5.54 ms	5.56 ms	0.01 ms (0.23%)	1.32%
handshake_tickets_aws_lc_rs_1.3_ecdsa_chacha	5.57 ms	5.58 ms	0.01 ms (0.19%)	1.08%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes	1.41 ms	1.41 ms	0.00 ms (0.19%)	1.22%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha	6.36 ms	6.35 ms	-0.01 ms (-0.17%)	1.09%
handshake_no_resume_ring_1.3_rsa_chacha	1.09 ms	1.09 ms	0.00 ms (0.16%)	1.64%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha	6.38 ms	6.39 ms	0.01 ms (0.12%)	1.00%
handshake_session_id_ring_1.2_rsa_aes	1.70 ms	1.70 ms	0.00 ms (0.09%)	3.18%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes	1.35 ms	1.35 ms	0.00 ms (0.08%)	1.63%
handshake_session_id_aws_lc_rs_1.3_rsa_aes	6.36 ms	6.36 ms	-0.00 ms (-0.06%)	1.20%
handshake_no_resume_ring_1.2_rsa_aes	1.07 ms	1.07 ms	0.00 ms (0.03%)	2.13%
handshake_session_id_aws_lc_rs_1.3_ecdsa_chacha	5.54 ms	5.54 ms	0.00 ms (0.01%)	1.00%

Additional information

Historical results

Checkout details:

• Base repo: https://github.com/rustls/rustls.git
• Base branch: main (0cd488d)
• Candidate repo: https://github.com/japaric/rustls.git
• Candidate branch: inplace-decode-decrypt (a970284)

[djc]

Hmm, I'm not really comfortable with some of the things that are happening here. In particular the work around the RawSlice which has some invariants which are neither enforced by the type system nor clearly documented, and some complexity around the AppendPayload trait and impls that it's not obvious are needed.

(Informed by my experience working on #1179.)

[cpu]

Hmm, I'm not really comfortable with some of the things that are happening here

Pulling some discussion out of a resolved review thread:

• I've added more documentation around the invariants required by the RawSlice portions of the work internal to the deframer.
• There's similar pre-existing "brittleness" w.r.t the deframer and Range operations.
• We're going to land this branch as-is, accepting that it introduces a bit more brittleness in the short term.
• I'm going to pick up a refactor branch that ctz started to try and reign in some of the complexity as follow-up work.