Documentation
¶
Overview ¶
Package cond surfaces the change-vs-unchanged signal that the etag transport already computes but currently erases before the response reaches the consumer. The etag layer sets HeaderCacheStatus on synth-200 (cache hit) and wire-200 (cache store); StatusOf maps it to the typed Status enum.
Use Fetch[T] for one-shot conditional GETs that want both the decoded value and the cache status. Use polling.WithChangeOnly to silently skip iterations when the resource hasn't changed.
When the etag layer is not in the transport chain (or a non-cache response is received), the header is absent and StatusOf returns Updated; consumers see "not from cache" semantics correctly.
Body lifecycle: Fetch[T] owns the response body and closes it via defer regardless of decode success. Decode errors are wrapped as "cond: decode: %w" for consistency with pages.As, polling.As, and search.iterate.
Index ¶
Constants ¶
const HeaderCacheStatus = "X-Ghkit-Cache"
HeaderCacheStatus is the response header the etag layer sets to signal cache hit ("hit"), wire store ("miss"), or absent (no etag layer in chain). etag and polling import this directly.
Variables ¶
var ErrNilClient = errors.New("cond: nil *http.Client")
ErrNilClient is returned by Fetch when the supplied *http.Client is nil.
var ErrNilContext = errors.New("cond: nil context")
ErrNilContext is returned by Fetch when the supplied context is nil.
var ErrNilRequest = errors.New("cond: nil *http.Request")
ErrNilRequest is returned by Fetch when the supplied *http.Request is nil.
Functions ¶
This section is empty.
Types ¶
type Status ¶
type Status uint8
Status reports the change-vs-unchanged signal for a response.
const ( // Updated is the default: a wire 200, or no etag layer in the // transport chain. The body is fresh from upstream. Updated Status = iota // Unchanged is a synth 200 produced by the etag layer from a // 304 cache hit. The body is byte-for-byte identical to the last // time this resource was fetched. Unchanged )
func Fetch ¶
func Fetch[T any](ctx context.Context, c *http.Client, req *http.Request, decode func(io.Reader) (T, error)) (T, Status, error)
Fetch issues req via c, decodes the response body via decode, and returns the typed value plus the change status. The body is closed via defer regardless of decode success. On any error (transport, decode, ctx), the zero value of T and Updated are returned.
Source Files