fastly / pushpin

GitHub

Code

Understand fastly/pushpin's source layout and find a starting point for your task using the saved repository evidence.

Detailed import-graph metrics were not captured for this report.

How the code fits together

Entry Points & BinariesExecutable entry points for different Pushpin services and adapters.
Connection ManagementClient connection pooling, lifecycle, and routing to backend handlers.
Protocol ImplementationHTTP/1.1 and WebSocket protocol parsing, serialization, and handling.
Core InfrastructureAsync runtime, event loop, I/O utilities, and low-level abstractions.
Configuration & UtilitiesConfiguration parsing, logging, metrics, and supporting utilities.

Files at 800110b646e8 · descriptions are AI-written.

The descriptions and the file list come from different revisions. Check responsibilities against source.

Where to start reading

Repository root
Repository root
Public API candidatename match
Suggested starting pointAI

Find files for a task

Add a new HTTP request handler

Suggested by the saved analysis. Verify the proposed change against these source files.

Create a new request handler type in src/connmgr/connection.rs handling incoming HTTP requests
Define routing logic in src/connmgr/server.rs to forward requests to the backend
Extend src/core/http1/protocol.rs if custom HTTP semantics are required
Register the new handler in src/connmgr/mod.rs main connection processing loop

Add a new WebSocket feature or message type

Suggested by the saved analysis. Verify the proposed change against these source files.

Extend src/connmgr/websocket.rs to handle the new message frame type
Update src/connmgr/zhttppacket.rs to serialize/deserialize the new packet format
Add upstream HTTP request mapping in src/connmgr/server.rs
Document backend integration in configuration schema (src/core/config.rs)

Add new metrics or observability

Suggested by the saved analysis. Verify the proposed change against these source files.

Define new metric types in src/connmgr/metrics.rs
Export metrics via Prometheus in src/core/prometheus.rs
Instrument code paths in src/connmgr/connection.rs or src/core/http1/protocol.rs
Configure metric collection interval in src/core/config.rs

Add TLS or certificate validation logic

Suggested by the saved analysis. Verify the proposed change against these source files.

Extend src/connmgr/tls.rs with new certificate or cipher configuration
Update src/core/config.rs to parse new TLS settings from configuration
Apply TLS settings in src/connmgr/listener.rs for incoming connections
Apply TLS settings in src/connmgr/server.rs for outgoing backend connections

Change the public API

Start with possible export surfaces, then check their consumers and tests. These suggestions use file names, not verified execution paths.

File-name match for this task.

Change build or automation

Inspect the relevant configuration and the commands it runs before changing the workflow. These suggestions use file names, not verified execution paths.

File-name match for this task.
File-name match for this task.
File-name match for this task.

File paths come from a snapshot of up to 500 captured paths; an omitted file may still exist.

Public and runtime candidates are based on file names; their exports and execution paths still need checking in source.
The file list was refreshed after the written analysis. Subsystem descriptions and suggested changes may describe an older revision.

Architecture and request flow

Start here — files every contributor must understand

AI · unverified

src/bin/pushpin.rs

Main entry point for the Pushpin reverse proxy; initializes all subsystems and orchestrates the core loop.

src/connmgr/mod.rs

Connection manager module that routes and multiplexes client connections to backend handlers.

src/core/http1/mod.rs

HTTP/1.1 protocol implementation core; handles request/response parsing and serialization.

src/connmgr/websocket.rs

WebSocket protocol handler that translates bidirectional socket activity into backend HTTP requests.

src/core/eventloop.rs

Event loop reactor that drives asynchronous I/O and message dispatch across all subsystems.

src/core/config.rs

Configuration parser and holder for Pushpin's proxy behavior and network settings.

src/connmgr/server.rs

Backend server communication layer that sends HTTP requests to configured upstream services.

Request flow

Technology choices

Rust & C++

Rust provides memory safety and async runtime; C++ used for legacy protocol handling and low-level optimizations.

Event-driven async I/O (custom eventloop)

Efficiently handles thousands of concurrent client connections with minimal overhead per connection.

HTTP/1.1 protocol translation

Decouples realtime clients (WebSocket, long-polling) from backend via stateless HTTP requests, enabling language-agnostic backends.

TLS termination

Offloads encryption/decryption from backend; simplifies client-to-proxy and proxy-to-backend security separately.

Build time and runtime

Build-time

▸
Rust compiler (1.81+) — Compiles Rust source to native binaries with safety guarantees.
▸
C++ compiler — Compiles legacy C++ protocol implementations and utilities.
▸
cargo build system — Orchestrates compilation, linking, and dependency resolution.

Runtime

▸
EventLoop reactor — Poll-based async I/O multiplexer driving all concurrent activity.
▸
TLS engine — Handles certificate validation, cipher negotiation, encryption/decryption.
▸
HTTP/1.1 parser/serializer — Parses incoming requests and formats outgoing responses.
▸
DNS resolver — Resolves backend hostnames to IP addresses for connection pooling.
▸
Prometheus metrics exporter — Periodically exports connection and throughput metrics.

