How duckduckgo/trackerradarkit works
Main Components
• Library Core (TrackerRadarKit): This is the heart of the package and contains the primary logic.
• TrackerData: A struct that models the JSON data sourced from DuckDuckGo’s Tracker Radar file.
• ContentBlockerRule: A data structure representing individual web content blocking rules.
• ContentBlockerRulesBuilder: The component that takes in TrackerData and an optional exception list (allowList) and transforms it into a set of content blocker rules.
• Utility Extensions: Files like ArrayExtension.swift, URLExtension.swift, and TrackerException.swift provide helper functionality which supports the core transformation and data handling.
Supporting Structures
• Swift Package Manager & Build Files:
• Package.swift: Shows how the package is structured and its dependency, notably the swift-argument-parser.
• .swiftlint.yml: Indicates enforced coding style and conventions.
• Xcode configuration folders (swiftpm/xcode): Infrastructure for building the package in Xcode.
• Validator Tool (Implicit Component):
• Although not directly seen in a separate source file, the README mentions a Validator tool that validates the Tracker Radar data by parsing, transforming, and compiling it into a rule list; this can be represented as a “runtime component” or “utility executable” that operates on the same core logic.
• Testing Suite:
• The Tests directory, which contains unit tests for critical modules (e.g., ArrayExtensionTests, ContentBlockerRulesBuilderTests, URLExtensionTests) along with test utilities and mock data, ensuring correctness.
Relationships and Interactions
• Data Flow:
• TrackerData (parsed JSON) → passed to ContentBlockerRulesBuilder.
• ContentBlockerRulesBuilder → processes TrackerData along with any exception/allowList → generates an array of ContentBlockerRule objects.
• Output of ContentBlockerRulesBuilder → encoded as JSON, which is then ultimately used for compiling a content rule list via WKContentRuleListStore.
• External Integration:
• The library serves as a bridge between raw Tracker Radar data and Apple’s WebKit content blocker mechanism.
• Testing & Validation:
• The tests validate the transformation and building process using mock JSON data and targeted test utilities.
Architectural Patterns and Design Principles
• Modularization: The project isolates different functionalities into separate files (data model, rule builder, utility extensions) to keep concerns separated.
• Reusability: By offering a Swift package that can be imported into various projects, the design supports extensibility.
• Testability: The clear separation between production code and testing (with dedicated test utilities) supports high test coverage.
• Command-Line/Automation Friendly: The presence of Swift Package Manager configurations as well as integration with GitHub Actions (in the .github folder) indicate a CI/CD-friendly structure.