---
title: "HTTP Helpers"
description: "\"HTTP Helpers\" in Hono serve as a modular suite of utility functions designed to abstract the complexities of standard web interfaces into developer-friendly APIs. By wrapping common HTTP tasks—suc..."
last_updated: "2026-07-02T09:13:47.155637+00:00"
canonical_url: "https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/system-utilities/http-helpers"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/middleware/language/language.ts](https://github.com/blade47/hono/blob/main/src/middleware/language/language.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/helper/proxy/index.ts](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts)
- [src/utils/url.ts](https://github.com/blade47/hono/blob/main/src/utils/url.ts)
- [src/client/utils.ts](https://github.com/blade47/hono/blob/main/src/client/utils.ts)
- [src/utils/ipaddr.ts](https://github.com/blade47/hono/blob/main/src/utils/ipaddr.ts)
- [src/utils/accept.ts](https://github.com/blade47/hono/blob/main/src/utils/accept.ts)
- [src/client/fetch-result-please.ts](https://github.com/blade47/hono/blob/main/src/client/fetch-result-please.ts)
- [src/helper/conninfo/types.ts](https://github.com/blade47/hono/blob/main/src/helper/conninfo/types.ts)
- [src/helper/accepts/accepts.ts](https://github.com/blade47/hono/blob/main/src/helper/accepts/accepts.ts)
- [src/adapter/vercel/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/vercel/conninfo.ts)
- [src/helper/accepts/index.ts](https://github.com/blade47/hono/blob/main/src/helper/accepts/index.ts)
- [src/utils/mime.ts](https://github.com/blade47/hono/blob/main/src/utils/mime.ts)
- [src/helper/conninfo/index.ts](https://github.com/blade47/hono/blob/main/src/helper/conninfo/index.ts)
- [src/adapter/netlify/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/conninfo.ts)
- [src/helper/adapter/index.ts](https://github.com/blade47/hono/blob/main/src/helper/adapter/index.ts)
- [src/adapter/lambda-edge/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/conninfo.ts)
- [src/adapter/bun/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/bun/conninfo.ts)
- [src/utils/headers.ts](https://github.com/blade47/hono/blob/main/src/utils/headers.ts)
- [src/adapter/deno/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/conninfo.ts)
- [src/helper/websocket/index.ts](https://github.com/blade47/hono/blob/main/src/helper/websocket/index.ts)
- [src/adapter/cloudflare-workers/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-workers/conninfo.ts)
- [src/adapter/netlify/mod.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/mod.ts)
- [src/utils/http-status.ts](https://github.com/blade47/hono/blob/main/src/utils/http-status.ts)
- [src/adapter/cloudflare-pages/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/conninfo.ts)
- [src/adapter/aws-lambda/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/conninfo.ts)
- [src/adapter/deno/websocket.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/websocket.ts)
</details>

"HTTP Helpers" in Hono serve as a modular suite of utility functions designed to abstract the complexities of standard web interfaces into developer-friendly APIs. By wrapping common HTTP tasks—such as header manipulation, connection metadata extraction, and content-negotiation—into coherent helpers, they allow developers to interact with the request/response lifecycle without manual implementation of low-level specs.

The design philosophy prioritizes platform portability and architectural separation. Because Hono is built on Web Standards, these helpers are designed to be environment-agnostic where possible, while exposing specific "adapter" modules for platform-specific capabilities (like AWS Lambda, Cloudflare, or Deno). This separation ensures the core framework remains lean while allowing the community to implement deep integrations for specialized environments.

These helpers exist to solve the "plumbing" problems of web development: safely extracting proxy-aware client IP addresses, parsing complex `Accept` headers into ranked arrays, and simplifying cross-platform WebSocket upgrades. They act as the bridge between the raw `Request`/`Response` interface and the semantic requirements of a feature-rich web application, maintaining stability across divergent runtime behaviors.

## Connection Information (`ConnInfo`)
The `ConnInfo` subsystem provides a unified API for retrieving network metadata, specifically the remote client address. Because different platforms (e.g., AWS Lambda, Bun, Cloudflare) propagate client IP addresses through different headers (like `cf-connecting-ip` or `x-forwarded-for`), Hono exposes platform-specific implementations that normalize this access through the `ConnInfo` interface.

> [!TIP]
> Use `getConnInfo(c)` to abstract away platform-specific header parsing; never manually parse `x-forwarded-for` if an adapter provides a `getConnInfo` implementation.

Sources: [src/helper/conninfo/types.ts:1-46](https://github.com/blade47/hono/blob/main/src/helper/conninfo/types.ts#L1-L46), [src/adapter/aws-lambda/conninfo.ts:1-74](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/conninfo.ts#L1-L74)

## Content Negotiation (`Accepts`)
The `accepts` helper provides a mechanism to parse standard `Accept` headers (e.g., `Accept-Language`, `Accept`) and match them against a server's supported values. The mechanism uses a recursive parser that consumes the header string, tracking quality factors (`q`) and parameter keys/values, ultimately returning the best match based on client preference.

The selection logic follows a descending sort by quality factor. In the `defaultMatch` implementation, candidates are sorted such that `b.q - a.q` ensures the client's most-preferred media type or language is selected.

```mermaid
flowchart LR
    A["Raw Accept Header"] --> B["parseAccept()"]
    B --> C["Accept[] (parsed)"]
    C --> D["Sort by .q"]
    D --> E["Find first match in 'supports' array"]
    E --> F["Return winning type or 'default'"]
```

Sources: [src/utils/accept.ts:211-238](https://github.com/blade47/hono/blob/main/src/utils/accept.ts#L211-L238), [src/helper/accepts/accepts.ts:21-25](https://github.com/blade47/hono/blob/main/src/helper/accepts/accepts.ts#L21-L25)

## WebSocket Upgrades
The `upgradeWebSocket` helper abstracts the platform-specific ceremony required to transition an HTTP connection to a WebSocket connection. It defines a `WSContext` that mirrors standard event listeners (`onOpen`, `onMessage`, `onClose`, `onError`), providing a platform-independent way to define logic.

For platform implementations (e.g., `src/adapter/deno/websocket.ts`), this helper performs the necessary native upgrade, creates the context, and binds the provided listener functions.

```mermaid
sequenceDiagram
    participant App as Hono App
    participant Helper as upgradeWebSocket
    participant Platform as Deno/Worker
    App->>Helper: call upgradeWebSocket(events)
    Helper->>Platform: perform native upgrade
    Platform-->>Helper: return socket
    Helper->>Helper: instantiate WSContext
    Helper->>Platform: bind onOpen, onMessage, etc.
```

Sources: [src/helper/websocket/index.ts:70-91](https://github.com/blade47/hono/blob/main/src/helper/websocket/index.ts#L70-L91), [src/adapter/deno/websocket.ts:4-38](https://github.com/blade47/hono/blob/main/src/adapter/deno/websocket.ts#L4-L38)

## Secure Headers Middleware
The `secureHeaders` helper is a complex middleware responsible for injecting security-focused headers into the response. It pre-processes security options (CSP, `Permissions-Policy`, etc.) into a normalized set of header pairs.

The mechanism uses a callback-based architecture to defer the finalization of headers until the request lifecycle has progressed. A key invariant is the `Content-Security-Policy` callback which handles dynamic values like `nonce` generation.

> [!IMPORTANT]
> The `secureHeaders` middleware evaluates callbacks *before* calling `await next()`. This ensures that nonce values set in the context are available for the entire response lifecycle.

Sources: [src/middleware/secure-headers/secure-headers.ts:181-224](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L181-L224)

## Proxy Helper
The `proxy` helper facilitates request forwarding by stripping "Hop-by-Hop" headers per RFC 2616 (e.g., `Connection`, `Keep-Alive`). This is crucial for avoiding header injection attacks and maintaining protocol integrity when acting as a gateway.

The implementation performs a strict check: if `strictConnectionProcessing` is enabled, it parses the `Connection` header and removes any listed headers, throwing an `HTTPException` if it encounters invalid characters that violate the token syntax.

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Hop-by-Hop stripping | Prevents header injection | Must maintain exclusion list |
| Middleware-style API | Familiar to Hono users | Requires async/await handling |
| RFC 9110 parsing | Correctness | Slightly higher CPU overhead |

Sources: [src/helper/proxy/index.ts:10-19](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts#L10-L19), [src/helper/proxy/index.ts:60-78](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts#L60-L78)

## URL Utilities
The `url.ts` utilities provide logic for routing and query parameter parsing. A notable mechanism is `_getQueryParam`, which is optimized for both simple and complex (encoded) URLs. It avoids the overhead of `URLSearchParams` for trivial cases by manually searching the `?` and `&` indices in the raw string.

```ts
// Example of manual index-based search used for optimization
while (keyIndex !== -1) {
  const trailingKeyCode = url.charCodeAt(keyIndex + key.length + 1)
  if (trailingKeyCode === 61) { // '='
    // Extract slice...
  }
}
```

Sources: [src/utils/url.ts:219-246](https://github.com/blade47/hono/blob/main/src/utils/url.ts#L219-L246)

## Related

- [Request Lifecycle](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/core-engine/request-lifecycle)


## Sitemap

See the full [sitemap](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/llms.txt) for all pages in this wiki.