netsplice

package
v0.6.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package netsplice is the raw-TCP proxy core shared by sandboxd's proxies: a bidirectional splice that replays bytes already read into a bufio.Reader, and a per-key plus global connection limiter. The L4 wake proxy (internal/service) uses both. The egress FQDN proxy (plans/egress-domain-filtering.md §5.5, D12 and D17) has the same contract, so half-close, idle and cap semantics exist once, with one set of tests.

Index

Constants

This section is empty.

Variables

View Source
var ErrIdleTimeout = errors.New("netsplice: idle timeout")

ErrIdleTimeout is returned by Splice when WithIdleTimeout ended the connection.

Functions

func Splice

func Splice(downstream, upstream net.Conn, br *bufio.Reader, opts ...Option) error

Splice copies downstream<->upstream until BOTH directions finish, then closes both conns. Bytes already buffered in br (read past a PROXY header, or a peeked ClientHello) are written upstream FIRST. br may be nil.

Half-close sequence (client finishes first; the mirror case is symmetric):

client            downstream ── Splice ── upstream            backend
  │ request ───────────►│  down→up copy  │─────────────────────►│
  │ CloseWrite (FIN) ──►│  EOF           │ CloseWrite(up) ─────►│ reads EOF
  │                     │                │                      │
  │◄────────────────────│  up→down copy  │◄──────────── response│
  │◄─ FIN ──────────────│ CloseWrite(down)  EOF ◄─── Close (FIN)│
                        └ both done: Close both conns, return nil

Each direction forwards its EOF as a FIN (CloseWrite) and the other direction keeps flowing. A conn without CloseWrite (net.Pipe) is closed instead, which also ends the other direction. The old shape returned on the first finished direction and closed both conns, so a client that half-closed after its request never received the response.

The copy runs raw conn to raw conn. Wrapping downstream in io.MultiReader (the shape before eng review 7A) hid the *net.TCPConn from io.Copy, so its bytes could not use Linux splice(2) and went through user space. That is why the prefix is written separately, and why idle detection samples with read deadlines instead of counting bytes through a wrapper.

A copy error (a reset, a broken pipe) closes both conns and is not returned: for a proxy that is how connections normally end. Splice returns a prefix write error (nothing was copied and both conns are left to the caller), ErrIdleTimeout, or nil. It owns both conns' deadlines and clears any the caller left behind (a ClientHello peek timeout, say), which would otherwise end a healthy copy. No goroutine outlives the call.

Types

type Limiter

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

Limiter caps concurrent connections per key (a sandbox ID) and globally. The hooks run under the limiter's lock, so state tied to a key's first acquire or last release (the wake proxy's activity generation) changes atomically with the count. The wake proxy relied on that when all of this lived under Service.l4LimitMu.

func NewLimiter

func NewLimiter(perKeyMax, globalMax func() int) *Limiter

NewLimiter returns a Limiter whose caps are read on every acquire, not captured here. The wake proxy builds its limiters once, lazily, from config it can still change afterwards; a fixed cap is func() int { return n }.

func (*Limiter) TryAcquire

func (l *Limiter) TryAcquire(key string, onAcquire func(first bool), onRelease func(last bool)) (release func(), ok bool)

TryAcquire reserves one slot for key, or returns ok=false at either cap. onAcquire(first) and the returned release's onRelease(last) run under the lock; either may be nil. The release func is idempotent, so a double release cannot drive counts negative or free another connection's slot.

func (*Limiter) WithLock

func (l *Limiter) WithLock(key string, fn func(count int))

WithLock runs fn with the limiter's lock held, passing the live count for key. Use it for state guarded by the hooks.

type Option

type Option func(*options)

Option configures Splice.

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout ends the splice once no byte has moved in either direction for d, so a silent peer cannot pin two goroutines, two sockets and a limiter slot forever. Zero or negative (the default) waits indefinitely: the L4 wake proxy carries database connections that legitimately sit idle for hours.

Detection is coarse on purpose (see splice.wait): a quiet connection closes between d and 2d after its last byte. A direction blocked for a whole period writing to a peer that does not read counts as idle too, since that peer pins the connection just the same.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL