ConnInfo

Access HTTP connection and network information

The ConnInfo helper provides type definitions for accessing HTTP connection information, including remote address, port, and transport protocol details. This is useful for logging, security checks, and network debugging.

Import

import type { ConnInfo, GetConnInfo, NetAddrInfo, AddressType } from 'hono/conninfo'

Type Definitions

The ConnInfo helper exports TypeScript types for working with connection information:

ConnInfo

The main connection information interface:

interface ConnInfo {
  /**
   * Remote connection information
   */
  remote: NetAddrInfo
}

NetAddrInfo

Network address information for a connection:

type NetAddrInfo = {
  /**
   * Transport protocol type
   */
  transport?: 'tcp' | 'udp'
  
  /**
   * Transport port number
   */
  port?: number
  
  /**
   * IP address or hostname
   */
  address?: string
  
  /**
   * Address type (IPv4 or IPv6)
   */
  addressType?: AddressType
} & (
  | {
      address: string
      addressType: AddressType
    }
  | {}
)

AddressType

The type of network address:

type AddressType = 'IPv6' | 'IPv4' | undefined

GetConnInfo

Helper type for functions that extract connection info from context:

type GetConnInfo = (c: Context) => ConnInfo

Usage with Adapters

Connection information extraction is adapter-specific. Many runtime adapters provide a getConnInfo function:

Cloudflare Workers

import { Hono } from 'hono'
import { getConnInfo } from 'hono/cloudflare-workers'

const app = new Hono()

app.get('/ip', (c) => {
  const info = getConnInfo(c)
  return c.json({
    address: info.remote.address,
    addressType: info.remote.addressType,
  })
})

Deno

import { Hono } from 'hono'
import { getConnInfo } from 'hono/deno'

const app = new Hono()

app.get('/connection', (c) => {
  const info = getConnInfo(c)
  return c.json({
    ip: info.remote.address,
    port: info.remote.port,
    transport: info.remote.transport,
  })
})

Bun

import { Hono } from 'hono'
import { getConnInfo } from 'hono/bun'

const app = new Hono()

app.get('/client-info', (c) => {
  const info = getConnInfo(c)
  return c.text(`Client IP: ${info.remote.address}`)
})

Node.js

import { Hono } from 'hono'
import { getConnInfo } from '@hono/node-server/conninfo'

const app = new Hono()

app.use('*', async (c, next) => {
  const info = getConnInfo(c)
  console.log(`Request from ${info.remote.address}:${info.remote.port}`)
  await next()
})

Common Use Cases

IP Address Logging

Log client IP addresses for requests:

import { getConnInfo } from 'hono/cloudflare-workers'

app.use('*', async (c, next) => {
  const info = getConnInfo(c)
  console.log(`[${new Date().toISOString()}] ${c.req.method} ${c.req.path} - ${info.remote.address}`)
  await next()
})

IP-based Rate Limiting

Implement simple IP-based rate limiting:

import { getConnInfo } from 'hono/cloudflare-workers'

const rateLimitMap = new Map<string, number>()

app.use('*', async (c, next) => {
  const info = getConnInfo(c)
  const ip = info.remote.address || 'unknown'
  
  const count = rateLimitMap.get(ip) || 0
  if (count > 100) {
    return c.text('Rate limit exceeded', 429)
  }
  
  rateLimitMap.set(ip, count + 1)
  await next()
})

Geolocation-based Content

Serve different content based on IP address:

import { getConnInfo } from 'hono/cloudflare-workers'

app.get('/localized', async (c) => {
  const info = getConnInfo(c)
  const ip = info.remote.address
  
  // Use IP geolocation service
  const region = await getRegionFromIP(ip)
  
  return c.json({
    ip,
    region,
    message: getLocalizedMessage(region)
  })
})

Security Checks

Implement IP allowlisting or blocklisting:

import { getConnInfo } from 'hono/cloudflare-workers'

const ALLOWED_IPS = ['192.168.1.1', '10.0.0.1']

app.use('/admin/*', async (c, next) => {
  const info = getConnInfo(c)
  const ip = info.remote.address
  
  if (!ip || !ALLOWED_IPS.includes(ip)) {
    return c.text('Forbidden', 403)
  }
  
  await next()
})

Debug Information

Return connection details for debugging:

import { getConnInfo } from 'hono/cloudflare-workers'

app.get('/debug/connection', (c) => {
  const info = getConnInfo(c)
  
  return c.json({
    remote: {
      address: info.remote.address,
      addressType: info.remote.addressType,
      port: info.remote.port,
      transport: info.remote.transport,
    },
    headers: Object.fromEntries(c.req.raw.headers),
  })
})

IPv4 vs IPv6

Check the address type to handle IPv4 and IPv6 differently:

import { getConnInfo } from 'hono/cloudflare-workers'

app.get('/ip-version', (c) => {
  const info = getConnInfo(c)
  const type = info.remote.addressType
  
  if (type === 'IPv6') {
    return c.text(`IPv6 address: ${info.remote.address}`)
  } else if (type === 'IPv4') {
    return c.text(`IPv4 address: ${info.remote.address}`)
  } else {
    return c.text('Address type unknown')
  }
})

Adapter Availability

Connection info support varies by runtime adapter:

Cloudflare Workers

Full support via hono/cloudflare-workers

Deno

Full support via hono/deno

Bun

Full support via hono/bun

Node.js

Available via @hono/node-server/conninfo

Check your specific adapter’s documentation for getConnInfo availability and implementation details.

Behind Proxies

When your application is behind a proxy or load balancer, the remote address will be the proxy’s IP. Use headers like X-Forwarded-For for the actual client IP:

import { getConnInfo } from 'hono/cloudflare-workers'

app.get('/real-ip', (c) => {
  // Try X-Forwarded-For first (from proxy)
  const forwardedFor = c.req.header('X-Forwarded-For')
  if (forwardedFor) {
    const clientIP = forwardedFor.split(',')[0].trim()
    return c.json({ ip: clientIP, source: 'X-Forwarded-For' })
  }
  
  // Fall back to direct connection info
  const info = getConnInfo(c)
  return c.json({ ip: info.remote.address, source: 'direct' })
})

Security: Only trust X-Forwarded-For and similar headers when you control the proxy. These headers can be spoofed by clients if not properly configured.

Best Practices

Check Adapter Support

Verify your runtime adapter supports getConnInfo before using

Handle Undefined

Always handle cases where address or port may be undefined

Proxy Awareness

Use appropriate headers when behind proxies or load balancers

Privacy Compliance

Be mindful of privacy laws when logging or storing IP addresses