ccn/Packages/Localization/Sources/Methods/Negotiate.swift

import Foundation

/// Negotiates the best supported language for a request from its `Accept-Language` header.
///
/// Bound to a bundle's catalog languages via ``LanguageList``, an instance is invoked like a
/// function — through ``callAsFunction(acceptLanguage:)`` — to resolve a header value to a
/// supported language identifier, falling back to the default language.
public struct Negotiate: Sendable {

    // MARK: Properties

    /// The supported languages and default language, derived from the bundle's String Catalog.
    private let list: LanguageList

    // MARK: Initializers

    /// Creates a language negotiator backed by the given bundle's String Catalog.
    /// - Parameter bundle: the bundle whose String Catalog defines the supported languages.
    public init(
        bundle: Bundle
    ) {
        self.list = .init(bundle: bundle)
    }

    // MARK: Methods

    /// Picks the best supported language for the given `Accept-Language` header value.
    ///
    /// Invoked by calling the instance directly, for example `negotiate(acceptLanguage: header)`.
    /// The header is split into its language tags (dropping any `q` weights), then each tag is matched
    /// against the supported languages in order of preference — first by an exact match, then by its
    /// primary language subtag, so `de-AT` resolves to a supported `de`. When the header is absent or
    /// matches nothing, the default language is returned.
    /// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
    /// - Returns: the identifier of the supported language to serve.
    public func callAsFunction(
        acceptLanguage language: String?
    ) -> String {
        guard let language else {
            return list.default
        }

        let tags = tags(from: language)

        guard !tags.isEmpty else {
            return list.default
        }

        let supported = list.all

        for tag in tags {
            if let match = match(tag: tag, in: supported) {
                return match
            }
        }

        return list.default
    }

}

// MARK: - Helpers

private extension Negotiate {

    // MARK: Methods

    /// Extracts the ordered language tags from an `Accept-Language` header value.
    ///
    /// Each comma-separated entry is reduced to its language tag by dropping the `;q=` weight, and
    /// blank entries are removed. The original order is kept, which mirrors descending preference
    /// closely enough for `preferredLocalizations(from:forPreferences:)` to resolve correctly.
    /// - Parameter acceptLanguage: the raw `Accept-Language` header value.
    /// - Returns: the ordered, weight-stripped language tags.
    func tags(
        from acceptLanguage: String
    ) -> [String] {
        acceptLanguage
            .split(separator: .Separator.comma)
            .map { entry in
                entry
                    .split(separator: .Separator.semicolon)
                    .first
                    .map(String.init)?
                    .trimmingCharacters(in: .whitespaces)
                ?? .empty
            }
            .filter { !$0.isEmpty }
    }

    /// Finds the supported language that best matches a single `Accept-Language` tag.
    ///
    /// An exact, case-insensitive match wins; otherwise the tag's primary subtag is matched against the
    /// supported languages' primary subtags, so a regional tag such as `de-AT` resolves to `de`.
    /// - Parameters:
    ///   - tag: a single language tag from the header.
    ///   - supported: the supported language identifiers.
    /// - Returns: the matching supported language, or `nil` when the tag matches none.
    func match(
        tag: String,
        in supported: [String]
    ) -> String? {
        let tag = tag.lowercased()

        if let exact = supported.first(
            where: { $0.lowercased() == tag }
        ) {
            return exact
        }

        let primary = tag.primarySubtag

        return supported.first {
            $0.lowercased().primarySubtag == primary
        }
    }

}

// MARK: - String+Extensions

private extension String {
    static let empty: String = ""

    /// The primary language subtag, i.e. everything before the first `-` (`de-AT` becomes `de`).
    var primarySubtag: String {
        split(separator: .Separator.dash)
            .first
            .map(String.init)
        ?? self
    }
}

// MARK: - Constants

private extension Character {
    enum Separator {
        static let comma: Character = ","
        static let dash: Character = "-"
        static let semicolon: Character = ";"
    }
}