hashprefix

package
v0.0.0-...-c1ed7b1 Latest Latest
Warning

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

Go to latest
Published: Jul 25, 2025 License: AGPL-3.0 Imports: 25 Imported by: 0

Documentation

Overview

Package hashprefix defines a storage of hashes of domain names used for filtering and serving TXT records with domain-name hashes.

Index

Constants

View Source
const (
	// PrefixLen is the length of the hash prefix of the filtered hostname.
	PrefixLen = 2

	// PrefixEncLen is the encoded length of the hash prefix.  Two text
	// bytes per one binary byte.
	PrefixEncLen = PrefixLen * 2
)

Hash and hash part length constants.

View Source
const IDPrefix = "filters/hashprefix"

IDPrefix is a common prefix for cache IDs, logging, and refreshes of hashprefix filters.

TODO(a.garipov): Consider better names.

Variables

This section is empty.

Functions

This section is empty.

Types

type EmptyMetrics

type EmptyMetrics struct{}

EmptyMetrics is the implementation of the Metrics interface that does nothing.

func (EmptyMetrics) IncrementLookups

func (EmptyMetrics) IncrementLookups(_ context.Context, _ bool)

IncrementLookups implements the Metrics interface for EmptyMetrics.

func (EmptyMetrics) UpdateCacheSize

func (EmptyMetrics) UpdateCacheSize(_ context.Context, _ int)

UpdateCacheSize implements the Metrics interface for EmptyMetrics.

type Filter

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

Filter is a filter that matches hosts by their hashes based on a hash-prefix table. It should be initially refreshed with Filter.RefreshInitial.

func NewFilter

func NewFilter(c *FilterConfig) (f *Filter, err error)

NewFilter returns a new hash-prefix filter. It also adds the caches with IDs [FilterListIDAdultBlocking], [FilterListIDSafeBrowsing], and [FilterListIDNewRegDomains] to the cache manager. c must not be nil.

func (*Filter) FilterRequest

func (f *Filter) FilterRequest(
	ctx context.Context,
	req *filter.Request,
) (r filter.Result, err error)

FilterRequest implements the [composite.RequestFilter] interface for *Filter. It modifies the request or response if host matches f.

func (*Filter) Refresh

func (f *Filter) Refresh(ctx context.Context) (err error)

Refresh implements the service.Refresher interface for *Filter.

func (*Filter) RefreshInitial

func (f *Filter) RefreshInitial(ctx context.Context) (err error)

RefreshInitial loads the content of the filter, using cached files if any, regardless of their staleness.

type FilterConfig

type FilterConfig struct {
	// Logger is used for logging the operation of the filter.
	Logger *slog.Logger

	// Cloner is used to clone messages taken from filtering-result cache.
	Cloner *dnsmsg.Cloner

	// CacheManager is the global cache manager.  CacheManager must not be nil.
	CacheManager agdcache.Manager

	// Hashes are the hostname hashes for this filter.
	Hashes *Storage

	// URL is the URL used to update the filter.
	URL *url.URL

	// ErrColl is used to collect non-critical and rare errors.
	ErrColl errcoll.Interface

	// HashPrefixMtcs are the specific metrics for the hashprefix filter.
	HashPrefixMtcs Metrics

	// Metrics are the metrics for the hashprefix filter.
	Metrics filter.Metrics

	// ID is the ID of this hash storage for logging and error reporting.
	ID filter.ID

	// CachePath is the path to the file containing the cached filtered
	// hostnames, one per line.
	CachePath string

	// ReplacementHost is the replacement host for this filter.  Queries matched
	// by the filter receive a response with the IP addresses of this host.  If
	// ReplacementHost contains a valid IP, that IP is used.  Otherwise, it
	// should be a valid domain name.
	ReplacementHost string

	// Staleness is the time after which a file is considered stale.
	Staleness time.Duration

	// CacheTTL is the time-to-live value used to cache the results of the
	// filter.
	//
	// TODO(a.garipov): Currently unused.  See AGDNS-398.
	CacheTTL time.Duration

	// RefreshTimeout is the timeout for the filter update operation.
	RefreshTimeout time.Duration

	// CacheCount is the count of the elements in the filter's result cache.
	CacheCount int

	// MaxSize is the maximum size of the downloadable rule-list.
	MaxSize datasize.ByteSize
}

FilterConfig is the hash-prefix filter configuration structure.

type Matcher

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

Matcher is a hash-prefix matcher that uses the hash-prefix storages as the source of its data.

func NewMatcher

func NewMatcher(storages map[string]*Storage) (m *Matcher)

NewMatcher returns a new hash-prefix matcher. storages is a mapping of domain-name suffixes to the storage containing hashes for this domain. If storages is empty, m.MatchByPrefix always returns nil, false, and nil.

func (*Matcher) MatchByPrefix

func (m *Matcher) MatchByPrefix(
	_ context.Context,
	host string,
) (hashes []string, matched bool, err error)

MatchByPrefix implements the filter.HashMatcher interface for *Matcher. It returns the matched hashes if the host matched one of the domain names in m's storages.

TODO(a.garipov): Use the context for logging etc.

type Metrics

type Metrics interface {
	// IncrementLookups increments the number of lookups.  hit is true if the
	// lookup returned a value.
	IncrementLookups(ctx context.Context, hit bool)

	// UpdateCacheSize is called when the cache size is updated.
	UpdateCacheSize(ctx context.Context, cacheLen int)
}

Metrics is an interface used for collection if the hashprefix filter statistics.

type Prefix

type Prefix [PrefixLen]byte

Prefix is the type of the SHA256 hash prefix used to match against the domain-name database.

type Storage

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

Storage stores hashes of the filtered hostnames. All methods are safe for concurrent use.

TODO(a.garipov): See if we could unexport this.

func NewStorage

func NewStorage(hostnames string) (s *Storage, err error)

NewStorage returns a new hash storage containing hashes of the domain names listed in hostnames, one domain name per line, requirements are described in Storage.Reset. Empty string causes no errors.

func (*Storage) Hashes

func (s *Storage) Hashes(prefs []Prefix) (hashes []string)

Hashes returns all hashes starting with the given prefixes, if any. The resulting slice shares storage for all underlying strings.

TODO(a.garipov): This currently doesn't take duplicates into account.

func (*Storage) Matches

func (s *Storage) Matches(host string) (ok bool)

Matches returns true if the host matches one of the hashes.

func (*Storage) Reset

func (s *Storage) Reset(hostnames string) (n int, err error)

Reset resets the hosts in the index using the domain names listed in hostnames and returns the total number of processed rules. hostnames should be a list of valid, lowercased domain names, one per line, and may include empty lines and comments ('#' at the first position).

Jump to

Keyboard shortcuts

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