Design trade-offs

Proxy-based architecture (not library-based)

Clients interact with Pushpin directly; backend remains unaware of individual client connections.

Requires network hop through proxy; enables transparent operation but adds latency and single point of failure.

Translate WebSocket to HTTP requests for backend

Backends can use standard HTTP frameworks without WebSocket support.

Backend must handle state via HTTP semantics (headers, body, etc.); slightly higher overhead than native WebSocket passthrough.

Short-lived backend HTTP requests (polling-style)

Avoids persistent connections to backend; simplifies load balancing and scaling.

Higher request frequency; not optimal for extremely low-latency scenarios requiring persistent backend connections.

Mixed Rust + C++ codebase

Rust for new safety-critical async code; C++ for legacy protocol implementations and performance-sensitive paths.

Increased maintenance complexity and FFI boundary; slower adoption of new abstractions.

Non-goals

✗Serve application logic; only transparent proxying and protocol translation.
✗Handle client authentication/authorization; delegates to backend via headers/JWT.
✗Persist messages or provide message queue durability; stateless proxy only.
✗Support protocols beyond HTTP/1.1, HTTP/2, WebSocket, and long-polling.
✗Provide load balancing logic; simple server-list configuration only.

Code quality and hotspots

Quality Score: 65/100

Medium Risk

This repo has some quality gaps (No tests detected, High complexity) but is maintainable with improvements.

No tests detected -15High complexity -10Multiple anti-patterns -10

Maintainability grade

Static analysis

How maintainable the code looks — from complexity, code issues, test presence, file size, and hotspot load. It grades the shape of the code, not defect risk, and doesn't replace review.

16/100

A ≥ 85, B ≥ 70, C ≥ 55, D ≥ 40, F < 40

Cyclomatic complexityavg 134

0/35

Code issues0 errors, 10 warnings

16/20

Testsnone detected

0/20

Largest file10,739 lines

0/15

Hotspot load6 high-risk files

0/10

Configuration status

CI/CD Pipeline — configured

Provider: GitHub Actions

3 GitHub Actions workflows

Test Suite — not detected

Add unit tests for critical paths

Test Coverage — ~0%heuristic

0 test files / 380 source files. This is a file-count ratio, not real line coverage — set up Codecov for authoritative numbers.

Dependency Scanning — 1 tool configured

CodeQL

Top hotspots

Files edited often AND hard to reason about. Churn = recent commit frequency, Complexity = branches and nesting, Risk = both combined. These are the highest-leverage targets for refactoring or testing.

handler/handlerengine.cpp

Churn: 60 (15 commits/180d)Complexity: 100Risk: 60

handler/httpsession.cpp

Churn: 56 (14 commits/180d)Complexity: 100Risk: 56

All hotspots

Files that change often and are complex tend to accumulate more bugs

AI-suggested anti-patterns

AI · unverified

Pattern-matches from the file structure and dependencies — useful as hypotheses, but not grounded in actual source. For real findings see Code Scanning above.

Mixed Rust/C++ FFI boundary without clear ownership

High

Memory ownership unclear at Rust-C++ boundary; potential for use-after-free or double-free if FFI contract violated.

src/core (split between .rs and .cpp/.h files)

Event loop blocking on I/O without timeout

High

Backend connection operations may block indefinitely if server hangs; no explicit timeout guards visible in critical paths.

src/core/eventloop.rs, src/connmgr/server.rs

Unbounded connection accumulation

Medium

No evidence of max connection limits or backpressure; malicious client or resource leak could exhaust memory.

src/connmgr/pool.rs, src/connmgr/connection.rs

Implicit buffer sizing in HTTP parsing

Medium

HTTP parser accumulates request data without apparent max header size or body size checks; potential for DoS.

src/core/http1/protocol.rs, src/core/buffer.rs

AI-suggested bottlenecks

AI · unverified

Speculation from file structure, not profiling data. Validate against real metrics before acting on these.

Concurrency Bottleneck

Single-threaded event loop is ultimate bottleneck; cannot saturate multi-core CPU for I/O-bound workloads.

src/core/eventloop.rs (poll/epoll loop)

I/O Bottleneck

Blocking DNS lookups can stall event loop; no apparent async resolver or caching strategy.

src/connmgr/resolver.rs (DNS resolution)

Concurrency Bottleneck

Backend connection pooling with fixed max size may cause head-of-line blocking under high concurrency.

src/connmgr/server.rs (backend connection pool)

Code metrics

Static analysis on sampled source files (up to 15 files).

Avg Cyclomatic Complexity134

Counts if/for/while/switch/catch/ternary branches

Errors / Warnings0 / 10

Secrets, empty catches, console.log, var usage, long lines

Largest File Analyzed10739 lines

src/connmgr/connection.rs