use Data.Default.Class for empty NmcDom

[pdns-pipe-nmc.git] / README.md

diff --git a/README.md b/README.md
index bac7d26f51eb6a86d4e33f7b1cd7a40d9e52e03d..bbb361c7bd6e9bdd66fc23969c1b5a53c3b409d6 100644 (file)
--- a/README.md
+++ b/README.md
@@ -15,16 +15,23 @@ frontend, and has simple backend interface.
 
 ## Building
 
 
 ## Building
 

-The program is built as a single executable to be run by PowerDns's
-pipe backend. It is written in [Haskell](http://www.haskell.org/).
-There is no `cabal` configuration at the moment, so to build it,
-simply run
+The program is a single executable to be run by PowerDns's pipe
+backend. It is written in [Haskell](http://www.haskell.org/).
+If you have haskell installed on your system, run

 
 ```
 
 ```

-ghc --make pdns-pipe-nmc
+cabal configure

 ```
 
 ```
 

-and install any missing packages it complains about.
+followed by
+
+```
+cabal build
+```
+
+and hopefully it will tell you what packages are missing. You can
+install them either with your OS package manager (if they exist in
+your distribution) or with `cabal install`.

 
 ## Installing
 
 
 ## Installing
 


@@ -82,29 +89,33 @@ your resolvers.
 
 ## Status
 
 
 ## Status
 

-Alpha. It is insufficiently tested, and there are loose ends in the
-functionality. For example, version in the `SOA` record is bogus.
-Some of the the problems are due to incomplete and/or imprecise
-[definition of the domain data format](https://wiki.namecoin.info/index.php?title=Domain_Name_Specification)
-on the wiki. That said, I am using it to access some of the `.bit` websites
-and did not notice anomalies so far.
+Beta. It is mostly feature-complete, but insufficiently tested.
+It implements the
+[data format specification](http://www.average.org/pdns-pipe-nmc/spec.html)
+(SPEC.md in the source distribution) that slightly deviates from the
+[official specification](https://wiki.namecoin.info/index.php?title=Domain_Name_Specification).
+I am using it to access some of the `.bit` websites and it works
+for me.

 
 Try at your risk.
 
 ## Unsolved problems
 
 
 Try at your risk.
 
 ## Unsolved problems
 

-The biggest problem by far is generating meaningful `SOA` records. DNS
-infrastructure (including PowerDNS implementation) relies on the "generation"
-field of the `SOA` RR when it makes decision to invalidate the cache. So,
-if there is zone data in the DNS cache, and a DNS server needs to respond
-to a request about an object from that zone, it first checks if the TTL
-has expired. If it has not, the server takes the data from the cache. If
-it has expired, the server asks the "authoritative source" (which is in
-our case the dnamecoin daemon) for the SOA record and compares the
-generation count in the received response with the number kept in the
-cache. If the "authoritative" SOA does not have a greater generation
-count than the cached SOA, DNS server **does not** refresh its cache,
-presuming that the data there is still valid.
+The biggest problem by far is generating meaningful `SOA` records.
+
+### SOA Version a.k.a. Generation Count
+
+DNS infrastructure (including PowerDNS implementation) relies on the
+"generation" field of the `SOA` RR when it makes decision to invalidate
+the cache. So, if there is zone data in the DNS cache, and a DNS server
+needs to respond to a request about an object from that zone, it first
+checks if the TTL has expired. If it has not, the server takes the data
+from the cache. If it has expired, the server asks the "authoritative
+source" (which is in our case the dnamecoin daemon) for the SOA record
+and compares the generation count in the received response with the
+number kept in the cache. If the "authoritative" SOA does not have a
+greater generation count than the cached SOA, DNS server **does not**
+refresh its cache, presuming that the data there is still valid.

 
 So, it is important that the generation count in the SOA record is
 incremented every time when the domain object, or any of the object that
 
 So, it is important that the generation count in the SOA record is
 incremented every time when the domain object, or any of the object that


@@ -120,13 +131,17 @@ recursive resolution of the subdomain tree is enforced for when
 SOA record is requested. That would invalidate the reason to have
 caching in the first place.
 
 SOA record is requested. That would invalidate the reason to have
 caching in the first place.
 

-One possible workaround would be to use some derivative of absolute
-time, such as the number of hours elapsed since the epoch, for the
-SOA generation count.
+One possible workaround, currently implemented in `pdns-pipe-nmc`, is to
+use a derivative of absolute time, in our case the number of 10-munute
+intervals elapsed since Namecoin was concieved, as the SOA generation
+count.
+
+### Nameserver field

 
 

-At the time of this writing, `pdns-pipe-nmc` simply reports zero as
-the SOA generation count. This leads to stale results until `pdnsd`
-is restarted.
+There is no "reasonable" value that could be placed there. Except
+possibly the name of the host on which the PoweDNS instance is running,
+in the `.bit` zone. Currently, `pdns-pipe-nmc` just puts a dot "."
+there, and no problems where noticed so far.

 
 ## Getting the Software
 
 
 ## Getting the Software
 


@@ -144,7 +159,8 @@ There is a binary built for x86_64 Linux with glibc6:
 
 | Executable file                                                                                                      | PGP                                                                 |
 |----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
 
 | Executable file                                                                                                      | PGP                                                                 |
 |----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|

-| [pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f](pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f) | [sig](pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f.sig) |
+| [**pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-22.git-108b6c2**](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-22.git-108b6c2) | [sig](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-22.git-108b6c2.sig) |
+| [pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f) | [sig](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f.sig) |

 
 ## Author
 
 
 ## Author