netjoin

Documentation

Overview

Package netjoin provides socket-level helpers for joining IPv6 multicast groups, branching between ASM (IPV6_JOIN_GROUP) and SSM (MCAST_JOIN_SOURCE_GROUP, RFC 3678) by the presence of a source list.

The helpers operate directly on file descriptors so they compose with existing raw-socket call sites that bypass Go's runtime poller. A Limiter and a Jitter helper are provided for cold-start storm protection at scale (hundreds of listeners × hundreds of publishers).

Index

• func Jitter(ctx context.Context, max time.Duration)
• func Join(fd, ifaceIdx int, group netip.Addr, sources []netip.Addr) error
• func Leave(fd, ifaceIdx int, group netip.Addr, sources []netip.Addr) error
• type Limiter
  • func NewLimiter(perSecond int) *Limiter
  • func (l *Limiter) Acquire(ctx context.Context) error
  • func (l *Limiter) Stop()

Functions

func Jitter

func Jitter(ctx context.Context, max time.Duration)

Jitter sleeps for a uniformly random duration in [0, max). When max is zero or negative, Jitter is a no-op. Intended to be called once at listener startup so a fleet of replicas does not issue MLDv2 reports in the same millisecond window.

func Join

func Join(fd, ifaceIdx int, group netip.Addr, sources []netip.Addr) error

Join joins an IPv6 multicast group on fd. When sources is empty the call is an ASM (*, G) join via unix.IPV6_JOIN_GROUP. When sources is non-empty the call issues one (S, G) join per source via unix.MCAST_JOIN_SOURCE_GROUP.

fd must be an IPv6 UDP socket already bound to the desired port. ifaceIdx is the outbound interface index (net.Interface.Index). group must be an IPv6 multicast address.

The function does not rate-limit; callers running at scale should wrap each invocation with a shared *Limiter.Acquire.

func Leave

func Leave(fd, ifaceIdx int, group netip.Addr, sources []netip.Addr) error

Leave is the counterpart to Join: ASM leave via unix.IPV6_LEAVE_GROUP when sources is empty, otherwise one unix.MCAST_LEAVE_SOURCE_GROUP per source.

Types

type Limiter

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

Limiter is a token-bucket rate limiter intended to bound the per-listener join/leave rate so a cold-start storm cannot overrun the upstream MLDv2 querier. Acquire one slot per setsockopt call:

lim := netjoin.NewLimiter(1000)        // 1000 joins/sec
defer lim.Stop()
for _, src := range sources {
    if err := lim.Acquire(ctx); err != nil { return err }
    if err := netjoin.Join(fd, ifIdx, grp, []netip.Addr{src}); err != nil { return err }
}

A nil receiver is a no-op (Acquire returns nil immediately), so the limiter can be threaded through call sites without requiring callers to nil-check.

func NewLimiter

func NewLimiter(perSecond int) *Limiter

NewLimiter creates a token-bucket limiter that allows up to perSecond operations per second with a burst of perSecond. perSecond must be > 0; a value of 0 or negative returns nil (no rate limiting).

func (*Limiter) Acquire

func (l *Limiter) Acquire(ctx context.Context) error

Acquire blocks until a token is available or ctx is cancelled.

func (*Limiter) Stop

func (l *Limiter) Stop()

Stop releases the underlying ticker. Safe to call on a nil receiver.