Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
156 lines (105 loc) · 2.79 KB

DEVELOPMENT.md

File metadata and controls

156 lines (105 loc) · 2.79 KB

Hackney Development Guide

This guide covers development setup, testing, and contributing to hackney.

Prerequisites

  • Erlang/OTP 27 or later
  • rebar3 3.24.0 or later

Platform-specific requirements

macOS:

brew install erlang

Ubuntu/Debian:

sudo apt-get install erlang build-essential

FreeBSD:

pkg install erlang-runtime28 rebar3

Building

Clone the repository:

git clone https://github.com/benoitc/hackney.git
cd hackney

Build the project:

rebar3 compile

This will compile all Erlang source files and fetch dependencies (including the pure Erlang QUIC library for HTTP/3 support).

Running Tests

Run all tests:

rebar3 eunit

Run specific test modules:

rebar3 eunit --module=hackney_quic_tests
rebar3 eunit --module=hackney_http3_tests

Running tests with httpbin

Some tests require the httpbin server. Start it before running tests:

pip3 install httpbin gunicorn
gunicorn -b 127.0.0.1:8000 httpbin:app &
rebar3 eunit

Local Docker Testing

A Dockerfile is provided for testing on Linux locally, which mirrors the GitHub CI environment.

Building the Docker image

docker build -f Dockerfile.test -t hackney-test .

Running tests in Docker

Run all tests:

docker run --rm hackney-test

Run specific test modules:

docker run --rm hackney-test bash -c "rebar3 eunit --module=hackney_quic_tests"

Interactive debugging in Docker

Start an interactive shell:

docker run --rm -it hackney-test bash

Then you can:

  • Run tests manually: rebar3 eunit
  • Start an Erlang shell: rebar3 shell

QUIC/HTTP3 Development

HTTP/3 support uses a pure Erlang QUIC implementation from the quic dependency.

Source Files

  • src/hackney_quic.erl - QUIC/HTTP3 transport wrapper
  • src/hackney_qpack.erl - QPACK header compression
  • src/hackney_h3.erl - HTTP/3 high-level API

The underlying QUIC implementation is in the quic dependency which provides:

  • TLS 1.3 handshake
  • QUIC packet encoding/decoding
  • Congestion control
  • Loss recovery

Code Style

Erlang

  • Follow standard Erlang conventions
  • Use edoc for function documentation
  • Keep lines under 100 characters

Submitting Changes

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make your changes
  4. Run tests locally and in Docker
  5. Commit with clear messages
  6. Push and create a pull request

Commit Message Format

type: short description

Longer description if needed.

Types: fix, feat, docs, test, refactor, ci, chore

Continuous Integration

CI runs on:

  • Linux x86_64 (OTP 27.2, 28.0)
  • Linux ARM64 (OTP 27.2)
  • macOS ARM64 (OTP 27)
  • FreeBSD 14.2 (OTP 28)

All CI jobs must pass before merging.