105 lines
4.7 KiB
C++
105 lines
4.7 KiB
C++
/*
|
|
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
|