netmux

netmux

netmux multiplexes a single TCP listener and a single UDP packet conn into many virtual ones, based on the payload of each connection/packet.

Two multiplexers, same idea:

ConnMux — stream multiplexing (TCP)

The server uses it to expose several protocols from a single TCP port: user matchers are registered first, then an AnyConn() catch-all picks up everything else (TLS, HTTP, WebSocket, ...).

mux := netmux.NewConnMux(listener)

socks := mux.Match(netmux.ConnSOCKS(5, 1, 0)) // SOCKS5 no-auth greetings
rest := mux.Match(netmux.AnyConn())           // everything else

go mux.Serve()

• Match(...ConnMatcher) / MatchWithWriters(...ConnMatchWriter) register a virtual listener; matchers are tried strictly in registration order, and each gets the connection's net.Addr (from RemoteAddr) alongside the sniffed reader. ConnMatchWriters additionally receive a writer that can send bytes back to the peer before the connection is delivered — used by the ...SendSettings HTTP/2 header-field matchers in the advanced examples for the h2c upgrade handshake:

  bannerLn := mux.MatchWithWriters(func(w io.Writer, r io.Reader, _ net.Addr) bool {
      if !netmux.ConnPrefixMatcher("BANNER")(r, nil) {
          return false
      }
      _, _ = w.Write([]byte("220 welcome\r\n")) // reply before Accept returns
      return true
  })
  

• Sniffing and replay: while matching, bytes read by the matchers are accumulated in a bufferedReader; each subsequent matcher sees the cumulative bytes of the ones before it, and the winning matcher's reads are replayed to the application (connSniff) — the protocol handler sees the exact byte stream as if it had read the connection directly.

• Serve() accepts from the root listener and dispatches each connection to the first matching virtual listener (blocked sends escape via the mux's and the listener's donec when closed). ConnMux.Close() makes every Accept return ErrConnMuxClosed — it stops the mux but does not close the root listener, which is owned by the caller (close it yourself to make Serve return). connListener.Close() closes only that virtual listener (ErrConnListenerClosed), leaving the rest of the mux running.

• SetReadTimeout bounds the sniffing reads; HandleError configures what happens to unmatched connections (default: close the connection and keep serving):

  mux.SetReadTimeout(200 * time.Millisecond) // matchers must decide within 200ms
  mux.HandleError(func(err error) bool {
      // Log and keep serving; return false to stop the mux entirely.
      log.Printf("connection error: %v", err)
      return true
  })
  

• Errors implement net.Error: ErrConnNotMatched is transient (the mux closes the connection and keeps serving), while ErrConnListenerClosed/ErrConnMuxClosed are permanent closed states.

Conn matchers (matchers.go)

The package is intentionally dependency-free, so the stricter HTTP/1, HTTP/2 and TLS matchers (a strict request-line parser, ConnHTTP2, ConnTLS, ConnHTTP1HeaderField, ConnHTTP2HeaderField, ConnHTTP2MatchHeaderField* SendSettings) are no longer shipped. Self-contained drop-in replacements for all of them live in Advanced matcher examples.

PacketConnMux — datagram multiplexing (UDP)

mux := netmux.NewPacketConnMux(packetConn)

quicPC := mux.Match(netmux.PacketPrefix([]byte{0xc0})) // e.g. QUIC Initials
turnPC := mux.Match(netmux.PacketPrefix([]byte{0x00, 0x01}))
otherPC := mux.Match(netmux.AnyPacket()) // catch-all

go mux.Serve()

• Match(...PacketConnMatcher) registers a virtual net.PacketConn (defaults to AnyPacket()). Serve() reads datagrams from the base conn, copies them into pooled datagrams and dispatches to the first matching virtual conn; unmatched or over-queue packets are dropped and their datagrams returned to the pool.
• Backpressure: each virtual conn has a 128-datagram buffer; enqueue is non-blocking, so a slow consumer drops packets instead of stalling the shared demux loop. The [closed-check + send] pair is serialized against Close()'s drain so no datagram is ever stranded after a close.
• WaitUntilServing(timeout) blocks until the demux loop is running; errors.Is(err, net.ErrClosed) detects close errors; deadlines are supported per virtual conn.
• Closing: PacketConnMux.Close() stops the mux and also closes the base PacketConn. Closing an individual virtual conn (via its Close()) stops that conn and unregisters it, leaving the mux and the other virtual conns running.

Packet matchers

Note: matcher ordering matters when the protocol shapes overlap. PacketTURN is a superset of PacketSTUN (it also accepts STUN-formatted messages), so register PacketSTUN first when both are used. And because PacketQUIC claims every packet with the 0x40 fixed bit, TURN ChannelData messages (first byte 0x40–0x7F) match it too — register PacketQUIC before PacketTURN only if QUIC traffic must win, or give the TURN matcher a narrower prefix.

Network helpers (netmux.go)

