HTTP Status Codes — Swift source

// HTTP Status Codes reference — pure, deterministic data + filter.
//
// Language: Swift 5.9 — standard library only, no third-party packages.
// Source: CosmoDev polyglot showcase port of http-status-codes,
//         ported from src/lib/httpStatus.ts.
// License: display source — part of CosmoDev's polyglot tool pages.
//
// Pure logic — no I/O. Behavior matches the TypeScript lib: same inputs
// produce identical outputs.

/// The five broad families an HTTP status code can belong to.
///
/// Modeled as a raw-value enum rather than a string so the compiler can prove
/// every `StatusCode` carries a valid family — and the raw value *is* the
/// canonical display string used across HTTP tooling, so the failable
/// initializer `StatusCategory(rawValue:)` resolves a family from free text
/// for free.
enum StatusCategory: String, CaseIterable, Sendable {
    case informational = "Informational"
    case success = "Success"
    case redirection = "Redirection"
    case clientError = "Client Error"
    case serverError = "Server Error"
}

/// A single HTTP status code entry.
///
/// All fields are immutable (`let`) and the type is a value — the table below
/// is constant reference data that is never mutated.
struct StatusCode: Equatable, Sendable {
    let code: Int
    let reason: String
    let category: StatusCategory
    let description: String
}

/// Reference table and filter for standard HTTP status codes.
///
/// A case-less enum used as a namespace: it cannot be instantiated, it cannot
/// be subclassed, and it groups the table with its filter in one type.
enum HttpStatusCodes {

