Is Hysteria Core Open-Source and How to Contribute to the Project

Yes, Hysteria's core library is fully open-source under the MIT license, and contributions are welcomed through GitHub pull requests following the standard fork-and-PR workflow.

The Hysteria 2 project, maintained by the Aperture Network in the apernet/hysteria repository, provides a high-performance network proxy and tunneling tool written entirely in Go. Its core implementation is publicly viewable, permissively licensed, and designed for community contributions, with the entire protocol stack residing in the core/ directory.

License and Open Source Status

The Hysteria core is released under the MIT license, a permissive open-source license that allows reuse, modification, and distribution in both open and closed-source projects. You can find the full license text in [core/LICENSE.md](https://github.com/apernet/hysteria/blob/master/core/LICENSE.md).

Unlike proprietary solutions, Hysteria contains no hidden binaries or obfuscated code. The implementation relies entirely on pure Go and the open-source quic-go library (also MIT-licensed), making it fully auditable and modifiable.

Core Architecture Overview

The Hysteria architecture splits functionality into four main components within the core/ directory:

Server Implementation

The server component listens for incoming QUIC connections, performs the Hysteria authentication handshake, and proxies TCP/UDP streams. Key files include:

• [core/server/server.go](https://github.com/apernet/hysteria/blob/master/core/server/server.go): Contains the main server implementation with the NewServer() constructor and Serve() method.
• [core/server/config.go](https://github.com/apernet/hysteria/blob/master/core/server/config.go): Defines the Config struct for server initialization.

Client Implementation

The client initiates QUIC connections, runs authentication handshakes, and exposes proxy methods:

• [core/client/client.go](https://github.com/apernet/hysteria/blob/master/core/client/client.go): Implements NewClient() and connection methods like TCP() and UDP().
• [core/client/config.go](https://github.com/apernet/hysteria/blob/master/core/client/config.go): Configuration structures for client instances.

Protocol and Utilities

These files handle the Hysteria protocol specifics:

• [core/internal/protocol/http.go](https://github.com/apernet/hysteria/blob/master/core/internal/protocol/http.go): HTTP-based authentication header encoding/decoding.
• [core/internal/utils/qstream.go](https://github.com/apernet/hysteria/blob/master/core/internal/utils/qstream.go): Wrapper for QUIC streams implementing net.Conn-like semantics.

Congestion Control

Pluggable algorithms for QUIC connection management:

• [core/internal/congestion/bbr/bbr_sender.go](https://github.com/apernet/hysteria/blob/master/core/internal/congestion/bbr/bbr_sender.go): BBR congestion-control implementation.
• [core/internal/congestion/brutal/brutal.go](https://github.com/apernet/hysteria/blob/master/core/internal/congestion/brutal/brutal.go): "Brutal" hard-limit congestion controller.

How to Contribute to Hysteria

Contributing to Hysteria follows the standard GitHub workflow. Here is the step-by-step process:

1. Fork the repository on GitHub and clone your fork locally:

   git clone https://github.com/<your-username>/hysteria.git
   cd hysteria

2. Set up the development environment:

   • Install Go 1.22 or newer (required for module support).
   • The project uses a go.work workspace file that pulls together the core and app modules.
   • Run go mod tidy to fetch dependencies including quic-go.

3. Run the test suite to ensure baseline functionality:

   go test ./...

   This executes all unit and integration tests defined in the core package, matching the CI workflow in [.github/workflows/test.yml](https://github.com/apernet/hysteria/blob/master/.github/workflows/test.yml).

4. Make your changes in the core/ directory:

   • Add features or fixes while keeping the public API stable for exported types in client and server packages.
   • Follow existing coding style (gofmt, golint-compatible naming).
   • Maintain import ordering consistency using goimports.

5. Update tests to cover new behavior, ensuring your changes pass the existing test suite.

6. Document your code with comments for any new exported symbols, as these are rendered by godoc.

7. Commit with clear messages:

   git commit -m "feat: add X congestion controller"

8. Submit a Pull Request:

   • Push your branch to your fork: git push origin my-feature.
   • Open a PR against apernet/hysteria:master.
   • Follow the PR template in .github/PULL_REQUEST_TEMPLATE.md describing your changes and testing performed.

Maintainers will run CI checks automatically. Address any reviewer comments, and once approved, your PR will be merged via the release workflow defined in [.github/workflows/release.yml](https://github.com/apernet/hysteria/blob/master/.github/workflows/release.yml).

Working with the Core Library

The following examples demonstrate how to use Hysteria core in your own Go applications.

Server Example

// server_example.go
package main

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

func main() {
    cfg := &server.Config{
        // Minimal config – TLS cert/key must be provided in a real deployment
        TLSConfig: server.TLSConfig{
            Certificates: []tls.Certificate{/* ... */},
        },
        // Enable UDP for demonstration
        DisableUDP: false,
    }
    s, err := server.NewServer(cfg)
    if err != nil {
        log.Fatalf("server init: %v", err)
    }
    log.Println("Hysteria server listening…")
    if err = s.Serve(); err != nil {
        log.Fatalf("serve error: %v", err)
    }
}

Client Example

// client_example.go
package main

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

func main() {
    cfg := &client.Config{
        ServerAddr: &net.UDPAddr{IP: net.ParseIP("1.2.3.4"), Port: 443},
        Auth:       "my-secret",
    }
    c, handshake, err := client.NewClient(cfg)
    if err != nil {
        log.Fatalf("client init: %v", err)
    }
    log.Printf("handshake: UDP enabled=%v, Tx=%d", handshake.UDPEnabled, handshake.Tx)
    
    conn, err := c.TCP("example.com:80")
    if err != nil {
        log.Fatalf("TCP error: %v", err)
    }
    defer conn.Close()
}

Summary

• Hysteria core is fully open-source under the MIT license, located in the core/ directory of the apernet/hysteria repository.
• Architecture comprises Server, Client, Protocol utilities, and pluggable Congestion Control components.
• Contributions require Go 1.22+, passing tests via go test ./..., and adherence to the PR template.
• Public API stability is maintained for client and server packages; breaking changes require version bumps.
• License compatibility requires any new dependencies to also be permissively licensed (MIT/BSD).

Frequently Asked Questions

What open source license covers Hysteria core?

Hysteria core is released under the MIT license, a permissive license allowing free use, modification, and distribution in both open and proprietary projects. The full text is available in [core/LICENSE.md](https://github.com/apernet/hysteria/blob/master/core/LICENSE.md).

What version of Go is required to build and contribute to Hysteria?

You need Go 1.22 or newer to build the project and run the test suite. The project uses Go modules, which automatically manage dependencies like quic-go when you run go mod tidy.

How do I run the test suite before submitting a contribution?

Execute go test ./... from the repository root. This command runs all unit and integration tests in the core package, replicating the checks performed by the CI workflow defined in [.github/workflows/test.yml](https://github.com/apernet/hysteria/blob/master/.github/workflows/test.yml).

Can the Hysteria core library be used in commercial applications?

Yes. The MIT license explicitly permits commercial use, distribution, and modification. Since the core is pure Go with no hidden binaries, you can integrate it into commercial products following the license attribution requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}