---
title: Generic DNS lookup
summary: Sends a caller-prepared DNS request to a chosen server and returns the parsed response.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-07-30
library: SAIF.Framework.DNS
reference_type: package
operation_id: OP-DNS-002
trigger: Caller invokes Resolver.Lookup
---

# Generic DNS lookup

This operation is the library's shared request/response pipeline, and every lookup — MX or otherwise — ultimately runs through it. It accepts a caller-prepared `Request`, converts it to DNS wire format, sends it to the selected DNS server over UDP, and builds a parsed `Response` object from the raw reply bytes.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-DNS-002 |
| **Trigger** | Caller requests resolution of a prepared DNS `Request` |
| **Inputs** | `request`, `dnsServer` |
| **Outputs** | Parsed `Response`; may throw `ArgumentNullException`, `NoResponseException`, or `InvalidResponseException` |
| **Primary components** | `Resolver.Lookup`, `Request.GetMessage`, `Resolver.UdpTransfer`, `Response.Response` |
| **Entry point** | `SAIF.Framework.DNS\Resolver.cs` |

## Steps

1. Confirm that `request` and `dnsServer` are not null before any network activity begins.
   - The `dnsServer` check enforces [BR-001](../business-rules.md#br-001-lookup-arguments-must-not-be-null).
   - On failure: throw `ArgumentNullException` and stop; nothing is sent.
2. Build an `IPEndPoint` that targets the supplied DNS server on UDP port 53.
3. Serialize the request by delegating to [DNS request serialization](dns-request-serialization.md) (`request.GetMessage()`).
   - If serialization raises an exception, let it propagate to the caller unchanged.
4. Transmit the serialized bytes by delegating to [UDP DNS transfer with retry](udp-dns-transfer-with-retry.md) with the target endpoint.
   - If no matching reply arrives after all retries, let `NoResponseException` propagate.
5. Parse the raw reply bytes into a `Response` by delegating to [DNS response parsing](dns-response-parsing.md).
   - If the reply's question section cannot be parsed, let `InvalidResponseException` propagate.
6. Return the fully populated `Response` to the caller.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller invokes Lookup]) --> V[Validate request and dnsServer]
	V --> E[Build UDP endpoint on port 53]
	E --> S[Serialize request to wire format]
	S --> T[Transfer request over UDP with retry]
	T --> P[Parse reply bytes into Response]
	P --> EndOk([Return parsed Response])
```

## Failure and edge-case behavior

- Null `request` or `dnsServer` arguments fail before the UDP endpoint is even created.
- This operation does not catch transport or parsing exceptions of its own; every exception raised by the delegated serialization, transfer, or parsing stages reaches the caller directly and unmodified.
- The target port is always UDP 53; the API gives callers no way to override it.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- SAIF.Framework.DNS\Resolver.cs
- SAIF.Framework.DNS\Request.cs
- SAIF.Framework.DNS\Response.cs