mirror of
https://github.com/google/nomulus.git
synced 2025-08-03 00:12:11 +02:00
Top-level domain name registry service on Google Cloud Platform
6debcceef4
* Don't write TX records for domains deleted in autorenew grace period When the project was originally being designed, we envisioned have a purely point-in-time architecture that would allow the system to run indefinitely without requiring any background batch jobs. That is, you could create a domain, and 10 years later you could infer every autorenewal billing event that should have happened during those 10 years, without ever having to run any code that would go through and retroactively create those events as they happened. This ended up being very complicated, especially when it came to generating invoices, so we gave up on it and instead wrote the ExpandRecurringBillingEventsAction mapreduce, which would run as a cronjob and periodically expand the recurring billing information into actual one-time billing events. This made the invoicing scripts MUCH less complicated since they only had to tabulate one-time billing events that had actually occurred over the past month, rather than perform complicated logic to infer every one-time event over an arbitrarily long period. I bring this up because this architectural legacy explains why billing events are more complicated than could otherwise be explained from current requirements. This is why, for instance, when a domain is deleted during the 45 day autorenewal period, the ExpandRecurringBillingEventsAction will still write out a history entry (and corresponding billing events) on the 45th day, because it needs to be offset by the cancellation billing event for the autorenew grace period that was already written out synchronously as part of the delete flow. This no longer really makes sense, and it would be simpler to just not write out these phantom history entries and billing events at all, but it would be a larger modification to fix this, so I'm not touching it here. Instead, what I have done is to simply not write out the DomainTransactionRecord in the mapreduce if the recurring billing event has already been canceled (i.e. because the domain was deleted or transferred). This seems inconsistent but actually does make sense, because domain transaction records are never written out speculatively (unlike history entries and billing events); they correspond only to actions that have actually happen. This is because they were architected much more recently than billing events, and don't use the point-in-time hierarchy. So, here's a full accounting of how DomainTransactionRecords work as of this commit: 1. When a domain is created, one is written out. 2. When a domain is explicitly renewed, one is written out. 3. When a domain is autorenewed, one is written out at the end of the grace period. 4. When a domain is deleted (in all cases), a record is written out recording the deletion. 5. When a domain is deleted in the add grace period, an offsetting record is written out with a negative number of years, in addition to the deletion record. 6. When a domain is deleted in the renewal grace period, an offsetting record is likely written out in addition. 7. When a domain is deleted in the autorenew grace period, there is no record that needs to be offset because no code ran at the exact time of the autorenew, so NO additional record should be written out by the expand mapreduce. *THIS IS CHANGED AS OF THIS COMMIT*. 8. When a domain is transferred, all existing grace periods are cancelled and corresponding cancelling records are written out. Note that transfers include a mandatory, irrevocable 1 year renewal. 9. In the rare event that a domain is restored, all recurring events are re-created, and there is a 1 year mandatory renewal as part of the restore with corresponding record written out. So, in summary, billing events and history entries are often written out speculatively, and can subsequently be canceled, but the same is not true of domain transaction records. Domain transaction records are only written out as part of a corresponding action (which for autorenewals is the expand recurring cronjob). * rm unused import |
||
|---|---|---|
| buildSrc | ||
| config | ||
| core | ||
| db/src/main/resources/sql/schema | ||
| docs | ||
| gradle | ||
| java-format | ||
| node_modules | ||
| prober | ||
| proxy | ||
| python/google/registry/scripts | ||
| release | ||
| services | ||
| third_party | ||
| util | ||
| .gcloudignore | ||
| .gitignore | ||
| .lgtm.yml | ||
| appengine_war.gradle | ||
| AUTHORS | ||
| build.gradle | ||
| CONTRIBUTING.md | ||
| CONTRIBUTORS | ||
| dependencies.gradle | ||
| dependency_lic.gradle | ||
| gradle.properties | ||
| gradlew | ||
| gradlew.bat | ||
| java_common.gradle | ||
| karma.conf.js | ||
| LICENSE | ||
| nomulus-logo.png | ||
| package-lock.json | ||
| package.json | ||
| projects.gradle | ||
| README.md | ||
| settings.gradle | ||
Nomulus
| Internal Build | FOSS Build | LGTM | License | Code Search |
|---|---|---|---|---|
 |
 |
 |
 |
 |
