HTTP Status Codes — Go source

// Package httpstatuscodes is the Go twin of CosmoDev's src/lib/httpStatus.ts
// (dual source: the web lib is TypeScript, the CLI lib is Go — kept in lock-step).
// Pure + deterministic, never panics. The table-driven tests in
// http-status-codes_test.go share vectors with src/lib/httpStatus.test.ts so the
// two implementations are held to the same contract.
//
// The package exposes the standard, widely-implemented HTTP status codes across
// 1xx–5xx and a FilterCodes function that mirrors filterCodes() in the TS lib.
package httpstatuscodes

import (
	"strconv"
	"strings"
)

// Category constants mirror the TS StatusCategory string union. They are the
// only legal Category values on any StatusCode in StatusCodes.
const (
	CategoryInformational = "Informational"
	CategorySuccess       = "Success"
	CategoryRedirection   = "Redirection"
	CategoryClientError   = "Client Error"
	CategoryServerError   = "Server Error"
)

// StatusCode mirrors the TS StatusCode interface: a status code, its reason
// phrase, its category, and a human-readable description.
type StatusCode struct {
	Code        int
	Reason      string
	Category    string
	Description string
}

// StatusCodes mirrors STATUS_CODES: the standard + widely-implemented HTTP
// status codes across 1xx–5xx.
var StatusCodes = []StatusCode{
	// --- 1xx Informational ---
	{Code: 100, Reason: "Continue", Category: CategoryInformational, Description: "The server has received the request headers and the client should proceed to send the request body."},
	{Code: 101, Reason: "Switching Protocols", Category: CategoryInformational, Description: "The requester has asked the server to switch protocols and the server has agreed to do so."},
	{Code: 103, Reason: "Early Hints", Category: CategoryInformational, Description: "Used to return some response headers before the final HTTP message so the browser can start preloading resources."},

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

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

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

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

// FilterCodes filters status codes by a free-text query and an optional category.
// It mirrors filterCodes() in src/lib/httpStatus.ts and must agree with it on
// every shared vector.
//
//   - query is matched case-insensitively against the numeric code (as a string),
//     the reason phrase, and the description. An empty/whitespace query returns
//     every code (in the given category, if one is supplied).
//   - category, when non-empty after trimming, restricts the pool to that
//     category before the text match. An empty/whitespace category means "no
//     category filter" (every category). An unknown non-empty category yields a
//     nil slice (no matches), mirroring the TS "unknown category → []" behavior.
func FilterCodes(query string, codes []StatusCode, category string) []StatusCode {
	cat := strings.TrimSpace(category)

	var pool []StatusCode
	if cat != "" {
		for _, c := range codes {
			if c.Category == cat {
				pool = append(pool, c)
			}
		}
	} else {
		pool = codes
	}

	q := strings.ToLower(strings.TrimSpace(query))
	if q == "" {
		return pool
	}

	var out []StatusCode
	for _, c := range pool {
		if strings.Contains(strconv.Itoa(c.Code), q) ||
			strings.Contains(strings.ToLower(c.Reason), q) ||
			strings.Contains(strings.ToLower(c.Description), q) {
			out = append(out, c)
		}
	}
	return out
}