cloudflared/AGENTS.md

Cloudflared

Cloudflare's command-line tool and networking daemon written in Go. Production-grade tunneling and network connectivity services used by millions of developers and organizations worldwide.

Essential Commands

Build & Test (Always run before commits)

# Full development check (run before any commit)
make test lint

# Build for current platform
make cloudflared

# Run all unit tests with coverage
make test
make cover

# Run specific test
go test -run TestFunctionName ./path/to/package

# Run tests with race detection
go test -race ./...

Platform-Specific Builds

# Linux
TARGET_OS=linux TARGET_ARCH=amd64 make cloudflared

# Windows
TARGET_OS=windows TARGET_ARCH=amd64 make cloudflared

# macOS ARM64
TARGET_OS=darwin TARGET_ARCH=arm64 make cloudflared

# FIPS compliant build
FIPS=true make cloudflared

Code Quality & Formatting

# Run linter (38+ enabled linters)
make lint

# Auto-fix formatting
make fmt
gofmt -w .
goimports -w .

# Security scanning
make vet

# Component tests (Python integration tests)
cd component-tests && python -m pytest test_file.py::test_function_name

Notes on linting:

• .golangci.yaml is configured with new-from-rev and whole-files: true. Touching a file triggers linting of the ENTIRE file, not just the changed hunks. Expect to fix pre-existing issues in files you modify, or add targeted // nolint: <linter> comments with a short justification.
• Prefer defer func() { _ = resource.Close() }() over defer resource.Close() for io.Closer values whose error truly does not matter — this satisfies errcheck without hiding real failures elsewhere.

Project Knowledge

Package Structure

• Use meaningful package names that reflect functionality
• Package names should be lowercase, single words when possible
• Avoid generic names like util, common, helper

Well-known shared packages

• crypto/: Single source of truth for TLS curve preferences and other cryptographic primitives shared by every edge-facing transport. Import as cfdcrypto "github.com/cloudflare/cloudflared/crypto" to avoid colliding with the standard library's crypto package. Do NOT duplicate TLS curve or cipher selection logic in other packages.
• tlsconfig/: Builds the base *tls.Config used for edge connections (CreateTunnelConfig) and loads origin/CA pools. Curve selection is intentionally NOT set here; it is applied per-connection from the crypto/ package so the same config can be cloned and reused across protocols.
• features/: Runtime feature flags including PostQuantumMode (PostQuantumPrefer = default, PostQuantumStrict = --post-quantum).
• fips/: Build-tag driven FIPS detection. Only fips.IsFipsEnabled() is exposed; never branch on fipsEnabled inside a function if the two branches return the same value.

Function and Method Guidelines

// Good: Clear purpose, proper error handling
func (c *Connection) HandleRequest(ctx context.Context, req *http.Request) error {
    if req == nil {
        return errors.New("request cannot be nil")
    }
    // Implementation...
    return nil
}

Error Handling

• Always handle errors explicitly, never ignore them
• Use fmt.Errorf for error wrapping
• Create meaningful error messages with context
• Use error variables for common errors

// Good error handling patterns
if err != nil {
    return fmt.Errorf("failed to process connection: %w", err)
}

Logging Standards

• Use github.com/rs/zerolog for structured logging
• Include relevant context fields
• Use appropriate log levels (Debug, Info, Warn, Error)

logger.Info().
    Str("tunnelID", tunnel.ID).
    Int("connIndex", connIndex).
    Msg("Connection established")

Testing Patterns

• Use github.com/stretchr/testify for assertions
• Test files end with _test.go
• Use table-driven tests for multiple scenarios
• Always use t.Parallel() for parallel-safe tests
• Use meaningful test names that describe behavior

func TestMetricsListenerCreation(t *testing.T) {
    t.Parallel()
    // Test implementation
    assert.Equal(t, expected, actual)
    require.NoError(t, err)
}

Constants and Variables

const (
    MaxGracePeriod       = time.Minute * 3
    MaxConcurrentStreams = math.MaxUint32
    LogFieldConnIndex    = "connIndex"
)

var (
    // Group related variables
    switchingProtocolText = fmt.Sprintf("%d %s", http.StatusSwitchingProtocols, http.StatusText(http.StatusSwitchingProtocols))
    flushableContentTypes = []string{sseContentType, grpcContentType, sseJsonContentType}
)

