opencode-skills-collection 4.0.36 → 4.0.38

package/bundled-skills/boost-asio-pro/references/build.md

@@ -0,0 +1,88 @@
+# Build Configuration
+
+
+### Boost.Asio (header-only since Boost 1.74+)
+
+```cmake
+find_package(Boost REQUIRED)
+find_package(OpenSSL REQUIRED)          # if using SSL
+find_package(Threads REQUIRED)
+
+target_link_libraries(myapp PRIVATE
+    Boost::headers                       # header-only Asio
+    OpenSSL::SSL OpenSSL::Crypto         # if using SSL
+    Threads::Threads
+)
+
+target_compile_features(myapp PRIVATE cxx_std_20)
+
+# REQUIRED for GCC coroutine support — build will fail without this
+target_compile_options(myapp PRIVATE
+    $<$<CXX_COMPILER_ID:GNU>:-fcoroutines>
+)
+
+# Optional: truly header-only (no Boost.System link needed)
+target_compile_definitions(myapp PRIVATE BOOST_ERROR_CODE_HEADER_ONLY)
+```
+
+### Standalone Asio (always header-only)
+
+```cmake
+# Standalone Asio has no CMake config — use pkg-config or manual path
+find_package(OpenSSL REQUIRED)
+find_package(Threads REQUIRED)
+
+# If installed via brew:
+find_path(ASIO_INCLUDE_DIR asio.hpp HINTS /opt/homebrew/include)
+
+target_include_directories(myapp PRIVATE ${ASIO_INCLUDE_DIR})
+target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto Threads::Threads)
+target_compile_features(myapp PRIVATE cxx_std_20)
+target_compile_definitions(myapp PRIVATE ASIO_STANDALONE)
+
+target_compile_options(myapp PRIVATE
+    $<$<CXX_COMPILER_ID:GNU>:-fcoroutines>
+)
+```
+
+### Dual-mode CMake (supports both)
+
+```cmake
+option(USE_STANDALONE_ASIO "Use standalone Asio instead of Boost.Asio" OFF)
+
+find_package(OpenSSL REQUIRED)
+find_package(Threads REQUIRED)
+
+if(USE_STANDALONE_ASIO)
+    find_path(ASIO_INCLUDE_DIR asio.hpp HINTS /opt/homebrew/include)
+    target_include_directories(myapp PRIVATE ${ASIO_INCLUDE_DIR})
+    target_compile_definitions(myapp PRIVATE USE_STANDALONE_ASIO ASIO_STANDALONE)
+else()
+    find_package(Boost REQUIRED)
+    target_link_libraries(myapp PRIVATE Boost::headers)
+    target_compile_definitions(myapp PRIVATE BOOST_ERROR_CODE_HEADER_ONLY)
+endif()
+
+target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto Threads::Threads)
+target_compile_features(myapp PRIVATE cxx_std_20)
+target_compile_options(myapp PRIVATE $<$<CXX_COMPILER_ID:GNU>:-fcoroutines>)
+```
+
+## Header-Only Usage
+
+**Boost.Asio:** Asio is header-only by default. The only thing that pulls in a Boost library to link is `boost::system::error_code`'s out-of-line symbols, so for a truly link-free build define **`BOOST_ERROR_CODE_HEADER_ONLY`**. `BOOST_ASIO_HEADER_ONLY` is rarely needed and only relevant if separate compilation was previously enabled; you do **not** normally need both.
+
+**Define `BOOST_ERROR_CODE_HEADER_ONLY` in exactly ONE place — prefer CMake** (`target_compile_definitions`, as shown above). Defining it in CMake *and* with a source `#define` triggers `-Wmacro-redefined`. So in source, just include — no `#define`:
+```cpp
+#include <boost/asio.hpp>
+#include <boost/asio/ssl.hpp>
+#include <boost/asio/experimental/awaitable_operators.hpp>
+```
+
+**Standalone Asio:**
+```cpp
+#include <asio.hpp>
+#include <asio/ssl.hpp>
+#include <asio/experimental/awaitable_operators.hpp>
+// No macros needed — always header-only
+```

