Unprincipled handling of exceeding `max_size` in `read_until`

[akrzemi1]

read and read_until, although similar, report the exceeding of the DynamicBuffer's max_size() in different ways.
read throws std::invalid_argument while read_until returns error code error::not_found.

[akrzemi1]

Note that it has serious design consequences.
error::not_found is only returned when the dynamic buffer has memory problems. If this is turned into an exception, error::not_found has no use. Having or not having found the pattern is determined by zero error code versus eof.

[vinniefalco]

not_found means that the pattern (the "until" condition) was not found. exceeding max size and all that should be exception-based. You can look to Asio for guidance on how it should work.

[akrzemi1]

The implementation also has this pattern which occurs in a number of places in Capy:

if (ec == cond::eof)
  co_return {error::eof, buffers.size()};
if (ec)
  co_return {ec, buffers.size()};

Currently, cond::eof matches only error::eof, so the first if-statement is redundant. If the goal is in the future for cond::eof to match also other error codes, then the first if-statement becomes a translation, which goes against the philosophy of error codes: you shall not change the original error value (because it carries information), only assign different interpretations via conditions.

[akrzemi1]

Do you want to translate eof/stream_truncated to not_found?

[akrzemi1]

I changed the title and the description based on the discussion.

[akrzemi1]

The contract of read shall be analogous to that in Boost.ASIO:
https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference/read/overload6.html:

Read until:

• either we read the number of bytes designated by (dynamic) buffer,
• or a contingency occurs.

[akrzemi1]

The following program currently throws, while it shouldn't

capy::task<> test_read(capy::ReadStream auto& rs)
{
    std::string s;
    capy::string_dynamic_buffer db(&s, 4);
    auto [ec, _] = co_await capy::read(rs, db, 1); // this shall return eof
    std::cout << ec << " " << s << std::endl; 
}

int main(int argc, char* argv[])
{
    capy::test::read_stream rs;
    rs.provide("ab\n");
    capy::test::run_blocking()(test_read(rs));
}

[akrzemi1]

Currently, the implementation of read (2nd and 3rd overload) turns eof from source.read() into ec = {}. eof is never returned from these overloads of read.

[vinniefalco]

This was Peter's idea

if (ec == cond::eof)
  co_return {error::eof, buffers.size()};
if (ec)
  co_return {ec, buffers.size()};

When you guys were trying to figure out the contract of read_some. But it looks like it didn't get translated correctly. I believe, what Peter said is that if you get eof and also n==M where M=the amount you wanted, then it should silently turn the eof into a success. Or something.

[akrzemi1]

The specification of read_until in ASIO is not sufficiently clear to be helpful. read_until could have one of two contracts:

1. Barring the cases when stream's operations return non-zero ec, keep reading until you have either found the pattern or reached max_size(). Either case is a success.
2. Barring the cases when stream's operations return non-zero ec, keep reading until you have found the pattern. If this causes going past max_size() propagate the exception thrown by the buffer.

[akrzemi1]

One more thing. The overloads of read and read_until taking DynamicBufferParam also take initial_amount. It is possible to pass these two parameters so that initial_amount > buffers.max_size(). Shall this be considered a user bug?

If this is a bug, can we make it a precondition, or do we apply this "pretend that this is fine" approach and still guarantee what will happen?

[akrzemi1]

Is there a precondition that the dynamic buffer passed to read/read_until is initially empty?

[vinniefalco]

1. if the dynamic buffer already has bytes in the read area, those will be searched first
2. the contract of read_until it never reads past max_size
3. when max_size is reached and the pattern is not found, it returns error::not_found
4. initial_amount represents the amount to attempt to read per call to read_some
5. when initial_amount is too large, it is simply clamped. there is no precondition
6. the dynamic buffer does not need to be empty, in fact if there is data in the dynamic buffer and the pattern is located, the function performs an immediate completion