Utilities and Encoding

Overview

The Hono framework provides a comprehensive set of low-level utilities and encoding helpers to support core operations, HTTP protocol management, templating, and request handling across diverse JavaScript runtimes. These modular helpers provide efficient mechanisms for cookie parsing, cryptographic signature verification, URI decoding, HTML escaping, Base64 and Base64Url data transformations, asynchronous task pooling, and status-code typing.

Sources: src/utils/cookie.ts:1-165, src/utils/url.ts:1-204, src/utils/html.ts:1-182, src/utils/encode.ts:1-34, src/utils/concurrent.ts:1-55, src/utils/http-status.ts:1-72

Cookie parsing and signature validation

Cookie Parsing and Helper Call Chains

Cookie parsing and retrieval are orchestrated through helper functions exposed in src/helper/cookie/index.ts backed by core algorithms in src/utils/cookie.ts. When a cookie is deleted or retrieved, request headers are inspected and processed through a deterministic execution flow.

1. deleteCookie initiates removal by calling getCookie with the target context, cookie name, and optional prefix constraints. Sources: src/helper/cookie/index.ts:141-144
2. getCookie extracts the raw Cookie header from c.req.raw.headers, resolves cookie prefixes (__Secure- or __Host-), and invokes parse. Sources: src/helper/cookie/index.ts:27-41
3. parse splits the raw cookie string by semicolons and iterates over individual pairs, using trimCookieWhitespace to strip leading and trailing spaces or tab characters from both names and values. Sources: src/utils/cookie.ts:79-115
4. tryDecode handles percent-encoded cookie values by attempting standard decoding and gracefully falling back on malformed or partially encoded byte sequences. Sources: src/utils/cookie.ts:128-130, src/utils/url.ts:80-93

Sources: src/helper/cookie/index.ts:27-144, src/utils/cookie.ts:79-130, src/utils/url.ts:80-93

Cryptographic Signature Validation

Signed cookies are parsed and verified using Web Crypto HMAC-SHA-256 operations via parseSigned. The implementation imports secrets into CryptoKey instances and validates base64-encoded signatures attached to cookie values.

Copyconst algorithm = { name: 'HMAC', hash: 'SHA-256' }
 
const getCryptoKey = async (secret: string | BufferSource): Promise<CryptoKey> => {
  const secretBuf = typeof secret === 'string' ? new TextEncoder().encode(secret) : secret
  return await crypto.subtle.importKey('raw', secretBuf, algorithm, false, ['sign', 'verify'])
}

Sources: src/utils/cookie.ts:37-42

Cookie Validation Patterns

Cookie names and values are validated against strict regular expressions adhering to RFC 6265 specifications, with allowances for common real-world characters.

Sources: src/utils/cookie.ts:70-77

Cookie serialization and attribute formatting

Execution Walkthrough and Sequence

Cookie serialization converts key-value pairs and attribute options into well-formed Set-Cookie header strings. The serialization helpers enforce security constraints based on cookie prefixes and append options like domain, path, max-age, and same-site policies.

The generation and dispatch of cookie headers follow a strict sequence across helper and utility modules.

1. deleteCookie initiates removal by capturing the current cookie value via getCookie and delegating to setCookie with an empty string and a maxAge of zero. Sources: src/helper/cookie/index.ts:141-144
2. setCookie passes the cookie name, value, and options to generateCookie to format the complete attribute string. Sources: src/helper/cookie/index.ts:99-102
3. generateCookie evaluates prefix options (secure or host), enforces strict path and domain requirements, and invokes serialize. Sources: src/helper/cookie/index.ts:78-97

Sources: src/helper/cookie/index.ts:78-144

URL path manipulation and decoding

Path Normalization and Segment Splitting

URL paths are split into array segments and merged through dedicated utilities that handle trailing slashes, root prefixes, and subpath concatenation. splitPath splits a path string by forward slashes and shifts off any leading empty element created by a leading slash. mergePath accepts multiple path arguments, recursively resolves nested inputs, normalizes leading forward slashes on subpaths, and preserves trailing slashes only when explicitly designated at the end of the base or subpath. Sources: src/utils/url.ts:8-14, src/utils/url.ts:158-169

Copyexport const splitPath = (path: string): string[] => {
  const paths = path.split('/')
  if (paths[0] === '') {
    paths.shift()
  }
  return paths
}

