Edge Context

The edge context provides information about how a request arrived—the network path, protocols, and infrastructure. Use it for security decisions, performance optimization, and debugging.

Overview

The edge context is available on every AgentExecutionContext:

import type { AgentExecutionContext } from '@ensemble-edge/conductor'

export default async function handler(ctx: AgentExecutionContext) {
  const { edge } = ctx

  // Datacenter
  console.log(edge?.colo)      // "DFW"
  console.log(edge?.coloName)  // "Dallas"

  // Network
  console.log(edge?.asn)            // 7922
  console.log(edge?.asOrganization) // "Comcast"

  // Protocol
  console.log(edge?.httpProtocol)  // "HTTP/2"
  console.log(edge?.tlsVersion)    // "TLSv1.3"

  // Detection helpers
  if (edge?.isFromCloudProvider()) {
    // Request from AWS, GCP, Azure, etc.
  }
}

Datacenter Information

Know which Cloudflare datacenter is serving the request:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge, logger } = ctx

  // Three-letter IATA airport code
  const colo = edge?.colo  // "DFW", "LHR", "NRT", etc.

  // Human-readable city name
  const coloName = edge?.coloName  // "Dallas", "London", "Tokyo"

  // Useful for debugging latency
  logger?.info(`Request served from ${coloName} (${colo})`)

  return { servedFrom: coloName }
}

Common Datacenter Codes

Code	City	Region
`DFW`	Dallas	North America
`LAX`	Los Angeles	North America
`EWR`	Newark	North America
`LHR`	London	Europe
`FRA`	Frankfurt	Europe
`CDG`	Paris	Europe
`NRT`	Tokyo	Asia Pacific
`SIN`	Singapore	Asia Pacific
`SYD`	Sydney	Asia Pacific

Network Detection

Identify the network provider (ASN) for security and routing decisions:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge } = ctx

  // Autonomous System Number
  const asn = edge?.asn  // 7922

  // Organization name
  const org = edge?.asOrganization  // "Comcast Cable Communications, LLC"

  return { asn, organization: org }
}

Cloud Provider Detection

Detect if the request originates from a known cloud provider:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge, logger } = ctx

  if (edge?.isFromCloudProvider()) {
    const provider = edge.getCloudProvider()
    logger?.warn('Request from cloud provider', { provider, asn: edge.asn })

    // Apply stricter rate limiting for potential automation
    return {
      rateLimit: 'strict',
      reason: `Traffic from ${provider}`
    }
  }

  return { rateLimit: 'normal' }
}

Detected cloud providers:

Provider	ASNs
AWS	16509, 14618
Google Cloud	15169, 396982
Microsoft Azure	8075, 8068
DigitalOcean	14061
Cloudflare	13335
Oracle Cloud	31898
Alibaba Cloud	45102
Linode	63949
Vultr	20473
Hetzner	24940
OVH	16276

VPN Detection

Detect if the request comes from a known VPN provider:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge, logger } = ctx

  if (edge?.isFromVPN()) {
    const provider = edge.getVPNProvider()
    logger?.info('Request from VPN', { provider })

    // VPN usage might indicate privacy-conscious user
    // Consider adjusting fingerprinting or tracking
  }

  return { vpnDetected: edge?.isFromVPN() }
}

VPN detection is based on ASN matching and is not foolproof. Many VPNs use residential or cloud IP addresses that won’t be detected.

Protocol Information

Check HTTP and TLS protocol details:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge } = ctx

  // HTTP version
  const protocol = edge?.httpProtocol  // "HTTP/1.1", "HTTP/2", "HTTP/3"

  // TLS details
  const tlsVersion = edge?.tlsVersion  // "TLSv1.3"
  const tlsCipher = edge?.tlsCipher    // "AEAD-AES128-GCM-SHA256"

  // Client capabilities
  const acceptEncoding = edge?.clientAcceptEncoding  // "gzip, deflate, br"

  return { protocol, tlsVersion, tlsCipher }
}

Protocol Helpers

export default async function handler(ctx: AgentExecutionContext) {
  const { edge } = ctx

  // Check HTTP/2 or higher
  if (edge?.isHTTP2OrHigher()) {
    // Can use HTTP/2+ features like server push
  }

  // Check HTTP/3 specifically (QUIC)
  if (edge?.isHTTP3()) {
    // Client supports QUIC protocol
  }

  // Check modern TLS (1.2+)
  if (edge?.isModernTLS()) {
    // Secure connection with modern cipher suite
  } else {
    // Consider warning about outdated client
  }
}

Use Cases

Bot & Scraper Detection

Requests from cloud providers often indicate automated traffic:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge, location, input } = ctx

  let suspicionScore = 0

  // Cloud provider traffic
  if (edge?.isFromCloudProvider()) {
    suspicionScore += 30
  }

  // VPN usage
  if (edge?.isFromVPN()) {
    suspicionScore += 10
  }

  // Missing or unusual Accept-Encoding
  if (!edge?.clientAcceptEncoding) {
    suspicionScore += 20
  }

  // Decide action based on score
  if (suspicionScore >= 50) {
    return {
      action: 'challenge',
      reason: 'Suspicious traffic pattern'
    }
  }

  return { action: 'allow' }
}

