Model

Overview

A Zone contains resource records. Resource records with the same name, class, and type are referred to as Resource Record Sets.

Immutability

Denominator employs immutable style. This implies that all parameters are passed at once to a constructor. It is widely recognized that factory methods and builders are preferred to constructors since they can hint the names of the parameters.

Zone

A zone is roughly analogous to a subdomain. Its name might be something like denominator.io or with trailing dot denominator.io. depending on the provider. When present, Zone.id() suggests duplicate zones may exist.

ResourceRecordSet

A Resource Record Set is what is signed when DNS providers implement DNSSEC. As DNSSEC is a feature denominator supports, when we list Resource Records, we are actually listing Resource Record Sets.

For example, the following is a resource record set which contains all ipv4 addresses associated with www in the zone foo.com. aka www.foo.com

name          class   type    rdata

www           IN      A       192.168.254.3
www           IN      A       192.168.254.4
www           IN      A       192.168.254.5

The denominator ResourceRecordSet class implements Set<R> adding fields corresponding to its textual representation: name, type, and optional ttl. Class IN is assumed and left out. ResourceRecordSet is an immutable set of either RData or Strings elements, allowing users to choose a type-safe builder or shortcuts depending on their context.

ex. using the type-safe approach

import static denominator.model.ResourceRecordSets.a;
...
ResourceRecordSet.<AData> builder()
                 .name("www.denominator.io.")
                 .ttl(3600)
                 .add(AData.create("192.168.254.3"))
                 .add(AData.create("192.168.254.4"))
                 .add(AData.create("192.168.254.5")).build();

ex. using the shortcuts

import static denominator.model.ResourceRecordSets.a;
...
a("www.denominator.io.", 3600, ImmutableList.of("192.168.254.3", "192.168.254.4", "192.168.254.5"))

Record Data (RData)

Resource records have several commonly used types. For example, the following record types are well-defined and supported across all DNS servers: A, AAAA, CNAME, MX, NS, PTR, SOA, SPF, SRV, TXT

For example, the rdata fields for an A record is a simple string that represents the IP address:

1.2.3.4

SOA rdata is a more complex structure:

ns.example.com. hostmaster.example.com. (
                              2003080800 ; sn = serial number
                              172800     ; ref = refresh = 2d
                              900        ; ret = update retry = 15m
                              1209600    ; ex = expiry = 2w
                              3600       ; nx = nxdomain ttl = 1h
                              )

Structure of RData

RData is anything that implements Map<String, Object>. The field names correspond to the binary field names in DNS. Common types are defined in the denominator.model.rdata package.

For example, the following are identical:

MXData.create(10, "mx.denominator.io.").getPreference();
MXData.create(10, "mx.denominator.io.").get("preference");
ImmutableMap.<String, Object> of("preference", 10, "exchange",  "mx.denominator.io.").get("preference");

Profiles

ResourceRecordSet.profiles() is a list of maps, where the key type is set to a well-known value, typically the lowercase name of the profile. For example, Geo extends from map, and its value of type is geo and its regions field is a multimap describing the territories it applies to. Weighted is another profile, and its weight field determines the fraction of traffic it receives.

Qualifier

A client sees at most one ResourceRecordSet for a record name and type using tools like dig. When present,ResourceRecordSet.qualifier() indicates there exist profiles which control conditions under which the records is visible to the client. Hence, ResourceRecordSet with different qualifiers are meaningfully distinct and may repeat for the same name, type query.