parental_categories.go

/*
File:    parental_categories.go
Version: 2.0.0 (Split)
Updated: 2026-04-10

Description:
  Category data management and lookups for the sdproxy parental subsystem.
  Extracted parsing, tree consolidation, and data loading into:
    - parental_loader.go
    - parental_parser.go
    - parental_consolidation.go

  WHAT LIVES HERE:
    categoryData / wildcardCatEntry — runtime lookup types.
    catMap        — atomic.Pointer holding the live category data.
    catMinLabels / catMaxLabels — suffix-walk depth bounds.
    isWildcard / matchGlob      — wildcard pattern matching.
    categoryOf                  — hot-path domain → category lookup.
*/

package main

import (
	"net/netip"
	"strings"
	"sync/atomic"
)

// ---------------------------------------------------------------------------
// Category data structures
// ---------------------------------------------------------------------------

// wildcardCatEntry holds a single glob pattern from an add: override and the
// category it belongs to. Stored in categoryData.patterns.
// Patterns are pre-lowercased; matching uses matchGlob().
type wildcardCatEntry struct {
	pattern string // glob pattern (contains '*' and/or '?')
	cat     string // category name
}

// cidrCatEntry holds a parsed CIDR network and its mapped category.
type cidrCatEntry struct {
	prefix netip.Prefix
	cat    string
}

// categoryData is the runtime lookup table for domain categorisation.
// Stored in catMap via atomic.Pointer for lock-free hot-path reads.
type categoryData struct {
	// apex maps lowercased apex domains (no trailing dot) to category names.
	// Populated from source entries and plain (non-wildcard) add: overrides.
	// Matched by suffix walk in categoryOf().
	apex map[string]string

	// patterns holds wildcard add: entries in insertion order.
	// Each entry is tested with matchGlob() against the full queried domain —
	// no suffix walk. Patterns are evaluated BEFORE the apex map so that
	// manual wildcard overrides always beat source entries.
	patterns []wildcardCatEntry

	// ips maps singular IP addresses to category names.
	ips map[netip.Addr]string

	// cidrs maps subnet blocks to category names.
	cidrs []cidrCatEntry
}

// catMap holds the current categoryData. Replaced atomically by
// loadAllCategoryLists; read lock-free by categoryOf on the hot path.
var catMap atomic.Pointer[categoryData]

// catMinLabels and catMaxLabels bound the suffix walk in categoryOf().
// Computed by computeCatLabelBounds() after every apex-map build.
// Defaults are conservative: min=1 (no floor), max=128 (no ceiling until load).
var (
	catMinLabels = 1
	catMaxLabels = 128
)

// ---------------------------------------------------------------------------
// Wildcard helpers
// ---------------------------------------------------------------------------

// isWildcard reports whether s contains any wildcard characters ('*' or '?').
func isWildcard(s string) bool {
	return strings.ContainsAny(s, "*?")
}

// matchGlob reports whether s fully matches the glob pattern p.
func matchGlob(p, s string) bool {
	starP, starS := -1, 0
	pi, si := 0, 0
	for si < len(s) {
		switch {
		case pi < len(p) && p[pi] == '*':
			starP = pi
			starS = si
			pi++
		case pi < len(p) && (p[pi] == '?' || p[pi] == s[si]):
			pi++
			si++
		case starP >= 0:
			starS++
			si = starS
			pi = starP + 1
		default:
			return false
		}
	}
	for pi < len(p) && p[pi] == '*' {
		pi++
	}
	return pi == len(p)
}

// ---------------------------------------------------------------------------
// Category lookup (hot path)
// ---------------------------------------------------------------------------

// categoryOf returns the matched category name and the exact apex/wildcard/IP
// pattern that triggered the match. Both are returned so the PARENTAL LOG
// subsystem can output explicit reasoning.
func categoryOf(qname string) (string, string) {
	data := catMap.Load()
	if data == nil {
		return "", ""
	}

	// 1. Directly short circuit for IP lookups (Filter IPs Support)
	if ip, err := netip.ParseAddr(qname); err == nil {
		ip = ip.Unmap()
		if cat, ok := data.ips[ip]; ok {
			return cat, ip.String()
		}
		for _, c := range data.cidrs {
			if c.prefix.Contains(ip) {
				return c.cat, c.prefix.String()
			}
		}
		return "", ""
	}

	for _, e := range data.patterns {
		if matchGlob(e.pattern, qname) {
			return e.cat, e.pattern
		}
	}
	labels := countDomainLabels(qname)
	ceiling := catMaxLabels
	if ceiling > labels {
		ceiling = labels
	}
	search := qname
	for labels > ceiling {
		idx := strings.IndexByte(search, '.')
		if idx < 0 {
			break
		}
		search = search[idx+1:]
		labels--
	}
	for {
		if cat, ok := data.apex[search]; ok {
			return cat, search
		}
		idx := strings.IndexByte(search, '.')
		if idx < 0 || labels <= catMinLabels {
			break
		}
		search = search[idx+1:]
		labels--
	}
	return "", ""
}