push.rocks/smartdns
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Philipp Kunz
2025-03-21 18:21:47 +00:00
parent 9bc8278464
commit 7997e9dc94
9 changed files with 6038 additions and 1922 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
readme.md
View File

@@ -1,4 +1,5 @@
# @push.rocks/smartdns
A TypeScript library for smart DNS methods, supporting various DNS records and providers.
## Install
@@ -31,11 +32,11 @@ import { Smartdns } from '@push.rocks/smartdns';
### Basic DNS Record Lookup
Often, the need arises to fetch various DNS records for a domain. `@push.rocks/smartdns` simplifies this by providing intuitive methods.
Often, the need arises to fetch various DNS records for a domain. `@push.rocks/smartdns` simplifies this by providing intuitive methods. A DNS record is essentially a map from a domain name to information about that domain, such as its IP address, mail exchange server, etc.
#### Fetching A Records
To fetch an "A" record for a domain:
To fetch an "A" record for a domain, which resolves the domain to an IPv4 address, use the following approach:
```typescript
import { Smartdns } from '@push.rocks/smartdns';
@@ -45,31 +46,37 @@ const aRecords = await dnsManager.getRecordsA('example.com');
console.log(aRecords);
```
This will return an array of records that include the IPv4 addresses mapped to the domain `example.com`.
#### Fetching AAAA Records
Similarly, for "AAAA" records:
For resolving a domain to an IPv6 address, you can fetch "AAAA" records in a similar manner:
```typescript
const aaaaRecords = await dnsManager.getRecordsAAAA('example.com');
console.log(aaaaRecords);
```
These queries are quite common where IPv6 addresses have been prevalent due to the scarcity of IPv4 addresses.
#### Fetching TXT Records
For "TXT" records:
TXT records store arbitrary text data associated with a domain. They are often used to hold information such as SPF records for email validation or Google site verification token.
```typescript
const txtRecords = await dnsManager.getRecordsTxt('example.com');
console.log(txtRecords);
```
TXT records have increasingly become significant with the growth of security features and integrations that require domain verification.
### Advanced DNS Management
Beyond simple queries, `@push.rocks/smartdns` offers functionalities suitable for more complex DNS management scenarios.
The `@push.rocks/smartdns` doesn't just stop at querying— it offers more advanced DNS management utilities, which are crucial for real-world applications involving DNS operations.
#### Checking DNS Propagation
When changing DNS records, ensuring that the new records have propagated fully is crucial. `@push.rocks/smartdns` facilitates this with a method to check a DNS record until it is available globally.
When changing DNS records, ensuring that the new records have propagated fully is crucial. `@push.rocks/smartdns` facilitates this with a method to check if a DNS record is available globally. This can be critical for ensuring that users worldwide are able to access your updated records in a consistent manner.
```typescript
const recordType = 'TXT'; // Record type: A, AAAA, CNAME, TXT etc.
@@ -83,13 +90,15 @@ if (isAvailable) {
}
```
This method repeatedly queries DNS servers until the expected DNS record appears, making sure that the changes made are visible globally.
### Leveraging DNS for Application Logic
DNS records can serve beyond mere domain-to-IP resolution; they can be instrumental in application logic, such as feature flagging or environment-specific configurations.
DNS records can function beyond their typical usage of domain-to-IP resolution. They can be extremely useful in application logic such as feature flagging or environment-specific configurations.
#### Example: Feature Flagging via TXT Records
Consider leveraging TXT records for enabling/disabling features dynamically without deploying new code.
One such advanced use case is using TXT records for enabling or disabling features dynamically without needing to redeploy or change the actual application code:
```typescript
const txtRecords = await dnsManager.getRecordsTxt('features.example.com');
@@ -101,16 +110,19 @@ const featureFlags = txtRecords.reduce((acc, record) => {
if (featureFlags['NewFeature']) {
// Logic to enable the new feature
console.log('New Feature enabled');
}
```
This approach enables applications to be more flexible and responsive to business needs as feature toggles can be managed through DNS.
### DNS Server Implementation
To implement a DNS server, `@push.rocks/smartdns` includes classes and methods to set up a UDP and HTTPS DNS server supporting DNSSEC.
`@push.rocks/smartdns` includes powerful features that allow you to implement your very own DNS server, complete with UDP and HTTPS protocols support and DNSSEC compliance.
#### Basic DNS Server Example
Here's a basic example of a UDP/HTTPS DNS server:
Implementing a DNS server involves setting it up to respond to various DNS queries. Here's how you can set up a basic DNS server using UDP and HTTPS protocols:
```typescript
import { DnsServer } from '@push.rocks/smartdns';
@@ -134,13 +146,15 @@ dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
dnsServer.start().then(() => console.log('DNS Server started'));
```
This sets up a basic DNS server responding to A records for the domain `example.com` and mirrors the common structure used in production applications.
### DNSSEC Support
`@push.rocks/smartdns` provides support for DNSSEC, including the generation, signing, and validation of DNS records.
DNS Security Extensions (DNSSEC) adds an additional layer of security to DNS, protecting against various types of attacks. With `@push.rocks/smartdns`, setting up a DNS server with DNSSEC is straightforward.
#### DNSSEC Configuration
To configure DNSSEC for your DNS server:
To configure DNSSEC for your DNS server, you’ll need to establish DNSSEC parameters including zone signatures and enabling key management. This setup ensures that DNS records are signed and can be verified for authenticity.
```typescript
import { DnsServer } from '@push.rocks/smartdns';
@@ -164,20 +178,23 @@ dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
dnsServer.start().then(() => console.log('DNS Server with DNSSEC started'));
```
This setup ensures that DNS records are signed and can be verified for authenticity.
### Handling DNS Queries Over Different Protocols
The library supports handling DNS queries over UDP and HTTPS.
The library supports handling DNS queries over UDP and HTTPS. This functionality allows for the flexible use and management of DNS inquiries and resolves, accommodating various protocol needs.
#### Handling UDP Queries
UDP is the traditional means of DNS query transport.
UDP is the traditional DNS protocol used for quick, non-persistent queries. Here’s how you can set up a DNS server to respond to UDP queries:
```typescript
import { DnsServer } from '@push.rocks/smartdns';
import dgram from 'dgram';
const dnsServer = new DnsServer({
udpPort: 53,
httpsPort: 443,
});
dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
name: question.name,
type: 'A',
@@ -199,9 +216,11 @@ client.on('message', (msg, rinfo) => {
client.send(Buffer.from('example DNS query'), dnsServer.getOptions().udpPort, 'localhost');
```
This segment of code creates a UDP server that listens for incoming DNS requests and responds accordingly.
#### Handling HTTPS Queries
DNS over HTTPS (DoH) is increasingly adopted for privacy and security.
DNS over HTTPS (DoH) offers a heightened level of privacy and security, where DNS queries are transmitted over HTTPS to prevent eavesdropping and man-in-the-middle attacks.
```typescript
import { DnsServer } from '@push.rocks/smartdns';
@@ -248,13 +267,17 @@ client.write(Buffer.from('example DNS query'));
client.end();
```
This ensures that DNS requests can be securely transmitted over the web, maintaining privacy for the clients querying the DNS server.
### Testing
To ensure that the DNS server behaves as expected, it is important to write tests for various scenarios.
Like any crucial application component, DNS servers require thorough testing to ensure reliability and correctness in different scenarios. Here we use TAP (Test Anything Protocol) to test various functionalities.
#### DNS Server Tests
Here is an example of how to test the DNS server with TAP:
`@push.rocks/smartdns` integrates seamlessly with TAP, allowing for comprehensive testing of server functionalities.
Here's an example of how you might set up tests for your DNS server:
```typescript
import { expect, tap } from '@push.rocks/tapbundle';
@@ -312,7 +335,6 @@ tap.test('should add a DNS handler', async () => {
});
tap.test('should query the server over HTTP', async () => {
// Assuming fetch or any HTTP client is available
const query = dnsPacket.encode({
type: 'query',
id: 2,
@@ -356,13 +378,11 @@ tap.test('should stop the server', async () => {
await tap.start();
```
### Conclusion
The above tests ensure that the DNS server setup, query handling, and proper stopping of the server are all functioning as intended.
`@push.rocks/smartdns` offers a versatile set of tools for DNS querying and management, tailored for applications at any scale. The examples provided illustrate the library's potential use cases, highlighting its applicability in various scenarios from basic lookups to facilitating complex application features through DNS.
In a realistic production environment, additional tests would include edge cases such as malformed requests, large queries, concurrent access handling, and integration tests with various DNS resolvers. These tests ensure robustness and reliability of DNS services provided by the server.
For the full spectrum of functionalities, including detailed method documentation and additional use cases, consult the module's [TypeDoc documentation](https://pushrocks.gitlab.io/smartdns/). This will serve as a comprehensive guide to leveraging `@push.rocks/smartdns` effectively in your projects.
Remember, DNS changes might take time to propagate worldwide, and the utility methods provided by `@push.rocks/smartdns` for checking record availability will be invaluable in managing these changes seamlessly.
This comprehensive guide demonstrates how to implement, manage, and test a DNS server using `@push.rocks/smartdns`, making it an ideal tool for developers tasked with handling DNS management and setup in TypeScript projects. The library supports the full scope of DNS operations needed for modern applications, from basic record query to full-scale DNS server operations with advanced security extensions.
## License and Legal Information