Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Naming of domain message args #854

Merged
merged 8 commits into from
Dec 15, 2020
Merged

Naming of domain message args #854

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c1ced7f
Fix message args for NSEC_SIG_VERIFY_ERROR
mattias-p Nov 28, 2020
864b556
Unused messages
mattias-p Nov 17, 2020
a904074
Refactor
mattias-p Nov 17, 2020
d908de3
Rename msgid arg: domain
mattias-p Nov 17, 2020
0b62b44
Update msgid arg names in PO files
mattias-p Nov 17, 2020
92196a8
Tidy PO files
mattias-p Nov 17, 2020
cde4261
Clean up fuzzy markers
mattias-p Nov 29, 2020
51d170d
Make domain refer to nsname
mattias-p Nov 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 1 addition & 4 deletions docs/logentry_args.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
| algo_descr | Text | The human readable description of a [DNSSEC algorithm]. |
| algo_mnemo | Text | The mnemonic of a [DNSSEC algorithm]. |
| algo_num | Non-negative integer | The numeric value for a [DNSSEC algorithm]. |
| domain | Domain name | A domain name. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A domain name on what? There is already "nsname" with the same data type. The description should be more specific so that it excludes name server names, or else there should only be one.

One approach is to let instances of domain name be represented by the same argument, e.g. "domain". In the case of non-negative integer you have taken the path to have different arguments for different use of non-negative number. If the same path is followed for domain name I find the split name server name, on one side, and all other use of domain name, on the other, not to be optimal for Zonemaster.

There are some domain names that are special for Zonemaster in the sense that they point out central concepts and are frequent.

  • Name server name
  • Zone name of parent
  • Zone name of child

Other use that we have include

  • Reverse name of name server IP address
  • Mail domain
  • Non-existing zone name

If there are more than one argument for data type domain name, then at least the first three (name server name, zone name of parent and zone name of child) should be their own arguments. The last three could be grouped into one argument, but could as well be their own arguments.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a relevant and difficult topic you bring up. But I'll try to spell out how I'm think about it. Maybe we ought to take it offline, but I want to gather my thoughts in text anyway so I'll just post it here. Bare in mind that since I started working with this my perspective has been evolving.

First of all I doubt we'll be able to find a perfect design for the argument naming. I have a feeling that no matter how we turn in this question, we'll have our butts behind us.

I see a few main reasons to have give variables different names.

  1. Differences in format E.g. things that have clearly distinct presentation formats.
  2. Differences in grammar. E.g. whether it should be "more than 5" or "longer than 5" depends on what the unit is.
  3. Disambiguation. When you need more than one variable of the same kind in the same message.

In the first case the format of an argument value might affect the best way to punctuate a message, so it's seems helpful to provide translators with a hint to that end.

I apply the same general idea to the second case. If the unit of an argument value might affect the language around it, it's seems helpful to provide a hint for that.

The third case is different in my mind. It seems impossible to come up with a partitioning of different kinds of variables that's both reasonable and granular enough to ensure that no message will need to use two variables of the same kind. We need some kind of general disambiguation solution. My first choice for solving this problem is using common prefixes that indicates the kind of variable together with locally unique disambiguation suffixes.
A way to mitigate the ambiguity problem and reduce (though not eliminate) the need for disambiguation suffixes is to single out a few very common sub-kinds and promote them to a proper kind of their own. The obvious example here is nsname which I estimate to be about a third of all domain name arguments.

Returning to your question "A domain name on what?". In my mind the msgid ought to be good enough to answer what kind of domain name. From my current understanding of the issue, I don't see any reason to disambiguate different kinds of domain names any further than "domain" and "nsname". If it can be shown that having distinct kinds for "nsname" doesn't help much with disambiguation, I think we should at least consider integrating it into the generic domain kind. The same goes for the special kinds of integers.

