Skip to content

SAIF.Framework.DNS operations and processes

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under operations/.

SAIF.Framework.DNS exposes two caller-facing operations — MX record lookup and Generic DNS lookup — that are both built on top of three internal pipeline stages: DNS request serialization, UDP DNS transfer with retry, and DNS response parsing. The library performs no database or security work; every rule it enforces is either argument validation or UDP transport behavior.

Operation catalog

Operation Intent Trigger Inputs Outputs Rules Tables SQL
MX record lookup Resolve a domain's mail-exchanger records and return them ordered from most- to least-preferred. Caller invokes Resolver.MXLookup. domain, dnsServer Sorted MXRecord[] (or null); may throw ArgumentNullException, ArgumentException, ArgumentOutOfRangeException, NoResponseException, or InvalidResponseException BR-001, BR-002, BR-003, BR-004, BR-008 — —
Generic DNS lookup Send a caller-prepared DNS request to a chosen server and hand back the parsed reply. Caller invokes Resolver.Lookup. request, dnsServer Parsed Response; may throw ArgumentNullException, NoResponseException, or InvalidResponseException BR-001 — —
DNS request serialization Encode a logical Request into the DNS wire-format byte layout the transport stage sends. Resolver.Lookup calls Request.GetMessage. Opcode, RecursionDesired, the Question collection Request byte[] — — —
UDP DNS transfer with retry Transmit the serialized request over UDP and wait for a reply whose transaction id matches, retrying on timeout. Resolver.Lookup calls Resolver.UdpTransfer. Target IPEndPoint, request byte[] Reply byte[]; throws NoResponseException once retries are exhausted BR-005, BR-006 — —
DNS response parsing Decode raw reply bytes into a structured Response, including typed resource records. Resolver.Lookup constructs a Response from the reply bytes. Reply byte[] Populated Response; throws InvalidResponseException on a malformed question section BR-007 — —

Process flow diagram

The following diagram visualizes how a caller's request moves through the library, from the two entry points down to the shared serialization, transport, and parsing stages.

flowchart TD
    Start([Caller starts lookup]) --> Decide{MX lookup or generic lookup?}
    Decide -->|MX record lookup| Mx[Build MX Question]
    Decide -->|Generic DNS lookup| Lookup[Use caller-supplied Request]
    Mx --> Lookup
    Lookup --> Serialize[DNS request serialization]
    Serialize --> Transfer[UDP DNS transfer with retry]
    Transfer --> Reply{Matching reply received?}
    Reply -->|Yes| Parse[DNS response parsing]
    Reply -->|No, retries exhausted| EndFail([Throw NoResponseException])
    Parse --> Filter{Called from MX record lookup?}
    Filter -->|Yes| Sort[Filter and sort MX answers]
    Filter -->|No| EndGeneric([Return parsed Response])
    Sort --> EndMx([Return sorted MXRecord array])

Failure and edge-case behavior

  • Both public entry points validate their arguments before any request object is built or any socket activity begins, so ArgumentNullException from a null domain, request, or dnsServer is always raised synchronously and immediately.
  • Request.GetMessage() serializes however many questions the caller added, including zero or several; the source comments warn that most DNS servers reject multi-question messages, but the library does not enforce a single-question limit.
  • Resolver.UdpTransfer silently discards any UDP reply whose transaction id does not match the outbound request and keeps waiting or retrying rather than surfacing the mismatch to the caller.
  • Response wraps only question-section parsing failures in InvalidResponseException; it tolerates unsupported resource-record types by skipping their RDATA rather than failing the whole parse.
  • Resolver.MXLookup returns null when the underlying lookup returns null, and returns an empty array (not null) when the response contains zero MX answers — callers should distinguish these two outcomes explicitly.

Sources

  • SAIF.Framework.DNS\Resolver.cs
  • SAIF.Framework.DNS\Request.cs
  • SAIF.Framework.DNS\Question.cs
  • SAIF.Framework.DNS\Response.cs
  • SAIF.Framework.DNS\ResourceRecord.cs
  • SAIF.Framework.DNS\Pointer.cs
  • SAIF.Framework.DNS\MXRecord.cs
  • SAIF.Framework.DNS\ANameRecord.cs
  • SAIF.Framework.DNS\NSRecord.cs
  • SAIF.Framework.DNS\SoaRecord.cs