smartdns/readme.plan.md

# SmartDNS Improvement Plan

Command to reread CLAUDE.md: `cat /home/philkunz/.claude/CLAUDE.md`

## Critical Issue: Support Multiple DNS Records of Same Type

### Current Status: Planning
**Priority: HIGH** - This issue blocks proper DNS server operation and domain registration

### Problem Summary
The DNS server currently exits after finding the first matching handler for a query, preventing it from serving multiple records of the same type (e.g., multiple NS records, multiple A records for round-robin, multiple TXT records).

### Implementation Plan

#### Phase 1: Analysis and Testing ✅ COMPLETED
- [x] Create comprehensive test cases demonstrating the issue
- [x] Test with multiple NS records scenario
- [x] Test with multiple A records (round-robin) scenario
- [x] Test with multiple TXT records scenario
- [x] Document current behavior vs expected behavior

#### Phase 2: Core Fix Implementation ✅ COMPLETED
- [x] Remove the `break` statement in `processDnsRequest` method (line 609)
- [x] Ensure all matching handlers are processed
- [x] Accumulate all answers from matching handlers
- [x] Add NS record serialization for DNSSEC support

#### Phase 3: Handler Interface Enhancement (Optional)
- [ ] Consider allowing handlers to return arrays of records
- [ ] Update `IDnsHandler` interface to support `DnsAnswer | DnsAnswer[] | null`
- [ ] Update processing logic to handle array responses
- [ ] Maintain backward compatibility with existing handlers

#### Phase 4: Testing and Validation
- [ ] Test multiple NS records return correctly
- [ ] Test round-robin DNS with multiple A records
- [ ] Test multiple TXT records (SPF + DKIM + verification)
- [ ] Test DNSSEC signatures for multiple records
- [ ] Verify no regression in single-record scenarios

#### Phase 5: Documentation and Examples
- [ ] Update documentation with multiple record examples
- [ ] Add example for registering multiple NS records
- [ ] Add example for round-robin DNS setup
- [ ] Document best practices for handler registration

### Technical Details

#### Current Code Issue (ts_server/classes.dnsserver.ts:609)
```typescript
answered = true;
break; // <-- This prevents multiple handlers from contributing answers
```

#### Proposed Fix
```typescript
answered = true;
// Continue processing other handlers instead of breaking
```

### Success Criteria
- DNS queries return ALL matching records from ALL matching handlers
- Domain registration with multiple NS records succeeds
- Round-robin DNS works with multiple A records
- Multiple TXT records can be served for the same domain
- DNSSEC signatures are properly generated for all returned records

### Implementation Summary

#### What Was Fixed
1. **Core Issue Resolved**: Removed the `break` statement at line 609 in `processDnsRequest` that was preventing multiple handlers from contributing DNS answers
2. **NS Record Serialization**: Added NS record type support in `serializeRData` method for DNSSEC compatibility
3. **Result**: DNS server now correctly returns multiple records of the same type from different handlers

#### Test Results
- ✅ Multiple NS records now work (2+ nameservers returned)
- ✅ Round-robin DNS with multiple A records works
- ✅ Multiple TXT records (SPF, DKIM, verification) work
- ⚠️ DNSSEC RRSIG generation needs additional fixes for multiple record scenarios

#### Code Changes
```typescript
// Before (line 609):
answered = true;
break;  // This was preventing multiple handlers from running

// After:
answered = true;
// Continue processing other handlers to allow multiple records
```

### Additional Improvements to Consider
1. Fix DNSSEC RRSIG generation for multiple records
2. Fix SOA record timeout issues
3. Make DNSSEC zone prefix configurable (remove hardcoded 'ns1.')
4. Improve error handling for edge cases
5. Consider handler interface enhancement to return arrays