    /// Standard + widely-implemented HTTP status codes across 1xx–5xx.
    ///
    /// A `let` constant — the table is never mutated. Order is grouped by
    /// category, ascending within each group.
    static let statusCodes: [StatusCode] = [
        // --- 1xx Informational ---
        StatusCode(code: 100, reason: "Continue", category: .informational, description: "The server has received the request headers and the client should proceed to send the request body."),
        StatusCode(code: 101, reason: "Switching Protocols", category: .informational, description: "The requester has asked the server to switch protocols and the server has agreed to do so."),
        StatusCode(code: 103, reason: "Early Hints", category: .informational, description: "Used to return some response headers before the final HTTP message so the browser can start preloading resources."),

        // --- 2xx Success ---
        StatusCode(code: 200, reason: "OK", category: .success, description: "Standard response for a successful HTTP request."),
        StatusCode(code: 201, reason: "Created", category: .success, description: "The request succeeded and a new resource was created."),
        StatusCode(code: 202, reason: "Accepted", category: .success, description: "The request has been accepted for processing but is not yet complete."),
        StatusCode(code: 203, reason: "Non-Authoritative Information", category: .success, description: "The returned metadata originated from a local or third-party copy rather than the origin server."),
        StatusCode(code: 204, reason: "No Content", category: .success, description: "The server processed the request successfully but is not returning any content."),
        StatusCode(code: 205, reason: "Reset Content", category: .success, description: "The server asks the client to reset the document view that sent the request."),
        StatusCode(code: 206, reason: "Partial Content", category: .success, description: "The server is delivering only part of the resource because the client requested a byte range."),
        StatusCode(code: 207, reason: "Multi-Status", category: .success, description: "WebDAV: conveys information about multiple resources in a single XML response."),
        StatusCode(code: 208, reason: "Already Reported", category: .success, description: "WebDAV: the members of a DAV binding have already been enumerated in a previous reply."),
        StatusCode(code: 226, reason: "IM Used", category: .success, description: "The server fulfilled a GET request using an instance-manipulation applied to the current instance."),

        // --- 3xx Redirection ---
        StatusCode(code: 300, reason: "Multiple Choices", category: .redirection, description: "The request has more than one possible response; the user agent can choose among them."),
        StatusCode(code: 301, reason: "Moved Permanently", category: .redirection, description: "This and all future requests should be directed to the given URL."),
        StatusCode(code: 302, reason: "Found", category: .redirection, description: "The resource resides temporarily under a different URL; the method may be changed to GET."),
        StatusCode(code: 303, reason: "See Other", category: .redirection, description: "The response to the request can be found under another URI using a GET request."),
        StatusCode(code: 304, reason: "Not Modified", category: .redirection, description: "The resource has not been modified since the version specified by the request headers."),
        StatusCode(code: 305, reason: "Use Proxy", category: .redirection, description: "The requested resource is available only through a proxy (deprecated)."),
        StatusCode(code: 306, reason: "Switch Proxy", category: .redirection, description: "No longer used; originally meant subsequent requests should use a specified proxy."),
        StatusCode(code: 307, reason: "Temporary Redirect", category: .redirection, description: "The request should be repeated with another URL; the request method must not change."),
        StatusCode(code: 308, reason: "Permanent Redirect", category: .redirection, description: "This and all future requests should use another URL; the request method must not change."),

        // --- 4xx Client Error ---
        StatusCode(code: 400, reason: "Bad Request", category: .clientError, description: "The server cannot process the request due to a client error such as malformed syntax."),
        StatusCode(code: 401, reason: "Unauthorized", category: .clientError, description: "Authentication is required and has either failed or not been provided."),
        StatusCode(code: 402, reason: "Payment Required", category: .clientError, description: "Reserved for future use; sometimes used for paywalled resources."),
        StatusCode(code: 403, reason: "Forbidden", category: .clientError, description: "The server understood the request but refuses to authorize it."),
        StatusCode(code: 404, reason: "Not Found", category: .clientError, description: "The requested resource could not be found on the server."),
        StatusCode(code: 405, reason: "Method Not Allowed", category: .clientError, description: "The request method is not supported for the requested resource."),
        StatusCode(code: 406, reason: "Not Acceptable", category: .clientError, description: "The requested resource can only generate content not acceptable per the Accept headers."),
        StatusCode(code: 407, reason: "Proxy Authentication Required", category: .clientError, description: "The client must first authenticate itself with the proxy."),
        StatusCode(code: 408, reason: "Request Timeout", category: .clientError, description: "The server timed out waiting for the client to send the request."),
        StatusCode(code: 409, reason: "Conflict", category: .clientError, description: "The request could not be processed because of a conflict with the current state of the resource."),
        StatusCode(code: 410, reason: "Gone", category: .clientError, description: "The resource is no longer available and will not be available again."),
        StatusCode(code: 411, reason: "Length Required", category: .clientError, description: "The request did not specify the length of its content, which is required by the resource."),
        StatusCode(code: 412, reason: "Precondition Failed", category: .clientError, description: "The server does not meet one of the preconditions given in the request headers."),
        StatusCode(code: 413, reason: "Content Too Large", category: .clientError, description: "The request payload is larger than the server is willing or able to process."),
        StatusCode(code: 414, reason: "URI Too Long", category: .clientError, description: "The URI provided was too long for the server to process."),
        StatusCode(code: 415, reason: "Unsupported Media Type", category: .clientError, description: "The request uses a media type the server does not support for the resource."),
        StatusCode(code: 416, reason: "Range Not Satisfiable", category: .clientError, description: "The portion of the resource requested in the Range header cannot be supplied by the server."),
        StatusCode(code: 417, reason: "Expectation Failed", category: .clientError, description: "The server cannot meet the requirements of the Expect request header field."),
        StatusCode(code: 418, reason: "I'm a Teapot", category: .clientError, description: "RFC 2324 joke status: the server refuses to brew coffee because it is, permanently, a teapot."),
        StatusCode(code: 421, reason: "Misdirected Request", category: .clientError, description: "The request was directed at a server that is not able to produce a response."),
        StatusCode(code: 422, reason: "Unprocessable Content", category: .clientError, description: "The server understands the content type and syntax but cannot process the contained instructions (WebDAV)."),
        StatusCode(code: 423, reason: "Locked", category: .clientError, description: "WebDAV: the source or destination resource of the method is locked."),
        StatusCode(code: 424, reason: "Failed Dependency", category: .clientError, description: "WebDAV: the method could not be performed because the requested action depended on another action that failed."),
        StatusCode(code: 425, reason: "Too Early", category: .clientError, description: "The server is unwilling to risk processing a request that might be a replay."),
        StatusCode(code: 428, reason: "Precondition Required", category: .clientError, description: "The origin server requires the request to be conditional."),
        StatusCode(code: 429, reason: "Too Many Requests", category: .clientError, description: "The user has sent too many requests in a given time (rate limiting)."),
        StatusCode(code: 431, reason: "Request Header Fields Too Large", category: .clientError, description: "The server is unwilling to process the request because its header fields are too large."),
        StatusCode(code: 451, reason: "Unavailable For Legal Reasons", category: .clientError, description: "The resource is unavailable due to legal demands such as government censorship or a takedown."),

        // --- 5xx Server Error ---
        StatusCode(code: 500, reason: "Internal Server Error", category: .serverError, description: "A generic error message: the server encountered an unexpected condition."),
        StatusCode(code: 501, reason: "Not Implemented", category: .serverError, description: "The server does not support the functionality required to fulfill the request."),
        StatusCode(code: 502, reason: "Bad Gateway", category: .serverError, description: "The server, acting as a gateway, received an invalid response from an upstream server."),
        StatusCode(code: 503, reason: "Service Unavailable", category: .serverError, description: "The server is currently unavailable, typically because it is overloaded or down for maintenance."),
        StatusCode(code: 504, reason: "Gateway Timeout", category: .serverError, description: "The server, acting as a gateway, timed out waiting for an upstream response."),
        StatusCode(code: 505, reason: "HTTP Version Not Supported", category: .serverError, description: "The server does not support the HTTP protocol version used in the request."),
        StatusCode(code: 506, reason: "Variant Also Negotiates", category: .serverError, description: "Transparent content negotiation for the request resulted in a circular reference."),
        StatusCode(code: 507, reason: "Insufficient Storage", category: .serverError, description: "WebDAV: the server is unable to store the representation needed to complete the request."),
        StatusCode(code: 508, reason: "Loop Detected", category: .serverError, description: "WebDAV: the server detected an infinite loop while processing the request."),
        StatusCode(code: 510, reason: "Not Extended", category: .serverError, description: "Further extensions to the request are required for the server to fulfill it."),
        StatusCode(code: 511, reason: "Network Authentication Required", category: .serverError, description: "The client must authenticate to gain network access, as with a captive portal."),
    ]

