Codecs documentation could use some fully formed examples

[rageshkrishna]

I've been trying to understand codecs and how to use them. I started at https://docs.rs/tokio-util/latest/tokio_util/codec/index.html, which got me thinking that what I need is either a LinesCodec or LengthDelimitedCodec (I'm just playing around so doesn't really matter which one) and a FramedRead to use it with a stream. I followed through to https://docs.rs/tokio-util/latest/tokio_util/codec/length_delimited/index.html which shows me how to configure a decoder, and https://docs.rs/tokio-util/latest/tokio_util/codec/struct.FramedRead.html which tells me what FramedRead has.

But I still haven't really seen any concrete example that ties everything together and shows me exactly how to read a frame from a stream. I'm gathering that I actually need tokio_stream::StreamExt so I can do .next() on my FramedRead. This does not seem to be explained anywhere in the docs I've seen so far, and I only figured it out by looking at https://users.rust-lang.org/t/understanding-framed-in-tokio/42449/2

The documentation, by itself, does not help a beginner to get to a working state.

[Darksonn]

Thank you for the report. Indeed, the current documentation explains how to write your own codec, but we don't explain how to use FramedRead/FramedWrite. Documentation for this would be very good to add.

[Dessix]

Is composition actually possible with these, in their current state? It's not clear from the Framed*::map setup, and either this is a hole in documentation or in functionality, but it's currently unclear which.

[Darksonn]

Composition of two codecs is fundamentally not possible. A codec is a function from AsyncRead to Stream<Item = T>. Therefore, to compose two codecs, you would need a conversion from Stream<Item = T> to AsyncRead in the middle.

However, codecs can be combined with stream combinators. For example, you can use StreamExt::map to perform an additional operation after the codec.

(The same is true for FramedWrite, just in reverse.)