Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
Stream.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
7#include <PhosphorChannel/phosphorchannel_export.h>
8
9#include <cstddef>
10#include <cstdint>
11#include <deque>
12#include <functional>
13#include <map>
14#include <memory>
15#include <set>
16#include <string>
17#include <string_view>
18
19// Several channels over one connected byte stream: a stream socket, or the
20// standard input and output of a process such as ssh, which passes no file
21// descriptors. The ssh process must not allocate a terminal (no -t): a
22// terminal rewrites the bytes. Each end begins with a hello that carries the
23// protocol version, and refuses the other end's version when it is not its
24// own.
25//
26// Each channel has its own flow control. The reader grants a window of
27// bytes, and the writer sends no more than the window until the reader has
28// read frames and returned their bytes. Each frame costs its size plus
29// Stream::FrameCost against the window. A full channel returns WouldBlock and
30// holds back no other channel. Frames go out in fragments, one fragment of
31// each channel in turn, so a large frame on one channel does not wait in
32// front of a small one on another for more than a few fragments, plus what
33// the kernel and the transport (ssh) already hold.
34//
35// A channel ends when its writer closes it and its reader has read every
36// frame (read() returned Closed). Then its id is free in that direction, and
37// the writer may open it again. The other end may open at most
38// Options::maxChannels channels at a time, with ids below
39// Options::maxChannelId, and the hello tells it both limits. Owners reuse ids
40// within the limit, as file descriptors are reused.
41//
42// tryWrite(), readable() and writable() never block. write(), pump(),
43// flush() and shutdown() block with their own poll. The owner polls readFd()
44// for input and writeFd() for output while wantsWrite(), and calls readable()
45// and writable(). Any call can queue output, reads included (a read returns
46// credit), so the owner checks wantsWrite() before each poll. Frames that
47// wait in a reader keep the window full and readFd() quiet: after each call
48// into the stream, the owner reads every reader until read() returns
49// something other than Frame, or does so in onReadable.
50//
51// Destroying the stream closes its file descriptors at once, and what still
52// waits to go out is lost. shutdown() ends a stream cleanly.
53//
54// All values on the wire are little-endian, so two computers of any byte
55// order agree.
56
57namespace PhosphorChannel {
58
59class Stream;
60
64class PHOSPHORCHANNEL_EXPORT StreamWriter
65{
66public:
67 StreamWriter(const StreamWriter&) = delete;
69
70 std::uint32_t id() const
71 {
72 return m_id;
73 }
74 const std::string& codec() const
75 {
76 return m_codec;
77 }
78
82 WriteResult tryWrite(std::string_view frame);
87 WriteResult write(std::string_view frame, int timeoutMs);
90 std::size_t maxFrame() const;
92 void close();
93
94private:
95 friend class Stream;
96 StreamWriter(Stream& stream, std::uint32_t id, std::string codec);
97
98 Stream& m_stream;
99 std::uint32_t m_id;
100 std::string m_codec;
101 std::size_t m_window = 0;
102 std::size_t m_credit = 0;
103 std::deque<std::string> m_queue;
104 std::size_t m_sent = 0;
105 bool m_granted = false;
106 bool m_closing = false;
107 bool m_closeSent = false;
108 bool m_released = false;
109 bool m_blocked = false;
110};
111
115class PHOSPHORCHANNEL_EXPORT StreamReader
116{
117public:
118 StreamReader(const StreamReader&) = delete;
120
121 std::uint32_t id() const
122 {
123 return m_id;
124 }
125 const std::string& codec() const
126 {
127 return m_codec;
128 }
129
136 ReadResult read(std::string& frame);
137
138private:
139 friend class Stream;
140 StreamReader(Stream& stream, std::uint32_t id, std::string codec);
141
142 Stream& m_stream;
143 std::uint32_t m_id;
144 std::string m_codec;
145 std::deque<std::string> m_frames;
146 std::string m_partial;
147 std::size_t m_peerCredit = 0;
148 std::size_t m_unreturned = 0;
149 std::size_t m_creditToSend = 0;
150 bool m_inFrame = false;
151 bool m_closed = false;
152 bool m_released = false;
153};
154
155class PHOSPHORCHANNEL_EXPORT Stream
156{
157public:
160 static constexpr std::size_t FrameCost = 64;
162 static constexpr std::size_t MinWindow = 1024;
163
164 struct Options
165 {
172 std::size_t window = std::size_t(4) << 20;
174 std::size_t fragment = 16 * 1024;
177 std::size_t maxChannels = 64;
182 std::uint32_t maxChannelId = 4096;
183 };
184
191 Stream(int readFd, int writeFd, Options options);
192 explicit Stream(int fd)
193 : Stream(fd, fd, Options())
194 {
195 }
197 Stream(const Stream&) = delete;
198 Stream& operator=(const Stream&) = delete;
199
208 StreamWriter* openWriter(std::uint32_t id, std::string codec, std::string* error);
210 StreamReader* reader(std::uint32_t id);
211
212 // The callbacks run after the stream handled what it read, never in the
213 // middle of a packet, in the order of the packets. They may call into the
214 // stream, and may destroy it: the call that ran them then returns false,
215 // or Closed, at once. A callback that throws leaves the call that ran it;
216 // the callbacks after it run in the next readable() or pump().
217
219 std::function<void(StreamReader&)> onReader;
228 std::function<void(StreamReader&)> onReadable;
230 std::function<void(StreamWriter&)> onWritable;
231
232 int readFd() const
233 {
234 return m_readFd;
235 }
236
244 int writeFd() const
245 {
246 return m_writeFd;
247 }
248 bool wantsWrite() const;
252 bool readable();
254 bool writable();
258 bool pump(int timeoutMs);
261 bool flush(int timeoutMs);
265 bool shutdown(int timeoutMs);
266
268 bool ready() const
269 {
270 return m_ready;
271 }
272
274 bool open() const
275 {
276 return m_error.empty() && !m_ended;
277 }
278
279 const std::string& error() const
280 {
281 return m_error;
282 }
283
284private:
285 friend class StreamWriter;
286 friend class StreamReader;
287
288 enum class Farewell {
289 Send,
290 Skip
291 };
292 enum class EventKind {
293 Opened,
294 Readable,
295 Writable
296 };
297 struct Event
298 {
299 EventKind kind;
300 std::uint32_t id;
301 };
302
303 bool canWrite() const
304 {
305 return m_error.empty() && !m_outputEnded;
306 }
307 void fail(std::string reason, Farewell farewell = Farewell::Send);
308 void refusePeer(std::string reason);
309 void sendFarewell();
310 void endOutput();
311 bool parseInput();
312 bool handlePacket(std::uint8_t type, std::uint8_t flags, std::uint32_t id, std::string_view payload);
313 bool handleHello(std::uint8_t type, std::string_view payload);
314 std::string helloMissing() const;
315 bool dispatch();
316 void queueControl(std::uint8_t type, std::uint32_t id, std::string_view payload);
317 void schedule();
318 void returnCredit(StreamReader& reader, std::size_t bytes);
319 void release(StreamReader& reader);
320 void announceEnd();
321 long writeOut(const char* bytes, std::size_t size);
322
323 Options m_options;
324 int m_readFd = -1;
325 int m_writeFd = -1;
326 int m_readFlags = -1;
327 int m_writeFlags = -1;
328 bool m_writeIsSocket = false;
329 std::unique_ptr<char[]> m_readBuffer;
330 std::string m_in;
331 std::size_t m_inHead = 0;
332 std::string m_out;
333 std::size_t m_outHead = 0;
334 std::string m_control;
335 std::set<std::uint32_t> m_creditDue;
336 std::set<std::uint32_t> m_releaseDue;
337 std::set<std::uint32_t> m_sending;
338 std::map<std::uint32_t, std::unique_ptr<StreamWriter>> m_writers;
339 std::map<std::uint32_t, std::unique_ptr<StreamReader>> m_readers;
340 std::deque<Event> m_events;
341 std::shared_ptr<bool> m_alive;
342 std::uint32_t m_nextTurn = 0;
343 std::size_t m_openReaders = 0;
344 std::size_t m_openWriters = 0;
345 std::size_t m_peerMaxChannels = 0;
346 std::uint32_t m_peerMaxChannelId = 0;
347 bool m_ready = false;
348 bool m_helloScheduled = false;
349 bool m_helloWritten = false;
350 bool m_ended = false;
351 bool m_outputEnded = false;
352 bool m_peerBroke = false;
353 std::string m_error;
354};
355
356} // namespace PhosphorChannel
std::uint32_t id() const
Definition Stream.h:121
StreamReader & operator=(const StreamReader &)=delete
const std::string & codec() const
Definition Stream.h:125
StreamReader(const StreamReader &)=delete
ReadResult read(std::string &frame)
The next complete frame, without waiting.
friend class Stream
Definition Stream.h:139
std::uint32_t id() const
Definition Stream.h:70
WriteResult write(std::string_view frame, int timeoutMs)
Waits up to timeoutMs (-1: no limit) for the window, and runs the stream meanwhile,...
StreamWriter(const StreamWriter &)=delete
const std::string & codec() const
Definition Stream.h:74
std::size_t maxFrame() const
The largest frame: the window less Stream::FrameCost.
StreamWriter & operator=(const StreamWriter &)=delete
friend class Stream
Definition Stream.h:95
WriteResult tryWrite(std::string_view frame)
Queues one frame without waiting.
void close()
No frame follows. The queued ones still go out.
Definition Stream.h:156
bool flush(int timeoutMs)
Writes until nothing waits, up to timeoutMs, and reads meanwhile.
StreamWriter * openWriter(std::uint32_t id, std::string codec, std::string *error)
Opens channel id for writing.
friend class StreamWriter
Definition Stream.h:285
int readFd() const
Definition Stream.h:232
Stream & operator=(const Stream &)=delete
bool pump(int timeoutMs)
One round of poll on readFd(), and on writeFd() while wantsWrite(), up to timeoutMs.
friend class StreamReader
Definition Stream.h:286
static constexpr std::size_t MinWindow
The smallest window.
Definition Stream.h:162
bool readable()
Reads what the fd has, up to a budget, and handles it.
bool open() const
The stream works: no failure and no end of its input.
Definition Stream.h:274
StreamReader * reader(std::uint32_t id)
The channel id that the other end opened, or nullptr.
int writeFd() const
-1 once the stream gave back an output fd separate from its input: after shutdown() got past its flus...
Definition Stream.h:244
bool shutdown(int timeoutMs)
Ends the stream cleanly: flushes, ends this end's output, and reads until the other end ends too,...
std::function< void(StreamReader &)> onReadable
A frame arrived on a reader, its writer closed it, or the stream ended or failed: read it until read(...
Definition Stream.h:228
static constexpr std::size_t FrameCost
What a frame costs against the window on top of its size, so that a window also bounds the number of ...
Definition Stream.h:160
bool ready() const
The hello of the other end arrived, with this end's version.
Definition Stream.h:268
std::function< void(StreamWriter &)> onWritable
A writer that returned WouldBlock may write again.
Definition Stream.h:230
Stream(int readFd, int writeFd, Options options)
Takes readFd and writeFd (the same fd for a socket), makes them non-blocking, and queues the hello.
Stream(int fd)
Definition Stream.h:192
bool writable()
Writes what waits. False when the stream failed.
const std::string & error() const
Why the stream failed. Empty while it works, and after a clean end.
Definition Stream.h:279
std::function< void(StreamReader &)> onReader
The other end opened a channel.
Definition Stream.h:219
Stream(const Stream &)=delete
Definition Channel.h:29
WriteResult
Definition Channel.h:43
ReadResult
Definition Channel.h:56
Definition Stream.h:165
std::uint32_t maxChannelId
The ids of the channels that the other end opens are below this.
Definition Stream.h:182
std::size_t maxChannels
The most channels that the other end may have open at once.
Definition Stream.h:177
std::size_t fragment
The largest fragment that this end sends: 1 KiB to 1 MiB.
Definition Stream.h:174
std::size_t window
The window, in bytes, that this end grants each channel that it reads.
Definition Stream.h:172