The package bundles portable socket helpers that set SO_REUSEADDR and SO_REUSEPORT on the underlying sockets via the platform-specific Control function. (SO_REUSEPORT is Unix-only; the Windows and Solaris builds set SO_REUSEADDR alone, which is the equivalent option there.)

Advanced matchers

The built-in matchers (AnyConn, ConnPrefixMatcher, ConnHTTP1, ConnSOCKS) keep the package dependency-free. The stricter matchers that used to ship — a strict request-line parser, HTTP/2, TLS, and header-field matching — are still available as single self-contained functions. Each example below shows only the function being explained, with no imports: copy it into your own package, add the imports named in the section's prose, and register it with ConnMux.Match / ConnMux.MatchWithWriters exactly like the built-ins.

ConnTLS — match TLS handshake records

ConnTLS matches TLS connections by their first bytes: the record type 0x16 (a handshake record) followed by the two protocol-version bytes (0x0303 is TLS 1.2). By default it accepts SSLv3 through TLS 1.2; pass specific versions to restrict it, e.g. ConnTLS(tls.VersionTLS12).

Imports: crypto/tls (version constants), net, plus the netmux import.

func ConnTLS(versions ...int) netmux.ConnMatcher {
	if len(versions) == 0 {
		// 0x0300 is SSLv3, matched by prefix only (crypto/tls.VersionSSL30
		// itself is deprecated).
		versions = []int{0x0300, tls.VersionTLS10, tls.VersionTLS11, tls.VersionTLS12}
	}
	prefixes := make([]string, 0, len(versions))
	for _, v := range versions {
		prefixes = append(prefixes, string([]byte{22, byte(v >> 8 & 0xff), byte(v & 0xff)}))
	}
	return netmux.ConnPrefixMatcher(prefixes...)
}

ConnHTTP1Strict — require a valid HTTP/1.x request line

The built-in ConnHTTP1 is optimistic: it matches any request whose first word is a standard HTTP method, without validating the rest. ConnHTTP1Strict is the stricter counterpart — it parses the first request line (METHOD URI PROTO) and requires the protocol to be HTTP/1.x. It reads up to 4096 bytes, so it is slower, but it only matches genuine HTTP/1 requests (and rejects e.g. GET / HTTP/2.0).

Imports: bufio, io, net, strings.

func ConnHTTP1Strict() netmux.ConnMatcher {
	const maxHTTPRead = 4096
	return func(r io.Reader, _ net.Addr) bool {
		br := bufio.NewReader(&io.LimitedReader{R: r, N: maxHTTPRead})
		l, part, err := br.ReadLine()
		if err != nil || part {
			return false
		}

		// Split "METHOD URI PROTO" (grabbed from net/http).
		line := string(l)
		s1 := strings.IndexByte(line, ' ')
		s2 := strings.IndexByte(line[s1+1:], ' ')
		if s1 < 0 || s2 < 0 {
			return false
		}
		proto := line[s1+1+s2+1:]

		// HTTP/1.x only: the version token starts with "HTTP/1.".
		return strings.HasPrefix(strings.ToUpper(proto), "HTTP/1.")
	}
}

ConnHTTP2 — match the HTTP/2 client preface

ConnHTTP2 matches the 24-byte HTTP/2 connection preface PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n. It compares the preface byte by byte, reading in a loop because the underlying net.Conn may fragment it across reads.

Imports: io, net.

func ConnHTTP2() netmux.ConnMatcher {
	const preface = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
	return func(r io.Reader, _ net.Addr) bool {
		var b [len(preface)]byte
		last := 0
		for {
			n, err := r.Read(b[last:])
			if err != nil {
				return false
			}
			last += n
			if string(b[:last]) != preface[:last] {
				return false
			}
			if last == len(preface) {
				return true
			}
		}
	}
}

Shared helper — matchHTTP1Field

matchHTTP1Field powers the two HTTP/1 header-field matchers: it skips the request line, then walks the header fields and applies the name/value predicate to each until one matches or the header block ends.

Imports: bufio, io, net, strings.

func matchHTTP1Field(name string, matches func(string) bool) netmux.ConnMatcher {
	return func(r io.Reader, _ net.Addr) bool {
		br := bufio.NewReader(r)
		// Skip the request line, then inspect the header fields.
		if _, err := br.ReadString('\n'); err != nil {
			return false
		}
		for {
			line, err := br.ReadString('\n')
			if err != nil {
				return false
			}
			line = strings.TrimRight(line, "\r\n")
			if line == "" {
				return false // end of headers without a match
			}
			i := strings.IndexByte(line, ':')
			if i < 0 {
				return false
			}
			if strings.EqualFold(strings.TrimSpace(line[:i]), name) {
				return matches(strings.TrimSpace(line[i+1:]))
			}
		}
	}
}

ConnHTTP1HeaderField / ConnHTTP1HeaderFieldPrefix — match an HTTP/1 header