Security Logging

Log edge information for security audits:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge, location, logger, input } = ctx

  // Log security-relevant details
  logger?.info('Request processed', {
    // Network
    colo: edge?.colo,
    asn: edge?.asn,
    asOrganization: edge?.asOrganization,
    isCloudProvider: edge?.isFromCloudProvider(),
    cloudProvider: edge?.getCloudProvider(),

    // Protocol security
    httpProtocol: edge?.httpProtocol,
    tlsVersion: edge?.tlsVersion,
    isModernTLS: edge?.isModernTLS(),

    // Geographic (from location context)
    country: location?.country,
    region: location?.regionCode
  })

  return { logged: true }
}

Feature Detection

Enable features based on client capabilities:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge } = ctx

  const features = {
    // HTTP/2+ enables multiplexing
    multiplexing: edge?.isHTTP2OrHigher(),

    // HTTP/3 enables QUIC benefits
    quic: edge?.isHTTP3(),

    // Modern TLS for secure features
    secureFeatures: edge?.isModernTLS(),

    // Compression support
    brotli: edge?.clientAcceptEncoding?.includes('br'),
    gzip: edge?.clientAcceptEncoding?.includes('gzip')
  }

  return { supportedFeatures: features }
}

Multi-Region Debugging

Debug latency issues by checking which datacenter served the request:

export default async function handler(ctx: AgentExecutionContext) {
  const { edge, location, logger } = ctx
  const startTime = Date.now()

  // Process request...
  const result = await processRequest()

  const latency = Date.now() - startTime

  // Log with geographic context
  logger?.info('Request timing', {
    latencyMs: latency,
    userCountry: location?.country,
    servingColo: edge?.colo,
    servingCity: edge?.coloName,
    // Useful for identifying routing issues
    expectedColo: getExpectedColo(location?.country)
  })

  return result
}

function getExpectedColo(country?: string): string {
  // Map countries to expected nearby datacenters
  const coloMap: Record<string, string> = {
    US: 'DFW/LAX/EWR',
    GB: 'LHR',
    DE: 'FRA',
    JP: 'NRT',
    AU: 'SYD',
    SG: 'SIN'
  }
  return coloMap[country ?? ''] ?? 'unknown'
}

TypeScript Types

Import the EdgeContext type:

import type { EdgeContext } from '@ensemble-edge/conductor'

// EdgeContext interface
interface EdgeContext {
  // Datacenter
  colo: string
  coloName: string

  // Network
  asn: number
  asOrganization: string

  // Protocol
  httpProtocol: string
  tlsVersion: string
  tlsCipher: string
  clientAcceptEncoding: string

  // Methods
  isFromCloudProvider(): boolean
  getCloudProvider(): string | null
  isFromVPN(): boolean
  getVPNProvider(): string | null
  isHTTP2OrHigher(): boolean
  isHTTP3(): boolean
  isModernTLS(): boolean
}

Edge vs Location

Both contexts come from Cloudflare’s request.cf, but serve different purposes:

Context	Purpose	Example Use
`location`	Where the user is	Localization, compliance, timezone
`edge`	How they connected	Security, debugging, feature detection

Use them together for comprehensive request intelligence:

export default async function handler(ctx: AgentExecutionContext) {
  const { location, edge } = ctx

  return {
    // Geographic intelligence
    country: location?.country,
    jurisdiction: location?.jurisdiction,
    language: location?.language,

    // Network intelligence
    datacenter: edge?.coloName,
    isAutomated: edge?.isFromCloudProvider(),
    isSecure: edge?.isModernTLS()
  }
}

Next Steps

Location Context

Geographic and jurisdiction data

Security

Authentication and authorization

Operations

Available operation types

Testing

Testing and observability

Conductor

Getting Started

Core Concepts

Building

Components

Operations Reference

Plugins

Starter Kit

Playbooks

Reference

Overview

Datacenter Information

Common Datacenter Codes

Network Detection

Cloud Provider Detection

VPN Detection

Protocol Information

Protocol Helpers

Use Cases

Bot & Scraper Detection

Security Logging

Feature Detection

Multi-Region Debugging

TypeScript Types

Edge vs Location

Next Steps

Location Context

Security

Operations

Testing

​Overview

​Datacenter Information

​Common Datacenter Codes

​Network Detection

​Cloud Provider Detection

​VPN Detection

​Protocol Information

​Protocol Helpers

​Use Cases

​Bot & Scraper Detection

​Security Logging

​Feature Detection

​Multi-Region Debugging

​TypeScript Types

​Edge vs Location

​Next Steps

Location Context

Security

Operations

Testing

Overview

Datacenter Information

Common Datacenter Codes

Network Detection

Cloud Provider Detection

VPN Detection

Protocol Information

Protocol Helpers

Use Cases

Bot & Scraper Detection

Security Logging

Feature Detection

Multi-Region Debugging

TypeScript Types

Edge vs Location

Next Steps