DNS Lookup

Summary

Internal name: DnsLookup
Category: Communication
Purpose: Resolve a domain name to an IP address using configurable DNS resolution strategies. Returns the resolved IP address as a string.
Task type: Normal

Compatibility

Minimum AndroMate version: 1.1.0
Maximum AndroMate version: 1.1.0
Minimum Android: Android 13 (API 33)
Maximum Android tested: Android 16 (API 36)
Required permissions:
- INTERNET
- ACCESS_NETWORK_STATE

Detailed description

The DNS Lookup task resolves the domain name or IP address provided in url to a resolved IP address. If the input is already a valid IPv4 or IPv6 address, no DNS query is performed — the address is returned directly.

For actual domain resolution, the task applies the strategy selected by resolve_ops (an integer key). An optional dns_server can be specified; if empty, the system default DNS server is used. All DNS queries have a fixed timeout of 5000 ms.

On success, the resolved IP address string is stored in value_output from StrTaskResult.

Input parameters

Parameter	Type	Required	Possible values	Android Compatibility	AndroMate Compatibility	Default
`url`	String	Yes	Domain name or IP address to resolve — supports `$variable`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`dns_server`	String	No	Custom DNS server IP address — empty string uses system default	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`resolve_ops`	Integer	No	Resolution strategy: `1` = FORCE_IPV4, `2` = FORCE_IPV6, `3` = PREFER_IPV6_FALLBACK_IPV4, `4` = HAPPY_EYEBALLS	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`0` (PREFER_IPV6_FALLBACK_IPV4)

`resolve_ops` strategy keys

Value	Strategy	Description
`1`	FORCE_IPV4	Query A records only
`2`	FORCE_IPV6	Query AAAA records only
`3`	PREFER_IPV6_FALLBACK_IPV4	Try IPv6 first, fallback to IPv4 if not found
`4`	HAPPY_EYEBALLS	RFC 8305 — concurrent IPv6 + IPv4 queries
`0` or omitted	PREFER_IPV6_FALLBACK_IPV4	Default behavior

Output parameters

