---
title: SAIF.Framework.DNS operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-07-30
library: SAIF.Framework.DNS
reference_type: package
---

# 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](operations/mx-record-lookup.md) and [Generic DNS lookup](operations/generic-dns-lookup.md) — that are both built on top of three internal pipeline stages: [DNS request serialization](operations/dns-request-serialization.md), [UDP DNS transfer with retry](operations/udp-dns-transfer-with-retry.md), and [DNS response parsing](operations/dns-response-parsing.md). 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](operations/mx-record-lookup.md) | 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](business-rules.md#br-001-lookup-arguments-must-not-be-null), [BR-002](business-rules.md#br-002-domain-name-length-must-be-1-255-characters), [BR-003](business-rules.md#br-003-dnstype-must-be-a-defined-non-none-enum-value), [BR-004](business-rules.md#br-004-dnsclass-must-be-a-defined-non-none-enum-value), [BR-008](business-rules.md#br-008-mx-records-are-ordered-by-ascending-preference) | — | — |
| [Generic DNS lookup](operations/generic-dns-lookup.md) | 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](business-rules.md#br-001-lookup-arguments-must-not-be-null) | — | — |
| [DNS request serialization](operations/dns-request-serialization.md) | 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](operations/udp-dns-transfer-with-retry.md) | 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](business-rules.md#br-005-udp-requests-are-retried-up-to-two-additional-times-before-failing), [BR-006](business-rules.md#br-006-udp-replies-are-only-accepted-when-the-transaction-id-matches) | — | — |
| [DNS response parsing](operations/dns-response-parsing.md) | 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](business-rules.md#br-007-malformed-embedded-questions-abort-response-construction) | — | — |

## 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.

```mermaid
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.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## 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