Type Definitions

• Define interfaces close to their usage
• Keep interfaces small and focused
• Use descriptive names for complex types

type TunnelConnection interface {
    Serve(ctx context.Context) error
}

type TunnelProperties struct {
    Credentials    Credentials
    QuickTunnelUrl string
}

Key Architectural Patterns

Context Usage

• Always accept context.Context as first parameter for long-running operations
• Respect context cancellation in loops and blocking operations
• Pass context through call chains

Concurrency

• Use channels for goroutine communication
• Protect shared state with mutexes
• Prefer sync.RWMutex for read-heavy workloads
• *tls.Config values stored in shared maps (e.g. TunnelConfig.EdgeTLSConfigs) must be Clone()d before mutating per-connection fields like CurvePreferences or NextProtos. Writing through the shared pointer races with concurrent connection attempts.

TLS & Post-Quantum key exchange

• Per-connection TLS configuration for edge connections is built via cfdcrypto.TLSConfigWithCurvePreferences(tlsConfig, pqMode). It clones the provided *tls.Config and sets CurvePreferences based on pqMode, so callers never need to clone or mutate CurvePreferences themselves. Do NOT reach for the package-private getCurvePreferences helper; the exported TLSConfigWithCurvePreferences is the only supported entry point.
• Two PQ modes are supported and apply identically to QUIC and HTTP/2:
  • PostQuantumPrefer (default): [X25519MLKEM768, P256Kyber768Draft00, CurveP256]
  • PostQuantumStrict (--post-quantum): [X25519MLKEM768, P256Kyber768Draft00]
• FIPS and non-FIPS builds use the same curve list. Do NOT reintroduce a fipsEnabled branch in curve-selection code; if the two modes ever diverge, express the divergence inside crypto/ so call sites remain untouched.
• HTTP/2 supports post-quantum handshakes. Never re-add a PostQuantumStrict-based rejection to H2 code paths, and never force --post-quantum to select QUIC-only in protocol selection.

Configuration

• Use structured configuration with validation
• Support both file-based and CLI flag configuration
• Provide sensible defaults

Metrics and Observability

• Instrument code with Prometheus metrics
• Use OpenTelemetry for distributed tracing
• Include structured logging with relevant context

Boundaries

✅ Always Do

• Run make test lint before any commit
• Handle all errors explicitly with proper context
• Use github.com/rs/zerolog for all logging
• Add t.Parallel() to all parallel-safe tests
• Follow the import grouping conventions
• Use meaningful variable and function names
• Include context.Context for long-running operations
• Close resources in defer statements

⚠️ Ask First Before

• Adding new dependencies to go.mod
• Modifying CI/CD configuration files
• Changing build system or Makefile
• Modifying component test infrastructure
• Adding new linter rules or changing golangci-lint config
• Making breaking changes to public APIs
• Changing logging levels or structured logging fields

🚫 Never Do

• Ignore errors without explicit handling (_ = err)
• Use generic package names (util, helper, common)
• Commit code that fails make test lint
• Use fmt.Print* instead of structured logging
• Modify vendor dependencies directly
• Commit secrets, credentials, or sensitive data
• Use deprecated or unsafe Go patterns
• Skip testing for new functionality
• Remove existing tests unless they're genuinely invalid

Dependencies Management

• Use Go modules (go.mod) exclusively
• Vendor dependencies for reproducible builds
• Keep dependencies up-to-date and secure
• Prefer standard library when possible
• Cloudflared uses a fork of quic-go always check release notes before bumping this dependency.

Security Considerations

• FIPS compliance support available
• Vulnerability scanning integrated in CI
• Credential handling follows security best practices
• Network security with TLS/QUIC protocols
• Regular security audits and updates
• Post quantum encryption

Common Patterns to Follow

1. Graceful shutdown: Always implement proper cleanup
2. Resource management: Close resources in defer statements
3. Error propagation: Wrap errors with meaningful context
4. Configuration validation: Validate inputs early
5. Logging consistency: Use structured logging throughout
6. Testing coverage: Aim for comprehensive test coverage
7. Documentation: Comment exported functions and types

Remember: This is a mission-critical networking tool used in production by many organizations. Code quality, security, and reliability are paramount.