Zonema...erview(3pm)

📦 version 1.0.16, in ubuntu jammy

💖 Zonemaster::Overview — The Zonemaster Test Engine 💖

okay bestie, pull up a chair, we're reading Zonemaster::Overview(3pm) together and it's genuinely such a serve. this is the tea on the Zonemaster test engine, the whole thing, no gatekeeping. 🫶

✨ INTRODUCTION ✨

so the Zonemaster system is a quality control tool for DNS zones, and it's a collab between AFNIC and IIS — those are the top-level registries for France and Sweden respectively, iconic duo behavior fr fr. it's the successor to both AFNIC's tool Zonecheck and IIS's tool DNSCheck, and the whole point is that it's meant to be an improvement over both. glow up achieved. 💅

the system as a whole is the test engine plus, as distributed by the project, two different front ends:

  • one is a command-line interface, intended for use by experienced technicians (that's the iykyk crowd)
  • one is a web interface, meant for use by anyone (yes literally anyone, main character energy for the general public)

and this document? it only talks about the test engine. just the engine. nothing else. periodt. 🎀

🌸 DESCRIPTION 🌸

🦋 Brief overview 🦋

conceptually, the test engine is a bunch of test implementation modules surrounded by a support framework. that's the whole vibe. anyone who wants to use Zonemaster to actually perform tests talks to the framework from the "outside", and all the modules implementing tests see the world entirely through the framework. no peeking behind the curtain bestie.

and the way we do things here buys us some genuinely great features:

  • the ability to test domains before they are published ✨
  • the ability to record entire test runs for later analysis 📼
  • and making sure that test results are — as far as reality allows — predictable and repeatable 🔁

💜 For users of Zonemaster 💜

okay so if all you wanna do is run tests, you only need to care about like four or five modules. not bad!

  • Zonemaster is the main access point to the framework, and it's via its methods that you set the configuration (if needed), request that tests be started, and access the logger.
  • the logger is where the test results end up, so that's pretty important, obviously.
  • on top of those, you may want Zonemaster::Translator to turn the results into human-readable messages. 🫶

and here's the thing — there are two ways you can get the results of a test you've requested:

  1. the simple-but-inflexible way
  2. the flexible-but-complex way

🍓 the simple-but-inflexible way 🍓

so every method in Zonemaster that runs tests returns lists of Zonemaster::Logger::Entry objects. those lists include all the results that the writer of the test module(s) considered important enough to return by default. the advantage? it is extremely easy to use. and here's a functional (if not very useful) way to run a full test and print the results right from a command line prompt:

perl -MZonemaster -E 'say "$_" for Zonemaster->new->test_zone("example.org")'

the main drawbacks though 😭:

  • there's no choice about what messages to see
  • it's entirely asynchronous — the code that started the test does not get a chance to do anything at all until the whole test has finished, which may be several minutes later

🧚 the flexible-but-complex way 🧚

to get around those drawbacks, there's the flexible-but-complex way, which consists of installing a callback that gets executed every time a message is logged. and ngl, code-wise it's not that much more complicated. here's an example that does roughly the same thing as the one above:

perl -MZonemaster -E 'Zonemaster->logger->callback(sub {say "$_[0]"}); Zonemaster->new->test_zone("example.org");'

if you try running those, you'll notice two main differences:

  1. the second variant prints results as they are generated ✨
  2. it generates a lot more output

and on the author's machine right now, the first example gives 94 lines of output, while the second example gives 17684. yes. seventeen thousand. 💀

you can do pretty much whatever you want with the message objects in the callback (including modifying them, although we don't promise that behavior will stay around, so don't get too attached 🙈).

⚠️ if the callback code throws an exception, and that exception is not a subclass of Zonemaster::Exception, the callback will be removed. gone. bye. 💅
⚠️ also note: while the callback is running, the test engine itself is not. so think twice before you do potentially time-consuming tasks (like sticking the message in a database) in the callback, bestie. after waiting for responses from remote name servers (which usually stands for more than 90% of the time used), result logging is the single most time-consuming task in a Zonemaster test run.

from here, you probably want to look at the documentation for:

  • Zonemaster
  • Zonemaster::Logger
  • Zonemaster::Logger::Entry
  • Zonemaster::Config
  • Zonemaster::Translator

🌈 For developers of Zonemaster Test Modules 🌈

if you want to develop a test module of your own, the Zonemaster::Test::Example module is intended to serve as an example. and the standard set of modules also fulfils that purpose to various degrees, of course. but here's the one that's especially interesting — Zonemaster::Test::DNSSEC — because it is an example of including default translation and policy data with the module source code. obsessed tbh.

as an entry point to the "inside" of the Zonemaster framework, you want to read Zonemaster::Zone and follow references from there. and after the zone class, the ones of particular interest are:

  • Zonemaster::Nameserver
  • and possibly Zonemaster::Recursor

and then, a personal note from the author: if you do write your own test module, they would very much appreciate feedback on which parts were tricky to figure out, because honestly they're not sure what needs to be explained here. so please, if there's something that you think really needs to be written about, add an issue about it at:

https://github.com/dotse/zonemaster-engine/issues

👑 For developers of the Zonemaster Test Framework 👑

random recommendations and advice, bestie. and note — this may be replaced with more coherent developer documentation in the future, so enjoy the chaos while it lasts. 💖

  • Stability, predictability and reliability are more important than performance. say it louder for the people in the back.
  • don't forget that starting with Perl version 5.18, the order in which you get the keys out of a hash will be different every time the script is run. get used to always writing sort keys %hash. no cap, just do it.
  • if two (or more) test implementation modules implement the same (or very similar) thing, it should probably be extracted into the framework.
  • the unit tests run against pre-recorded data, unless the environment variable ZONEMASTER_RECORD is set to a (perl-)true value. in that case, it runs against the live DNS world and records all results for future use. unfortunately this sometimes means that some tests fail, when we were relying on seeing certain problems in certain domains, and those no longer look the same. 😭
  • the translation strings returned from a test module are used as keys in the GNU gettext system, so if you change anything in them don't forget to also change the translation .po files in share.
  • adding a new message tag is more work than it first looks, since it needs to be added to the test module metadata, the default policy and the translation system in order to be fully functional. it's giving ✨three places at once✨.

🔗 REFERENCES

  • <https://github.com/dotse/zonemaster> — bestie this is the main repository, and it's holding, among other things, our test specifications. like it's the mothership okurrr ✨

📚 List of all RFCs referred to in the test specifications

okay so this is the reading list and honestly? it's giving ✨syllabus✨. every single one of these is cited somewhere in the test specs, so here they all are, no skips, no skimming, we are completing the assignment 💅

and that's the whole list bestie, all 55 of them, we ate and left no crumbs 🍓 go read them at your own pace, hydrate, take breaks, the RFCs aren't going anywhere 💜

this page was brought to you by perl v5.32.0, dated 2021-01-06, and it's the Zonema...erview(3pm) one — thanks for reading all the way to the bottom, you're literally the main character 🫶✨💅

📦 where this page comes from