Documentation
¶
Overview ¶
Package statuses maps between HTTP status codes and their standard reason phrases and classifies codes by behavior. It is a Go port of the npm "statuses" package, reimplemented using only the Go standard library. Where the Node original exposes a callable module plus lookup tables, this package exposes the same capabilities as ordinary functions and returns Go-idiomatic values and errors.
A web framework or HTTP client reaches for this package whenever it needs the canonical text for a numeric status code (for example, to build a default response body or a log line reading "404 Not Found"), or the reverse: to turn a human-written phrase such as "Not Found" back into the number 404. It also answers the three behavioral questions that middleware most often asks about a status: is it a redirect, may the request be retried, and must the response be sent without a body.
Internally the package is backed by a code-to-message map covering the common registered codes in the 100-511 range and a lazily built, lower-cased message-to-code map for the reverse direction. Message performs a direct map lookup and returns the empty string for an unknown code. Code trims and lower-cases its input before looking it up, so matching is case-insensitive and tolerant of surrounding whitespace; an unknown phrase yields a non-nil error rather than a zero code that could be mistaken for a valid status.
Three small sets drive classification. IsRedirect reports true for the 3xx codes that carry a Location header and cause the client to follow it (300, 301, 302, 303, 305, 307, 308); note that 304 Not Modified is deliberately excluded because it is a cache-validation response, not a redirect. IsRetry reports true for the gateway-family codes 502, 503, and 504, which typically represent a transient upstream failure that a client may safely retry. IsEmpty reports true for 204, 205, and 304, whose responses must never include a message body. These sets mirror the classification tables of the npm original.
Codes returns every known status code sorted in ascending order, which is convenient for iterating over the full table (for instance to validate a round trip between Message and Code). Compared with the Node package, the data tables and classification rules are kept in parity, while the API surface is adapted to Go conventions: functions instead of a callable with attached properties, an (int, error) return from Code instead of a thrown exception, and a plain []int from Codes instead of an array of strings.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Code ¶
Code returns the status code for the given reason phrase. Matching is case-insensitive. It returns an error if the message is unknown.
Example ¶
ExampleCode performs the reverse lookup, turning a reason phrase back into its numeric status code. Matching is case-insensitive and tolerant of surrounding whitespace because Code trims and lower-cases its argument before consulting the table. A recognized phrase yields the code and a nil error, so both "Not Found" and "not found" resolve to 404. An unrecognized phrase yields a zero code together with a non-nil error, which this example prints to show the failure path.
package main
import (
"fmt"
"github.com/malcolmston/express/statuses"
)
func main() {
code, err := statuses.Code("Not Found")
fmt.Println(code, err)
code, err = statuses.Code("not found")
fmt.Println(code, err)
code, err = statuses.Code("nonsense")
fmt.Println(code, err)
}
Output: 404 <nil> 404 <nil> 0 invalid status message: "nonsense"
func Codes ¶
func Codes() []int
Codes returns all known status codes in ascending order.
Example ¶
ExampleCodes lists every known status code in ascending order and pairs each with its reason phrase. Codes returns a freshly sorted slice, so iterating it visits the table in a stable, predictable sequence. This example prints only the first few entries to keep the output short while still demonstrating both the ordering and the round trip between a code and its Message. The values are deterministic because the backing table never changes at runtime. Such iteration is handy for validating that Message and Code agree for every code.
package main
import (
"fmt"
"github.com/malcolmston/express/statuses"
)
func main() {
for _, code := range statuses.Codes()[:3] {
fmt.Printf("%d %s\n", code, statuses.Message(code))
}
}
Output: 100 Continue 101 Switching Protocols 102 Processing
func IsRedirect ¶
IsRedirect reports whether the status code is a redirect.
Example ¶
ExampleIsRedirect demonstrates classifying status codes by behavior. The three predicate functions each consult a fixed set of codes: IsRedirect covers the 3xx codes that carry a Location header, IsRetry covers the gateway-family codes that a client may safely retry, and IsEmpty covers the codes whose responses must not include a body. This example checks a redirect (302), confirms that 304 is not treated as a redirect, checks a retriable gateway timeout (504), and checks an empty-body code (204). The boolean results are deterministic and mirror the classification tables of the npm original.
package main
import (
"fmt"
"github.com/malcolmston/express/statuses"
)
func main() {
fmt.Println("302 redirect:", statuses.IsRedirect(302))
fmt.Println("304 redirect:", statuses.IsRedirect(304))
fmt.Println("504 retry:", statuses.IsRetry(504))
fmt.Println("204 empty:", statuses.IsEmpty(204))
}
Output: 302 redirect: true 304 redirect: false 504 retry: true 204 empty: true
func Message ¶
Message returns the reason phrase for the given status code. It returns an empty string if the code is unknown.
Example ¶
ExampleMessage looks up the canonical reason phrase for a numeric HTTP status code. The Message function performs a direct table lookup and returns the registered phrase, such as "Not Found" for 404 and "Internal Server Error" for 500. When the code is not part of the known table it returns the empty string rather than an error, which makes it convenient for building default response text. This example prints the phrase for a couple of well-known codes and then shows the empty result for an unregistered code. The output is fully deterministic because the underlying table is fixed.
package main
import (
"fmt"
"github.com/malcolmston/express/statuses"
)
func main() {
fmt.Printf("%q\n", statuses.Message(404))
fmt.Printf("%q\n", statuses.Message(500))
fmt.Printf("%q\n", statuses.Message(799))
}
Output: "Not Found" "Internal Server Error" ""
Types ¶
This section is empty.
Source Files