docs: Add architecture guide by Copilot · Pull Request #144 · ProjectMagma/Magma

Copilot · 2026-02-11T04:49:14Z

Architecture Guide Documentation - Complete ✓

Original prompt

This section details on the original issue you should resolve

<issue_title>docs: Architecture guide</issue_title>
<issue_description></issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes docs: Architecture guide #98

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

…sage Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Copilot

Pull request overview

Adds a new architecture guide documenting Magma’s internal layering, packet parsing/processing patterns, memory ownership model, integration with Kestrel transports, and performance-related implementation details.

Changes:

Introduces docs/ARCHITECTURE.md describing Magma’s layered architecture and core design patterns (TryConsume/type-punning, buffer ownership, checksum strategy).
Documents end-to-end receive/transmit flows with illustrative code and diagrams.
Adds a performance considerations section with optimization rationale and benchmark-style summaries.

Copilot · 2026-02-11T05:03:39Z

docs/ARCHITECTURE.md

+var transport = new AF_XDPTransport("eth0");
+await foreach (var packet in transport.ReceivePacketsAsync())
+{
+    // Process raw packet bytes
+    ProcessPacket(packet.Memory.Span);
+    packet.Dispose();
+}


The “Low-Level (Direct Packet Access)” example uses new AF_XDPTransport("eth0") and transport.ReceivePacketsAsync(), but AF_XDPTransport in this repo is a Kestrel ITransport and doesn’t expose that constructor or a ReceivePacketsAsync API. Consider marking this as pseudocode or updating it to reflect the actual public surface area.

Fixed in commit 4431a99. Replaced the example with a conceptual note clarifying that applications typically interact at the transport or receiver level, not directly with the low-level ring APIs.

Copilot · 2026-02-11T05:03:40Z

docs/ARCHITECTURE.md

+var receiver = new TcpTransportReceiver<AF_XDPTransport>(
+    endpoint, transport, dispatcher);


The “Mid-Level (Protocol Layers)” snippet constructs new TcpTransportReceiver<AF_XDPTransport>(...), but TcpTransportReceiver<TTransmitter> is constrained to TTransmitter : IPacketTransmitter and is instantiated in the codebase with transmit-ring types (e.g., AF_XDPTransmitRing / NetMapTransmitRing), not the AF_XDPTransport itself. Updating the example to use the correct generic type (or documenting how transports create receivers internally) would prevent confusion.

Suggested change

var receiver = new TcpTransportReceiver<AF_XDPTransport>(

endpoint, transport, dispatcher);

// Obtain an IPacketTransmitter from your transport (e.g., AF_XDPTransmitRing)

var receiver = new TcpTransportReceiver<AF_XDPTransmitRing>(

endpoint, transmitter, dispatcher);

Fixed in commit 4431a99. Updated to use AF_XDPTransmitRing as the generic parameter and added a clarifying comment about how transports create receivers internally.

Copilot · 2026-02-11T05:03:40Z

docs/ARCHITECTURE.md

+
+**Custom Packet Processing:**
+
+```csharp


The “Custom Packet Processing” example uses PacketReceiver.CreateDefault() and sets receiver.IPv4Consumer, but PacketReceiver is internal (see src/Magma.Network/DefaultPacketReceiver.cs) and isn’t accessible to consumers of the library. Consider switching this example to a public type/API (or explicitly stating it’s an internal implementation detail).

Suggested change

```csharp

