// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System.Net.Sockets;
using System.Threading;
using System.Threading.Tasks;

namespace System.Net
{
    public static partial class Dns
    {
        // Shared DnsResolver instance used by the static Resolve* methods.
        // Uses the system-configured DNS servers. A benign race may construct more
        // than one instance, but only one is published; DnsResolver holds no
        // unmanaged state, so the extra instance is simply collected.
        private static DnsResolver DefaultResolver => field ??= new();

        /// <summary>
        /// Resolves the IPv4 (A) and IPv6 (AAAA) addresses for the specified host name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The host name to resolve.</param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the address records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static DnsResult<AddressRecord> ResolveAddresses(string name)
            => DefaultResolver.ResolveAddresses(name);

        /// <summary>
        /// Resolves the addresses of the specified family for the specified host name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The host name to resolve.</param>
        /// <param name="addressFamily">
        /// The address family to query. Use <see cref="AddressFamily.InterNetwork"/> for A records,
        /// <see cref="AddressFamily.InterNetworkV6"/> for AAAA records, or
        /// <see cref="AddressFamily.Unspecified"/> for both.
        /// </param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the address records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static DnsResult<AddressRecord> ResolveAddresses(string name, AddressFamily addressFamily)
            => DefaultResolver.ResolveAddresses(name, addressFamily);

        /// <summary>
        /// Asynchronously resolves the IPv4 (A) and IPv6 (AAAA) addresses for the specified host name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The host name to resolve.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the address records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static Task<DnsResult<AddressRecord>> ResolveAddressesAsync(string name, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolveAddressesAsync(name, cancellationToken);

        /// <summary>
        /// Asynchronously resolves the addresses of the specified family for the specified host name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The host name to resolve.</param>
        /// <param name="addressFamily">
        /// The address family to query. Use <see cref="AddressFamily.InterNetwork"/> for A records,
        /// <see cref="AddressFamily.InterNetworkV6"/> for AAAA records, or
        /// <see cref="AddressFamily.Unspecified"/> for both.
        /// </param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the address records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static Task<DnsResult<AddressRecord>> ResolveAddressesAsync(string name, AddressFamily addressFamily, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolveAddressesAsync(name, addressFamily, cancellationToken);

        /// <summary>
        /// Resolves the service (SRV) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The name to resolve, typically in the form <c>_service._protocol.host</c>.</param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the SRV records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static DnsResult<SrvRecord> ResolveSrv(string name)
            => DefaultResolver.ResolveSrv(name);

        /// <summary>
        /// Asynchronously resolves the service (SRV) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The name to resolve, typically in the form <c>_service._protocol.host</c>.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the SRV records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static Task<DnsResult<SrvRecord>> ResolveSrvAsync(string name, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolveSrvAsync(name, cancellationToken);

        /// <summary>
        /// Resolves the mail exchange (MX) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The domain name to resolve.</param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the MX records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static DnsResult<MxRecord> ResolveMx(string name)
            => DefaultResolver.ResolveMx(name);

        /// <summary>
        /// Asynchronously resolves the mail exchange (MX) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The domain name to resolve.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the MX records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static Task<DnsResult<MxRecord>> ResolveMxAsync(string name, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolveMxAsync(name, cancellationToken);

        /// <summary>
        /// Resolves the text (TXT) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The domain name to resolve.</param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the TXT records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static DnsResult<TxtRecord> ResolveTxt(string name)
            => DefaultResolver.ResolveTxt(name);

        /// <summary>
        /// Asynchronously resolves the text (TXT) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The domain name to resolve.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the TXT records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static Task<DnsResult<TxtRecord>> ResolveTxtAsync(string name, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolveTxtAsync(name, cancellationToken);

        /// <summary>
        /// Resolves the canonical name (CNAME) record for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The domain name to resolve.</param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the CNAME records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static DnsResult<CNameRecord> ResolveCName(string name)
            => DefaultResolver.ResolveCName(name);

        /// <summary>
        /// Asynchronously resolves the canonical name (CNAME) record for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The domain name to resolve.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the CNAME records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static Task<DnsResult<CNameRecord>> ResolveCNameAsync(string name, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolveCNameAsync(name, cancellationToken);

        /// <summary>
        /// Resolves the pointer (PTR) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The name to resolve, typically a reverse-lookup name such as <c>4.3.2.1.in-addr.arpa</c>.</param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the PTR records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static DnsResult<PtrRecord> ResolvePtr(string name)
            => DefaultResolver.ResolvePtr(name);

        /// <summary>
        /// Resolves the pointer (PTR) records for the specified IP address using the system-configured DNS servers.
        /// </summary>
        /// <param name="address">The IP address to perform a reverse lookup for.</param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the PTR records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="address"/> is <see langword="null"/>.</exception>
        public static DnsResult<PtrRecord> ResolvePtr(IPAddress address)
            => DefaultResolver.ResolvePtr(address);

        /// <summary>
        /// Asynchronously resolves the pointer (PTR) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The name to resolve, typically a reverse-lookup name such as <c>4.3.2.1.in-addr.arpa</c>.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the PTR records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static Task<DnsResult<PtrRecord>> ResolvePtrAsync(string name, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolvePtrAsync(name, cancellationToken);

        /// <summary>
        /// Asynchronously resolves the pointer (PTR) records for the specified IP address using the system-configured DNS servers.
        /// </summary>
        /// <param name="address">The IP address to perform a reverse lookup for.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the PTR records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="address"/> is <see langword="null"/>.</exception>
        public static Task<DnsResult<PtrRecord>> ResolvePtrAsync(IPAddress address, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolvePtrAsync(address, cancellationToken);

        /// <summary>
        /// Resolves the authoritative name server (NS) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The domain name to resolve.</param>
        /// <returns>A <see cref="DnsResult{T}"/> containing the NS records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static DnsResult<NsRecord> ResolveNs(string name)
            => DefaultResolver.ResolveNs(name);

        /// <summary>
        /// Asynchronously resolves the authoritative name server (NS) records for the specified name using the system-configured DNS servers.
        /// </summary>
        /// <param name="name">The domain name to resolve.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>A task that completes with a <see cref="DnsResult{T}"/> containing the NS records.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
        /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
        public static Task<DnsResult<NsRecord>> ResolveNsAsync(string name, CancellationToken cancellationToken = default)
            => DefaultResolver.ResolveNsAsync(name, cancellationToken);
    }
}