HTTP Methods Reference — Go source

// Package httpmethods is the Go twin of CosmoDev's src/lib/http-methods.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-methods_test.go share vectors with src/lib/http-methods.test.ts so the
// two implementations are held to the same contract.
//
// Property flags (Safe / Idempotent / Cacheable / HasBody) follow RFC 9110 and
// the MDN reference table, mirroring the TS lib's data and lookups exactly.
package httpmethods

import "strings"

// MethodEntry describes a single HTTP request method.
type MethodEntry struct {
	Method      string
	Safe        bool // Read-only semantics — no server state change.
	Idempotent  bool // Repeating the call has the same effect as a single call.
	Cacheable   bool // Responses may be stored by a cache (per RFC 9110 / MDN).
	HasBody     bool // The method conventionally carries a request body.
	Description string
	TypicalUse  string
}

// Methods is the nine HTTP request methods (RFC 9110 / 9111). Mirrors METHODS
// in src/lib/http-methods.ts — same entries, same order, same property flags.
var Methods = []MethodEntry{
	{
		Method:      "GET",
		Safe:        true,
		Idempotent:  true,
		Cacheable:   true,
		HasBody:     false,
		Description: "Retrieves a representation of the target resource; a read-only request.",
		TypicalUse:  "Fetching a web page, reading an API resource, loading an image.",
	},
	{
		Method:      "POST",
		Safe:        false,
		Idempotent:  false,
		Cacheable:   true,
		HasBody:     true,
		Description: "Submits data to be processed, typically creating a new resource or triggering an action.",
		TypicalUse:  "Submitting a form, creating a record, publishing a message.",
	},
	{
		Method:      "PUT",
		Safe:        false,
		Idempotent:  true,
		Cacheable:   false,
		HasBody:     true,
		Description: "Replaces the target resource entirely with the request body.",
		TypicalUse:  "Updating a full record at a known URL, uploading a file by its path.",
	},
	{
		Method:      "PATCH",
		Safe:        false,
		Idempotent:  false,
		Cacheable:   false,
		HasBody:     true,
		Description: "Applies a partial modification to the target resource.",
		TypicalUse:  "Updating one field of a record, toggling a flag.",
	},
	{
		Method:      "DELETE",
		Safe:        false,
		Idempotent:  true,
		Cacheable:   false,
		HasBody:     false,
		Description: "Removes the target resource.",
		TypicalUse:  "Deleting a record or file by its URL.",
	},
	{
		Method:      "HEAD",
		Safe:        true,
		Idempotent:  true,
		Cacheable:   true,
		HasBody:     false,
		Description: "Identical to GET but returns only the response headers, no body.",
		TypicalUse:  "Checking existence, size, or freshness before downloading.",
	},
	{
		Method:      "OPTIONS",
		Safe:        true,
		Idempotent:  true,
		Cacheable:   false,
		HasBody:     false,
		Description: "Describes the communication options for the target resource.",
		TypicalUse:  "CORS preflight requests, discovering allowed methods.",
	},
	{
		Method:      "CONNECT",
		Safe:        false,
		Idempotent:  false,
		Cacheable:   false,
		HasBody:     false,
		Description: "Establishes a tunnel to the server (used with TLS/HTTPS proxies).",
		TypicalUse:  "Proxying encrypted connections through an intermediary.",
	},
	{
		Method:      "TRACE",
		Safe:        true,
		Idempotent:  true,
		Cacheable:   false,
		HasBody:     false,
		Description: "Performs a message loop-back test along the path to the target (debugging only).",
		TypicalUse:  "Diagnosing request transformations by intermediaries.",
	},
}

// MethodFilter mirrors MethodFilter in the TS lib. The boolean fields are *bool
// so the zero value (nil) means "omitted / ignored" while a non-nil value
// (including false) constrains to that value — exactly like the TS lib's
// distinction between undefined and a present flag.
type MethodFilter struct {
	Safe       *bool
	Idempotent *bool
	Cacheable  *bool
	// Query is free text matched (case-insensitively) against Method,
	// Description, and TypicalUse. Empty (the zero value) returns the
	// flag-filtered pool unchanged.
	Query string
}

// GetMethod is a case-insensitive single-method lookup; returns nil when the
// name is unknown. Mirrors getMethod() in src/lib/http-methods.ts.
func GetMethod(name string) *MethodEntry {
	n := strings.ToUpper(strings.TrimSpace(name))
	for i := range Methods {
		if Methods[i].Method == n {
			return &Methods[i]
		}
	}
	return nil
}

// FilterMethods filters the method set by boolean flags and an optional text
// query. Omitted flags are ignored; a present flag constrains to that value. An
// empty query returns the flag-filtered pool unchanged. Mirrors filterMethods()
// in src/lib/http-methods.ts.
func FilterMethods(opts MethodFilter) []MethodEntry {
	q := strings.ToLower(strings.TrimSpace(opts.Query))
	out := make([]MethodEntry, 0, len(Methods))
	for _, m := range Methods {
		if opts.Safe != nil && m.Safe != *opts.Safe {
			continue
		}
		if opts.Idempotent != nil && m.Idempotent != *opts.Idempotent {
			continue
		}
		if opts.Cacheable != nil && m.Cacheable != *opts.Cacheable {
			continue
		}
		if q != "" {
			if !(strings.Contains(strings.ToLower(m.Method), q) ||
				strings.Contains(strings.ToLower(m.Description), q) ||
				strings.Contains(strings.ToLower(m.TypicalUse), q)) {
				continue
			}
		}
		out = append(out, m)
	}
	return out
}

// MethodComparison surfaces where two methods' semantics agree and differ.
// Mirrors MethodComparison in the TS lib.
type MethodComparison struct {
	SameSafety      bool
	SameIdempotence bool
	Differences     []string
}

// CompareMethods compares two methods, surfacing where their semantics agree
// and differ. Differences lists every mismatched property (Safe, Idempotent,
// Cacheable, HasBody) as a human-readable sentence. Mirrors compareMethods() in
// src/lib/http-methods.ts — unknown methods compare as fully-different.
func CompareMethods(a, b MethodEntry) MethodComparison {
	differences := []string{}
	if a.Safe != b.Safe {
		differences = append(differences,
			a.Method+" is "+flagWord("safe", a.Safe)+", "+b.Method+" is "+flagWord("safe", b.Safe)+".")
	}
	if a.Idempotent != b.Idempotent {
		differences = append(differences,
			a.Method+" is "+flagWord("idempotent", a.Idempotent)+", "+b.Method+" is "+flagWord("idempotent", b.Idempotent)+".")
	}
	if a.Cacheable != b.Cacheable {
		differences = append(differences,
			a.Method+" is "+flagWord("cacheable", a.Cacheable)+", "+b.Method+" is "+flagWord("cacheable", b.Cacheable)+".")
	}
	if a.HasBody != b.HasBody {
		differences = append(differences,
			a.Method+" "+bodyWord(a.HasBody)+" a body, "+b.Method+" "+bodyWord(b.HasBody)+" a body.")
	}
	return MethodComparison{
		SameSafety:      a.Safe == b.Safe,
		SameIdempotence: a.Idempotent == b.Idempotent,
		Differences:     differences,
	}
}

// flagWord renders "word" when b is true, "not word" otherwise — the boolean
// phrasing used by the difference sentences in the TS lib.
func flagWord(word string, b bool) string {
	if b {
		return word
	}
	return "not " + word
}

// bodyWord renders "takes" / "does not take", matching the TS lib's HasBody
// phrasing.
func bodyWord(b bool) string {
	if b {
		return "takes"
	}
	return "does not take"
}