條件式 HTTP 請求與快取驗證子

http_request 從不送出 If-None-Match / If-Modified-Since 也不讀取 Cache-Control,因此每次 輪詢都會重新下載未變更的資源。本功能從回應擷取快取驗證子、解析 Cache-Control、判定新鮮度,並為下一個 請求加上條件標頭,讓伺服器可回應 304 Not Modified。

純標準函式庫;不匯入 PySide6。新鮮度判定接受明確的 age(不使用 wall clock),因此邏輯在 CI 中完全 具決定性。

無頭 API

from je_auto_control import (
    store_validators, conditioned_call, is_fresh, is_not_modified,
    parse_cache_control, build_call,
)

response = http_request(url)
validators = store_validators(response)
if is_fresh(validators, age_seconds=now - stored_at):
    use_cached()
else:
    revalidation = conditioned_call(build_call(url), validators)
    fresh = perform(revalidation)
    if is_not_modified(fresh):
        use_cached()           # 304 → 已儲存的內文仍有效

store_validators 從回應取出 etag / last_modified / date 與解析後的 cache_control。 parse_cache_control 把標頭轉成 directive dict(max-age 為 int,旗標為 True)。conditioned_call 把 If-None-Match / If-Modified-Since 加到 build_call dict。is_fresh 在給定 age 下回報快取項 是否仍新鮮(no-store / no-cache 永不新鮮)。is_not_modified 偵測 304 回應。

執行器命令

AC_parse_cache_control 對 headers 回傳 {directives};``AC_store_validators`` 對 response 回傳 {validators}。兩者皆以 MCP 工具(ac_parse_cache_control / ac_store_validators)以及 Script Builder 中 Data 分類下的命令提供。