Files
MobileGL/MobileGL/MG_Remote/Transport/Framing.h
T
swung0x48 c1a7ffac94 [Fix] (MG_Remote, Transport): give descriptor offers their own condition variable, cap the ring at what a 32-bit size field can describe, and keep the frontend umbrella out of Framing.h
- InProcessChannel::Direction served two different predicates from one
  condition_variable signalled with notify_one, so a SendFrame wakeup could be
  delivered to a thread blocked in ReceiveFd, which re-tests its own predicate
  and goes back to sleep - leaving a queued message undelivered until some
  unrelated later event. ITransport narrows the contract to one dedicated
  reader thread, but that is a comment, not a mechanism, and the first caller
  that splits its reader should not have to discover this. Offers now have
  their own fdCv, and Close() notifies both.

- RingProducer/RingConsumer accepted any power-of-two capacity while
  RingRecordHeader::size is 32-bit by wire contract (plan section 8.1 ->
  PLAN.md section 6.3: 8-byte RecHeader). At 4 GiB or more a record's size -
  or a wrap filler's, which is sized by the distance to the boundary - would be
  truncated on the way in, and the consumer would then bounds-check the
  truncated value against the real one. kMaxRingCapacity rejects that at
  construction, the same class of guard as the power-of-two and
  smaller-than-a-header checks beside it. Unreachable today (SEG_CMD 8 MiB,
  SEG_STAGE 32 MiB), which is the point of catching it now.

- Framing.h included MG_Util/Debug/Log.h, which includes Includes.h, the GL
  frontend's umbrella header: 661 headers by `clang++ -H`. It is the one header
  under Transport/ that broke the rule ITransport.h states for this layer
  ("nothing about a byte pipe needs the GL frontend's umbrella header"), which
  matters when the server-side binary links this and when the include-graph
  purity gate of plan section 10.3 (gate A, asserted on -H output rather than
  on symbols) lands. Its three error paths now call WireLogError, declared in a
  new dependency-free WireLog.h whose .cpp owns the umbrella. Framing.h is down
  to 134 headers, none of them MG_State, Includes.h or Log.h.

- Two documentation corrections. ITransport::Shutdown documented a one-sided
  "releases the endpoint" while InProcessTransport::Shutdown closes both
  directions - which is what closing a socket does, so the spawn transport will
  behave the same way; the interface now says whole-connection teardown, and
  keeps the promise that queued messages stay readable until drained.
  InProcessTransport.h cited a CMake option
  MOBILEGL_BUILD_DISAGGREGATED_INPROC that grep finds nowhere: plan appendix B
  reserves it for the role-isolation shim, this skeleton does not add it, and
  the delivery mode is a runtime choice (MOBILEGL_TRANSPORT), not a build one.

- Evidence: both configurations reconfigured and rebuilt; nm --defined-only on
  the OFF build still reports 0 MG_Remote symbols and the ldd dependency set is
  byte-identical to the OFF link (plan section 10.3, the two surviving
  byte-level equalities). Negative controls: removing the capacity ceiling
  makes RingTest.RejectsACapacityTheRecordHeaderCannotDescribe fail on both
  roles; collapsing fdCv back into cv makes
  InProcessTransportTest.AFrameWakeupIsNotEatenByAWaiterOnDescriptors fail at
  3950ms against its 2000ms bound.
2026-09-05 20:16:50 -04:00

209 lines
8.7 KiB
C++

