documentation and tidy up tls stream APIs

Author: vinniefalco

.cursor/rules/awaitable-ops.mdc

@@ -0,0 +1,21 @@
+---
+description: doc javadoc for async awaitable functions of I/O objects
+alwaysApply: false
+---
+
+**Checklist for an outstanding awaitable function javadoc:**
+- **Brief** — One-sentence summary starting with a verb, e.g. "Read data from the stream asynchronously."
+- **Extended description** — Short paragraph explaining what the function does. State that it is an asynchronous operation that suspends the calling coroutine until completion. If composed, state which underlying operations it is implemented in terms of.
+- **Completion conditions** — Bulleted `@li` list of conditions under which the operation completes and the coroutine resumes (e.g. "The supplied buffers are full", "An error occurs", "The operation was canceled").
+- **Concurrency and overlap** — State which operations may be simultaneously in flight. E.g. for a read: "At most one write operation may be in flight concurrently with this read operation. No other read operations may be in flight until this operation completes." Clarify that simultaneous in-flight operations does *not* imply that the initiating calls themselves may be made concurrently; all calls to the stream must be made from the same implicit or explicit serialization context.
+- **`@param` for each parameter** — Including ownership/lifetime semantics. For buffers: state that the caller retains ownership and must guarantee validity until the operation completes. For string/view parameters: state whether the implementation copies the data or requires it to remain valid for the duration.
+- **`@return`** — Describe the returned aggregate and its elements. The first element is always `error_code`. Name and describe each subsequent element (e.g. "bytes_transferred", "endpoint"). Note that the result is customarily destructured by the caller.
+- **Error conditions** — Document the notable `error_code` values or conditions that may appear in the first element. E.g. `capy::cond::canceled` if the stop token was activated or the i/o object's `cancel()` was called, EOF conditions, protocol-specific errors, etc. State that error codes should be compared to error conditions, not specific values.
+- **`@throws`** — Typically only for precondition violations. State which preconditions trigger exceptions, or state that no exceptions are thrown during normal operation.
+- **Cancellation** — State that the operation supports cancellation via `stop_token` propagated through the IoAwaitable protocol, or via the i/o object's `cancel()` member. State that the resulting error compares equal to `capy::cond::canceled`.
+- **`@par Example`** — Two or three `@code` blocks showing different usage patterns: typical happy path with destructuring, error handling, cancellation, different overloads, etc.
+- **`@note` / `@par Remarks`** — Behavioral gotchas. E.g. "This operation may not read all of the requested bytes." Or equivalence to another overload.
+- **`@tparam`** — For non-variadic template parameters. State the concept requirement (e.g. "The type must satisfy the *AsyncStream* concept"). Don't document `Args...`.
+- **`@see`** — Always last. Cross-references to related functions, concepts, and relevant RFC sections.
+- Keep the ascii-art to a minimum, only add dividers if the class declaration is very long
+- Don't emit @tparam for deduced types or concepts

.cursor/rules/doc-awaitable.mdc

@@ -126,7 +126,7 @@ class BOOST_COROSIO_DECL io_stream : public io_object
     template<capy::MutableBufferSequence MB>
     auto read_some(MB const& buffers)
     {
-        return read_some_awaitable<MutableBufferSequence>(*this, buffers);
+        return read_some_awaitable<MB>(*this, buffers);
     }
 
     /** Asynchronously write data to the stream.
@@ -192,7 +192,7 @@ class BOOST_COROSIO_DECL io_stream : public io_object
     template<capy::ConstBufferSequence CB>
     auto write_some(CB const& buffers)
     {
-        return write_some_awaitable<ConstBufferSequence>(*this, buffers);
+        return write_some_awaitable<CB>(*this, buffers);
     }
 
 protected:

include/boost/corosio/io_stream.hpp

@@ -136,6 +136,9 @@ class BOOST_COROSIO_DECL openssl_stream final
         return stream_;
     }
 
+    std::string_view
+    name() const noexcept override;
+
 protected:
     capy::io_task<std::size_t>
     do_read_some(capy::some_mutable_buffers buffers) override;

include/boost/corosio/openssl_stream.hpp

@@ -17,6 +17,7 @@
 #include <boost/capy/io_task.hpp>
 
 #include <cstddef>
+#include <string_view>
 
 namespace boost::corosio {
 
@@ -145,6 +146,13 @@ class BOOST_COROSIO_DECL tls_stream
     virtual capy::any_stream const&
     next_layer() const noexcept = 0;
 
+    /** Returns the name of the TLS backend.
+
+        @return A string identifying the TLS implementation,
+            such as "openssl" or "wolfssl".
+    */
+    virtual std::string_view name() const noexcept = 0;
+
 protected:
     tls_stream() = default;
 

include/boost/corosio/tls_stream.hpp

@@ -136,6 +136,9 @@ class BOOST_COROSIO_DECL wolfssl_stream final
         return stream_;
     }
 
+    std::string_view
+    name() const noexcept override;
+
 protected:
     capy::io_task<std::size_t>
     do_read_some(capy::some_mutable_buffers buffers) override;

include/boost/corosio/wolfssl_stream.hpp

@@ -735,4 +735,11 @@ shutdown()
     co_return co_await impl_->do_shutdown();
 }
 
+std::string_view
+openssl_stream::
+name() const noexcept
+{
+    return "openssl";
+}
+
 } // namespace boost::corosio

src/openssl/src/openssl_stream.cpp

@@ -953,4 +953,11 @@ shutdown()
     co_return co_await impl_->do_shutdown();
 }
 
+std::string_view
+wolfssl_stream::
+name() const noexcept
+{
+    return "wolfssl";
+}
+
 } // namespace boost::corosio

src/wolfssl/src/wolfssl_stream.cpp

@@ -46,6 +46,18 @@ struct openssl_stream_test
         test::context_mode::separate_cert
     };
 
+    void testName()
+    {
+        using namespace test;
+
+        io_context ioc;
+        auto ctx = make_anon_context();
+        tcp_socket sock( ioc );
+        openssl_stream stream( &sock, ctx );
+
+        BOOST_TEST( stream.name() == "openssl" );
+    }
+
     /** Test certificate chain validation (OpenSSL-specific).
 
         OpenSSL supports sending full certificate chains via
@@ -91,6 +103,7 @@ struct openssl_stream_test
         test::testMtls( make_stream );
 
         testCertificateChain();
+        testName();
     }
 };
 

test/unit/openssl_stream.cpp

@@ -46,6 +46,18 @@ struct wolfssl_stream_test
         test::context_mode::separate_cert
     };
 
+    void testName()
+    {
+        using namespace test;
+
+        io_context ioc;
+        auto ctx = make_client_context();
+        tcp_socket sock( ioc );
+        wolfssl_stream stream( &sock, ctx );
+
+        BOOST_TEST( stream.name() == "wolfssl" );
+    }
+
     /** Test certificate chain validation (WolfSSL-specific).
 
         WolfSSL has limited certificate chain support compared to OpenSSL.
@@ -98,6 +110,7 @@ struct wolfssl_stream_test
         test::testMtls( make_stream );
 
         testCertificateChain();
+        testName();
     }
 };