Amazon Route 53 - DNS Zone File

Making it easy to use and extend DNS Zone Files. BIND format and beyond.

Modular and extensible. Built-in features use the same API available to consumers. A core parser and validator are exported and their default visitors are imported by the consumer. Consumers extend functionality with adapters and visitors to satisfy domain requirements.

Features

0 dependencies.

| Feature | Support | |---------|----------------| | Parse zone file | Yes | | Validate zone file | Yes | | Extendable validation | Yes | | Extendable parsing | Yes | | Export zone file | Open feature request | | Custom directives | Open feature request | | Custom record types | Open feature request |

Basic Usage

For advanced usage, see src/example and the tests.

Parser

The Parser is an es6 class that turns string zone files into objects for varied use cases.

It does this by transforming the input string into an array with normalized and grouped values. The array is looped through and the visitors are called with the value group. The visitors take the values, parse the contents, add the output to zoneObj, and then add meta information which is saved to parsingMeta (a sort of source map).

See the parser typings for more details.

import { Parser } from 'amazon-route-53-dns-zone-file'

const parser = new Parser('igloo.com').setText(`
  $TTL 1w
  1 A 127.0.0.1
  2 A 127.0.0.1
  3 A 127.0.0.1
`).parse();

Validator

Important the getErrorText option is so that you can add i18n/translated error messages.

This es6 class is instantiated with an options object. These are merged with the default ones. Note this behaviour is likely to change.

When the validate(parser) method is called, the preValidators[] are called, then the sourceMeta<Map> is looped through and the loopValidators[] are called, then the postValidators[] are called.

Errors thrown by any validators are added to the public property errors. Note this may change to a more general name ("problems") so that it can be used for multiple levels of severity in the future.

import { Parser, Validator } from 'amazon-route-53-dns-zone-file'
const parser = new Parser('igloo.com').setText(`1 A 1w 127.0.0.1`).parse();
const { errors } = new Validator().validate(parser);

With translation

import { translate } from 'react-i18n'
import { Parser, Validator } from 'amazon-route-53-dns-zone-file'

const parser = new Parser('igloo.com').setText(`1 A 1w 127.0.0.1`).parse();
const validation = new Validator({getErrorText}).validate(parser);

High-level architecture

The goal of this library is to

1. Not try and to boil-the-ocean.
2. Write built-in functionality using the same API available to consumers.

Code patterns

Why have notes about design patterns? Consider these 2 options:

1. 🍪 "cookie" is quick-and-easy to understand.
2. 🧑‍🍳 "1 tsp baking sugar, 1/2 tsp salt, 1 tsp vanilla, 1 cup butter, 3/4 cup sugar, 1 egg, 2 cups semi-sweet chocolate chips baked at 350° f for 10 minutes." is not as quick-and-easy to communicate or understand.

The list in the next section works like a name rather than a recipe. Knowing the general thing makes it faster to get up-to-speed on the flow.

The design patterns communicate what high-level concepts are being used. The concepts are the same, but the recipes may differ. This means it may not be 1:1 with how you may write the same pattern.

Design patterns

1. SOLID design principles. Open for extension.
2. Modular. Exposes/exports pieces.

• The modules are imported by consumer applications.
• Applications combine the modules, extend functionality, and use adapters to satisfy their unique domain-specific requirements.

3. Visitor design pattern. Used to do something similar to the template method but by
4. Object pooling. Similar to React SyntheticEvent Object Pooling, future versions will be simplified and remove object pooling and improve performance in other ways. Really there is only 1 node instance used and the properties are updated. In practical terms, just do not keep a reference to the node. Note this will change in upcoming releases. POLA.
5. Fluent interfaces. The API uses method chaining to improve readability.

Code flow

The library

• Instantiate the Parser with the default $ORIGIN.
  • Pass in the text .
  • Call parse().
• Instantiate the Validator
  • Pass in your options. These are merged with the default options.
  • Call validate(). You pass the instance of parser here.
• Custom domain-specific validations or transforms can be run in-between parsing and validating.

Your application

• Imports the parts of this library you need and configures it.
• Takes input from a customer and passes it to the library.
• Uses the returned values and errors/warnings/problems to show updates to your customer.

Appendix

Organizational hierarchy

• /__tests__/
  • Unit tests.
• /src/example/
  • Advanced consumer setup. Extends validation and adapt the parsed obj to a format required by an API.
  • Note this is not exported! This is entirely decoupled from the rest of the package.
• /src/errors
  • Classes extending Error with added properties.
• /src/parser
  • Bulk of the code is in here. Classes for the parser node, typings, utils, and default visitors.
• /src/validation
  • Similar to /parser, but simpler. This depends on (and takes in as a param) the output of the parser.
  • Classes for the validation node, an error builder, validation utils, typings, and default validators (which are simplified visitors).
• /src/shared
  • Utils, constants, and typings used by /parser/, /validation/, and
• /src/ttl
  • Some utils to parse different types of TTL (Time To Live) input and return errors when that format is invalid. Constants and enums for date/time calculations.

Tech stack

• Changes follow semantic versioning.
• Commits follow conventional commits.
• Code formatting done with prettier and eslint.
• TypeScript typings are grouped under namespaces. This helps keep related types together and autocompleted imports short.
• Unit tests run with jest.
• React tests use testing-library.

FAQ

Why are there no index files in each folder? I want to import!

The top-level index file (src/index) is the public interface. Organizational hierarchy / folder structure and file names may change in the future so importing directly is potentially unsafe.

Does this library throw errors?

No. Errors are caught and put into arrays so that the consumer can decide what to do with them conditionally (if (...)), rather than forcing a try catch.

Learn more

• Bind 9 format

Project package

Contributing

See CONTRIBUTING.

Security

See CONTRIBUTING#security-issue-notifications for more information.

License

This project is licensed under the Apache-2.0 License.