| keytag | Non-negative integer | A keytag for a DNSKEY record or a keytag used in a DS or RRSIG record. |
| module | A Zonemaster test module, or `all` | The name of a Zonemaster test module. |
| module_list | List of Zonemaster test modules | A list of Zonemaster test modules, separated by ":". |
Expand All @@ -29,7 +30,6 @@
|| DNSKEY key length| The key length for a DNSKEY. The interpretation of this value various quite a bit with the algorithm. Be careful when using it for algorithms that aren't RSA-based.|
|| DNSSEC delegation verification failure reason| A somewhat human-readable reason why the delegation step between the tested zone and its parent is not secure.|
|| DS digest type| The digest type used in a DS record.|
| dname (?) | Domain name| A domain name.|
| dlabel (?) | Domain name label| A single label from a domain name.|
| dlength (?) | Domain name label length| The length of a domain name label.|
|| Duration in seconds| An integer number of seconds.|
Expand All @@ -56,8 +56,6 @@
|| Number of DNSKEY RRs in packet| The number of DNSKEY records found in a packet.|
|| Number of RRSIG RRs in packet| The number of RRSIG records found in a packet.|
|| Number of SOA RRs in packet| The number of SOA records found in a packet.|
|| PTR query name| The domain name generated from an IP address for a reverse name lookup.|
| pname (?) | Parent zone name| The name of a tested zone's parent zone.|
|| Protocol (UDP or TCP)| The protocol used for a query.|
| rcode (?) | RCODE| An RCODE from a DNS packet.|
|| RFC reference| A reference to an RFC.|
Expand All @@ -79,7 +77,6 @@
|| Smallest SOA serial number seen| The smallest value seen in a SOA serial field in the tested zone.|
|| TLD| The name of a top-level domain.|
|| `time_t` value when RRSIG validation was attempted| The time when an RRSIG validation was attempted, in Unix `time_t` format.|
| zname (?) | Zone name| The domain name of the zone being tested.|

Message names maked with a question mark should not be considered stable.

Expand Down
2 changes: 1 addition & 1 deletion lib/Zonemaster/Engine/Nameserver.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,7 @@ sub _query {
chomp( $msg );
$msg =~ s/$trailing_info.*/\./;
Zonemaster::Engine->logger->add( LOOKUP_ERROR =>
{ message => $msg, ns => "$self", name => "$name", type => $type, class => $href->{class} } );
{ message => $msg, ns => "$self", domain => "$name", type => $type, class => $href->{class} } );
if ( not $href->{q{blacklisting_disabled}} ) {
$self->blacklisted->{ $flags{usevc} }{ $flags{dnssec} } = 1;
if ( !$flags{dnssec} ) {
Expand Down
6 changes: 3 additions & 3 deletions lib/Zonemaster/Engine/Test.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ sub run_all_for {
} ## end foreach my $mod ( __PACKAGE__...)
} ## end if ( Zonemaster::Engine::Test::Basic...)
else {
push @results, info( CANNOT_CONTINUE => { zone => $zone->name->string } );
push @results, info( CANNOT_CONTINUE => { domain => $zone->name->string } );
}

return @results;
Expand Down Expand Up @@ -146,7 +146,7 @@ sub run_module {
}
}
else {
info( CANNOT_CONTINUE => { zone => $zone->name->string } );
info( CANNOT_CONTINUE => { domain => $zone->name->string } );
}

return;
Expand Down Expand Up @@ -200,7 +200,7 @@ sub run_one {
$zname = $arg->name;
}
}
info( CANNOT_CONTINUE => { zone => $zname } );
info( CANNOT_CONTINUE => { domain => $zname } );
}

