Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

What are the trade-offs between http::HeaderMap::append and insert for handling multiple header values?

HeaderMap::insert replaces all existing values for a header name with a single new value, while HeaderMap::append adds a value to the existing values for that header, allowing multiple values for the same header name. The choice between them depends on whether you want to preserve existing values (append) or completely replace them (insert), with important implications for HTTP semantics since many headers legitimately support multiple values.

The Fundamental Difference

use http::HeaderMap;
use http::header::{CONTENT_TYPE, SET_COOKIE, ACCEPT};
 
fn basic_difference() {
    let mut headers = HeaderMap::new();
    
    // insert: Replaces all existing values
    headers.insert(CONTENT_TYPE, "text/html".parse().unwrap());
    headers.insert(CONTENT_TYPE, "application/json".parse().unwrap());
    // Only "application/json" remains
    
    let values: Vec<_> = headers.get_all(CONTENT_TYPE).iter().collect();
    assert_eq!(values.len(), 1);
    assert_eq!(headers.get(CONTENT_TYPE).unwrap(), "application/json");
    
    // append: Adds to existing values
    let mut cookies = HeaderMap::new();
    cookies.append(SET_COOKIE, "session=abc".parse().unwrap());
    cookies.append(SET_COOKIE, "user=john".parse().unwrap());
    
    let values: Vec<_> = cookies.get_all(SET_COOKIE).iter().collect();
    assert_eq!(values.len(), 2);
}

insert overwrites; append accumulates.

Insert Behavior: Complete Replacement

use http::HeaderMap;
use http::header::{CACHE_CONTROL, CONTENT_TYPE};
 
fn insert_behavior() {
    let mut headers = HeaderMap::new();
    
    // First insert
    headers.insert(CACHE_CONTROL, "no-cache".parse().unwrap());
    assert_eq!(headers.get(CACHE_CONTROL).unwrap(), "no-cache");
    
    // Second insert replaces first
    headers.insert(CACHE_CONTROL, "max-age=3600".parse().unwrap());
    assert_eq!(headers.get(CACHE_CONTROL).unwrap(), "max-age=3600");
    
    // Only one value exists
    assert_eq!(headers.get_all(CACHE_CONTROL).iter().count(), 1);
    
    // insert returns the previous values if any
    let previous = headers.insert(CACHE_CONTROL, "no-store".parse().unwrap());
    assert!(previous.is_some());
    assert_eq!(previous.unwrap().iter().count(), 1);
    // Previous was "max-age=3600"
    
    // Inserting None removes the header entirely
    headers.insert(CACHE_CONTROL, None);
    assert!(!headers.contains_key(CACHE_CONTROL));
}

Use insert when a header should have exactly one value and previous values are irrelevant.

Append Behavior: Value Accumulation

use http::HeaderMap;
use http::header::{SET_COOKIE, ALLOW};
 
fn append_behavior() {
    let mut headers = HeaderMap::new();
    
    // Append adds values
    headers.append(SET_COOKIE, "session=abc".parse().unwrap());
    headers.append(SET_COOKIE, "theme=dark".parse().unwrap());
    headers.append(SET_COOKIE, "lang=en".parse().unwrap());
    
    // All values preserved
    assert_eq!(headers.get_all(SET_COOKIE).iter().count(), 3);
    
    // get() returns only the FIRST value
    assert_eq!(headers.get(SET_COOKIE).unwrap(), "session=abc");
    
    // append returns true if the header name was new
    let mut new_headers = HeaderMap::new();
    assert!(new_headers.append(ALLOW, "GET".parse().unwrap())); // true: new key
    assert!(!new_headers.append(ALLOW, "POST".parse().unwrap())); // false: existing key
    
    // Values are retained in order of insertion
    let values: Vec<_> = headers.get_all(SET_COOKIE).iter().collect();
    assert_eq!(values[0], "session=abc");
    assert_eq!(values[1], "theme=dark");
    assert_eq!(values[2], "lang=en");
}

Use append when a header can have multiple values that should all be preserved.

HTTP Semantics: When Multiple Values Matter

use http::HeaderMap;
use http::header::{SET_COOKIE, LINK, ACCEPT, ALLOW, VIA, WARNING};
 
fn http_semantics() {
    // Headers that commonly need multiple values:
    
    // 1. Set-Cookie: Each cookie needs its own header line
    let mut response = HeaderMap::new();
    response.append(SET_COOKIE, "session=abc123; Path=/".parse().unwrap());
    response.append(SET_COOKIE, "preferences=dark; Path=/prefs".parse().unwrap());
    // HTTP response will have two Set-Cookie lines
    
    // 2. Link: Multiple links can be provided
    let mut link_headers = HeaderMap::new();
    link_headers.append(LINK, "<style.css>; rel=stylesheet".parse().unwrap());
    link_headers.append(LINK, "<icon.png>; rel=icon".parse().unwrap());
    
    // 3. Allow: Multiple methods
    let mut allow = HeaderMap::new();
    allow.append(ALLOW, "GET".parse().unwrap());
    allow.append(ALLOW, "POST".parse().unwrap());
    allow.append(ALLOW, "PUT".parse().unwrap());
    
    // 4. Via: Proxy chain information
    let mut via = HeaderMap::new();
    via.append(VIA, "1.0 proxy1.example.com".parse().unwrap());
    via.append(VIA, "1.1 proxy2.example.com".parse().unwrap());
    
    // 5. Warning: Multiple warnings
    let mut warnings = HeaderMap::new();
    warnings.append(WARNING, '110 anderson "Response is stale"'.parse().unwrap());
    warnings.append(WARNING, '112 anderson "Operation discontinued"'.parse().unwrap());
}

HTTP/1.1 specifies that certain headers can appear multiple times with different values.

Headers That Should Have Single Values

use http::HeaderMap;
use http::header::{CONTENT_TYPE, CONTENT_LENGTH, HOST, LOCATION};
 
fn single_value_headers() {
    // These headers should have exactly one value:
    
    let mut headers = HeaderMap::new();
    
    // Content-Type: Single MIME type
    headers.insert(CONTENT_TYPE, "application/json".parse().unwrap());
    // Using insert prevents accidental multiple values
    
    // Content-Length: Single number
    headers.insert(CONTENT_LENGTH, "1024".parse().unwrap());
    
    // Host: Single host
    headers.insert(HOST, "example.com".parse().unwrap());
    
    // Location: Single URL for redirect
    headers.insert(LOCATION, "https://example.com/new".parse().unwrap());
    
    // For these headers, insert is semantically correct
    // Multiple values would be invalid or confusing
}

Use insert for headers where multiple values violate HTTP semantics.

Combining Insert and Append

use http::HeaderMap;
use http::header::{SET_COOKIE, CONTENT_TYPE, CACHE_CONTROL};
 
fn combined_usage() {
    let mut headers = HeaderMap::new();
    
    // Use insert for single-value headers
    headers.insert(CONTENT_TYPE, "text/html".parse().unwrap());
    
    // Use append for multi-value headers
    headers.append(SET_COOKIE, "session=abc".parse().unwrap());
    headers.append(SET_COOKIE, "user=john".parse().unwrap());
    
    // Headers that can have multiple values with different semantics:
    // Cache-Control can have multiple directives in ONE value (use insert)
    // Or can be sent as multiple headers (use append - unusual)
    
    // Typical usage: single value with multiple directives
    headers.insert(CACHE_CONTROL, "no-cache, no-store, max-age=0".parse().unwrap());
    
    // Alternative (unusual): multiple Cache-Control headers
    // Some servers might combine these, but behavior varies
}

Choose based on HTTP header semantics, not just data structure behavior.

Reading Multi-Value Headers

use http::HeaderMap;
use http::header::{SET_COOKIE, CONTENT_TYPE};
 
fn reading_values() {
    let mut headers = HeaderMap::new();
    headers.append(SET_COOKIE, "a=1".parse().unwrap());
    headers.append(SET_COOKIE, "b=2".parse().unwrap());
    headers.insert(CONTENT_TYPE, "text/plain".parse().unwrap());
    
    // get() returns Option<&HeaderValue> - only FIRST value
    let first_cookie = headers.get(SET_COOKIE);
    assert_eq!(first_cookie.unwrap(), "a=1");
    
    // get_all() returns GetValue iterator for ALL values
    let all_cookies: Vec<_> = headers.get_all(SET_COOKIE).iter().collect();
    assert_eq!(all_cookies.len(), 2);
    
    // For single-value headers, both work but get() is clearer
    let content_type = headers.get(CONTENT_TYPE);
    assert_eq!(content_type.unwrap(), "text/plain");
    
    // Iterating over all headers
    for (name, value) in headers.iter() {
        // Note: For multi-value headers, this gives each value separately
        // (internally, HeaderMap stores each value with its name)
    }
    
    // Checking if header exists
    assert!(headers.contains_key(SET_COOKIE));
    assert!(headers.contains_key(CONTENT_TYPE));
}

