go-gost/x
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(admission): add package and symbol doc comments

Browse Source 
Add package-level documentation and Go doc comments for all exported
types, functions, and methods across the admission package, its plugin
sub-packages, and connection/listener wrappers.
This commit is contained in:
ginuerzh
2026-05-22 17:19:48 +08:00
parent 174bc082d1
commit b9d74c1b8e
5 changed files with 275 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
admission/wrapper/conn.go
+68
View File
@@ -18,11 +18,22 @@ var (
errUnsupport = errors.New("unsupported operation")
)
// serverConn wraps a TCP connection (net.Conn) with per-read admission
// checking. Unlike the listener wrapper — which rejects at accept time —
// this wrapper re-validates the remote address on each Read call.
// This is useful when the admission rules may change during the lifetime
// of a connection, or when the connection was established before
// admission wrappers were applied.
type serverConn struct {
net.Conn
admission admission.Admission
}
// WrapConn wraps a net.Conn with per-read admission control.
// If admission is nil, the original connection is returned unchanged.
//
// When admission is denied on a Read, io.EOF is returned so the caller
// sees a clean end-of-stream rather than a hard error.
func WrapConn(admission admission.Admission, c net.Conn) net.Conn {
if admission == nil {
return c
@@ -33,6 +44,9 @@ func WrapConn(admission admission.Admission, c net.Conn) net.Conn {
}
}
// Read checks the remote address against the admission controller
// before delegating to the underlying connection. If denied, it returns
// io.EOF to signal end-of-stream.
func (c *serverConn) Read(b []byte) (n int, err error) {
if c.admission != nil &&
!c.admission.Admit(context.Background(), c.RemoteAddr().Network(), c.RemoteAddr().String()) {
@@ -42,6 +56,9 @@ func (c *serverConn) Read(b []byte) (n int, err error) {
return c.Conn.Read(b)
}
// SyscallConn exposes the underlying raw connection for socket-level
// operations (e.g. setting SO_MARK, SO_REUSEPORT). Returns
// errUnsupport if the inner connection does not support this.
func (c *serverConn) SyscallConn() (rc syscall.RawConn, err error) {
if sc, ok := c.Conn.(syscall.Conn); ok {
rc, err = sc.SyscallConn()
@@ -51,6 +68,7 @@ func (c *serverConn) SyscallConn() (rc syscall.RawConn, err error) {
return
}
// CloseRead shuts down the read side of the connection if supported.
func (c *serverConn) CloseRead() error {
if sc, ok := c.Conn.(xio.CloseRead); ok {
return sc.CloseRead()
@@ -58,6 +76,7 @@ func (c *serverConn) CloseRead() error {
return xio.ErrUnsupported
}
// CloseWrite shuts down the write side of the connection if supported.
func (c *serverConn) CloseWrite() error {
if sc, ok := c.Conn.(xio.CloseWrite); ok {
return sc.CloseWrite()
@@ -65,6 +84,8 @@ func (c *serverConn) CloseWrite() error {
return xio.ErrUnsupported
}
// Context returns the context carried by the underlying connection,
// or nil if the connection does not carry context.
func (c *serverConn) Context() context.Context {
if innerCtx, ok := c.Conn.(ctx.Context); ok {
return innerCtx.Context()
@@ -72,11 +93,19 @@ func (c *serverConn) Context() context.Context {
return nil
}
// packetConn wraps a net.PacketConn with per-packet admission checking.
// Packets from denied addresses are silently dropped and the read
// loop continues to the next packet.
type packetConn struct {
net.PacketConn
admission admission.Admission
}
// WrapPacketConn wraps a net.PacketConn with per-packet admission control.
// If admission is nil, the original connection is returned unchanged.
//
// Denied packets are silently discarded; ReadFrom loops until it receives
// a packet from an allowed address or encounters an error.
func WrapPacketConn(admission admission.Admission, pc net.PacketConn) net.PacketConn {
if admission == nil {
return pc
@@ -87,6 +116,8 @@ func WrapPacketConn(admission admission.Admission, pc net.PacketConn) net.Packet
}
}
// ReadFrom reads the next packet from an admitted address. Packets from
// denied addresses are discarded and the method retries automatically.
func (c *packetConn) ReadFrom(p []byte) (n int, addr net.Addr, err error) {
for {
n, addr, err = c.PacketConn.ReadFrom(p)
@@ -103,6 +134,7 @@ func (c *packetConn) ReadFrom(p []byte) (n int, addr net.Addr, err error) {
}
}
// Context returns the context carried by the underlying packet connection.
func (c *packetConn) Context() context.Context {
if innerCtx, ok := c.PacketConn.(ctx.Context); ok {
return innerCtx.Context()
@@ -110,11 +142,21 @@ func (c *packetConn) Context() context.Context {
return nil
}
// udpConn wraps a packet connection as a UDP-specific connection.
// It provides the same admission filtering as packetConn, plus UDP-
// specific operations (ReadFromUDP, ReadMsgUDP, WriteToUDP, WriteMsgUDP,
// SetDSCP, etc.).
//
// The wrapper delegates to optional interfaces on the underlying
// connection, returning errUnsupport if the capability is not available.
type udpConn struct {
net.PacketConn
admission admission.Admission
}
// WrapUDPConn wraps a net.PacketConn as a udp.Conn with admission control.
// This is used in UDP forwarding paths where the connection is treated
// as a connected UDP socket.
func WrapUDPConn(admission admission.Admission, pc net.PacketConn) udp.Conn {
return &udpConn{
PacketConn: pc,
@@ -122,6 +164,9 @@ func WrapUDPConn(admission admission.Admission, pc net.PacketConn) udp.Conn {
}
}
// RemoteAddr returns the remote address from the underlying connection
// if it implements the RemoteAddr interface. This is used for "connected"
// UDP sockets that have a fixed peer.
func (c *udpConn) RemoteAddr() net.Addr {
if nc, ok := c.PacketConn.(xnet.RemoteAddr); ok {
return nc.RemoteAddr()
@@ -129,6 +174,7 @@ func (c *udpConn) RemoteAddr() net.Addr {
return nil
}
// SetReadBuffer sets the socket receive buffer size.
func (c *udpConn) SetReadBuffer(n int) error {
if nc, ok := c.PacketConn.(xnet.SetBuffer); ok {
return nc.SetReadBuffer(n)
@@ -136,6 +182,7 @@ func (c *udpConn) SetReadBuffer(n int) error {
return errUnsupport
}
// SetWriteBuffer sets the socket send buffer size.
func (c *udpConn) SetWriteBuffer(n int) error {
if nc, ok := c.PacketConn.(xnet.SetBuffer); ok {
return nc.SetWriteBuffer(n)
@@ -143,6 +190,8 @@ func (c *udpConn) SetWriteBuffer(n int) error {
return errUnsupport
}
// Read delegates to the underlying connection's Read method if available
// (for connected UDP sockets that support stream-like reads).
func (c *udpConn) Read(b []byte) (n int, err error) {
if nc, ok := c.PacketConn.(io.Reader); ok {
n, err = nc.Read(b)
@@ -152,6 +201,8 @@ func (c *udpConn) Read(b []byte) (n int, err error) {
return
}
// ReadFrom reads the next packet from an admitted address, discarding
// packets from denied addresses.
func (c *udpConn) ReadFrom(p []byte) (n int, addr net.Addr, err error) {
for {
n, addr, err = c.PacketConn.ReadFrom(p)
@@ -166,6 +217,8 @@ func (c *udpConn) ReadFrom(p []byte) (n int, addr net.Addr, err error) {
}
}
// ReadFromUDP reads the next UDP packet from an admitted address.
// Packets from denied addresses are discarded transparently.
func (c *udpConn) ReadFromUDP(b []byte) (n int, addr *net.UDPAddr, err error) {
if nc, ok := c.PacketConn.(udp.ReadUDP); ok {
for {
@@ -184,6 +237,8 @@ func (c *udpConn) ReadFromUDP(b []byte) (n int, addr *net.UDPAddr, err error) {
return
}
// ReadMsgUDP reads a UDP packet with out-of-band data from an admitted
// address. Packets from denied addresses are silently skipped.
func (c *udpConn) ReadMsgUDP(b, oob []byte) (n, oobn, flags int, addr *net.UDPAddr, err error) {
if nc, ok := c.PacketConn.(udp.ReadUDP); ok {
for {
@@ -202,6 +257,8 @@ func (c *udpConn) ReadMsgUDP(b, oob []byte) (n, oobn, flags int, addr *net.UDPAd
return
}
// Write delegates to the underlying connection's Write method if available
// (for connected UDP sockets).
func (c *udpConn) Write(b []byte) (n int, err error) {
if nc, ok := c.PacketConn.(io.Writer); ok {
n, err = nc.Write(b)
@@ -211,11 +268,15 @@ func (c *udpConn) Write(b []byte) (n int, err error) {
return
}
// WriteTo sends a packet to the specified address via the underlying
// packet connection. No admission check is performed on writes.
func (c *udpConn) WriteTo(p []byte, addr net.Addr) (n int, err error) {
n, err = c.PacketConn.WriteTo(p, addr)
return
}
// WriteToUDP sends a UDP packet to the specified address if the
// underlying connection supports UDP-specific writes.
func (c *udpConn) WriteToUDP(b []byte, addr *net.UDPAddr) (n int, err error) {
if nc, ok := c.PacketConn.(udp.WriteUDP); ok {
n, err = nc.WriteToUDP(b, addr)
@@ -225,6 +286,7 @@ func (c *udpConn) WriteToUDP(b []byte, addr *net.UDPAddr) (n int, err error) {
return
}
// WriteMsgUDP sends a UDP packet with out-of-band data if supported.
func (c *udpConn) WriteMsgUDP(b, oob []byte, addr *net.UDPAddr) (n, oobn int, err error) {
if nc, ok := c.PacketConn.(udp.WriteUDP); ok {
n, oobn, err = nc.WriteMsgUDP(b, oob, addr)
@@ -234,6 +296,8 @@ func (c *udpConn) WriteMsgUDP(b, oob []byte, addr *net.UDPAddr) (n, oobn int, er
return
}
// SyscallConn exposes the underlying raw connection for socket-level
// operations if supported.
func (c *udpConn) SyscallConn() (rc syscall.RawConn, err error) {
if nc, ok := c.PacketConn.(xnet.SyscallConn); ok {
return nc.SyscallConn()
@@ -242,6 +306,9 @@ func (c *udpConn) SyscallConn() (rc syscall.RawConn, err error) {
return
}
// SetDSCP sets the Differentiated Services Code Point on the socket
// for traffic classification/QoS. Silently succeeds if not supported
// (best-effort).
func (c *udpConn) SetDSCP(n int) error {
if nc, ok := c.PacketConn.(xnet.SetDSCP); ok {
return nc.SetDSCP(n)
@@ -249,6 +316,7 @@ func (c *udpConn) SetDSCP(n int) error {
return nil
}
// Context returns the context carried by the underlying packet connection.
func (c *udpConn) Context() context.Context {
if innerCtx, ok := c.PacketConn.(ctx.Context); ok {
return innerCtx.Context()
admission/wrapper/listener.go
+34 -1
View File
@@ -1,3 +1,14 @@
// Package wrapper provides net.Listener and net.Conn wrappers that
// enforce admission control at the network level.
//
// The listener wrapper checks each accepted connection against the
// admission controller before returning it to the caller. Denied
// connections are closed immediately and the listener continues
// accepting (transparent rejection).
//
// The connection wrappers (TCP, UDP, generic packet) check admission
// on each read operation, effectively dropping traffic from denied
// addresses without closing the underlying transport.
package wrapper
import (
@@ -9,13 +20,22 @@ import (
xctx "github.com/go-gost/x/ctx"
)
// listener wraps a net.Listener and performs admission checks on each
// accepted connection. Connections from denied addresses are silently
// closed and the accept loop continues.
type listener struct {
service string
service string
net.Listener
admission admission.Admission
log logger.Logger
}
// WrapListener wraps a net.Listener with admission control. If admission
// is nil, the original listener is returned unchanged (no-op).
//
// The service name is passed to the admission controller via
// admission.WithService so that the controller can distinguish
// between different services sharing the same admission rules.
func WrapListener(service string, admission admission.Admission, ln net.Listener) net.Listener {
if admission == nil {
return ln
@@ -27,6 +47,16 @@ func WrapListener(service string, admission admission.Admission, ln net.Listener
}
}
// Accept blocks until a connection is accepted from the underlying
// listener, then checks it against the admission controller. Denied
// connections are closed and the loop retries. The caller never sees
// a rejected connection.
//
// The client address used for the admission check is determined by:
// 1. The srcAddr value from the connection's context (if available),
// which is the original client address before any proxy protocol
// or NAT rewriting.
// 2. Falling back to the raw RemoteAddr of the accepted connection.
func (ln *listener) Accept() (net.Conn, error) {
for {
c, err := ln.Listener.Accept()
@@ -34,6 +64,7 @@ func (ln *listener) Accept() (net.Conn, error) {
return nil, err
}
// Extract the context from the connection if it carries one.
ctx := context.Background()
if cc, ok := c.(xctx.Context); ok {
if cv := cc.Context(); cv != nil {
@@ -41,6 +72,8 @@ func (ln *listener) Accept() (net.Conn, error) {
}
}
// Prefer the original source address from context (e.g. set by
// proxy protocol handling), falling back to the raw remote address.
clientAddr := c.RemoteAddr()
if addr := xctx.SrcAddrFromContext(ctx); addr != nil {
clientAddr = addr