.

Author: cablehead

book/metadata.md

@@ -56,20 +56,33 @@ This naming convention helps ensure different parts of the system don't overwrit
 
 ## HTTP Response Metadata
 
-All HTTP commands (`http get`, `http post`, etc.) automatically attach response metadata under the `"http_response"` key. This includes the status code, headers, and redirect history.
+All HTTP commands (`http get`, `http post`, etc.) attach response metadata:
 
-You can access this metadata using the [`metadata access`](/commands/docs/metadata_access.md) command, which is especially useful for streaming large responses:
+```nu
+http get https://api.example.com | metadata | get http_response
+# => ╭─────────┬───────────────────╮
+# => │ status  │ 200               │
+# => │ headers │ [list]            │
+# => │ urls    │ [list]            │
+# => ╰─────────┴───────────────────╯
+```
+
+The metadata includes:
+- `status` - HTTP status code (200, 404, 500, etc.)
+- `headers` - Response headers as `[{name, value}, ...]`
+- `urls` - Redirect history
+
+For large responses, use [`metadata access`](/commands/docs/metadata_access.md) to check metadata before the body downloads:
 
 ```nu
-# Check status code while streaming the response
 http get https://api.example.com/large-file
 | metadata access {|meta|
     if $meta.http_response.status != 200 {
         error make {msg: "Request failed"}
     } else { }
   }
-| lines
+| lines  # body streams through only if status is 200
 | each {|line| process $line }
 ```
 
-The `else { }` clause passes the input through when the check succeeds, allowing the response body to stream through the pipeline. This pattern lets you fail fast on error responses without downloading the entire body.
+The `else { }` passes the input through when the check succeeds.

cookbook/http.md

@@ -258,29 +258,34 @@ http post https://httpbin.org/post --content-type "multipart/form-data" {
 
 ---
 
-### Checking HTTP Response Status While Streaming
+### Accessing HTTP Response Metadata
 
-When working with large HTTP responses, you often want to stream the response body while still checking the HTTP status code. All HTTP commands automatically attach response metadata under the `"http_response"` key, which you can access using `metadata access`.
+All HTTP commands attach response metadata (status, headers, redirect history):
 
 ```nu
-# Stream a large response while checking the status code
-http get https://api.example.com/large-stream
+# After response completes
+http get https://api.example.com/data.json
+| metadata
+| get http_response.status
+# => 200
+```
+
+For large responses, check status *before* downloading the body:
+
+```nu
+# Fail fast without downloading body on error
+http get https://api.example.com/large-file.bin
 | metadata access {|meta|
     if $meta.http_response.status != 200 {
         error make {msg: $"Request failed with status ($meta.http_response.status)"}
     } else { }
   }
-| lines
-| each {|line| process $line }
+| save large-file.bin  # only runs if status is 200
 ```
 
-The `metadata access` command allows you to inspect metadata before the response body streams through. The `else { }` clause is required to pass the input through when the status check succeeds. This pattern is useful for:
-
-- Failing fast on error responses without downloading the entire body
-- Handling large payloads efficiently (the body still streams)
-- Checking response metadata without blocking the pipeline
+This checks metadata before the body streams through. If the status isn't 200, the error occurs immediately—the body is never downloaded.
 
-The response metadata includes:
-- `status` - HTTP status code (e.g., 200, 404, 500)
-- `headers` - Response headers as a list of `{name, value}` records
-- `urls` - Redirect history (list of URLs followed)
+Available metadata:
+- `status` - HTTP status code (200, 404, 500, etc.)
+- `headers` - `[{name, value}, ...]`
+- `urls` - Redirect history