Use get() for the first value, get_all() for all values.

Removing and Replacing Values

use http::HeaderMap;
use http::header::{SET_COOKIE, CACHE_CONTROL};
 
fn remove_and_replace() {
    let mut headers = HeaderMap::new();
    headers.append(SET_COOKIE, "session=old".parse().unwrap());
    headers.append(SET_COOKIE, "user=old".parse().unwrap());
    
    // Remove ALL values for a header
    let removed = headers.remove(SET_COOKIE);
    assert!(removed.is_some());
    // Contains all removed values
    
    // Replace with new value (using insert)
    headers.insert(SET_COOKIE, "session=new".parse().unwrap());
    assert_eq!(headers.get_all(SET_COOKIE).iter().count(), 1);
    
    // Append new values
    headers.append(SET_COOKIE, "user=new".parse().unwrap());
    assert_eq!(headers.get_all(SET_COOKIE).iter().count(), 2);
    
    // Common pattern: replace single-value header
    headers.insert(CACHE_CONTROL, "max-age=3600".parse().unwrap());
    // Completely replaces any previous Cache-Control
    
    // Pattern: append to existing or create new
    headers.append(SET_COOKIE, "lang=en".parse().unwrap());
    // If SET_COOKIE didn't exist, creates it with one value
    // If it existed, adds to existing values
}

remove clears all values; insert replaces all values; append adds to existing.

Server-Side Response Building

use http::{HeaderMap, Response};
use http::header::{SET_COOKIE, CONTENT_TYPE, CONTENT_LENGTH};
 
fn build_response() {
    let mut response = Response::new("Hello".as_bytes().to_vec());
    
    // Single-value headers: use insert
    *response.headers_mut() = HeaderMap::new();
    response.headers_mut().insert(CONTENT_TYPE, "text/plain".parse().unwrap());
    response.headers_mut().insert(CONTENT_LENGTH, "5".parse().unwrap());
    
    // Multi-value headers: use append
    response.headers_mut().append(SET_COOKIE, "session=abc; HttpOnly".parse().unwrap());
    response.headers_mut().append(SET_COOKIE, "preferences=dark; Path=/".parse().unwrap());
    
    // If you're not sure whether header exists:
    // - Use insert to guarantee single value
    // - Use append to add without removing existing
    
    // Common pattern: conditional logic
    fn set_content_type(headers: &mut HeaderMap, ct: &str) {
        headers.insert(CONTENT_TYPE, ct.parse().unwrap());
    }
    
    fn add_cookie(headers: &mut HeaderMap, cookie: &str) {
        headers.append(SET_COOKIE, cookie.parse().unwrap());
    }
}

Response building typically uses insert for metadata and append for cookies.

Client-Side Request Headers

use http::{HeaderMap, Request};
use http::header::{ACCEPT, AUTHORIZATION, USER_AGENT, ACCEPT_ENCODING};
 
fn build_request() {
    let mut request = Request::builder()
        .uri("https://api.example.com/data")
        .body(())
        .unwrap();
    
    // Headers that should have single value:
    request.headers_mut().insert(USER_AGENT, "MyApp/1.0".parse().unwrap());
    request.headers_mut().insert(AUTHORIZATION, "Bearer token123".parse().unwrap());
    
    // Accept can have multiple values or one combined value
    // Option 1: Single Accept header with multiple MIME types (common)
    request.headers_mut().insert(ACCEPT, "text/html, application/json, */*".parse().unwrap());
    
    // Option 2: Multiple Accept headers (less common, some servers might not handle well)
    // Generally prefer single combined value for Accept
    
    // Accept-Encoding: single value with multiple algorithms
    request.headers_mut().insert(ACCEPT_ENCODING, "gzip, deflate, br".parse().unwrap());
    
    // Custom headers might support multiple values
    request.headers_mut().append("X-Custom-ID", "123".parse().unwrap());
    request.headers_mut().append("X-Custom-ID", "456".parse().unwrap());
}

