Clarify the contract of `max_size` in `DynamicBufferParam`

[akrzemi1]

During discussions it became apparent that member function max_size on types modelling DynamicBufferParam (so this probably also applies to DynamicBuffer) has different meaning than the member function of the same name and signature in STL containers.

In STL containers max_size() means (https://en.cppreference.com/cpp/container/vector/max_size):

The maximum number of elements the container of this type is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the largest container.

In Capy, DynamicBuffer defines max_capacity vaguely:

Maximum allowed size. Attempts to grow beyond this throw or fail.

But some algorithms (read_until) inconsistently use it for controlling the number of bytes to be read from the stream, which follows the pattern from ASIO: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference/read/overload6.html.

Document clearly what the contract of this operation in DynamicBufferParam is. (It could be an additional semantic requirement relative to DynamicBuffer). If the goal is to control the logic of stream algorithms, change the name of the function so that does not incorrectly imply the semantics of max_size from STL containers.

[akrzemi1]

I recommend:

• calling it size_limit, and
• documenting that its primary purpose is security (DoS attack prevention).

[akrzemi1]

@vinniefalco, your opinion?

[vinniefalco]

1. DynamicBufferParam is a refinement of DynamicBuffer and should have no opinion on max_size

2. DynamicBuffer is not documented fully. There is no information about max_size

3. I would guess that max_size represents the largest allowable sum of the input region and the output region. This means a call to prepare(n) would throw if n > max_size() - size()

4. I think we should leave it at max_size since we are borrowing from Asio. And note, if you adapt a vector into a DynamicBuffer, the max_size() of the dynamic buffer will equal vector::max_size():
   https://github.com/cppalliance/capy/blob/develop/include/boost/capy/buffers/vector_dynamic_buffer.hpp#L113

5. The goal is not "to control the logic of stream algorithms," it is to define a maximum size. That stream algorithms avoid going over max_size is a property of the algorithm not the dynamic buffer.

6. We can and should document potential use-case for max_size but we should not use "primary purpose" framing. All use-cases are equally valid