Wire.h File Reference

Milestone S2 wire format for the editor sandbox. See docs/design_docs/0023-editor_sandbox.md §"Wire format". More...

#include <cstdint>
#include <cstring>
#include <span>
#include <string>
#include <string_view>
#include <vector>

Include dependency graph for Wire.h:

This graph shows which files directly or indirectly include this file:

Classes
class	donner::editor::sandbox::WireWriter
	Append-only byte buffer writer. Cheap by design — a std::vector<uint8_t> owner with a few typed helpers. No growth policy beyond the vector's. More...
struct	donner::editor::sandbox::WireWriter::MessageToken
	Reserves a payload-length slot before the payload is encoded, returning a token the caller hands back to finishMessage() once the payload is complete. This avoids having to buffer the payload twice. More...
class	donner::editor::sandbox::WireReader
	Read cursor into an immutable byte span. Every read that could overflow the buffer returns false and leaves failed_ set, so callers can do their work without interleaved error checking and verify success at the end. More...

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.

Enumerations
enum class	donner::editor::sandbox::Opcode : uint32_t {   kInvalid = 0 ,   kStreamHeader = 1 ,   kBeginFrame = 10 ,   kEndFrame = 11 ,   kSetTransform = 20 ,   kPushTransform = 21 ,   kPopTransform = 22 ,   kPushClip = 30 ,   kPopClip = 31 ,   kPushIsolatedLayer = 40 ,   kPopIsolatedLayer = 41 ,   kSetPaint = 50 ,   kPushMask = 42 ,   kTransitionMaskToContent = 43 ,   kPopMask = 44 ,   kBeginPatternTile = 45 ,   kEndPatternTile = 46 ,   kDrawPath = 60 ,   kDrawRect = 61 ,   kDrawEllipse = 62 ,   kDrawImage = 63 ,   kDrawText = 64 ,   kPushFilterLayer = 47 ,   kPopFilterLayer = 48 ,   kUnsupported = 1000 }
	Opcodes. One per supported RendererInterface method, plus control ops. More...
enum class	donner::editor::sandbox::UnsupportedKind : uint32_t {   kPushFilterLayer = 1 ,   kPopFilterLayer = 2 ,   kPushMask = 3 ,   kTransitionMaskToContent = 4 ,   kPopMask = 5 ,   kBeginPatternTile = 6 ,   kEndPatternTile = 7 ,   kDrawImage = 8 ,   kDrawText = 9 ,   kPaintServerGradient = 10 ,   kPaintServerPattern = 11 ,   kPaintServerResolvedReference = 12 ,   kClipMaskChain = 13 ,   kColorNonRgba = 14 }
	Tag identifying which unsupported RendererInterface method was skipped.

Variables
constexpr uint32_t	donner::editor::sandbox::kWireMagic = 0x524E5244u
	Magic identifier ("DRNR" as a little-endian u32).
constexpr uint32_t	donner::editor::sandbox::kWireVersion = 1
	Wire format version. Bumped on any payload layout change.
constexpr uint32_t	donner::editor::sandbox::kMaxVectorCount = 10'000'000
	Hard caps the reader enforces on variable-length fields. Bounding these turns "parser allocates 18 exabytes" into a graceful kReadFailed.
constexpr uint32_t	donner::editor::sandbox::kMaxStringBytes = 10u * 1024u * 1024u
constexpr uint32_t	donner::editor::sandbox::kMaxFrameBytes = 256u * 1024u * 1024u
constexpr uint32_t	donner::editor::sandbox::kMaxPayloadBytes = kMaxFrameBytes

Detailed Description

Milestone S2 wire format for the editor sandbox. See docs/design_docs/0023-editor_sandbox.md §"Wire format".

A wire stream is a sequence of messages: u32 opcode, u32 payload_length, u8 payload[payload_length]. Everything is little-endian, which matches every platform Donner targets today. The first message per stream is a kStreamHeader carrying the magic + version so a reader can detect mixed versions up-front.

Every primitive read in WireReader is bounds-checked against the remaining buffer; every length field is capped by kMax* constants to bound untrusted input. The reader must never crash on adversarial bytes — this is the single most important invariant in the whole sandbox design.

---

Class Documentation

donner::editor::sandbox::WireWriter::MessageToken

struct donner::editor::sandbox::WireWriter::MessageToken

Reserves a payload-length slot before the payload is encoded, returning a token the caller hands back to finishMessage() once the payload is complete. This avoids having to buffer the payload twice.

Class Members
size_t	lengthOffset
size_t	payloadStart

Enumeration Type Documentation

Opcode

enum class donner::editor::sandbox::Opcode : uint32_t

strong

Opcodes. One per supported RendererInterface method, plus control ops.

Values are stable across patch releases; new opcodes append at the end. Do not renumber existing opcodes without bumping kWireVersion.

Enumerator
kStreamHeader	Stream metadata. Always the first message.
kBeginFrame	Frame lifecycle.
kSetTransform	Transform stack.
kPushClip	Clip stack. S2 encodes rect + path shapes; masks fall through as kUnsupported.
kPushIsolatedLayer	Isolated compositing layer (opacity + blend mode only).
kSetPaint	Paint state. S2 encodes PaintServer::None and PaintServer::Solid; any other paint-server variant (gradient, pattern, resolved reference) emits kUnsupported and the frame is considered lossy.
kPushMask	Mask sub-scope. Between kPushMask and kTransitionMaskToContent the stream carries the mask's own drawing commands (what will be used to derive the alpha mask). Between kTransitionMaskToContent and kPopMask the stream carries the masked content itself.
kBeginPatternTile	Pattern tile sub-scope. Draw calls between kBeginPatternTile and kEndPatternTile are recorded into an offscreen pattern surface instead of the main framebuffer, then used as the paint source for the next draw call.
kDrawPath	Drawing primitives.
kPushFilterLayer	Filter layer sub-scope (transparent pass-through in S2 — the primitive chain is not yet serialized, so the filter has no visual effect but preserves the compositing stack).
kUnsupported	Placeholder for any method SerializingRenderer can't faithfully encode (text — see UnsupportedKind). Payload is a single u32 identifying which kind was hit, for diagnostics.