## Data Format
-`DomObj` is a JSON object, specifically a `Map` (not an `Array`), or a
-`String` containing a dotted quad (see Note below).
-
### `DomObj` Object
-`DomObj` is a JSON `Map`, with the following attributes, all optional:
-
-| Key | Type | Comment |
-|-------------|---------------------------------------|---------------------------------|
-| service | Array(SrvObj) | Located two levels above pos. |
-| ip | Array(String) | Dotted quad "1.2.3.4" |
-| ip6 | Array(String) | Semicolon format "DEAD::BEEF" |
-| tor | String | Onion name |
-| i2p | I2pObj | |
-| freenet | String | |
-| alias | String | Nullifies other attributes |
-| translate | String | Nullifies other attributes |
-| email | String | Used in `SOA` |
-| loc | String | Format suitable for `LOC` |
-| info | JsonObj | Currently unspecified |
-| ns | Array(String) | Domain names as in `NS` |
-| delegate | String | Replaces current object |
-| import | String | "Deep" merges into current obj. |
-| map | Map(String:DomObj) | Tree of subdomain objects |
-| fingerprint | Array(String) | |
-| tls | Map(String:Map(String:Array(TlsObj))) | |
-| ds | Array(DsObj) | |
+`DomObj` either a `String` containing a dotted quad (see Note below),
+or a JSON `Map`, with the following attributes, all optional:
+
+| Key | Type | Comment |
+|-------------|---------------------------------------|--------------------------------------------|
+| service | Array(SrvObj) | Located two levels above position |
+| ip | Array(String) | Dotted quad format "1.2.3.4" |
+| ip6 | Array(String) | Semicolon format "DEAD::BEEF" |
+| tor | String | Onion name |
+| i2p | I2pObj | |
+| freenet | String | |
+| alias | String | Nullifies other attributes |
+| translate | String | Nullifies other attributes |
+| email | String | Used in `SOA` |
+| loc | String | Format suitable for `LOC` |
+| info | JsonObj | Currently unspecified |
+| ns | Array(String) | Domain names as in `NS` |
+| delegate | String | Replaces current object |
+| import | Array(String) | "Deep" merges into current object |
+| map | Map(String:DomObj) | Tree of subdomain objects |
+| fingerprint | Array(String) | |
+| tls | Map(String:Map(String:Array(TlsObj))) | Outer `Map` by `Protocol`, inner by `Port` |
+| ds | Array(DsObj) | |
#### Notes:
* Any attribute specified as `Array(String)` may be present in the
- JSON document as `String`, which is interpreted the same way as
- an `Array` containing a single `String` element.
-* In any place where `DomObj` is expected there may be a `String`, which
- is interpreted as an IPv4 address. In other words, a string `"1.2.3.4"`
- is interpreted the same way as the object `"{\"ip\":\"1.2.3.4\"}"`
- Such "shorthand" DomObj can be present at the top level or as a value
- in the `"map"` attribute.
+ JSON document as a plain `String`, which is interpreted the same way
+ as an `Array` containing a single `String` element.
+* If `DomObj` is a `String`, it is interpreted as an IPv4 address.
+ In other words, string `"1.2.3.4"` is the same as the Map
+ `"{\"ip\":\"1.2.3.4\"}"`. Such "shorthand" DomObj can be present at
+ the top level or as a value in the `"map"` attribute.
### `SrvObj` Object
* `Service` and `Protocol` are two elements of the domain name, without
the undescore '_'.
* `SrvObj` with Service `"smtp"`, Protocol `"tcp"` and Port `25` is also
- interpteted as an `MX` DNS respource.
+ interpteted as an `MX` DNS resource.
* When lookup is performed for `SRV` records at fqdn
`"_serv._proto.sub.dom.bit"`, domain object for `"sub.dom.bit"` must be
fetched, and in this object, `SrvObj`s for the Service `"serv"` and
- Protocol `"proto"` selected from it.
+ Protocol `"proto"` selected from its `"service"` attribute.
### `TlsObj` Object
## Data Interpretation
-Assuming a query for a subdomain of a basedomain in the `.bit` TLD
-(subdomain possibly being empty), lookup starts by fetching the
-"base" object for basedomain. The domain object is then transformed
-by the following sequece applied recursively:
+### Semantics of the Attributes
+
+#### service attribute
+
+Translates to DNS `SRV` RR, only it is located in the subdomain tree
+two levels higher than the `SRV` record would. For example, a
+`"service"` attribute in the `"map"` hieararchy at the point
+corresponding to the FQDN "sub.dom.bit" with the value
+
+```
+"service": [ ["imap", "tcp", 0, 0, 143, "mail.host.com." ],
+ ["smtp", "tcp", 0, 0, 25, "relay.host.com."] ]
+```
+
+corresponds to two `SRV` RRs at two different points in the
+subdomain tree:
+
+```
+_imap._tcp.sub.dom.bit. IN SRV 0 0 143 mail.host.com.
+_smtp._tcp.sub.dom.bit. IN SRV 0 0 25 relay.host.com.
+```
+
+In addition to these, an `MX` RR is syntesized at the "sub.dom.bit"
+level:
+
+```
+sub.dom.bit. IN MX 0 relay.host.com.
+```
+
+#### ip attribute
+
+Contains a list of strings representing IPv4 addresses in dotted
+quad notation. For example,
+
+```
+"ip": ["1.2.3.4", "5.6.7.8"]
+```
+
+translates into a series of `A` RRs:
+
+```
+ IN A 1.2.3.4
+ IN A 5.6.7.8
+```
+
+#### ip6 attribute
+
+
+#### tor attribute
+
+
+#### i2p attribute
+
+
+#### freenet attribute
+
+
+#### alias attribute
+
+
+#### translate attribute
+
+
+#### email attribute
+
+
+#### loc attribute
+
+
+#### info attribute
+
+
+#### ns attribute
+
+
+#### delegate attribute
+
+
+#### import attribute
+
+
+#### map attribute
+
+
+#### fingerprint attribute
+
+
+#### tls attribute
+
+
+#### ds attribute
+
+
+### Lookup Sequence
+
+Assuming a query is performed for
+`sdN`++"."++{...}++"."++`sd2`++"."++`sd1`++"."++`dom`++".bit"
+(`sdX` list possibly being empty), the lookup process starts by
+querying the database for the object corresponding to `dom`.
+Technically, it is easiest to populate a "seed" DomObj with a
+single attribute `"import"` the value of which corresponds to the
+`dom` name in the Namecoin namespace, which is `"d/" ++ dom`.
+This domain object is then transformed by the following
+recursive sequece:
1. Value of the element of the `"map"` attribute with the key `""`
(empty string) is recursively merged into the base domain. The
2. If attribute `"import"` does not exist in the resulting object,
recursion stops, and step 3 is performed on the result
If attribute `"import"` exists in the resulting object, lookup is
- is performed for the value of this attribute, and fetched object
- is recursively merged into the base domain. The `"import"` attribute
+ is performed for the values of this attribute, and fetched objects
+ are recursively merged into the base domain. The `"import"` attribute
is removed from the result. Then the result is passed as base
domain to step 1.
3. If subdomain chain is empty, recursion stops, and step 4 is
Note that the process involves recursion nested to three levels.
-## Merging
+### Merging Procedure
When a domain object `sub` needs merging into a domain object `base`,
the following rules are applied:
projects / pdns-pipe-nmc.git / blobdiff