Documentation
¶
Overview ¶
Package catdb is Layer 2 of the two-tier URL categorisation engine — the community category store. It is a self-contained leaf extracted from the flat package main per ADR-0002; it contains the BadgerDB dependency (the proxy's only category-DB use of Badger) behind a narrow API.
Storage: BadgerDB (v4, pure-Go, no CGo).
Key layout: []byte(domain) e.g. "facebook.com" Value layout: []byte(mapped category) e.g. "Social"
Subdomain matching: domain walking — query most-specific label first, then strip the leftmost label and retry, stopping before a bare TLD. e.g. "sub.facebook.com" → "facebook.com" → stop (next would be "com").
Layer 1 (the admin-managed catStore in package main) is always consulted first; this community store is the fallback for entries not in the admin-managed lists.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CommunityDB ¶
type CommunityDB struct {
// contains filtered or unexported fields
}
CommunityDB wraps a BadgerDB instance for URL category lookups. All exported methods are safe for concurrent use.
func Open ¶
func Open(dir string) (*CommunityDB, error)
Open opens (or creates) a BadgerDB at the given directory. Truncate is enabled so a crashed container can restart without manual intervention — BadgerDB replays and truncates a corrupted value log.
func (*CommunityDB) BulkWrite ¶
func (c *CommunityDB) BulkWrite(entries map[string]string) error
BulkWrite atomically writes a batch of domain→category pairs into BadgerDB. Existing entries for the same domain are overwritten. Uses WriteBatch for high-throughput ingestion without holding a long-lived transaction — safe to call while the DB serves concurrent reads.
func (*CommunityDB) Close ¶
func (c *CommunityDB) Close() error
Close flushes and closes the underlying BadgerDB. Must be called on graceful shutdown to prevent value-log corruption.
func (*CommunityDB) Lookup ¶
func (c *CommunityDB) Lookup(host string) (string, bool)
Lookup returns the mapped category for host (or any of its parent domains). Uses domain walking: tries host, then strips the leftmost label and retries, stopping when no further parent exists above the TLD. Returns ("", false) when no entry is found.
func (*CommunityDB) Stats ¶
func (c *CommunityDB) Stats() (keys int64)
Stats returns the estimated number of keys stored in the DB.
Source Files