Milestone v0.5.0: Bidirectional Packet Relay Engine

Author: HelloPrincePal

CHANGELOG.md

@@ -16,6 +16,22 @@ Format:
 
 ## [Unreleased]
 
+*(Add entries here as you work. Move to a version block on each git push.)*
+
+---
+
+## v0.5.0 — 2026-03-28
+
+### 2026-03-28 14:35 — Implement Bidirectional Packet Relay Engine
+- What: Added `Relay` struct to bridge macOS `utun` packets and USB Bulk endpoints, complete with Ethernet and RNDIS encapsulation synthesis.
+- Why: Milestone v0.5.0; this is the core engine that actually moves data between the phone and the Mac.
+- Files: `internal/daemon/relay.go`, `internal/usb/device.go`, `internal/rndis/messages.go`
+- Breaking: yes (switched to asynchronous relay loops)
+
+---
+
+## v0.4.0 — 2026-03-28
+
 ### 2026-03-28 14:00 — Implement utun creation on macOS
 - What: Created `internal/tun/utun_darwin.go` to support spawning virtual network interfaces via `AF_SYSTEM` / `SYSPROTO_CONTROL`; integrated into daemon callback.
 - Why: Milestone v0.4.0; enable the OS to talk to our daemon via a standard network handle.

VERSIONS.md

@@ -10,6 +10,13 @@ v1.0.0 = MVP complete and working on M1/M2/M3.
 
 ---
 
+## v0.5.0 — 2026-03-28
+- Milestone: Packet Relay Engine
+- What works: Bidirectional shuttle service over USB Bulk Endpoints. Reads IP packets from macOS `utun`, synthesizes Ethernet headers, wraps in RNDIS encapsulation, and pushes to Android. Strips RNDIS headers from Android replies and writes to `utun`.
+- Next: IP assignment and DHCP handling.
+
+---
+
 ## v0.4.0 — 2026-03-28
 - Milestone: utun interface creation
 - What works: Native macOS virtual interface creation (`utun`). The daemon now spawns a real network interface on the Mac when the phone connects.

internal/daemon/daemon.go

@@ -46,7 +46,8 @@ func (d *Daemon) Run() error {
 			Msg("Android RNDIS device connected!")
 
 		session := rndis.NewSession(dev)
-		if err := session.Handshake(); err != nil {
+		phoneMAC, err := session.Handshake()
+		if err != nil {
 			log.Error().Str("component", "daemon").Err(err).Msg("RNDIS Handshake failed")
 			return
 		}
@@ -62,33 +63,30 @@ func (d *Daemon) Run() error {
 		log.Info().
 			Str("component", "daemon").
 			Str("interface", iface.Name()).
-			Msg("Virtual network interface created and ACTIVE. You can now run 'ifconfig' on it.")
+			Msg("Virtual network interface created and ACTIVE.")
+
+		// Milestone v0.5.0: The Relay Engine
+		relay, err := NewRelay(dev, iface, phoneMAC)
+		if err != nil {
+			log.Error().Str("component", "daemon").Err(err).Msg("Failed to initialize Relay")
+			time.Sleep(2 * time.Second) // prevent busy loops on retry
+			return
+		}
 
-		// Keep the session alive until the watcher signals detachment.
-		// For now, we'll just block on a channel that is closed when the phone is unplugged.
-		// In Milestone v0.5.0, this handles the Packet Relay loop.
-		
 		stopChan := make(chan bool)
 		watcher.OnDetach(func() {
 			log.Info().Str("component", "daemon").Msg("Android RNDIS device detached.")
+			relay.Stop()
 			close(stopChan)
 		})
 
-		// Simple stay-alive logger to show the pipe is still open
-		ticker := time.NewTicker(30 * time.Second)
-		defer ticker.Stop()
-		go func() {
-			for {
-				select {
-				case <-ticker.C:
-					log.Debug().Str("component", "daemon").Str("interface", iface.Name()).Msg("RNDIS session active")
-				case <-stopChan:
-					return
-				}
-			}
-		}()
-
-		// Block here until phone is detached
+		// Start the relay loop (blocks until error or stop)
+		if err := relay.Start(); err != nil {
+			log.Error().Str("component", "daemon").Err(err).Msg("Relay ended with error")
+			time.Sleep(1 * time.Second)
+		}
+
+		// Wait here until phone is detached
 		<-stopChan
 	})
 

internal/daemon/relay.go

@@ -0,0 +1,159 @@
+package daemon
+
+import (
+	"context"
+	"encoding/binary"
+	"fmt"
+	"io"
+
+	"github.com/google/gousb"
+	"github.com/princePal/droidtether/internal/rndis"
+	"github.com/princePal/droidtether/internal/tun"
+	"github.com/princePal/droidtether/internal/usb"
+	"github.com/rs/zerolog/log"
+)
+
+// Relay handles the packet shuttle between USB Bulk and Tunnel interface.
+type Relay struct {
+	dev   *usb.Device
+	tun   tun.Interface
+	ctx   context.Context
+	cancel context.CancelFunc
+
+	usbIn  *gousb.InEndpoint
+	usbOut *gousb.OutEndpoint
+
+	phoneMAC []byte
+}
+
+// NewRelay creates a new bidirectional relay.
+func NewRelay(dev *usb.Device, tun tun.Interface, phoneMAC []byte) (*Relay, error) {
+	in, out, err := dev.OpenBulkEndpoints()
+	if err != nil {
+		return nil, err
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	return &Relay{
+		dev:      dev,
+		tun:      tun,
+		ctx:      ctx,
+		cancel:   cancel,
+		usbIn:    in,
+		usbOut:   out,
+		phoneMAC: phoneMAC,
+	}, nil
+}
+
+// Start spawns the relay goroutines and blocks until context is cancelled or an error occurs.
+func (r *Relay) Start() error {
+	errChan := make(chan error, 2)
+
+	// Mac -> Phone (Tunnel -> USB)
+	go func() {
+		buf := make([]byte, 2048)
+		for {
+			select {
+			case <-r.ctx.Done():
+				return
+			default:
+				n, err := r.tun.Read(buf)
+				if err != nil {
+					if err != io.EOF {
+						errChan <- fmt.Errorf("relay: tun read error: %w", err)
+					}
+					return
+				}
+
+				// macOS utun header is 4 bytes [0 0 0 2] for IPv4. Strip it.
+				if n < 4 {
+					continue
+				}
+				rawIP := buf[4:n]
+
+				// Construct Ethernet Header (L2)
+				// [DstMAC(6)] [SrcMAC(6)] [Type(2)]
+				eth := make([]byte, 14+len(rawIP))
+				copy(eth[0:6], r.phoneMAC)
+				copy(eth[6:12], []byte{0x02, 0x00, 0x00, 0x00, 0x00, 0x01})
+				binary.BigEndian.PutUint16(eth[12:14], 0x0800) // IPv4
+				copy(eth[14:], rawIP)
+
+				// Wrap in RNDIS (L1-ish)
+				pkt := rndis.EncapsulatePacket(eth)
+				_, err = r.usbOut.Write(pkt)
+				if err != nil {
+					errChan <- fmt.Errorf("relay: usb write error: %w", err)
+					return
+				}
+				log.Info().Str("component", "relay").Int("bytes", len(pkt)).Msg("Sent packet to phone")
+			}
+		}
+	}()
+
+
+	// Phone -> Mac (USB -> Tunnel)
+	go func() {
+		buf := make([]byte, 16384)
+		for {
+			select {
+			case <-r.ctx.Done():
+				return
+			default:
+				n, err := r.usbIn.Read(buf)
+				if err != nil {
+					errChan <- fmt.Errorf("relay: usb read error: %w", err)
+					return
+				}
+
+				offset := 0
+				for offset < n {
+					msg := buf[offset:]
+					if len(msg) < 8 {
+						break
+					}
+					msgType := binary.LittleEndian.Uint32(msg[0:4])
+					msgLen := int(binary.LittleEndian.Uint32(msg[4:8]))
+					
+					if msgType == rndis.MsgPacket && msgLen > 44 {
+						ethPkt, err := rndis.DecapsulatePacket(msg[:msgLen])
+						if err == nil && len(ethPkt) > 14 {
+							// Strip Ethernet header (14 bytes)
+							rawIP := ethPkt[14:]
+							
+							// Prepend macOS utun header [0 0 0 2]
+							outBuf := make([]byte, 4+len(rawIP))
+							binary.BigEndian.PutUint32(outBuf[0:4], 2)
+							copy(outBuf[4:], rawIP)
+							
+							_, _ = r.tun.Write(outBuf)
+							log.Info().Str("component", "relay").Int("bytes", len(outBuf)).Msg("Received packet from phone")
+						}
+					}
+					
+					if msgLen == 0 {
+						break
+					}
+					offset += msgLen
+				}
+			}
+		}
+	}()
+
+
+	log.Info().Str("component", "relay").Msg("Bidirectional packet relay started")
+	
+	// Wait for error or shutdown
+	select {
+	case err := <-errChan:
+		r.cancel()
+		return err
+	case <-r.ctx.Done():
+		return nil
+	}
+}
+
+// Stop shuts down the relay.
+func (r *Relay) Stop() {
+	r.cancel()
+}

internal/rndis/messages.go

@@ -146,3 +146,45 @@ func UnmarshalSetCmplt(data []byte) (uint32, uint32, error) { // returns Request
 	}
 	return binary.LittleEndian.Uint32(data[8:12]), binary.LittleEndian.Uint32(data[12:16]), nil
 }
+
+// EncapsulatePacket wraps a raw Ethernet packet with an RNDIS header.
+func EncapsulatePacket(packet []byte) []byte {
+	headerLen := 44
+	totalLen := headerLen + len(packet)
+	// RNDIS packets should be padded to 8-byte boundaries for some devices
+	padding := (8 - (totalLen % 8)) % 8
+	
+	b := make([]byte, totalLen+padding)
+	binary.LittleEndian.PutUint32(b[0:4], MsgPacket)
+	binary.LittleEndian.PutUint32(b[4:8], uint32(totalLen+padding))
+	binary.LittleEndian.PutUint32(b[8:12], 36) // DataOffset (relative to byte 8)
+	binary.LittleEndian.PutUint32(b[12:16], uint32(len(packet)))
+	// Bytes 16-43 are reserved/optional fields (offset/length for OOB data, info, etc.)
+	// We leave them zeroed.
+	
+	copy(b[44:], packet)
+	return b
+}
+
+// DecapsulatePacket strips the RNDIS header and returns the raw Ethernet packet.
+func DecapsulatePacket(data []byte) ([]byte, error) {
+	if len(data) < 44 {
+		return nil, fmt.Errorf("packet: too short")
+	}
+	msgType := binary.LittleEndian.Uint32(data[0:4])
+	if msgType != MsgPacket {
+		return nil, fmt.Errorf("packet: not a data packet (0x%08X)", msgType)
+	}
+
+	dataOff := binary.LittleEndian.Uint32(data[8:12])
+	dataLen := binary.LittleEndian.Uint32(data[12:16])
+
+	start := int(8 + dataOff)
+	end := start + int(dataLen)
+
+	if end > len(data) {
+		return nil, fmt.Errorf("packet: payload out of bounds")
+	}
+
+	return data[start:end], nil
+}

internal/rndis/rndis.go

@@ -22,7 +22,7 @@ func NewSession(dev *usb.Device) *Session {
 }
 
 // Handshake performs the RNDIS INIT -> QUERY(MAC) -> SET(FILTER) sequence.
-func (s *Session) Handshake() error {
+func (s *Session) Handshake() ([]byte, error) {
 	log.Info().Str("component", "rndis").Msg("Starting RNDIS handshake...")
 
 	// 1. Send INIT
@@ -33,20 +33,20 @@ func (s *Session) Handshake() error {
 	}
 
 	if err := s.sendControl(initMsg.Marshal()); err != nil {
-		return fmt.Errorf("rndis: failed to send INIT: %w", err)
+		return nil, fmt.Errorf("rndis: failed to send INIT: %w", err)
 	}
 
 	initResp, err := s.receiveControl()
 	if err != nil {
-		return fmt.Errorf("rndis: failed to receive INIT_CMPLT: %w", err)
+		return nil, fmt.Errorf("rndis: failed to receive INIT_CMPLT: %w", err)
 	}
 
 	initCmplt, err := UnmarshalInitializeCmplt(initResp)
 	if err != nil {
-		return err
+		return nil, err
 	}
 	if initCmplt.Status != StatusSuccess {
-		return fmt.Errorf("rndis: INIT failed with status 0x%08X", initCmplt.Status)
+		return nil, fmt.Errorf("rndis: INIT failed with status 0x%08X", initCmplt.Status)
 	}
 
 	log.Debug().
@@ -62,17 +62,17 @@ func (s *Session) Handshake() error {
 	}
 
 	if err := s.sendControl(queryMac.Marshal()); err != nil {
-		return fmt.Errorf("rndis: failed to query MAC: %w", err)
+		return nil, fmt.Errorf("rndis: failed to query MAC: %w", err)
 	}
 
 	queryResp, err := s.receiveControl()
 	if err != nil {
-		return fmt.Errorf("rndis: failed to receive MAC_QUERY_CMPLT: %w", err)
+		return nil, fmt.Errorf("rndis: failed to receive MAC_QUERY_CMPLT: %w", err)
 	}
 
 	macCmplt, err := UnmarshalQueryCmplt(queryResp)
 	if err != nil {
-		return err
+		return nil, err
 	}
 	log.Info().
 		Str("component", "rndis").
@@ -88,24 +88,24 @@ func (s *Session) Handshake() error {
 	}
 
 	if err := s.sendControl(setFilter.Marshal()); err != nil {
-		return fmt.Errorf("rndis: failed to set packet filter: %w", err)
+		return nil, fmt.Errorf("rndis: failed to set packet filter: %w", err)
 	}
 
 	setResp, err := s.receiveControl()
 	if err != nil {
-		return fmt.Errorf("rndis: failed to receive SET_CMPLT: %w", err)
+		return nil, fmt.Errorf("rndis: failed to receive SET_CMPLT: %w", err)
 	}
 
 	_, setStatus, err := UnmarshalSetCmplt(setResp)
 	if err != nil {
-		return err
+		return nil, err
 	}
 	if setStatus != StatusSuccess {
-		return fmt.Errorf("rndis: SET filter failed with status 0x%08X", setStatus)
+		return nil, fmt.Errorf("rndis: SET filter failed with status 0x%08X", setStatus)
 	}
 
 	log.Info().Str("component", "rndis").Msg("RNDIS handshake complete. Device in DATA mode.")
-	return nil
+	return macCmplt.Payload, nil
 }
 
 // sendControl sends an encapsulated RNDIS command via USB control endpoint.