Request headers typically use insert; custom headers might need append.

Performance Characteristics

use http::HeaderMap;
use http::header::SET_COOKIE;
 
fn performance() {
    // Insert performance:
    // - O(1) amortized for replacement
    // - Overwrites existing values (no iteration needed)
    // - Memory: old values are dropped
    
    // Append performance:
    // - O(1) amortized for adding
    // - Maintains linked list of values
    // - Memory: values accumulate
    
    let mut headers = HeaderMap::new();
    
    // Appending many values
    for i in 0..100 {
        headers.append(SET_COOKIE, format!("cookie{}={}", i, i).parse().unwrap());
    }
    // All 100 values stored
    
    // Iterating over all values is O(n) for n values
    let count = headers.get_all(SET_COOKIE).iter().count();
    assert_eq!(count, 100);
    
    // Replacing with insert clears all accumulated values
    headers.insert(SET_COOKIE, "single=value".parse().unwrap());
    assert_eq!(headers.get_all(SET_COOKIE).iter().count(), 1);
    
    // Memory implications:
    // - append can accumulate many values over time
    // - insert keeps memory bounded
    // - Consider memory for long-lived HeaderMaps
}

append accumulates memory; insert bounds it to a single value.

Return Values and Introspection

use http::HeaderMap;
use http::header::{CONTENT_TYPE, SET_COOKIE};
 
fn return_values() {
    let mut headers = HeaderMap::new();
    
    // insert returns Option<GetValue> - previous values if any
    let previous = headers.insert(CONTENT_TYPE, "text/html".parse().unwrap());
    assert!(previous.is_none()); // No previous value
    
    let previous = headers.insert(CONTENT_TYPE, "application/json".parse().unwrap());
    assert!(previous.is_some()); // Had previous value
    let prev_values: Vec<_> = previous.unwrap().iter().collect();
    assert_eq!(prev_values.len(), 1);
    assert_eq!(prev_values[0], "text/html");
    
    // append returns bool - whether key was new
    let new_key = headers.append(SET_COOKIE, "a=1".parse().unwrap());
    assert!(new_key); // Key didn't exist before
    
    let existing_key = headers.append(SET_COOKIE, "b=2".parse().unwrap());
    assert!(!existing_key); // Key already existed
    
    // Use return values for conditional logic
    fn ensure_single_value(headers: &mut HeaderMap, name: &'static str, value: &str) {
        headers.insert(name.try_into().unwrap(), value.parse().unwrap());
    }
    
    fn add_cookie(headers: &mut HeaderMap, cookie: &str) -> bool {
        headers.append(SET_COOKIE, cookie.parse().unwrap())
    }
}

Return values help understand what was replaced or added.

Wire Format Implications

use http::HeaderMap;
use http::header::SET_COOKIE;
 
fn wire_format() {
    // When serializing to HTTP/1.1:
    
    let mut headers = HeaderMap::new();
    headers.append(SET_COOKIE, "session=abc".parse().unwrap());
    headers.append(SET_COOKIE, "user=john".parse().unwrap());
    headers.append(SET_COOKIE, "theme=dark".parse().unwrap());
    
    // HTTP/1.1 wire format:
    // Set-Cookie: session=abc\r\n
    // Set-Cookie: user=john\r\n
    // Set-Cookie: theme=dark\r\n
    
    // For Set-Cookie, multiple headers is the correct format
    // (Cookie header on requests uses single combined header instead)
    
    // Contrast with insert:
    let mut single = HeaderMap::new();
    single.insert(SET_COOKIE, "session=abc".parse().unwrap());
    // Would produce:
    // Set-Cookie: session=abc\r\n
    
    // HTTP/2 and HTTP/3 use pseudo-headers and may combine
    // multiple values differently (concatenation)
}

HTTP/1.1 sends multiple headers; HTTP/2+ might concatenate them.

Common Patterns and Anti-Patterns

use http::HeaderMap;
use http::header::{SET_COOKIE, CONTENT_TYPE, CACHE_CONTROL};
 
