免费在 GitHub 公开

curl-head-vs-get-header-debugging

Fix misleading HTTP response header values when debugging with curl -I or curl -sI. Use when: (1) Response headers differ between curl testing and actual browser/client behavior, (2) Cache-Control or other headers show unexpected values despite correct middleware code, (3) Server-side middleware that only applies to GET requests appears to not work when testing with curl -I. The -I flag sends HEAD requests, and middleware that checks for GET method will skip processing, returning handler-level headers instead of middleware-overridden ones.

中文简介正在准备中。当前显示原文说明。

divinevideo/divine-mobile

查看安装方法

包含的文件（1）

SKILL.md3.3 KB

SKILL.md（原文）

安装前可以查看交给 AI 代理的指令内容。

curl -I Sends HEAD, Not GET — Header Debugging Trap

Problem

When debugging HTTP response headers with curl -I or curl -sI, the response may show different header values than what actual GET requests receive. This is because -I sends a HEAD request, and server middleware that only processes GET requests will be skipped.

Context / Trigger Conditions

Testing cache headers with curl -sI and seeing unexpected values
Middleware that checks method == GET before setting headers (common in cache middleware)
Headers appear correct in automated tests but wrong in manual curl testing
Cache-Control, Surrogate-Control, or Surrogate-Key values don't match expectations
Axum/Express/any framework middleware with method guards

Solution

Use curl -s -D - -o /dev/null instead of curl -I to get response headers from a GET request:

# WRONG — sends HEAD request, middleware may skip processing
curl -sI https://example.com/api/endpoint

# CORRECT — sends GET request, dumps headers, discards body
curl -s -D - -o /dev/null https://example.com/api/endpoint

If you need just specific headers:

curl -s -D - -o /dev/null https://example.com/api/endpoint | grep -iE 'cache-control|surrogate'

Verification

Compare output from both methods:

echo "=== HEAD (curl -I) ===" 
curl -sI https://example.com/api/endpoint | grep cache-control

echo "=== GET (curl -D) ==="
curl -s -D - -o /dev/null https://example.com/api/endpoint | grep cache-control

If the values differ, your middleware has a GET-only guard (which is correct behavior).

Example

Axum middleware that only sets cache headers for GET requests:

async fn cache_middleware(request: Request, next: Next) -> Response {
    let method = request.method().clone();
    let mut response = next.run(request).await;
    
    // HEAD requests skip this — curl -I won't see these headers!
    if method != Method::GET {
        return response;
    }
    
    response.headers_mut().insert("cache-control", ...);
    response.headers_mut().insert("surrogate-control", ...);
    response
}

Notes

This is NOT a bug — it's correct behavior. Cache headers should only apply to cacheable GET responses.
HTTP spec says HEAD responses SHOULD include the same headers as GET, but middleware implementations often don't replicate this because HEAD is rarely used by CDNs or browsers for caching decisions.
Fastly, Cloudflare, and other CDNs send GET requests to origins, so the cache behavior is correct even if curl -I shows different headers.
This trap is especially insidious because curl -I is the most common way to check headers.

评价

还没有评价。欢迎分享你的使用感受。

无需登录即可发表。欢迎分享使用感受、提问，或说明在哪些环境下无法运行。

还没有评论。来写第一条吧。

同一仓库的技能

argocd-externalsecret-namespace-permission

免费

Fix ArgoCD ExternalSecret deployment failing with "namespace X is not permitted in project Y". Use when: (1) ExternalSecret shows OutOfSync in ArgoCD but won't sync, (2) ArgoCD application status shows "namespace X is not permitted in project 'infrastructure'", (3) ExternalSecret targets a namespace managed by a different ArgoCD project, (4) Using apps-of-apps pattern with separate infrastructure and application projects.

中文简介正在准备中。当前显示原文说明。