feed

Documentation

Overview

Package feed holds the published lists the controller pushes as data: lists/<name>.set in the received bundle — one canonical prefix a line under a header naming the count and the hash — loaded into sets of their own in the agent's table (internal/nft feeds). The kernel is the only copy: nothing of a feed enters the store, and a boot rebuilds the sets from the files. A refresh is a diff: what left is deleted, what came is added, in batches.

What a feed may never do: block the machine itself, its controller, or anything the operator exempted — every entry is checked against those before it reaches the kernel, and a feed that cannot be read whole (a bad line, a count or a hash that does not match) is refused whole: the previous state stands.

Index

• Constants
• func Covering(received string, a netip.Addr) []string
• func Dir(received string) string
• func Subtract(p netip.Prefix, cuts []netip.Prefix) []netip.Prefix
• type Applier
• type Feed
  • func Load(received string) ([]Feed, []error)
• type Manager
  • func NewManager(applier Applier, log *slog.Logger) *Manager
  • func (m *Manager) Stats(q Querier) []Stat
  • func (m *Manager) Sync(feeds []Feed, protect func(netip.Prefix) bool, now time.Time) error
• type Querier
• type Stat

Constants

const (
	// MaxEntries bounds one feed — a million addresses is a big one; past
	// it the file is refused as a mistake or worse.
	MaxEntries = 2_000_000

	// Batch is how many elements travel in one nft transaction.
	Batch = 5000
)

Functions

func Covering

func Covering(received string, a netip.Addr) []string

Covering says which loaded feeds list an address — `shield why` reads the files, the running agent its memory.

func Dir

func Dir(received string) string

Dir is where the received bundle holds the feeds.

func Subtract

func Subtract(p netip.Prefix, cuts []netip.Prefix) []netip.Prefix

Subtract cuts every prefix of cuts out of p: the pieces of p that touch none of them, largest first. A prefix entirely inside a cut leaves nothing; one touching no cut comes back whole. Each split halves the prefix, so the work is bounded by the address width.

Types

type Applier

type Applier interface {
	Apply(script string) error
}

Applier is what the manager writes the kernel through — nft.Exec in the agent, a recorder in tests.

type Feed

type Feed struct {
	Name    string
	Set     string // the nftables identifier (nft.FeedSet)
	Hash    string // sha256 of the body, as the header says
	Entries []netip.Prefix
}

Feed is one list as received.

func Load

func Load(received string) ([]Feed, []error)

Load reads every feed under dir/lists. A file that cannot be read whole is reported and left out; the others load.

type Manager

type Manager struct {

	// Carve, when set, says what of a list's prefix may be blocked: the
	// prefix minus the exempted addresses — an exempted /32 inside a
	// banned /16 keeps the rest of the /16 blocked (protect alone
	// dropped the whole prefix). nil: keep it whole; empty: none of it.
	Carve func(netip.Prefix) []netip.Prefix
	// contains filtered or unexported fields
}

Manager keeps the kernel's feed sets equal to the files.

func NewManager

func NewManager(applier Applier, log *slog.Logger) *Manager

func (*Manager) Stats

func (m *Manager) Stats(q Querier) []Stat

Stats reads the feeds' counters (through q, when given) and returns what each feed amounts to, by name.

func (*Manager) Sync

func (m *Manager) Sync(feeds []Feed, protect func(netip.Prefix) bool, now time.Time) error

Sync makes the kernel hold exactly these feeds: new ones declared and filled, changed ones diffed, gone ones dropped. protect says what may never be blocked; a feed entry covering a protected address is left out (and counted in Dropped). The table must exist: a boot calls this after the table is (re)created, on an empty manager.

type Querier

type Querier interface {
	Query(args ...string) ([]byte, error)
}

Querier reads counters; optional.

type Stat

type Stat struct {
	Name    string `json:"name"`
	Entries int    `json:"entries"` // held in the kernel after the protections
	Dropped int    `json:"dropped"` // entries left out: the machine's own, the controller's, the exempted
	Packets int64  `json:"packets"` // since boot
	Bytes   int64  `json:"bytes"`   // since boot
	Applied string `json:"applied"` // when the kernel last took it
	Hash    string `json:"hash"`
}

Stat is what a feed amounts to in the kernel.