pfilter

README

pfilter

Small Go package for filtering packets from a single net.PacketConn into multiple virtual net.PacketConn's based on some predicate.

Used to multiplex/weave in STUN packets on top of an existing UDP connection, where IP address based routing would not work due to STUN sending replies back from random addresses.

Connections also implement PacketReceiver. Set a receiver before starting the filter to process claimed packets on its read goroutine instead of calling ReadFrom:

conn.(pfilter.PacketReceiver).SetPacketReceiver(func(data []byte, addr net.Addr, err error) {
    // Process data before returning; copy it if it must outlive this call.
    // A terminal read error is delivered with data == nil.
})

Callbacks must return promptly because they run on the shared read goroutine. They may close their own connection. Passing nil restores queueing for subsequent packets; previously queued packets remain readable, and an in-flight callback may still finish after the receiver is replaced.

Documentation

Index

• type Config
• type Filter
• type PacketFilter
  • func NewPacketFilter(conn net.PacketConn) *PacketFilter
  • func NewPacketFilterWithConfig(config Config) (*PacketFilter, error)
  • func (d *PacketFilter) Dropped() uint64
  • func (d *PacketFilter) NewConn(priority int, filter Filter) net.PacketConn
  • func (d *PacketFilter) NumberOfConns() int
  • func (d *PacketFilter) Overflow() uint64
  • func (d *PacketFilter) Start()
• type PacketReceiver

Types

type Config

type Config struct {
	Conn net.PacketConn

	// Size of the byte array passed to the read operations of the underlying
	// socket. Buffer that is too small could result in truncated reads. Defaults to 15000
	BufferSize int

	// Backlog of how many packets we are happy to buffer in memory
	Backlog int

	// If non-zero, uses ipv4.PacketConn.ReadBatch, using the size of the batch given.
	// Defaults to 1 on Darwin/FreeBSD and 8 on Linux.
	BatchSize int
}

type Filter

type Filter interface {
	Outgoing([]byte, net.Addr)
	ClaimIncoming([]byte, net.Addr) bool
}

Filter object receives all data sent out on the Outgoing callback, and is expected to decide if it wants to receive the packet or not via the Receive callback

type PacketFilter

type PacketFilter struct {
	// contains filtered or unexported fields
}

PacketFilter embeds a net.PacketConn to perform the filtering.

func NewPacketFilter

func NewPacketFilter(conn net.PacketConn) *PacketFilter

NewPacketFilter creates a packet filter object wrapping the given packet connection.

func NewPacketFilterWithConfig

func NewPacketFilterWithConfig(config Config) (*PacketFilter, error)

NewPacketFilterWithConfig creates a packet filter object with the configuration provided

func (*PacketFilter) Dropped

func (d *PacketFilter) Dropped() uint64

Dropped returns number of packets dropped due to nobody claiming them.

func (*PacketFilter) NewConn

func (d *PacketFilter) NewConn(priority int, filter Filter) net.PacketConn

NewConn returns a new net.PacketConn object which filters packets based on the provided filter. If filter is nil, the connection will receive all packets. Priority decides which connection gets the ability to claim the packet.

func (*PacketFilter) NumberOfConns

func (d *PacketFilter) NumberOfConns() int

NumberOfConns returns the number of currently active virtual connections

func (*PacketFilter) Overflow

func (d *PacketFilter) Overflow() uint64

Overflow returns number of packets were dropped due to receive buffers being full.

func (*PacketFilter) Start

func (d *PacketFilter) Start()

Start starts reading packets from the socket and forwarding them to connections. Should call this after creating all the expected connections using NewConn, otherwise the packets read will be dropped.

type PacketReceiver

type PacketReceiver interface {
	net.PacketConn
	SetPacketReceiver(func(b []byte, addr net.Addr, err error))
}

PacketReceiver is implemented by connections returned by NewConn. It allows consumers to process packets without a goroutine calling ReadFrom.