Implementation Checklist

A step-by-step guide for reimplementing Xray-core in another framework. Items are ordered by dependency — earlier items are needed by later ones.

Phase 1: Foundation

Buffer System

• [ ] Implement pooled byte buffer (8KB default size, sync.Pool equivalent)
• [ ] Start/end cursor for zero-copy slicing
• [ ] MultiBuffer (list of buffers) for batch I/O
• [ ] Buffer.UDP field for per-packet destination metadata
• [ ] Reader / Writer interfaces with ReadMultiBuffer() / WriteMultiBuffer()
• [ ] Copy(reader, writer) loop with activity timer callback
• [ ] BufferedWriter for batching header + first payload

Pipe

• [ ] Bidirectional pipe: New() → (Reader, Writer)
• [ ] Backpressure: configurable size limit, block on write when full
• [ ] Signal-based notification (non-blocking signal, blocking wait)
• [ ] Done instance for close notification
• [ ] Timeout read support (ReadMultiBufferTimeout)

Network Primitives

• [ ] Address type: IPv4, IPv6, Domain
• [ ] Destination type: Network (TCP/UDP) + Address + Port
• [ ] AddressParser: serialization (type byte + address) with port-then-address order

Session Context

• [ ] Inbound metadata: Source, Tag, User, Conn, CanSpliceCopy
• [ ] Outbound metadata: Target, OriginalTarget, RouteTarget, Tag, CanSpliceCopy
• [ ] Content metadata: Protocol, SniffingRequest, Attributes
• [ ] Context threading through all calls

Phase 2: Core Pipeline

Transport Link

• [ ] Link = (Reader, Writer) pair
• [ ] Pipe pair creation: inboundLink ↔ outboundLink (cross-wired)

Dispatcher

• [ ] Dispatch(ctx, destination) → Link (async routing)
• [ ] DispatchLink(ctx, destination, link) (sync routing)
• [ ] Pipe pair creation with stats wrappers
• [ ] cachedReader for sniffing without consuming data
• [ ] Sniffing pipeline: HTTP, TLS SNI, QUIC, BitTorrent, FakeDNS
• [ ] shouldOverride() decision logic
• [ ] RouteOnly vs full override
• [ ] routedDispatch() — forced tag → router → default outbound

Sniffer

• [ ] HTTP method + Host header detection
• [ ] TLS ClientHello SNI extraction
• [ ] QUIC Initial packet SNI extraction
• [ ] BitTorrent protocol detection
• [ ] FakeDNS metadata sniffer (IP pool lookup)
• [ ] Composite result (metadata domain + content protocol)
• [ ] 200ms timeout, max 2 attempts

Router

• [ ] Sequential rule evaluation (first match wins)
• [ ] Domain matchers: Full, Domain (suffix), Substr, Regex
• [ ] IP matchers: CIDR range with binary search
• [ ] Port matchers: exact and range
• [ ] Network, Protocol, User, InboundTag matchers
• [ ] GeoIP .dat file loading
• [ ] GeoSite .dat file loading
• [ ] Domain strategy: AsIs, IPIfNonMatch, IPOnDemand
• [ ] Balancers: random, roundRobin, leastPing, leastLoad

Feature System

• [ ] Feature registry (type → instance mapping)
• [ ] Dependency resolution (RequireFeatures equivalent)
• [ ] Config registry (protobuf type → factory function)
• [ ] Instance lifecycle: create → add features → resolve → start

Phase 3: Transport Layer

Transport Registry

• [ ] RegisterTransportDialer(name, dialer)
• [ ] RegisterTransportListener(name, listener)
• [ ] MemoryStreamConfig (runtime transport + security config)
• [ ] Dialer: Dial(ctx, dest) → Connection
• [ ] Listener: accepts connections with callback

TCP Transport

• [ ] Basic TCP dial and listen
• [ ] Socket options: SO_MARK, TCP_FASTOPEN, SO_REUSEPORT
• [ ] Happy Eyeballs (RFC 8305) for dual-stack
• [ ] TProxy / Redirect support (Linux)

TLS Security

• [ ] Standard TLS with configurable certificates
• [ ] uTLS fingerprinting (Chrome, Firefox, Safari, etc.)
• [ ] ALPN negotiation
• [ ] Certificate pinning

REALITY Security

