# What Are the Dependencies of the Hysteria Core Module?

> Discover the direct and indirect dependencies of the Hysteria core module. Explore its reliance on custom QUIC, rate limiting, cryptography, and testing utilities.

- Repository: [Aperture Internet Laboratory/hysteria](https://github.com/apernet/hysteria)
- Tags: internals
- Published: 2026-05-13

---

**The Hysteria core module relies on five direct Go dependencies—including a customized QUIC transport (`apernet/quic-go`), rate limiting (`golang.org/x/time`), and testing utilities (`testify`, `goleak`)—alongside eleven indirect dependencies that handle cryptography, YAML parsing, and low-level networking.**

The **Hysteria core module** (`github.com/apernet/hysteria/core/v2`) provides the essential client and server implementations for the Hysteria 2 protocol, a high-performance, censorship-resistant networking stack built on QUIC. Developers exploring the codebase or integrating the library into custom applications need to understand what external packages power this functionality. All dependencies are declared in the `require` and `indirect` blocks of [`core/go.mod`](https://github.com/apernet/hysteria/blob/master/core/go.mod), which serves as the canonical manifest for the module's build requirements.

## Direct Dependencies Declared in core/go.mod

The `require` block in `core/go.mod` explicitly declares five direct dependencies that the core module imports for compilation, runtime operation, and testing.

**`github.com/apernet/quic-go`** (`v0.59.1-0.20260425001925-6c6cc9bcb716`) provides the customized QUIC transport that Hysteria builds upon. This fork of `quic-go` contains protocol modifications specific to Hysteria's congestion control and performance optimizations.

**`github.com/stretchr/testify`** (`v1.11.1`) supplies assertions and test helpers used throughout the core test suite to validate client and server behavior.

**`go.uber.org/goleak`** (`v1.2.1`) detects goroutine leaks in tests, ensuring clean shutdown of core components and preventing resource exhaustion in long-running applications.

**`golang.org/x/exp`** (`v0.0.0-20240506185415-9bf2ced13842`) supplies experimental utilities such as generic constraints and map functions used by the core code for type-safe operations.

**`golang.org/x/time`** (`v0.12.0`) provides time-related helpers such as `rate.Limiter` for traffic shaping and bandwidth management within the QUIC streams.

## Indirect (Transitive) Dependencies

The `go.mod` file also contains an `// indirect` block that pulls in packages required by the direct dependencies or by the test infrastructure. These are not imported directly by core package code but are necessary for compilation or testing:

- **`github.com/davecgh/go-spew`** – Pretty-printing of Go data structures used in debugging output.
- **`github.com/kr/text`** – Terminal text handling utilities.
- **`github.com/pmezard/go-difflib`** – Diff generation for test output comparisons.
- **`github.com/quic-go/qpack`** – QPACK header compression implementation used internally by `quic-go`.
- **`github.com/rogpeppe/go-internal`** – Internal testing utilities and build helpers.
- **`github.com/stretchr/objx`** – Generic map handling used by `testify`.
- **`golang.org/x/crypto`** – Cryptographic primitives including TLS and AEAD ciphersuites.
- **`golang.org/x/net`** – Low-level networking helpers and transport utilities.
- **`golang.org/x/sys`** – OS-specific system-call wrappers for optimized I/O.
- **`golang.org/x/text`** – Text processing and Unicode normalization utilities.
- **`gopkg.in/yaml.v3`** – YAML marshaling and unmarshaling used for configuration file parsing in [`core/server/config.go`](https://github.com/apernet/hysteria/blob/main/core/server/config.go).

## How Dependencies Power the Core Architecture

The core module stitches these dependencies together to provide a cohesive networking stack. The **QUIC transport** (`apernet/quic-go`) creates loss-tolerant data streams, while **rate limiting** (`x/time`, `x/exp`) enables smooth traffic shaping that distinguishes Hysteria's performance characteristics. **TLS and cryptography** (`x/crypto`) secure the QUIC payloads, and **YAML handling** (`yaml.v3`) parses server and client configuration files.

These dependencies are reflected across the core's key source files:

- **Client implementation** – [`core/client/client.go`](https://github.com/apernet/hysteria/blob/main/core/client/client.go) and [`core/client/udp.go`](https://github.com/apernet/hysteria/blob/main/core/client/udp.go) import the QUIC transport and rate limiters.
- **Server implementation** – [`core/server/config.go`](https://github.com/apernet/hysteria/blob/main/core/server/config.go) uses `yaml.v3` for configuration loading, while [`core/server/copy.go`](https://github.com/apernet/hysteria/blob/main/core/server/copy.go) handles data streaming between QUIC and underlying TCP/UDP connections.
- **Error definitions** – [`core/errors/errors.go`](https://github.com/apernet/hysteria/blob/main/core/errors/errors.go) provides centralized error types consumed by both client and server packages.

## Importing and Using the Core Module

Below are practical examples demonstrating how a consumer of the core module imports these dependencies transitively. The examples assume the module is available as `github.com/apernet/hysteria/core/v2`.

### Starting a Hysteria Server

This example loads a server configuration and instantiates the server, which internally initializes the QUIC transport:

```go
package main

import (
	"log"
	"github.com/apernet/hysteria/core/v2/core/server"
)

func main() {
	// Load configuration from YAML (uses gopkg.in/yaml.v3 internally)
	cfg, err := server.LoadConfigFile("server.yaml")
	if err != nil {
		log.Fatalf("config error: %v", err)
	}

	// Create and start the server; QUIC transport powered by apernet/quic-go
	srv, err := server.New(cfg)
	if err != nil {
		log.Fatalf("server init: %v", err)
	}
	if err := srv.Start(); err != nil {
		log.Fatalf("server run: %v", err)
	}
}

```

### Creating a Hysteria Client

This example demonstrates programmatic client configuration and UDP tunneling:

```go
package main

import (
	"context"
	"log"
	"time"

	"github.com/apernet/hysteria/core/v2/core/client"
)

func main() {
	// Configure client programmatically
	ccfg := client.Config{
		RemoteAddr: "example.com:443",
		Auth: client.AuthConfig{
			Password: "my-secret",
		},
		Transport: client.TransportConfig{
			IdleTimeout: 30 * time.Second,
		},
	}

	// Instantiate client; uses quic-go and golang.org/x/time for rate limiting
	cl, err := client.New(&ccfg)
	if err != nil {
		log.Fatalf("client init: %v", err)
	}
	defer cl.Close()

	// Open UDP tunnel through server
	udpConn, err := cl.DialUDP(context.Background(), "8.8.8.8:53")
	if err != nil {
		log.Fatalf("dial udp: %v", err)
	}
	defer udpConn.Close()

	// Use udpConn for DNS queries over QUIC
}

```

## Key Source Files

The following files in the `apernet/hysteria` repository consume the dependencies listed above:

- **`core/go.mod`** – Declares all direct and indirect Go dependencies with pinned versions.
- **[`core/client/client.go`](https://github.com/apernet/hysteria/blob/main/core/client/client.go)** – Main client struct and constructor; wires together QUIC transport, authentication, and connection helpers.
- **[`core/client/udp.go`](https://github.com/apernet/hysteria/blob/main/core/client/udp.go)** – UDP session handling and tunnel implementation for the client side.
- **[`core/server/config.go`](https://github.com/apernet/hysteria/blob/main/core/server/config.go)** – Configuration loader and validation; imports `gopkg.in/yaml.v3`.
- **[`core/server/copy.go`](https://github.com/apernet/hysteria/blob/main/core/server/copy.go)** – Handles bidirectional data copy between QUIC streams and underlying network connections.
- **[`core/errors/errors.go`](https://github.com/apernet/hysteria/blob/main/core/errors/errors.go)** – Centralized error definitions used throughout the core package.

## Summary

- The Hysteria core module declares **five direct dependencies** in `core/go.mod`: `apernet/quic-go`, `stretchr/testify`, `go.uber.org/goleak`, `golang.org/x/exp`, and `golang.org/x/time`.
- **Eleven indirect dependencies** provide cryptographic primitives (`x/crypto`), YAML parsing (`yaml.v3`), and QUIC headers (`qpack`).
- The `apernet/quic-go` fork at `v0.59.1-0.20260425001925-6c6cc9bcb716` provides the customized transport layer essential to Hysteria 2's performance.
- Rate limiting via `golang.org/x/time` and experimental generic utilities via `golang.org/x/exp` enable the core's traffic shaping capabilities.
- Consumer applications import `github.com/apernet/hysteria/core/v2/core/client` or `core/server` to transitively pull in the required networking and crypto libraries.

## Frequently Asked Questions

### What is the most critical dependency for Hysteria's performance?

**`github.com/apernet/quic-go`** is the most critical dependency. This customized fork of `quic-go` (`v0.59.1-0.20260425001925-6c6cc9bcb716`) provides the underlying QUIC transport with modifications specific to Hysteria's congestion control algorithms, enabling the protocol to achieve higher throughput over lossy networks compared to standard TCP or unmodified QUIC implementations.

### Does the core module require CGO or OS-specific libraries?

No. The core module relies purely on Go standard library extensions (`golang.org/x/*`) and pure-Go implementations of QUIC and cryptography. The `golang.org/x/sys` package provides OS-specific wrappers, but these are implemented in Go assembly and do not require external C libraries or CGO, making the core module highly portable across Linux, macOS, Windows, and BSD systems.

### How does the core module handle configuration file parsing?

The core module uses **`gopkg.in/yaml.v3`** to parse YAML configuration files. In [`core/server/config.go`](https://github.com/apernet/hysteria/blob/main/core/server/config.go), the `server.LoadConfigFile` function unmarshals server settings from disk into Go structs. This is an indirect dependency pulled in by the server configuration logic, meaning consumers who programmatically configure the client without YAML files can avoid importing the YAML parser at runtime.

### Are the dependencies audited for security vulnerabilities?

According to the `apernet/hysteria` source code, the project pins specific versions of all dependencies in `core/go.mod` via Go modules, ensuring reproducible builds. The use of `go.uber.org/goleak` in the test suite helps validate that the core module does not leak goroutines, a common class of resource exhaustion vulnerabilities in network servers. Developers integrating the core module should run `go mod verify` and monitor the `golang.org/x/crypto` version for security updates.