ConnHTTP1HeaderField matches the first request when the header named name has the exact value; ConnHTTP1HeaderFieldPrefix matches when the value starts with prefix. The field name is compared case-insensitively, and the Host header is matched like any other field. Both need the matchHTTP1Field helper above.

Imports: io, net (+ strings for the prefix variant), plus the helper.

func ConnHTTP1HeaderField(name, value string) netmux.ConnMatcher {
	return matchHTTP1Field(name, func(got string) bool { return got == value })
}

func ConnHTTP1HeaderFieldPrefix(name, prefix string) netmux.ConnMatcher {
	return matchHTTP1Field(name, func(got string) bool { return strings.HasPrefix(got, prefix) })
}

Shared helper — matchHTTP2Field

matchHTTP2Field powers the four HTTP/2 header-field matchers: it verifies the client preface with ConnHTTP2, then reads frames and HPACK-decodes the HEADERS/CONTINUATION header-block fragments, applying the name/value predicate until the header block ends. When a non-ACK SETTINGS frame arrives it answers with our own SETTINGS frame (that is the SendSettings behavior); once the peer acknowledges, it stops writing them. It returns as soon as the header block is complete.

Imports: io, net, golang.org/x/net/http2, golang.org/x/net/http2/hpack; plus the ConnHTTP2 matcher for the preface check.

func matchHTTP2Field(w io.Writer, r io.Reader, name string, matches func(string) bool) bool {
	if !ConnHTTP2()(r, nil) {
		return false
	}

	done := false
	matched := false
	framer := http2.NewFramer(w, r)
	hdec := hpack.NewDecoder(uint32(4<<10), func(hf hpack.HeaderField) {
		if hf.Name == name {
			done = true
			if matches(hf.Value) {
				matched = true
			}
		}
	})
	for {
		f, err := framer.ReadFrame()
		if err != nil {
			return false
		}

		switch f := f.(type) {
		case *http2.SettingsFrame:
			// The peer acknowledged our SETTINGS frame; do not write it
			// again.
			if f.IsAck() {
				break
			}
			if err := framer.WriteSettings(); err != nil {
				return false
			}
		case *http2.ContinuationFrame:
			if _, err := hdec.Write(f.HeaderBlockFragment()); err != nil {
				return false
			}
			done = done || f.FrameHeader.Flags&http2.FlagHeadersEndHeaders != 0
		case *http2.HeadersFrame:
			if _, err := hdec.Write(f.HeaderBlockFragment()); err != nil {
				return false
			}
			done = done || f.FrameHeader.Flags&http2.FlagHeadersEndHeaders != 0
		}

		if done {
			return matched
		}
	}
}

ConnHTTP2HeaderField / ConnHTTP2HeaderFieldPrefix — match an HTTP/2 header

ConnHTTP2HeaderField matches the first HEADERS frame when the header named name has the exact value; ConnHTTP2HeaderFieldPrefix matches when the value starts with prefix. HPACK-decoding follows CONTINUATION frames until the header block ends. Both need the matchHTTP2Field helper (and through it ConnHTTP2).

Imports: io, net, strings (prefix variant), golang.org/x/net/http2 + hpack, plus the helper and ConnHTTP2.

func ConnHTTP2HeaderField(name, value string) netmux.ConnMatcher {
	return func(r io.Reader, _ net.Addr) bool {
		return matchHTTP2Field(io.Discard, r, name, func(got string) bool { return got == value })
	}
}

func ConnHTTP2HeaderFieldPrefix(name, prefix string) netmux.ConnMatcher {
	return func(r io.Reader, _ net.Addr) bool {
		return matchHTTP2Field(io.Discard, r, name, func(got string) bool { return strings.HasPrefix(got, prefix) })
	}
}

ConnHTTP2MatchHeaderFieldSendSettings / ...PrefixSendSettings — h2c upgrade

The plain ConnHTTP2HeaderField* matchers above read the client's headers but never write anything back. For an h2c (HTTP/2 cleartext) upgrade the client blocks until the server sends its own SETTINGS frame, so the matcher must reply during matching. These two ConnMatchWriters do exactly that — register them with MatchWithWriters instead of Match. Prefer the plain ConnHTTP2HeaderField* variants when the client does not block on receiving SETTINGS.

Imports: io, net, strings (prefix variant), golang.org/x/net/http2 + hpack, plus the helper and ConnHTTP2.

func ConnHTTP2MatchHeaderFieldSendSettings(name, value string) netmux.ConnMatchWriter {
	return func(w io.Writer, r io.Reader, _ net.Addr) bool {
		return matchHTTP2Field(w, r, name, func(got string) bool { return got == value })
	}
}

func ConnHTTP2MatchHeaderFieldPrefixSendSettings(name, prefix string) netmux.ConnMatchWriter {
	return func(w io.Writer, r io.Reader, _ net.Addr) bool {
		return matchHTTP2Field(w, r, name, func(got string) bool { return strings.HasPrefix(got, prefix) })
	}
}