browser wasm

interfaces/Crafter.Network-WebTransport.cppm

@@ -0,0 +1,105 @@
+/*
+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