return;
Expand Down
6 changes: 3 additions & 3 deletions lib/Zonemaster/Engine/Test/Address.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ Readonly my %TAG_DESCRIPTIONS => (
},
NO_RESPONSE_PTR_QUERY => sub {
__x # ADDRESS:NO_RESPONSE_PTR_QUERY
'No response from nameserver(s) on PTR query ({reverse}).', @_;
'No response from nameserver(s) on PTR query ({domain}).', @_;
},
TEST_CASE_END => sub {
__x # ADDRESS:TEST_CASE_END
Expand Down Expand Up @@ -221,7 +221,7 @@ sub address02 {
push @results,
info(
NO_RESPONSE_PTR_QUERY => {
reverse => $ptr_query,
domain => $ptr_query,
}
);
}
Expand Down Expand Up @@ -289,7 +289,7 @@ sub address03 {
push @results,
info(
NO_RESPONSE_PTR_QUERY => {
reverse => $ptr_query,
domain => $ptr_query,
}
);
}
Expand Down
20 changes: 10 additions & 10 deletions lib/Zonemaster/Engine/Test/Basic.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,11 +130,11 @@ sub metadata {
Readonly my %TAG_DESCRIPTIONS => (
DOMAIN_NAME_LABEL_TOO_LONG => sub {
__x # BASIC:DOMAIN_NAME_LABEL_TOO_LONG
"Domain name ({dname}) has a label ({dlabel}) too long ({dlength}/{max}).", @_;
"Domain name ({domain}) has a label ({dlabel}) too long ({dlength}/{max}).", @_;
},
DOMAIN_NAME_ZERO_LENGTH_LABEL => sub {
__x # BASIC:DOMAIN_NAME_ZERO_LENGTH_LABEL
"Domain name ({dname}) has a zero-length label.", @_;
"Domain name ({domain}) has a zero-length label.", @_;
},
DOMAIN_NAME_TOO_LONG => sub {
__x # BASIC:DOMAIN_NAME_TOO_LONG
Expand All @@ -150,11 +150,11 @@ Readonly my %TAG_DESCRIPTIONS => (
},
HAS_A_RECORDS => sub {
__x # BASIC:HAS_A_RECORDS
"Nameserver {ns} returned \"A\" record(s) for {dname}.", @_;
"Nameserver {ns} returned \"A\" record(s) for {domain}.", @_;
},
NO_A_RECORDS => sub {
__x # BASIC:NO_A_RECORDS
"Nameserver {ns} did not return \"A\" record(s) for {dname}.", @_;
"Nameserver {ns} did not return \"A\" record(s) for {domain}.", @_;
},
HAS_NAMESERVERS => sub {
__x # BASIC:HAS_NAMESERVERS
Expand Down Expand Up @@ -228,7 +228,7 @@ sub basic00 {
push @results,
info(
q{DOMAIN_NAME_LABEL_TOO_LONG} => {
dname => "$name",
domain => "$name",
dlabel => $local_label,
dlength => length( $local_label ),
max => $LABEL_MAX_LENGTH,
Expand All @@ -239,7 +239,7 @@ sub basic00 {
push @results,
info(
q{DOMAIN_NAME_ZERO_LENGTH_LABEL} => {
dname => "$name",
domain => "$name",
}
);
}
Expand Down Expand Up @@ -427,17 +427,17 @@ sub basic03 {
push @results,
info(
HAS_A_RECORDS => {
ns => $ns->string,
dname => $name,
ns => $ns->string,
domain => $name,
}
);
}
else {
push @results,
info(
NO_A_RECORDS => {
ns => $ns->string,
dname => $name,
ns => $ns->string,
domain => $name,
}
);
}
Expand Down
4 changes: 0 additions & 4 deletions lib/Zonemaster/Engine/Test/Consistency.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,10 +256,6 @@ Readonly my %TAG_DESCRIPTIONS => (
__x # CONSISTENCY:TEST_CASE_START
'TEST_CASE_START {testcase}.', @_;
},
TOTAL_ADDRESS_MISMATCH => sub {
__x # CONSISTENCY:TOTAL_ADDRESS_MISMATCH
'No common nameserver IP addresses between child ({child}) and parent ({glue}).', @_;
},
);

sub tag_descriptions {
Expand Down
Loading