package/bundled-skills/boost-asio-pro/references/classic-boost.md

@@ -0,0 +1,33 @@
+# Classic Boost (pre-1.66, the `io_service` era — verified to 1.62)
+
+
+To support Boost older than 1.66 (no `io_context`, no `make_strand`, no `any_io_executor`), drop to the classic API — verified building **back to Boost 1.62** (Debian 9) while still compiling on current Boost via a tiny shim:
+
+| Modern (1.66+) | Classic (pre-1.66) |
+|----------------|--------------------|
+| `io_context` | `io_service` |
+| `make_strand(ex)` / `strand<any_io_executor>` | `io_service::strand strand(io)` |
+| `bind_executor(strand, h)` | `strand.wrap(h)` |
+| `timer.expires_after(d)` | `timer.expires_from_now(d)` |
+| move-return `async_accept()` | `async_accept(socket_, handler)` |
+| header-only `error_code` | link **Boost.System** (`find_package(Boost COMPONENTS system)`) |
+
+Only the `io_service`/`io_context` name and the `expires_after`/`expires_from_now` call actually differ across 1.62…1.90 — isolate both behind `#if BOOST_VERSION >= 106600`:
+```cpp
+#include <boost/version.hpp>
+#include <boost/asio/steady_timer.hpp>     // not pulled in by <boost/asio.hpp> on old Boost
+#if BOOST_VERSION >= 106600
+  using io_service_t = boost::asio::io_context;
+#else
+  using io_service_t = boost::asio::io_service;
+#endif
+template <class T, class Rep, class Period>
+void timer_expires_in(T& t, std::chrono::duration<Rep,Period> d) {
+#if BOOST_VERSION >= 106600
+    t.expires_after(d);
+#else
+    t.expires_from_now(d);
+#endif
+}
+```
+CMake for this range: `cmake_minimum_required(VERSION 3.5)` (Debian 9 ships cmake 3.7), link `Boost::system` only if the component is found (modern Boost is header-only and has no such component), and use the classic out-of-source build (`mkdir build && cd build && cmake ..`) since `-S`/`-B` need cmake ≥ 3.13.

package/bundled-skills/boost-asio-pro/references/coroutines.md

