Crafter.Network/interfaces/Crafter.Network-WebTransport.cppm

/*
Crafter®.Network
Copyright (C) 2026 Catcrafts®
Catcrafts.net

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 3.0 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
*/

export module Crafter.Network:WebTransport;
import std;
import :ClientQUIC;

#ifndef CRAFTER_NETWORK_BROWSER
namespace Crafter {
    // Server-side handle to one accepted WebTransport-over-HTTP/3 session.
    // Constructed by ListenerHTTP when it receives an extended-CONNECT
    // request whose :path matches a registered WT route. Handed to the
    // user's route handler as the only argument.
    //
    // API shape mirrors ClientQUIC so application code can be written once
    // and used on either side of the wire — open bidi streams, register an
    // OnStream handler for peer-initiated streams, close the session.
    //
    // Lifetime: the session owns the CONNECT stream that was upgraded.
    // Destruction (or explicit Close()) FINs that stream, which the peer
    // interprets as session-end. Phase 1 does not emit a CLOSE_WEBTRANSPORT
    // _SESSION capsule — bare FIN is sufficient for Chrome / Firefox.
    //
    // Phase 1 scope:
    //   - bidirectional streams: OpenStream + OnStream
    //   - session close via Close() / destruction
    // Out of scope (later phases):
    //   - datagrams (SendDatagram / OnDatagram are stubs that no-op)
    //   - unidirectional streams (OpenStream(unidirectional=true) throws)
    //   - capsule protocol (DRAIN/CLOSE capsules)
    export class WebTransportSession {
    public:
        // Underlying QUIC stream id of the CONNECT stream. The peer
        // identifies streams that belong to this session by this number.
        std::uint64_t sessionId = 0;

        // Path the client connected to. Useful for routing within a single
        // wtRoutes handler that's registered against multiple paths.
        std::string path;

        WebTransportSession();
        ~WebTransportSession();
        WebTransportSession(const WebTransportSession&) = delete;
        WebTransportSession(WebTransportSession&&) noexcept;
        WebTransportSession& operator=(WebTransportSession&&) noexcept;

        // Open a new bidi stream toward the peer. The WT_STREAM prefix
        // (frame type + session id) is written to the stream automatically
        // before this returns; the caller's first Send* delivers the first
        // bytes of opaque payload. Throws on connection close.
        QUICStream OpenStream(bool unidirectional = false);

        // Register a handler for streams the peer opens against this
        // session. Already-buffered streams that arrived before the
        // handler was installed are drained into the new handler.
        void OnStream(std::function<void(QUICStream)> callback);

        // Register a handler for datagrams the peer sends on this
        // session. Phase 1 STUB — datagrams are not yet plumbed through.
        void OnDatagram(std::function<void(std::vector<char>)> callback);

        // Send a datagram. Phase 1 STUB — silently drops.
        void SendDatagram(const void* buffer, std::uint32_t size);

        // FIN the CONNECT stream. Subsequent OpenStream calls throw; any
        // pending receivers on owned streams will fail with the connection
        // close. Idempotent.
        void Close();

    private:
        struct Impl;
        std::unique_ptr<Impl> impl;
        friend class ListenerHTTP;
        friend void WebTransportInitialise(WebTransportSession&, ClientQUIC*, QUICStream,
                                           std::uint64_t, std::string);
        friend void WebTransportDeliverStream(WebTransportSession&, QUICStream);
    };

    // Internal — used by ListenerHTTP's WT demuxer. Not exported (and only
    // visible to other TUs within the Crafter.Network module).
    void WebTransportInitialise(WebTransportSession& session,
                                ClientQUIC* connection,
                                QUICStream connectStream,
                                std::uint64_t sessionId,
                                std::string path);
    void WebTransportDeliverStream(WebTransportSession& session, QUICStream stream);
}
#endif