fn patterns() {
    let mut headers = HeaderMap::new();
    
    // GOOD: Clear intent for single-value headers
    headers.insert(CONTENT_TYPE, "application/json".parse().unwrap());
    
    // GOOD: Explicit accumulation for multi-value headers
    headers.append(SET_COOKIE, "session=abc".parse().unwrap());
    headers.append(SET_COOKIE, "csrf=xyz".parse().unwrap());
    
    // BAD: Using append for single-value headers
    // This creates multiple Content-Type headers, which is invalid
    headers.append(CONTENT_TYPE, "text/html".parse().unwrap()); // Wrong!
    headers.append(CONTENT_TYPE, "application/json".parse().unwrap()); // Invalid!
    
    // BAD: Using insert for multi-value headers
    // This discards previous cookies unexpectedly
    headers.insert(SET_COOKIE, "new=value".parse().unwrap()); // Lost previous!
    
    // PATTERN: Conditional replacement
    fn set_content_type_once(headers: &mut HeaderMap, ct: &str) {
        if !headers.contains_key(CONTENT_TYPE) {
            headers.insert(CONTENT_TYPE, ct.parse().unwrap());
        }
    }
    
    // PATTERN: Clear and set new values
    fn replace_all_cookies(headers: &mut HeaderMap, cookies: &[&str]) {
        headers.remove(SET_COOKIE); // Clear existing
        for cookie in cookies {
            headers.append(SET_COOKIE, cookie.parse().unwrap());
        }
    }
}

Match the method to the header's HTTP semantics.

Summary Table

fn summary() {
    // | Method   | Behavior              | Returns        | Use Case              |
    // |----------|-----------------------|----------------|----------------------|
    // | insert   | Replaces all values   | Option<GetValue> | Single-value headers |
    // | append   | Adds to existing      | bool (new key) | Multi-value headers  |
    // | remove   | Removes all values    | Option<GetValue> | Clear header         |
    
    // | Header          | Insert | Append | Typical Usage           |
    // |-----------------|--------|--------|-------------------------|
    // | Content-Type    | Yes    | No     | Single MIME type        |
    // | Content-Length  | Yes    | No     | Single size             |
    // | Set-Cookie      | Rare   | Yes    | Multiple cookies        |
    // | Link            | No     | Yes    | Multiple links          |
    // | Allow           | No     | Yes    | Multiple methods        |
    // | Via             | No     | Yes    | Multiple proxies        |
    // | Warning         | No     | Yes    | Multiple warnings       |
    // | Accept          | Yes    | Rare   | Combined or single      |
    
    // | Method | Memory     | Iteration      | Wire Format       |
    // |--------|------------|----------------|-------------------|
    // | insert | Bounded    | Single value   | One header line   |
    // | append | Accumulates| Multiple values| Multiple lines    |
}

Synthesis

Quick reference:

use http::HeaderMap;
use http::header::{SET_COOKIE, CONTENT_TYPE};
 
let mut headers = HeaderMap::new();
 
// insert: Replace all values with single value (for single-value headers)
headers.insert(CONTENT_TYPE, "text/html".parse().unwrap());
 
// append: Add value to existing values (for multi-value headers)
headers.append(SET_COOKIE, "session=abc".parse().unwrap());
headers.append(SET_COOKIE, "user=john".parse().unwrap());
 
// Read all values
let all_cookies: Vec<_> = headers.get_all(SET_COOKIE).iter().collect();
 
// Read first/only value
let content_type = headers.get(CONTENT_TYPE);

Key insight: The choice between insert and append reflects HTTP semantics, not just data structure behavior. HTTP headers fall into two categories: those that should have exactly one value (Content-Type, Content-Length, Host, Location) and those that legitimately have multiple values (Set-Cookie, Link, Allow, Via, Warning). Use insert for the former—it replaces any existing value and guarantees a single value, preventing accidental multi-value headers that would violate HTTP specifications. Use append for the latter—it accumulates values, allowing multiple header lines in the HTTP response which clients interpret as separate headers. The return values differ semantically: insert returns the previous values (useful for detecting replacement), while append returns a boolean indicating whether the key was new (useful for tracking state). Memory implications matter for long-lived HeaderMaps: append can accumulate many values over time, while insert bounds memory to a single value. The HTTP wire format differs accordingly—append produces multiple header lines, which is correct for Set-Cookie but unusual for most other headers. When in doubt about HTTP semantics, prefer insert for most headers and reserve append for headers like Set-Cookie that explicitly support multiple values.