@@ -0,0 +1,415 @@
+# C++20 Coroutine Style (Boost ≥ 1.77)
+
+The preferred style when the toolchain allows it. Read `SKILL.md` first — the rules there (write queue, buffer lifetime, version floors) apply here and are not repeated.
+
+## Core Architecture
+
+Boost.Asio uses the **Proactor pattern**: async operations run in the background, completion handlers are invoked with results.
+
+```
+Program → I/O Object → Execution Context → OS → (completion) → Handler
+```
+
+**Execution contexts:** `io_context` (single/multi-thread event loop), `thread_pool`, `system_context`
+
+**I/O objects:** `tcp::socket`, `tcp::acceptor`, `udp::socket`, `steady_timer`, `ssl::stream<>`
+
+**Completion tokens:** Control how async results are delivered — `use_awaitable`, `deferred` (default), `detached`, callbacks, futures.
+
+## C++20 Coroutines (Preferred Style)
+
+```cpp
+#include <boost/asio.hpp>
+#include <boost/asio/co_spawn.hpp>
+#include <boost/asio/use_awaitable.hpp>
+
+namespace asio = boost::asio;
+using tcp = asio::ip::tcp;
+
+asio::awaitable<void> echo_session(tcp::socket socket) {
+    try {
+        char data[1024];
+        for (;;) {
+            std::size_t n = co_await socket.async_read_some(asio::buffer(data));
+            co_await async_write(socket, asio::buffer(data, n));
+        }
+    } catch (std::exception&) {
+        // Connection closed or error — coroutine ends
+    }
+}
+
+asio::awaitable<void> listener(tcp::acceptor acceptor) {
+    for (;;) {
+        auto socket = co_await acceptor.async_accept();
+        co_spawn(acceptor.get_executor(), echo_session(std::move(socket)), asio::detached);
+    }
+}
+
+int main() {
+    asio::io_context io(1); // concurrency_hint=1 for single-threaded
+    tcp::acceptor acceptor(io, {tcp::v4(), 8080});
+    co_spawn(io, listener(std::move(acceptor)), asio::detached);
+    io.run();
+}
+```
+
+**Key rules:**
+- `co_spawn(executor, coroutine, completion_token)` launches a coroutine
+- Without explicit token, async ops use `deferred` (returns awaitable object for `co_await`)
+- Errors become `system_error` exceptions by default inside coroutines
+- Use `asio::detached` when you don't need the coroutine's result
+
+## Error Handling in Coroutines
+
+**Default:** Errors throw `boost::system::system_error`.
+
+**Explicit error handling with `as_tuple`:**
+```cpp
+auto [ec, n] = co_await socket.async_read_some(
+    asio::buffer(data), asio::as_tuple(asio::use_awaitable));
+if (ec) { /* handle error, no exception */ }
+```
+**Wrap, don't use bare `as_tuple`.** Always write `as_tuple(use_awaitable)`. Bare `asio::as_tuple` resolves against the operation's *default* completion token (often `deferred`), which compiles in some contexts but fails in others — wrapping an explicit base token is unambiguous everywhere.
+
+**With `redirect_error`:**
+```cpp
+boost::system::error_code ec;
+std::size_t n = co_await socket.async_read_some(
+    asio::buffer(data), asio::redirect_error(asio::use_awaitable, ec));
+```
+
+## Strands (Thread Safety)
+
+**Rule: All async operations on a shared object MUST execute on the same strand.**
+
+```cpp
+// Per-connection strand
+asio::strand<asio::io_context::executor_type> strand(io.get_executor());
+co_spawn(strand, session(std::move(socket)), asio::detached);
+
+// Bind handler to strand
+socket.async_read_some(asio::buffer(data),
+    asio::bind_executor(strand, [](error_code ec, size_t n) { /*...*/ }));
+```
+
+**Implicit strands (no explicit strand needed):**
+- Single-threaded `io_context::run()` — all handlers are sequential
+- Single chain of async ops on one connection (half-duplex)
+
+**Explicit strand required when:**
+- Multiple threads call `io_context::run()`
+- Full-duplex read+write on same socket
+- Shared state accessed from multiple async chains
+
+## Full-Duplex: Strand + Write Queue
+
+**A strand serializes handler *execution*, NOT whole composed operations.** Two `async_write`s started "concurrently" on the same strand still overlap and **interleave bytes on the wire** — the strand only orders the intermediate handlers, not the byte stream. For full-duplex (a read loop plus pushes/replies writing at the same time on one socket), a strand alone is **not** enough: you must serialize outbound writes yourself with a queue.
+
+```cpp
+// Give each accepted socket its OWN strand, then run every chain (read loop,
+// pushes, replies) on that strand. Passing an executor to async_accept means you
+// must ALSO pass an explicit completion token — the default-deferred shortcut on
+// the zero-arg form no longer applies.
+auto socket = co_await acceptor.async_accept(asio::make_strand(io), asio::use_awaitable);
+std::make_shared<connection>(std::move(socket))->start();
+
+class connection : public std::enable_shared_from_this<connection> {
+    tcp::socket socket_;                 // bound to its own strand
+    std::deque<std::string> outbox_;
+    bool writing_ = false;
+public:
+    explicit connection(tcp::socket s) : socket_(std::move(s)) {}
+
+    void start() {
+        // Each chain captures `self` so the connection outlives all its coroutines.
+        co_spawn(socket_.get_executor(),
+                 [self = shared_from_this()] { return self->read_loop(); }, asio::detached);
+    }
+
+    // Call ONLY from the connection's strand (e.g. from its own coroutines).
+    // From another thread/strand: asio::dispatch(socket_.get_executor(), ...).
+    void send(std::string frame) {
+        outbox_.push_back(std::move(frame));
+        if (!writing_)
+            co_spawn(socket_.get_executor(),
+                     [self = shared_from_this()] { return self->write_loop(); }, asio::detached);
+    }
+private:
+    asio::awaitable<void> write_loop() {
+        writing_ = true;
+        while (!outbox_.empty()) {
+            co_await async_write(socket_, asio::buffer(outbox_.front()));
+            outbox_.pop_front();         // pop only AFTER the write completes
+        }
+        writing_ = false;
+    }
+    asio::awaitable<void> read_loop();   // reads frames, calls send() for replies
+};
+```
+
+**Why each rule matters:**
+- One strand per connection → read loop and write loop never run their handlers concurrently.
+- Write queue + `writing_` flag → at most one `async_write` in flight, so frames never interleave.
+- `enable_shared_from_this` + capturing `self` in every `co_spawn` → the connection survives until all of its read/write/timer chains finish.
+- The accepted socket from `async_accept(make_strand(...))` is `basic_stream_socket<tcp, strand<...>>`, **not** `tcp::socket`. Take it **by value** (`connection(tcp::socket s)`, store `tcp::socket socket_`) — the strand executor type-erases into `any_io_executor` on the move. Passing that accepted socket to a `tcp::socket&` (by reference) instead will **fail to compile** — use `auto` or accept by value.
+
+**Strand from inside a coroutine** (when `io` isn't a captured local): get the executor from the coroutine and make a strand off it — no `io_context&` needed:
+```cpp
+auto ex = co_await asio::this_coro::executor;
+auto socket = co_await acceptor.async_accept(asio::make_strand(ex), asio::use_awaitable);
+```
+
+**Run the read loop and idle watch together** — two `awaitable<void>` branches; don't inspect the result, the first to finish unwinds the other:
+```cpp
+using namespace asio::experimental::awaitable_operators;
+co_await (read_loop() || idle_watch(socket_, timer_));   // either returning tears down the connection
+```
+
+**Stopping a detached side-coroutine** (e.g. a per-symbol ticker that must end on unsubscribe/close): a detached `co_spawn` won't stop itself. Either (a) have its loop re-check a flag each iteration and `co_return` when gone:
+```cpp
+while (subscriptions_.contains(symbol) && socket_.is_open()) {
+    timer.expires_after(250ms);
+    co_await timer.async_wait(asio::as_tuple(asio::use_awaitable));
+    if (/* still subscribed */) send(make_tick(symbol));
+}
+```
+or (b) spawn it with a `cancellation_signal` and `emit()` cancellation on unsubscribe. The flag approach is simpler for per-subscription tickers.
+
+## Timers and Timeouts
+
+```cpp
+asio::awaitable<void> with_timeout(tcp::socket& socket) {
+    asio::steady_timer timer(co_await asio::this_coro::executor);
+    timer.expires_after(std::chrono::seconds(30));
+
+    // Race: read vs timeout (requires awaitable_operators)
+    using namespace asio::experimental::awaitable_operators;
+
+    auto result = co_await (
+        socket.async_read_some(asio::buffer(data), asio::use_awaitable)
+        || timer.async_wait(asio::use_awaitable)
+    );
+
+    if (result.index() == 0) { /* read completed */ }
+    else { /* timeout — cancel the socket */ socket.close(); }
+}
+```
+
+**Re-armable idle timeout** (reset on every received frame — the common server pattern):
+```cpp
+// Run as a long-lived parallel branch. Calling expires_after() again cancels the
+// pending wait, resolving the in-flight async_wait with operation_aborted — that
+// is the signal to keep waiting, NOT an error. Genuine expiry resolves with no error.
+asio::awaitable<void> idle_watch(tcp::socket& sock, asio::steady_timer& timer) {
+    for (;;) {
+        auto [ec] = co_await timer.async_wait(asio::as_tuple(asio::use_awaitable));
+        if (ec == asio::error::operation_aborted) continue;  // re-armed → keep waiting
+        if (ec) co_return;                                   // timer error
+        sock.close();                                        // real timeout fired
+        co_return;
+    }
+}
+// On every frame received from the peer: timer.expires_after(30s);
+```
+
+**Parallel operations (`&&` and `||`):**
+```cpp
+#include <boost/asio/experimental/awaitable_operators.hpp>
+using namespace asio::experimental::awaitable_operators;
+
+// Wait for both (AND) — cancels other on failure
+auto [read_n, write_n] = co_await (
+    async_read(sock, in_buf, use_awaitable) &&
+    async_write(sock, out_buf, use_awaitable)
+);
+
+// Wait for first (OR) — cancels other on success
+auto result = co_await (
+    async_read(sock, buf, use_awaitable) ||
+    timer.async_wait(use_awaitable)
+);
+```
+
+**Note:** `||` and `&&` operators require explicit `use_awaitable` token, and the `awaitable_operators.hpp` header (Boost ≥ 1.77 — see the version floors in SKILL.md).
+
+**Void branches:** when a branch returns `void` (e.g. two `awaitable<void>` chains), that arm contributes `std::monostate` to the result variant. If *both* branches are void the result is `variant<monostate, monostate>` — don't inspect `.index()`; just `co_await` the expression and let whichever finishes first unwind the other.
+
+## Cancellation
+
+```cpp
+asio::awaitable<void> cancellable_work() {
+    // Check cancellation state
+    auto cs = co_await asio::this_coro::cancellation_state;
+    if (cs.cancelled() != asio::cancellation_type::none) {
+        co_return;
+    }
+
+    // Enable cancellation types
+    co_await asio::this_coro::reset_cancellation_state(
+        asio::enable_total_cancellation());
+}
+```
+
+## TCP Server Pattern
+
+```cpp
+asio::awaitable<void> server(asio::io_context& io, unsigned short port) {
+    tcp::acceptor acceptor(io, {tcp::v4(), port});
+    acceptor.set_option(tcp::acceptor::reuse_address(true));
+
+    for (;;) {
+        auto socket = co_await acceptor.async_accept();
+        co_spawn(
+            io.get_executor(),  // or a strand for multi-threaded
+            handle_client(std::move(socket)),
+            [](std::exception_ptr ep) {
+                if (ep) std::rethrow_exception(ep);
+            }
+        );
+    }
+}
+```
+
+## Buffers
+
+| Type | Use |
+|------|-----|
+| `asio::buffer(data, size)` | Wrap existing memory (no ownership) |
+| `asio::dynamic_buffer(vec)` | Growable buffer over `vector`/`string` |
+| `asio::streambuf` | Legacy stream buffer |
+| `asio::const_buffer` | Read-only view |
+| `asio::mutable_buffer` | Writable view |
+
+**Critical:** `asio::buffer()` does NOT own memory. The underlying storage must outlive the async operation.
+
+## Resolver (DNS)
+
+```cpp
+asio::awaitable<void> connect_to(asio::io_context& io,
+                                  std::string host, std::string port) {
+    tcp::resolver resolver(io);
+    auto endpoints = co_await resolver.async_resolve(host, port);
+
+    tcp::socket socket(io);
+    co_await asio::async_connect(socket, endpoints);
+    // socket is now connected
+}
+```
+
+## Multi-Threaded io_context
+
+```cpp
+asio::io_context io;
+std::vector<std::thread> threads;
+
+for (int i = 0; i < std::thread::hardware_concurrency(); ++i) {
+    threads.emplace_back([&io] { io.run(); });
+}
+
+// All handlers MUST be strand-protected when sharing state
+for (auto& t : threads) t.join();
+```
+
+## Composed Async Operations (Custom)
+
+```cpp
+template <typename CompletionToken>
+auto async_echo(tcp::socket& socket, CompletionToken&& token) {
+    return asio::async_initiate<CompletionToken, void(boost::system::error_code)>(
+        asio::co_composed<void(boost::system::error_code)>(
+            [](auto state, tcp::socket& socket) -> void {
+                state.throw_if_cancelled(true);
+                state.reset_cancellation_state(asio::enable_terminal_cancellation());
+                try {
+                    char data[1024];
+                    for (;;) {
+                        std::size_t n = co_await socket.async_read_some(asio::buffer(data));
+                        co_await async_write(socket, asio::buffer(data, n));
+                    }
+                } catch (const boost::system::system_error& e) {
+                    co_return {e.code()};
+                }
+            }, socket),
+        token, std::ref(socket));
+}
+```
+
+## Line-Based Protocols
+
+For newline-delimited protocols, prefer `async_read_until` over manual `async_read_some` + buffer parsing:
+
+```cpp
+asio::awaitable<void> line_echo(tcp::socket socket) {
+    asio::streambuf buf;
+    for (;;) {
+        std::size_t n = co_await asio::async_read_until(socket, buf, '\n');
+        std::string line(asio::buffers_begin(buf.data()),
+                         asio::buffers_begin(buf.data()) + n);
+        buf.consume(n);
+        co_await async_write(socket, asio::buffer(line));
+    }
+}
+```
+
+Or with `dynamic_buffer` over a `std::string`:
+```cpp
+std::string buf;
+std::size_t n = co_await asio::async_read_until(socket, asio::dynamic_buffer(buf), '\n');
+std::string line = buf.substr(0, n);
+buf.erase(0, n);
+```
+
+## Length-Prefixed Binary Framing
+
+For binary protocols, read the fixed-size header fully, then the body fully — two sequential **composed** reads (`async_read` fills the whole buffer, handling short reads). Do NOT use `async_read_some` for framing.
+
+```cpp
+// Frame: [4-byte big-endian length N][N-byte body]
+asio::awaitable<std::string> read_frame(tcp::socket& sock) {
+    constexpr uint32_t max_frame_size = 16 * 1024 * 1024;
+    uint32_t len_be = 0;
+    co_await async_read(sock, asio::buffer(&len_be, sizeof len_be));  // exactly 4 bytes
+    uint32_t n = ntohl(len_be);                    // <arpa/inet.h>; or hand-roll endian swap
+    if (n > max_frame_size) {
+        throw std::length_error("frame exceeds 16 MiB limit");  // <stdexcept>
+    }
+    std::string body(n, '\0');
+    co_await async_read(sock, asio::buffer(body));  // exactly n bytes
+    co_return body;
+}
+
+asio::awaitable<void> write_frame(tcp::socket& sock, std::string_view body) {
+    uint32_t len_be = htonl(static_cast<uint32_t>(body.size()));
+    std::array<asio::const_buffer, 2> bufs{
+        asio::buffer(&len_be, sizeof len_be), asio::buffer(body)};
+    co_await async_write(sock, bufs);              // gather-write header + body atomically
+    // len_be and body must outlive the write — they do here (co_await suspends in-frame).
+}
+```
+
+## Graceful Shutdown (signal_set)
+
+```cpp
+asio::signal_set signals(io, SIGINT, SIGTERM);
+signals.async_wait([&](const boost::system::error_code&, int /*signo*/) {
+    acceptor.close();   // stop accepting; let in-flight sessions drain, then io.run() returns
+    // or, for an immediate stop: io.stop();
+});
+```
+
+For coroutine-style shutdown, `co_await signals.async_wait()` in a dedicated coroutine instead of a callback.
+
+## Quick Reference
+
+| Operation | Function |
+|-----------|----------|
+| Launch coroutine | `co_spawn(executor, coro, token)` |
+| Accept connection | `co_await acceptor.async_accept()` |
+| Read some bytes | `co_await socket.async_read_some(buffer)` |
+| Read exact/until | `co_await async_read(stream, buf)` / `async_read_until(stream, buf, delim)` |
+| Write all | `co_await async_write(stream, buffer)` |
+| Connect | `co_await async_connect(socket, endpoints)` |
+| Resolve DNS | `co_await resolver.async_resolve(host, port)` |
+| Wait timer | `co_await timer.async_wait()` |
+| TLS handshake | `co_await stream.async_handshake(type)` |
+| Get executor | `co_await asio::this_coro::executor` |