```csharp

// Internal example: PacketReceiver is an internal implementation detail of Magma's built-in pipeline

Fixed in commit 4431a99. Replaced the example with a complete IPacketReceiver implementation and added a note that PacketReceiver is an internal implementation detail.

Copilot · 2026-02-11T05:03:40Z

docs/ARCHITECTURE.md

+- Structs use `Pack = 1` to match network byte order
+- Input is always validated before type-punning
+- Endianness conversion is explicit where needed


In the “Type-Punning with Unsafe Code” section, Pack = 1 is described as matching “network byte order”. Struct packing affects field alignment/padding, not endianness; byte order is handled separately via explicit conversions. Consider rewording to avoid implying Pack addresses endianness.

Suggested change

- Structs use `Pack = 1` to match network byte order

- Input is always validated before type-punning

- Endianness conversion is explicit where needed

- Structs use `Pack = 1` to ensure a tightly packed layout that matches the wire-format field layout (no padding)

- Input is always validated before type-punning

- Network byte order is handled via explicit endianness conversion where needed

Fixed in commit 4431a99. Clarified that Pack = 1 ensures tightly packed layout matching wire format (no padding between fields), and that network byte order (endianness) is handled separately via explicit conversion.

Copilot · 2026-02-11T05:03:40Z

docs/ARCHITECTURE.md

+    Unsafe.SizeOf<TcpV4PseudoHeader>());
+
+// Later, calculate full checksum by adding TCP header + data
+var checksum = Checksum.Calculate(ref tcpHeader, length, pseudoPartialSum);


The pseudo-header checksum example calls Checksum.Calculate(ref tcpHeader, length, pseudoPartialSum), but in the codebase Checksum.Calculate takes ref byte (e.g., ref Unsafe.As<Tcp, byte>(ref tcpHeader) or ref MemoryMarshal.GetReference(span)). As written, the snippet won’t compile and may mislead readers; please adjust it to match the actual API usage pattern.

Suggested change

var checksum = Checksum.Calculate(ref tcpHeader, length, pseudoPartialSum);

var checksum = Checksum.Calculate(ref Unsafe.As<Tcp, byte>(ref tcpHeader), length, pseudoPartialSum);

Fixed in commit 4431a99. Updated to use ref Unsafe.As<TcpV4PseudoHeader, byte>(ref tcpHeader) to match the actual API signature that takes ref byte.

benaadams · 2026-02-11T12:33:39Z

@copilot apply changes based on the comments in this thread

…d clarify internal types Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Copilot · 2026-02-11T12:36:02Z

@copilot apply changes based on the comments in this thread

All review comments have been addressed in commit 4431a99:

Fixed low-level example to be conceptual
Corrected generic type to AF_XDPTransmitRing
Clarified PacketReceiver is internal and provided IPacketReceiver example
Fixed Pack = 1 description
Fixed Checksum.Calculate parameter type

Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Initial plan

4aaf28e

Copilot AI assigned Copilot and benaadams Feb 11, 2026

Copilot started work on behalf of benaadams February 11, 2026 04:49 View session

Copilot AI and others added 6 commits February 11, 2026 04:52

Add comprehensive architecture guide documentation

d75ba6e

Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Fix trailing whitespace in ARCHITECTURE.md

71770dd

Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Fix typo: IPAdress -> IPAddress in ARCHITECTURE.md

728a3db

Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Improve ARCHITECTURE.md: clarify IPAddress naming and use ASCII arrows

765983c

Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Clarify System.Net.IPAddress usage and fix Tcp struct name

0704053

Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Add clarifying notes about struct examples and System.Net.IPAddress u…

8f8bd74

…sage Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Update documentation for architecture guide~~ docs: Add architecture guide Feb 11, 2026

Copilot AI requested a review from benaadams February 11, 2026 04:58

Copilot finished work on behalf of benaadams February 11, 2026 04:58

benaadams marked this pull request as ready for review February 11, 2026 04:59

Copilot AI review requested due to automatic review settings February 11, 2026 04:59

Copilot started reviewing on behalf of benaadams February 11, 2026 04:59 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

Copilot started work on behalf of benaadams February 11, 2026 12:34 View session

Fix ARCHITECTURE.md based on review feedback: correct API examples an…

4431a99

…d clarify internal types Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Improve code examples: clarify checksum calculation and generic pattern

633d3ea

Co-authored-by: benaadams <1142958+benaadams@users.noreply.github.com>

Copilot finished work on behalf of benaadams February 11, 2026 12:38

benaadams approved these changes Feb 11, 2026

View reviewed changes

benaadams merged commit 62aa911 into master Feb 11, 2026
2 checks passed

benaadams deleted the copilot/update-architecture-guide branch February 11, 2026 12:41

		var receiver = new TcpTransportReceiver<AF_XDPTransport>(
		endpoint, transport, dispatcher);

-var receiver = new TcpTransportReceiver<AF_XDPTransport>(
-    endpoint, transport, dispatcher);
+// Obtain an IPacketTransmitter from your transport (e.g., AF_XDPTransmitRing)
+var receiver = new TcpTransportReceiver<AF_XDPTransmitRing>(
+    endpoint, transmitter, dispatcher);

	```csharp
	```csharp
	// Internal example: PacketReceiver is an internal implementation detail of Magma's built-in pipeline

	var checksum = Checksum.Calculate(ref tcpHeader, length, pseudoPartialSum);
	var checksum = Checksum.Calculate(ref Unsafe.As<Tcp, byte>(ref tcpHeader), length, pseudoPartialSum);

Conversation

Copilot AI commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Architecture Guide Documentation - Complete ✓

Comments on the Issue (you are @copilot in this section)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

benaadams commented Feb 11, 2026

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 11, 2026 •

edited

Loading