// MobileGL - MobileGL/MG_Remote/Transport/Framing.h
// Copyright (c) 2025-2026 MobileGL-Dev
// Licensed under the GNU Lesser General Public License v3.0:
// https://www.gnu.org/licenses/gpl-3.0.txt
// https://www.gnu.org/licenses/lgpl-3.0.txt
// SPDX-License-Identifier: LGPL-3.0-only
// End of Source File Header
// Control-channel wire framing: [u32 magic 'MGLF'][u32 payloadLength][payload].
// Length excludes the 8-byte header and is capped at 64 MiB.
//
// Two defects of the earlier branch's codec are fixed here, and both are the
// reason this file is not a copy of it:
//
// 1. Its Feed() unconditionally returned OK and its header peek merely
// returned false on a bad magic or an oversized length. A corrupt or
// desynchronized stream therefore turned into a silent, permanent hang -
// the reader kept waiting for a message that could never be parsed, with
// no error anywhere. Here a violation latches a failed state, is logged at
// ERROR, and every later call returns MOBILEGL_ERR_PROTOCOL_MISMATCH.
//
// 2. Its receive path failed the call and consumed the message when the
// caller's buffer was too small, wedging the stream. Here
// MOBILEGL_ERR_BUFFER_TOO_SMALL reports the required size and KEEPS the
// message queued.
//
// The reader is a plain byte-stream reassembler: it never assumes a read()
// returned a whole frame.
#pragma once
#include "../Protocol/mg_protocol_base.h"
// NOT <MG_Util/Debug/Log.h>: that header pulls the GL frontend's umbrella into
// every translation unit that reassembles a frame. See WireLog.h.
#include "WireLog.h"
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <vector>
namespace MobileGL::MG_Remote::Transport {
// 'MGLF', little-endian on the wire (both ends are the same machine).
inline constexpr std::uint32_t kFrameMagic = 0x464C474Du;
inline constexpr std::uint64_t kFrameHeaderSize = 8;
inline constexpr std::uint64_t kMaxFramePayloadSize = 64ull * 1024 * 1024;
// Compaction threshold: consumed bytes are dropped from the front once
// enough of them accumulate, so a long-lived reader neither memmoves per
// message nor grows without bound.
inline constexpr std::uint64_t kFrameReaderCompactThreshold = 64ull * 1024;
// Appends one framed message to `out`.
inline MobileGLResult AppendFrame(std::vector<std::uint8_t>& out, const void* payload,
std::uint64_t size) {
if (size > kMaxFramePayloadSize) {
WireLogError("MG_Remote framing: refusing to send a %llu byte payload (cap %llu); "
"bulk bytes belong in shm",
static_cast<unsigned long long>(size),
static_cast<unsigned long long>(kMaxFramePayloadSize));
return MOBILEGL_ERR_INVALID_ARGUMENT;
}
if (size != 0 && payload == nullptr) {
return MOBILEGL_ERR_INVALID_ARGUMENT;
}
std::uint8_t header[kFrameHeaderSize];
const std::uint32_t magic = kFrameMagic;
const std::uint32_t length = static_cast<std::uint32_t>(size);
std::memcpy(header + 0, &magic, sizeof(magic));
std::memcpy(header + 4, &length, sizeof(length));
out.insert(out.end(), header, header + kFrameHeaderSize);
const auto* bytes = static_cast<const std::uint8_t*>(payload);
out.insert(out.end(), bytes, bytes + size);
return MOBILEGL_OK;
}
// Incremental frame extractor over a raw byte stream.
class FrameReader {
public:
// Feeds raw stream bytes. Validates the frame header the moment enough
// bytes for one exist - a bad magic or an oversized length is reported
// here, not swallowed.
MobileGLResult Feed(const void* data, std::uint64_t size) {
if (m_failed) {
return MOBILEGL_ERR_PROTOCOL_MISMATCH;
}
if (size != 0) {
if (data == nullptr) {
return MOBILEGL_ERR_INVALID_ARGUMENT;
}
const auto* bytes = static_cast<const std::uint8_t*>(data);
m_buffer.insert(m_buffer.end(), bytes, bytes + size);
}
return ParseHeader();
}
bool Failed() const { return m_failed; }
bool HasMessage() const {
return !m_failed && m_haveHeader && Available() >= kFrameHeaderSize + m_pendingSize;
}
// Size of the next complete message, or 0 when none is complete yet.
std::uint64_t PendingMessageSize() const { return HasMessage() ? m_pendingSize : 0; }
std::uint64_t BufferedBytes() const { return Available(); }
// Copies the next complete message out.
// MOBILEGL_OK - copied, *outSize set, message consumed
// MOBILEGL_ERR_BUFFER_TOO_SMALL - *outSize = required size, message KEPT
// MOBILEGL_ERR_TIMEOUT - no complete message buffered
// MOBILEGL_ERR_PROTOCOL_MISMATCH- the stream is latched failed
MobileGLResult TakeMessage(MobileGLMutableByteSpan buffer, std::uint64_t* outSize) {
if (m_failed) {
return MOBILEGL_ERR_PROTOCOL_MISMATCH;
}
if (!HasMessage()) {
return MOBILEGL_ERR_TIMEOUT;
}
if (outSize != nullptr) {
*outSize = m_pendingSize;
}
if (buffer.size < m_pendingSize) {
// The message stays queued; the caller retries with a big
// enough buffer.
return MOBILEGL_ERR_BUFFER_TOO_SMALL;
}
if (m_pendingSize != 0) {
if (buffer.data == nullptr) {
return MOBILEGL_ERR_INVALID_ARGUMENT;
}
std::memcpy(buffer.data, m_buffer.data() + m_readPos + kFrameHeaderSize,
static_cast<std::size_t>(m_pendingSize));
}
Consume();
return MOBILEGL_OK;
}
// Convenience overload that sizes the destination itself.
MobileGLResult TakeMessage(std::vector<std::uint8_t>& out) {
if (m_failed) {
return MOBILEGL_ERR_PROTOCOL_MISMATCH;
}
if (!HasMessage()) {
return MOBILEGL_ERR_TIMEOUT;
}
const auto* first = m_buffer.data() + m_readPos + kFrameHeaderSize;
out.assign(first, first + m_pendingSize);
Consume();
return MOBILEGL_OK;
}
private:
std::uint64_t Available() const { return m_buffer.size() - m_readPos; }
MobileGLResult ParseHeader() {
if (m_haveHeader || Available() < kFrameHeaderSize) {
return MOBILEGL_OK;
}
std::uint32_t magic = 0;
std::uint32_t length = 0;
std::memcpy(&magic, m_buffer.data() + m_readPos, sizeof(magic));
std::memcpy(&length, m_buffer.data() + m_readPos + 4, sizeof(length));
if (magic != kFrameMagic) {
m_failed = true;
WireLogError("MG_Remote framing: bad frame magic 0x%08X (expected 0x%08X); the "
"control stream is desynchronized and this transport is now dead",
magic, kFrameMagic);
return MOBILEGL_ERR_PROTOCOL_MISMATCH;
}
if (length > kMaxFramePayloadSize) {
m_failed = true;
WireLogError("MG_Remote framing: frame length %u exceeds the %llu byte cap; "
"refusing to allocate on a peer-supplied length",
length, static_cast<unsigned long long>(kMaxFramePayloadSize));
return MOBILEGL_ERR_PROTOCOL_MISMATCH;
}
m_pendingSize = length;
m_haveHeader = true;
return MOBILEGL_OK;
}
void Consume() {
m_readPos += kFrameHeaderSize + m_pendingSize;
m_pendingSize = 0;
m_haveHeader = false;
if (m_readPos == m_buffer.size()) {
m_buffer.clear();
m_readPos = 0;
} else if (m_readPos >= kFrameReaderCompactThreshold) {
m_buffer.erase(m_buffer.begin(),
m_buffer.begin() + static_cast<std::ptrdiff_t>(m_readPos));
m_readPos = 0;
}
// Header of the next message may already be buffered.
(void)ParseHeader();
}
std::vector<std::uint8_t> m_buffer;
std::uint64_t m_readPos = 0;
std::uint64_t m_pendingSize = 0;
bool m_haveHeader = false;
bool m_failed = false;
};
} // namespace MobileGL::MG_Remote::Transport