Sources: src/utils/url.ts:8-14

Group Mark Replacement and Parameter Extraction

Routing paths containing parameter blocks or braces are normalized via group extraction and replacement routines. extractGroupsFromPath scans path strings for bracketed expressions, extracts them into key-value group pairs, and substitutes temporary placeholder marks formatted as @${index}. splitRoutingPath combines this extraction step with segment splitting and replaceGroupMarks to reconstruct the original segments with their group placeholders intact. Sources: src/utils/url.ts:16-21, src/utils/url.ts:23-33, src/utils/url.ts:35-48

Sources: src/utils/url.ts:8-14, src/utils/url.ts:23-48, src/utils/url.ts:171-203

Fault-Tolerant URI Decoding

URI decoding utilities wrap native decoding functions with recovery logic to handle malformed percent-encoded strings and invalid UTF-8 sequences without throwing uncaught exceptions. tryDecode attempts to execute a provided decoder function, falling back to a regex-based matcher that isolates percent-encoded byte sequences and decodes valid sub-segments individually. tryDecodeURI applies this fault-tolerant behavior directly to decodeURI. Sources: src/utils/url.ts:80-104

Copyexport const tryDecode = (str: string, decoder: Decoder): string => {
  try {
    return decoder(str)
  } catch {
    return str.replace(/(?:%[0-9A-Fa-f]{2})+/g, (match) => {
      try {
        return decoder(match)
      } catch {
        return match
      }
    })
  }
}

Sources: src/utils/url.ts:81-93

HTML escaping and template rendering

Escaped String Wrappers and Buffer Escape Mechanics