    /// Trim whitespace from both ends of a string.
    ///
    /// `Character.isWhitespace` is standard library, so Foundation's
    /// `trimmingCharacters(in:)` is deliberately not pulled in — this port
    /// stays dependency-free.
    private static func trim(_ s: String) -> Substring {
        var view = s[...]
        while let first = view.first, first.isWhitespace {
            view = view.dropFirst()
        }
        while let last = view.last, last.isWhitespace {
            view = view.dropLast()
        }
        return view
    }

    /// Filter status codes by a free-text query and an optional category.
    ///
    /// `query` is matched case-insensitively against the numeric code (as a
    /// decimal string), the reason phrase, and the description. An
    /// empty/whitespace query returns every code in the pool. `category`
    /// restricts the pool first: `nil` or blank means "no restriction"; an
    /// unknown name yields an empty result — matching the TypeScript
    /// semantics. The original order is preserved.
    ///
    /// `String.lowercased()` on ASCII-only text coincides with JavaScript's
    /// `toLowerCase`.
    static func filterCodes(
        _ query: String,
        in codes: [StatusCode] = statusCodes,
        category: String? = nil
    ) -> [StatusCode] {
        // Resolve the category: nil/blank -> no filter; a name that does not
        // initialize a known family -> nothing can match, short-circuit.
        let categoryName = category.map { String(trim($0)) } ?? ""
        var pool = codes
        if !categoryName.isEmpty {
            guard let resolved = StatusCategory(rawValue: categoryName) else {
                return []
            }
            pool = codes.filter { $0.category == resolved }
        }

        // Case-insensitive substring match across code/reason/description.
        let needle = String(trim(query)).lowercased()
        if needle.isEmpty {
            return pool
        }

        return pool.filter {
            // The code is matched against its decimal form, so "40" hits 404, 405, ...
            String($0.code).contains(needle)
                || $0.reason.lowercased().contains(needle)
                || $0.description.lowercased().contains(needle)
        }
    }
}