• [ ] Server: impersonate real TLS server, Short ID auth
• [ ] Client: uTLS with custom SessionID
• [ ] No CA needed (uses target's real certificate)

Additional Transports (implement as needed)

• [ ] WebSocket (gorilla/websocket or equivalent)
• [ ] gRPC (bidirectional streaming)
• [ ] HTTPUpgrade (HTTP/1.1 Upgrade)
• [ ] SplitHTTP (POST upload + GET download)
• [ ] mKCP (UDP reliable transport)

Phase 4: Proxy Protocols

VLESS (Priority: High)

• [ ] Request header: version + UUID + addons + command + address
• [ ] Response header: version + addons
• [ ] Addons protobuf encoding/decoding
• [ ] User validator (UUID → account lookup)
• [ ] Inbound: decode header, authenticate, dispatch
• [ ] Outbound: encode header, dial transport, bidirectional copy
• [ ] Fallback system: name → ALPN → path
• [ ] UDP: length-prefixed packets (2B + payload)
• [ ] Mux detection and handling
• [ ] XUDP detection (session=0, network=UDP)

VLESS Vision (Priority: High for performance)

• [ ] TrafficState tracking per connection
• [ ] XtlsPadding: variable-length padding with command
• [ ] XtlsUnpadding: remove padding, parse commands
• [ ] XtlsFilterTls: detect TLS version from ServerHello
• [ ] VisionWriter: pad during handshake, switch to direct on AppData
• [ ] VisionReader: unpad, detect direct copy command
• [ ] Direct copy / splice support

Freedom (Priority: High)

• [ ] Direct outbound connection
• [ ] Domain strategy: AsIs, UseIP, UseIPv4, UseIPv6
• [ ] Destination override / redirect
• [ ] TLS ClientHello fragmentation (Fragment option)

VMess

• [ ] AEAD header: auth ID + length (AES-GCM) + command (AES-GCM)
• [ ] Body encryption: AES-128-GCM, ChaCha20-Poly1305, none
• [ ] Per-message nonce with counter
• [ ] Time-based authentication (±120s)

Trojan

• [ ] SHA224(password) + CRLF + command + address + CRLF
• [ ] Fallback support
• [ ] UDP framing (2B length + payload)

Shadowsocks

• [ ] AEAD: AES-128/256-GCM, ChaCha20-Poly1305
• [ ] Key derivation (HKDF)
• [ ] Replay protection (nonce filter)
• [ ] Shadowsocks 2022 (via sing-shadowsocks or reimplemented)

Other Protocols

• [ ] SOCKS5 (RFC 1928)
• [ ] HTTP proxy (CONNECT + plain)
• [ ] Dokodemo-door (transparent proxy)
• [ ] Blackhole (null sink)
• [ ] Loopback (re-enter routing)

Phase 5: Advanced Features

Mux

• [ ] Frame format: meta_len + session_id + status + option + address
• [ ] Client: ClientManager → ClientWorker pool
• [ ] Server: ServerWorker demux + dispatch
• [ ] Session management (create, data, close, keepalive)

XUDP

• [ ] PacketWriter: per-packet addressing in mux frames
• [ ] PacketReader: extract per-packet destination
• [ ] GlobalID: BLAKE3 hash of source address
• [ ] Cone mode context flag

DNS

• [ ] Multi-server DNS with domain-based routing
• [ ] UDP, TCP, DoH, DoQ backends
• [ ] Caching with TTL
• [ ] Fake-IP pool (LRU, CIDR-based allocation)
• [ ] Integration with dispatcher sniffing

TUN

• [ ] Platform-specific TUN device creation
• [ ] Userspace IP stack (gVisor or alternative)
• [ ] TCP forwarder (handshake → net.Conn)
• [ ] UDP Full-Cone NAT handler
• [ ] Raw UDP packet construction for return path

Statistics

• [ ] Per-user traffic counters
• [ ] Online user tracking
• [ ] SizeStatWriter wrapper

Other

• [ ] Reverse proxy (Bridge + Portal)
• [ ] Observatory (health checking)
• [ ] Commander (gRPC management API)
• [ ] Policy (timeouts, buffer sizes, per-level)

Phase 6: Configuration

• [ ] JSON config parsing
• [ ] Config → runtime object conversion
• [ ] Inbound/outbound handler creation
• [ ] Stream settings (transport + security)
• [ ] Sniffing configuration
• [ ] Routing rules configuration

Priority Order for MVP

For a minimal viable proxy:

1. Buffer + Pipe — foundation
2. Dispatcher + Router — core pipeline (can start with simple tag-based routing)
3. TCP Transport + TLS — connectivity
4. Freedom outbound — direct connections
5. VLESS protocol — one full protocol (inbound + outbound)
6. Sniffing — at least TLS SNI for domain-based routing
7. DNS — basic UDP DNS resolver

This gives you a working VLESS proxy. Add features incrementally from there.