The HTML helper system relies on branded string types and buffer utilities to manage template tags src/utils/html.ts:17-21, src/helper/html/index.ts:11-14. The raw function constructs an HtmlEscapedString object wrapping an underlying value, setting its isEscaped flag to true and attaching optional callbacks src/utils/html.ts:40-46. Text escaping is handled by escapeToBuffer, which scans strings for characters matching the regular expression /[&<>'\"]/ and appends entity codes to a StringBuffer src/utils/html.ts:51-51, src/utils/html.ts:90-127.

Sources: src/utils/html.ts:102-117

Template Tag Processing and StringBuffer Resolution

The html tagged template function iterates over template strings and interpolated values, flattening array children and handling strings, numbers, booleans, null, undefined, escaped objects, and promises src/helper/html/index.ts:11-48. Interpolated items containing active callbacks or asynchronous promises cause the buffer to prepend items via buffer.unshift('', child), alternating strings and promises src/helper/html/index.ts:33-44. stringBufferToString processes these buffers from tail to head, resolving promises and collecting embedded callbacks src/utils/html.ts:53-88.

Copy* StringBuffer contains string and Promise<string> alternately
* The length of the array will be odd, the odd numbered element will be a string,
* and the even numbered element will be a Promise<string>.
* When concatenating into a single string, it must be processed from the tail.
* @example
* [
*   'framework.',
*   Promise.resolve('ultra fast'),
*   'a ',
*   Promise.resolve('is '),
*   'Hono',
* ]
*/

Sources: src/utils/html.ts:24-36

Synchronous and Asynchronous Callback Resolution

Callback resolution supports distinct execution phases defined by HtmlEscapedCallbackPhase src/utils/html.ts:6-10. resolveCallbackSync evaluates stringification callbacks synchronously when no asynchronous promises or streams are present src/utils/html.ts:129-140. For asynchronous rendering flows, resolveCallback awaits promises, maps over callback functions with specific execution phases, filters truthy results, and recursively resolves nested values src/utils/html.ts:142-182.

Sources: src/utils/html.ts:6-10

Binary and Base64 encoding helpers

Base64 and Base64Url Operations

Encoding and decoding binary buffers and URL-safe strings rely on standard Base64 transformations combined with custom character substitutions. encodeBase64 converts any ArrayBufferLike into a Base64 string by iterating over its bytes via Uint8Array, converting each character code to a binary string, and passing the result to btoa src/utils/encode.ts:15-22. Conversely, decodeBase64 decodes a Base64 string using atob and populates a Uint8Array from both ends simultaneously src/utils/encode.ts:25-33. For URL-safe representations, encodeBase64Url replaces forward slashes with underscores and plus signs with hyphens, while decodeBase64Url reverses these substitutions prior to decoding src/utils/encode.ts:6-11. UTF-8 text encoding and decoding utilities are exposed directly through utf8Encoder and utf8Decoder instances src/utils/jwt/utf8.ts:6-7.

Sources: src/utils/encode.ts:6-33, src/utils/jwt/utf8.ts:6-7

Cryptographic Hashing Wrappers

Cryptographic hashing utilities generate message digests using the Web Crypto API's crypto.subtle.digest interface src/utils/crypto.ts:45-56. The createHash function accepts data in various formats, stringifying JSON objects and encoding plain strings with TextEncoder when the input is not already an ArrayBuffer or ArrayBufferView [src/utils/crypto.ts:33-43]. The resulting digest buffer is converted into a hexadecimal string by mapping each byte to a zero-padded hex representation src/utils/crypto.ts:52-55. Specific algorithm wrappers provide pre-configured parameters for standard hash functions.

Sources: src/utils/crypto.ts:15-31

Concurrency control and task pools

Task Throttling and Execution Pools

Managing concurrent asynchronous execution pools is handled via the createPool helper, which limits simultaneous task execution during batch operations src/utils/concurrent.ts:12-18. By default, pools enforce a maximum concurrency limit of 1024 active tasks when no options are provided src/utils/concurrent.ts:6, src/utils/concurrent.ts:19. The returned Pool interface exposes a single run method that accepts a task function returning a value or a promise src/utils/concurrent.ts:8-10.

Copyexport const createPool = ({
  concurrency,
  interval,
}: {
  concurrency?: number
  interval?: number
} = {}): Pool => {
  concurrency ||= DEFAULT_CONCURRENCY
 
  if (concurrency === Infinity) {
    // unlimited
    return {
      run: async (fn) => fn(),
    }
  }
 
  const pool: Set<{}> = new Set()
  const run = async <T>(
    fn: () => T,
    promise?: Promise<T>,
    resolve?: (result: T) => void
  ): Promise<T> => {
    if (pool.size >= (concurrency as number)) {
      promise ||= new Promise<T>((r) => (resolve = r))
      setTimeout(() => run(fn, promise, resolve))
      return promise
    }
    const marker = {}
    pool.add(marker)
    const result = await fn()
    if (interval) {
      setTimeout(() => pool.delete(marker), interval)
    } else {
      pool.delete(marker)
    }
    if (resolve) {
      resolve(result)
      return promise as Promise<T>
    } else {
      return result
    }
  }
  return { run }

Sources: src/utils/concurrent.ts:12-54

When the pool's active set size reaches the configured concurrency threshold, incoming execution requests queue up by returning a deferred promise that re-evaluates via setTimeout src/utils/concurrent.ts:34-38. If concurrency is explicitly set to Infinity, throttling is disabled entirely, executing tasks immediately without tracking or queuing src/utils/concurrent.ts:21-26.

Pool Configuration Options

The createPool function accepts a configuration object defining concurrency limits and release intervals src/utils/concurrent.ts:12-18.

Sources: src/utils/concurrent.ts:6, src/utils/concurrent.ts:16-17, src/utils/concurrent.ts:19, src/utils/concurrent.ts:42-43

HTTP headers and status codes

HTTP Status Code Mappings

Hono provides comprehensive TypeScript type definitions categorizing standard HTTP status codes by their functional classification src/utils/http-status.ts:6-40. These types include informatory responses, successful operations, redirects, client errors, and server errors src/utils/http-status.ts:6-40. Unofficial or custom status codes can be cast using UnofficialStatusCode (-1) when interacting with non-standard server extensions src/utils/http-status.ts:43-52.

Sources: src/utils/http-status.ts:6-40

Header Utilities and Proxy Management

Typed utilities define strict unions for request and response headers in src/utils/headers.ts, covering standard IANA HTTP field names src/utils/headers.ts:8-322. Additionally, proxy helpers process hop-by-hop headers such as connection, keep-alive, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, and upgrade src/helper/proxy/index.ts:10-19. When strictConnectionProcessing is enabled, connection header values are validated against ALLOWED_TOKEN_PATTERN (/^[!#$%&'*+\-.0-9A-Z^_a-z|~]+$/`) before stripping listed headers src/helper/proxy/index.ts:22-22, src/helper/proxy/index.ts:63-76.

Related

• Execution Context
• Request Lifecycle