Documentation
¶
Overview ¶
Package httpcache provides stable core conditional request helpers for REST APIs.
Start with StrongETag, WeakETag, HashETag, Validators, EvaluateRead, and EvaluateWrite to implement ETag and Last-Modified handling without tying a handler to a storage backend. SetValidators, WriteNotModified, and WritePreconditionFailed provide the common HTTP response path.
The package only evaluates standard validators: ETag, Last-Modified, If-None-Match, If-Modified-Since, If-Match, and If-Unmodified-Since. Callers still own resource versioning, authorization, and persistence updates.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/httpcache`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetValidators ¶
func SetValidators(w http.ResponseWriter, validators Validators)
SetValidators writes ETag and Last-Modified response headers when present.
func WriteNotModified ¶
func WriteNotModified(w http.ResponseWriter, validators Validators)
WriteNotModified writes a 304 response with validators and no body.
func WritePreconditionFailed ¶
func WritePreconditionFailed(w http.ResponseWriter)
WritePreconditionFailed writes a 412 Problem Details response.
Types ¶
type Decision ¶
Decision describes the result of evaluating conditional request headers.
func EvaluateRead ¶
func EvaluateRead(r *http.Request, validators Validators) Decision
EvaluateRead evaluates conditional read headers for GET or HEAD handlers.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"github.com/aatuh/api-toolkit/v4/httpcache"
)
func main() {
etag := httpcache.StrongETag("widgets-v1")
req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/widgets", nil)
req.Header.Set("If-None-Match", etag.String())
decision := httpcache.EvaluateRead(req, httpcache.Validators{ETag: etag})
fmt.Println(decision.NotModified)
fmt.Println(decision.Status)
}
Output: true 304
func EvaluateWrite ¶
func EvaluateWrite(r *http.Request, validators Validators) Decision
EvaluateWrite evaluates write preconditions for unsafe handlers.
type ETag ¶
type ETag string
ETag is an HTTP entity tag, including quotes and optional weak prefix.
func StrongETag ¶
StrongETag builds a strong ETag from an opaque value.
type Validators ¶
Validators are the current validators for a representation.
Source Files