Documentation
¶
Overview ¶
SPDX-License-Identifier: MPL-2.0 Copyright (c) 2025 Antonios Voulvoulis <contact@nftban.com>
Package util provides common utility functions for NFTBan.
meta:name="util" meta:type="package" meta:description="Common utility functions (JSON, parsing, etc.)" meta:inventory.files="" meta:inventory.binaries="" meta:inventory.env_vars="" meta:inventory.config_files="" meta:inventory.systemd_units="" meta:inventory.network="" meta:inventory.privileges=""
SPDX-License-Identifier: MPL-2.0 Copyright (c) 2025 Antonios Voulvoulis <contact@nftban.com>
meta:name="util_parse" meta:type="package" meta:description="Common parsing utilities (bool, float, int)" meta:inventory.files="" meta:inventory.binaries="" meta:inventory.env_vars="" meta:inventory.config_files="" meta:inventory.systemd_units="" meta:inventory.network="" meta:inventory.privileges=""
Index ¶
- func ExtractJSON(output string) string
- func ExtractJSONArray(output string) string
- func FileExists(path string) bool
- func FormatBytes(bytes int64) string
- func FormatBytesUint(bytes uint64) string
- func FormatPercent(value float64) string
- func IsDir(path string) bool
- func IsFile(path string) bool
- func IsJSON(s string) bool
- func LoadLines(path string, handle func(line string) error) error
- func ParseBool(s string, defaultVal bool) bool
- func ParseFloat(s string, defaultVal float64) float64
- func ParseInt(s string, defaultVal int) int
- func ParseInt64(s string, defaultVal int64) int64
- func ParseUint(s string, defaultVal uint64) uint64
- func RemoveLineFromFile(filePath string, shouldRemove func(line string) bool) (bool, error)
- type DiffResult
- type Set
- func (s Set[T]) Add(v T)
- func (s Set[T]) Clear()
- func (s Set[T]) Clone() Set[T]
- func (s Set[T]) Difference(other Set[T]) Set[T]
- func (s Set[T]) Has(v T) bool
- func (s Set[T]) Intersection(other Set[T]) Set[T]
- func (s Set[T]) Len() int
- func (s Set[T]) Remove(v T)
- func (s Set[T]) ToSlice() []T
- func (s Set[T]) Union(other Set[T]) Set[T]
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractJSON ¶ added in v1.8.2
ExtractJSON extracts JSON object from mixed output string. Useful for parsing CLI output that may contain non-JSON text.
func ExtractJSONArray ¶ added in v1.8.2
ExtractJSONArray extracts JSON array from mixed output string.
func FileExists ¶ added in v1.8.2
FileExists checks if a file or directory exists at the given path. Returns true if the path exists, false otherwise.
func FormatBytes ¶ added in v1.8.2
FormatBytes formats a byte count into a human-readable string. Uses binary units (1024-based): B, KB, MB, GB, TB, PB, EB.
func FormatBytesUint ¶ added in v1.8.2
FormatBytesUint formats an unsigned byte count into a human-readable string.
func FormatPercent ¶ added in v1.8.2
FormatPercent formats a percentage value with one decimal place.
func IsDir ¶ added in v1.8.2
IsDir checks if the given path is a directory. Returns true if it's a directory, false if it doesn't exist or is a file.
func IsFile ¶ added in v1.8.2
IsFile checks if the given path is a regular file. Returns true if it's a file, false if it doesn't exist or is a directory.
func LoadLines ¶
LoadLines reads a file line-by-line and calls the handler for each line. Designed for efficient processing of large files (threat feeds, logs, configs).
Key optimizations: - Preallocated 64KB buffer prevents allocations for typical lines - 1MB max line length handles pathological cases safely - Single pass, streaming design for memory efficiency - Early error returns prevent partial processing
The handler function receives each line as a string and can: - Return nil to continue processing - Return error to stop and propagate error
Use cases in nftban v1.0: - Whitelist/blacklist file loading - Threat feed parsing - Suricata eve.json tailing - Mail/panel log parsing - Any line-oriented file processing
Example usage:
err := util.LoadLines("/etc/nftban/whitelist.conf", func(line string) error {
line = strings.TrimSpace(line)
if line == "" || strings.HasPrefix(line, "#") {
return nil // skip empty lines and comments
}
// process line...
return nil
})
func ParseBool ¶ added in v1.8.2
ParseBool parses boolean string with multiple formats. Recognizes: true/false, yes/no, 1/0, on/off
func ParseFloat ¶ added in v1.8.2
ParseFloat parses float string with default fallback
func ParseInt64 ¶ added in v1.8.2
ParseInt64 parses int64 string with default fallback
func RemoveLineFromFile ¶
RemoveLineFromFile removes lines from a file that match the given predicate. The predicate function receives each line and returns true if the line should be removed. Returns whether any lines were removed.
This is used by both whitelist and blacklist packages to remove IPs from config files. The atomic write pattern (write to tmp, then rename) ensures file integrity.
Example usage:
removed, err := util.RemoveLineFromFile("/etc/nftban/blacklist.d/99-manual.conf",
func(line string) bool {
ip := strings.Fields(strings.TrimSpace(line))[0]
return ip == "192.168.1.100"
})
Types ¶
type DiffResult ¶
type DiffResult[T comparable] struct { ToAdd []T ToRemove []T Unchanged int }
DiffResult is a generic diff result between two slices of comparable values. This replaces the old string-specific diff and can be reused for IPs, ports, feed IDs, alert types, or any comparable type.
func ComputeDiff ¶
func ComputeDiff[T comparable](desired, current []T) DiffResult[T]
ComputeDiff returns which items should be added/removed to transform `current` into `desired`.
This is the foundation for all sync operations in nftban v1.0: - IP set synchronization (whitelist/blacklist) - Threat feed updates - Suricata alert type management - Port set updates - Any set-based diff operation
Performance characteristics: - O(n + m) time complexity where n=len(desired), m=len(current) - Preallocated maps with capacity hints for efficiency - Zero allocations for unchanged items
Example usage:
desired := []string{"1.2.3.4", "5.6.7.8"}
current := []string{"5.6.7.8", "9.9.9.9"}
diff := util.ComputeDiff(desired, current)
// Result: ToAdd=["1.2.3.4"], ToRemove=["9.9.9.9"], Unchanged=1
type Set ¶
type Set[T comparable] map[T]struct{}
Set is a generic set implementation using Go's map type. Uses struct{} as value type for zero memory overhead.
This replaces map[string]bool and similar patterns throughout the codebase with a consistent, efficient, and type-safe API.
Benefits over map[T]bool: - Zero memory overhead for values (struct{} vs bool) - Consistent API across all set operations - Type-safe - Self-documenting code
func NewSet ¶
func NewSet[T comparable](values ...T) Set[T]
NewSet creates a new set and optionally adds initial values. Preallocates map with correct capacity if initial values provided.
Example:
// Empty set ips := util.NewSet[string]() // Set with initial values ports := util.NewSet(80, 443, 8080)
func (Set[T]) Add ¶
func (s Set[T]) Add(v T)
Add adds a value to the set. Safe to call multiple times with same value (idempotent).
func (Set[T]) Clear ¶
func (s Set[T]) Clear()
Clear removes all elements from the set. More efficient than creating a new set if you plan to reuse.
func (Set[T]) Clone ¶
Clone creates a shallow copy of the set. Useful when you need to preserve the original.
func (Set[T]) Difference ¶
Difference returns a new set containing elements in s but not in other.
func (Set[T]) Intersection ¶
Intersection returns a new set containing only elements present in both sets.
func (Set[T]) Remove ¶
func (s Set[T]) Remove(v T)
Remove removes a value from the set. Safe to call even if value doesn't exist.
Source Files