Overview
Nomulus is an open source, scalable, cloud-based service for operating top-level domains (TLDs). It is the authoritative source for the TLDs that it runs, meaning that it is responsible for tracking domain name ownership and handling registrations, renewals, availability checks, and WHOIS requests. End-user registrants (i.e. people or companies that want to register a domain name) use an intermediate domain name registrar acting on their behalf to interact with the registry.
Nomulus runs on Google App Engine and is written primarily in Java. It is the software that Google Registry uses to operate TLDs such as .google, .app, .how, .soy, and .みんな. It can run any number of TLDs in a single shared registry system using horizontal scaling. Its source code is publicly available in this repository under the Apache 2.0 free and open source license.
Getting started
The following resources provide information on getting the code and setting up a running system:
- Install guide
- View the source code for the GAE app and for the GKE proxy
- Other docs
- Javadoc
- Nomulus discussion group, for any other questions
If you are thinking about running a production registry service using our platform, please drop by the user group and introduce yourself and your use case. To report issues or make contributions, use GitHub issues and pull requests.
Capabilities
Nomulus has the following capabilities:
- Extensible Provisioning Protocol (EPP): An XML protocol that is the standard format for communication between registrars and registries. It includes operations for registering, renewing, checking, updating, and transferring domain names.
- DNS interface: The registry provides a pluggable interface that can be implemented to handle different DNS providers. It includes a sample implementation using Google Cloud DNS as well as an RFC 2136 compliant implementation that works with BIND.
- WHOIS: A text-based protocol that returns ownership and contact information on registered domain names.
- Registration Data Access Protocol (RDAP): A JSON API that returns structured, machine-readable information about domain name ownership. It is essentially a newer version of WHOIS.
- Registry Data Escrow (RDE): A daily export of all ownership information for a TLD to a third party escrow provider to allow take-over by another registry operator in the event of serious failure. This is required by ICANN for all new gTLDs.
- Premium pricing: Communicates prices for premium domain names (i.e. those that are highly desirable) and supports configurable premium registration and renewal prices. An extensible interface allows fully programmatic pricing.
- Billing history: A full history of all billable events is recorded, suitable for ingestion into an invoicing system.
- Registration periods: Qualified Launch Partner, Sunrise, Landrush, Claims, and General Availability periods of the standard gTLD lifecycle are all supported.
- Brand protection for trademark holders (via TMCH): Allows rights-holders to protect their brands by blocking registration of domains using their trademark. This is required by ICANN for all new gTLDs.
- Registrar support console: A self-service web console that registrars can use to manage their accounts in the registry system.
- Reporting: Support for required external reporting (such as ICANN monthly registry reports, CZDS, Billing and Registration Activity) as well as internal reporting using BigQuery.
- Administrative tool: Performs the full range of administrative tasks needed to manage a running registry system, including creating and configuring new TLDs.
- DNS interface: An interface for DNS operations is provided so you can write an implementation for your chosen provider, along with a sample implementation that uses Google Cloud DNS. If you are using Google Cloud DNS you may need to understand its capabilities and provide your own multi-AS solution.
- GAE Proxy: App Engine Standard only serves HTTP/S traffic. A proxy to forward traffic on EPP and WHOIS ports to App Engine via HTTPS is provided. Instructions on setting up the proxy on Google Kubernetes Engine is available. Running the proxy on GKE supports IPv4 and IPv6 access, per ICANN's requirements for gTLDs. The proxy can also run as a single jar file, or on other Kubernetes providers, with modifications.
Additional components
Registry operators interested in deploying Nomulus will likely require some additional components that are need to be configured separately.
- A way to invoice registrars for domain name registrations and accept payments. Nomulus records the information required to generate invoices in billing events.
- Fully automated reporting to meet ICANN's requirements for gTLDs. Nomulus includes substantial reporting functionality but some additional work will be required by the operator in this area.
- A secure method for storing cryptographic keys. A keyring interface is provided for plugging in your own implementation (see configuration doc for details).
- System status and uptime monitoring.
Outside references
- Donuts Registry has helped review the code and provided valuable feedback
- CoCCa and FRED are other open-source registry platforms in use by many TLDs
- We are not aware of any fully open source domain registrar projects, but open source EPP Toolkits (not yet tested with Nomulus; may require integration work) include:
- Some Open Source DNS Projects that may be useful, but which we have not tested: