-
Notifications
You must be signed in to change notification settings - Fork 110
Model
A Zone contains resource records. Resource records with the same name, class, and type are referred to as Resource Record Sets.
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.
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 including name, class, type, and ttl. It is an immutable set of either RData or Strings elements, allowing users to choose a type-safe or type-free approach depending on their context.
ex. using the type-safe approach
ResourceRecordSet.<AData> builder()
.name("www")
.ttl(3600)
.add(a().address("192.168.254.3"))
.add(a().address("192.168.254.4"))
.add(a().address("192.168.254.5")).build();
ex. using the type-free approach
ResourceRecordSet.<String> builder()
.name("www")
.ttl(3600)
.type(1)
.add("192.168.254.3")
.add("192.168.254.4")
.add("192.168.254.5").build();
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
)
When Denominator calls toString() on the RData, it expects it to be a well-formed based on its type.
It is possible to create records that do not have well-known types like FUBAR. In fact, the spec reserves many type codes for your extension pleasure. Due to this, there are likely conditions where the friendly type is not know. For example, we know that AAAA is type code 28. However, we may not know the type corresponding to 32770. This means that we cannot use java Enum to represent all types.
The structure of the RData is type-specific, but eventually renders to a String. Exporters such as Edda do not need to deconstruct the RData into a java type, as they are only logging it. Intermediaries can also leave the rdata in its native String form, as all supported DNS providers simply accept and produce opaque rdata strings. That said, deconstructing RData is useful for some who are interested in the semantics of the record data. For example, a GUI might be interested so that it can populate fields without knowing the type up front. Since these two camps, type-safe and type-free, need to coexist, Denominator represents a ResourceRecordSet as primarily a Set of strings, optionally viewable as a Set of RData objects.
RData ranges from zero-length to highly structured data. RData contains an inner static interface Builder with a single build method. This allows concrete types to define any parameters they need.
RData.Builder<R extends RData> {
R build();
}
The generically parameter on build() allows RData-aware collections to add elements and implicitly call build() on behalf of the user.
For example, a user can call rcollection.add(SomeRData.builder().foo("bar")) as opposed to the more verbose rcollection.add(SomeRData.builder().foo("bar").build()) when said collection overloads with add(Builder<R> record).
We wish to reduce clutter where possible, For example, while technically A.builder().address("1.2.3.4") is necessary, a shortcut a().address("1.2.3.4") should be exposed to reduce the noise for users. a() in this case is a static method.
While all record data can be represented as an opaque string, well known types have formats specified in an RFC such as rfc1035. For the types that can only have specific formats, we facilitate populating them in a type-safe way through builders. Builders expose parameter names and allow us to validate fields are correct. Denominator includes a number of common RData types to facilitate easy and safe construction of most records.
ex. AData is simple, but is validatable.
rData = AData.builder().address("1.2.3.4").build();
ex. MXData is structured with two mandatory parts.
rData = MXData.builder().preference(2).exchange("server2.mydomain.com.").build();
ex. SOAData is complex.
rData = SOAData.builder()
.ns("ns.mynameserver.com.")
.email("root.ns.mynameserver.com.")
.serial(2004123001)
....
.build();
Many users will employ type-safe classes such as SOAData to construct record data. Others, for example those writing parsers, may wish to opt-out of the type safe classes. For example, it is a common case simply to pass records from one source to another. Converting to narrowed java types isn't necessary in this case, and attempts to do so would result is a large switch statement or complex factory lookup code. Users in these scenarios should not use RData types and instead just use Strings.
Ex. instead of the more verbose and high maintenance approach of type-specific lookups
rdata = findParser(row.column(3)).parse(row.column(4));
just use the string.
rdata = row.column(4);