Field	Type	Trigger condition	Android Compatibility	AndroMate Compatibility	Default
`value_output`	String	Always on success — resolved IP address	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`

Exceptions

Code	Exception Name	Description
`DNS-LOOK-UP-001`	Empty URL	The `url` field is empty (from `AndromateExceptionTypes.DNS_LOOKUP_EMPTY_URL`).
`DNS-LOOK-UP-002`	DNS Resolution Failed	DNS lookup failed for the given domain — no A/AAAA records found or DNS server error (from `AndromateExceptionTypes.DNS_LOOKUP_FAILED`).

Execution flowchart

flowchart TD
    Start([▶ DnsLookup]) --> ResolveParams[🔄 Resolve url, dns_server,\nresolve_ops]

    ResolveParams --> ValidateURL{url empty?}

    ValidateURL -->|Yes| E1[❌ DNS-LOOK-UP-001\nEmpty URL]
    ValidateURL -->|No| CheckIP{Already a valid\nIPv4 or IPv6?}

    CheckIP -->|Yes| ReturnIP[📍 Return IP directly\nNo DNS query performed]
    CheckIP -->|No| Strategy{resolve_ops\nstrategy}

    Strategy -->|1 = FORCE_IPV4| ForceIPV4[🔍 Query A records only]
    Strategy -->|2 = FORCE_IPV6| ForceIPV6[🔍 Query AAAA records only]
    Strategy -->|3 or default = PREFER_IPV6_FALLBACK_IPV4| PreferIPV6[🔄 Try IPv6 first\nfallback to IPv4]
    Strategy -->|4 = HAPPY_EYEBALLS| HappyEyeballs[⚡ RFC 8305\nconcurrent IPv6 + IPv4]

    ForceIPV4 --> DNSQuery[📡 DNS Query\nTimeout: 5000ms]
    ForceIPV6 --> DNSQuery
    PreferIPV6 --> DNSQuery
    HappyEyeballs --> DNSQuery

    ReturnIP --> StoreResult[💾 Set value_output\nStrTaskResult]

    DNSQuery -->|Success| GetIP[📥 Extract resolved IP address]
    DNSQuery -->|Failed| E2[❌ DNS-LOOK-UP-002\nDNS Resolution Failed]

    GetIP --> StoreResult

    StoreResult --> LogReport[📋 Log report]

    LogReport --> Success([✅ StrTaskResult])

    E1 --> Error([❌ Exception])
    E2 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style E1 fill:#ffcdd2
    style E2 fill:#ffcdd2
    style ResolveParams fill:#fff9c4
    style DNSQuery fill:#f3e5f5
    style StoreResult fill:#c8e6c9
    style CheckIP fill:#fff9c4
    style Strategy fill:#fff9c4

How it works:

Resolve parameters: url, dns_server, and resolve_ops are resolved from the workflow context
Validate URL: throws DNS-LOOK-UP-001 if url is empty
Check if already IP: if the input is already a valid IPv4 or IPv6 address, it is returned directly in value_output — no DNS query is performed
Select resolution strategy: chooses the DNS resolution strategy based on the resolve_ops integer value
DNS query: performs the DNS lookup with a fixed 5000 ms timeout; uses dns_server if specified, otherwise uses the system default
On failure: throws DNS-LOOK-UP-002
Extract IP: retrieves the resolved IP address
Store result: sets value_output with the resolved IP string
Result: returns StrTaskResult

Code examples

Example 1 — Resolve a domain with default strategy

{
  "DnsLookup": [
    {
      "id": "1",
      "title": "Resolve API domain",
      "url": "api.example.com",
      "value_output": "$resolved_ip"
    }
  ]
}

Example 2 — Force IPv4 resolution

{
  "DnsLookup": [
    {
      "id": "2",
      "title": "Force IPv4 resolution",
      "url": "api.example.com",
      "resolve_ops": 1,
      "value_output": "$ipv4_address"
    }
  ]
}

Example 3 — Custom DNS server with Happy Eyeballs

{
  "DnsLookup": [
    {
      "id": "3",
      "title": "Happy Eyeballs with custom DNS",
      "url": "$domain_to_resolve",
      "dns_server": "1.1.1.1",
      "resolve_ops": 4,
      "value_output": "$resolved_ip"
    }
  ]
}

Example 4 — Force IPv6 with custom DNS

{
  "DnsLookup": [
    {
      "id": "4",
      "title": "IPv6 only resolution",
      "url": "ipv6.example.com",
      "dns_server": "8.8.8.8",
      "resolve_ops": 2,
      "value_output": "$ipv6_address"
    }
  ]
}

Input parameter details

1. `url` — Domain or IP to resolve

The domain name or IP address to process. If already a valid IPv4 or IPv6 address, returned directly without any DNS query. Supports $workflow_variable references.

Valid	Behavior
`api.example.com`	DNS query performed
`192.168.1.1`	Returned directly (no DNS query)
`2001:db8::1`	Returned directly (no DNS query)
`$domain`	Resolved from variable, then processed
`""`	Throws `DNS-LOOK-UP-001`

Default: ""

2. `dns_server` — Custom DNS server

The IP address of a custom DNS server to use for resolution. If empty (""), the system default DNS server is used (from device network settings).

Example	Description
`"8.8.8.8"`	Google DNS
`"1.1.1.1"`	Cloudflare DNS
`"208.67.222.222"`	OpenDNS
`""`	System default (device DNS settings)

Default: "" (system default)

3. `resolve_ops` — Resolution strategy

An integer key selecting the DNS resolution strategy. Default behavior (value 0 or omitted) is PREFER_IPV6_FALLBACK_IPV4.

Value	Strategy	Description
`1`	FORCE_IPV4	A records only — IPv4 address returned
`2`	FORCE_IPV6	AAAA records only — IPv6 address returned
`3`	PREFER_IPV6_FALLBACK_IPV4	Try IPv6 first; fallback to IPv4 if no AAAA found
`4`	HAPPY_EYEBALLS	RFC 8305 concurrent queries — fastest response wins
`0` or omitted	PREFER_IPV6_FALLBACK_IPV4	Default

Type: Integer
Default: 0 (PREFER_IPV6_FALLBACK_IPV4)

Output parameter details

`value_output` — Resolved IP address

Stores the resolved IP address string (from StrTaskResult) in the specified workflow variable.

For domain inputs: the IP address resolved by DNS
For IP inputs already passed in: the same IP address returned directly
May be IPv4 (e.g. "93.184.216.34") or IPv6 (e.g. "2606:2800:220:1:248:1893:25c8:1946") depending on the resolution strategy

DNS Resolution Strategies

Strategy 1: FORCE_IPV4 (`resolve_ops: 1`)

Queries only A records. Returns the first IPv4 address found. Throws DNS-LOOK-UP-002 if no A records are available.

Use case: Legacy systems that require IPv4 only.

Strategy 2: FORCE_IPV6 (`resolve_ops: 2`)

Queries only AAAA records. Returns the first IPv6 address found. Throws DNS-LOOK-UP-002 if no AAAA records are available.

Use case: IPv6-only network environments.

Strategy 3: PREFER_IPV6_FALLBACK_IPV4 (`resolve_ops: 3` or default)

First queries AAAA records. If an IPv6 address is found, returns it. If no AAAA records exist, falls back to querying A records. Throws DNS-LOOK-UP-002 if neither is found.

Use case: Modern networks preferring IPv6 with backward compatibility.

Strategy 4: HAPPY_EYEBALLS (`resolve_ops: 4`)

Implements RFC 8305. Starts an IPv6 (AAAA) query, then after a short delay starts an IPv4 (A) query concurrently. The first query to return a result wins. Throws DNS-LOOK-UP-002 if both fail.

Use case: Optimal performance on any network type.

Strategy Comparison

Strategy	`resolve_ops`	IPv4	IPv6	Use Case
FORCE_IPV4	`1`	✅	❌	Legacy systems
FORCE_IPV6	`2`	❌	✅	IPv6-only networks
PREFER_IPV6_FALLBACK_IPV4	`3` or `0`	✅ (fallback)	✅ (preferred)	Balanced modern networks
HAPPY_EYEBALLS	`4`	✅	✅	Optimized (RFC 8305)

Complete JSON example

{
  "DnsLookup": [
    {
      "id": "1",
      "title": "DNS Lookup",
      "url": "api.example.com",
      "dns_server": "8.8.8.8",
      "resolve_ops": 4,
      "value_output": "$RESOLVED_IP"
    }
  ]
}