Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (108 loc) · 4.53 KB

CONTRIBUTING.md

File metadata and controls

135 lines (108 loc) · 4.53 KB
Raw

Contributing to Quick-

Project Overview

QUICK- is a TCP-over-QUIC traffic accelerator optimized for satellite networks (LEO/MEO/GEO). The production implementation is Rust, using Cloudflare's quiche library for QUIC with BBR/BBR2 congestion control.

Repository Structure

Quick-/
├── Cargo.toml              # Workspace manifest
├── Cargo.lock
├── rust-toolchain.toml
├── deny.toml               # cargo-deny config
├── Dockerfile              # Production image
├── Dockerfile.e2e          # E2E test image
├── bins/
│   ├── quick-entry/        # TCP -> QUIC proxy (entry point)
│   └── quick-exit/         # QUIC -> TCP proxy (exit point)
├── crates/
│   ├── quick-transport/    # QUIC client+server, BBR2, GSO/GRO
│   ├── quick-fec/          # Reed-Solomon FEC (plugin)
│   ├── quick-kcp/          # KCP ARQ fallback (plugin)
│   ├── quick-protocol/     # Wire protocol (StreamHeader v1)
│   ├── quick-config/       # TOML config schema
│   ├── quick-reload/       # Hot-reload API + SIGHUP
│   ├── quick-container/    # Dependency injection factory
│   ├── quick-metrics/      # Prometheus metrics (plugin)
│   ├── quick-logging/      # Structured logging, SSE (plugin)
│   ├── quick-dpi/          # Deep Packet Inspection (plugin)
│   ├── quick-dpi-storage/  # PostgreSQL DPI persistence
│   └── quick-core/         # Buffer pools, shutdown, timing
├── tests/                  # E2E tests and benchmarks
├── configs/                # TOML configs and satellite profiles
├── benchmarks/             # Comparative benchmark suite
├── deployments/            # Docker, systemd, validation
├── docs/                   # Documentation
├── infra/                  # CI runner infrastructure
├── scripts/                # Utility scripts
├── .github/workflows/      # CI/CD pipelines
├── rnd/                    # R&D implementations (read-only)
│   ├── quiche-google/      # C++ (Bazel)
│   └── msquic/             # C
└── archives/               # Historical code
    ├── go-implementation/  # Original Go prototype
    └── quic-go-implementation/

Branch Naming

  • feat/issue-{N}-short-desc -- New features
  • fix/issue-{N}-short-desc -- Bug fixes
  • refactor/short-desc -- Refactoring
  • docs/short-desc -- Documentation only
  • test/short-desc -- Test additions
  • ci/short-desc -- CI/CD changes
  • perf/short-desc -- Performance improvements

Commit Messages

Format: type(scope): description

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

Scope: crate name or area (transport, fec, ci, config, deploy, etc.)

Rules:

  • Keep subject line under 72 characters
  • Reference issues: Fixes #N or Refs #N
  • Use imperative mood: "add feature" not "added feature"
  • No emojis, no Co-Authored-By lines

Examples:

feat(transport): add BBR3 congestion control support
fix(fec): correct Reed-Solomon decode for burst losses
ci: update cache paths for root-level workspace
docs(config): document satellite profile parameters

PR Workflow

  1. Branch from main
  2. One logical change per PR
  3. All CI checks must pass (cargo build, cargo test, cargo clippy)
  4. Squash or merge commit (preserve meaningful history)
  5. Delete branch after merge

Build and Test

# Build
cargo build --release

# Test
cargo test

# Lint
cargo clippy --all-features --all-targets -- -D warnings

# Format check
cargo fmt --all -- --check

# Security audit
cargo audit
cargo deny check

# E2E tests (Docker, requires privileged mode)
docker build -f Dockerfile.e2e -t quick-e2e .
docker run --rm --privileged quick-e2e leo

Satellite Profiles

QUICK- supports network profiles for different orbital scenarios:

Profile RTT Use Case
terrestrial ~5ms Baseline, no satellite optimization
leo ~50ms Starlink, OneWeb
meo ~250ms O3b, SES
geo ~600ms Eutelsat, Inmarsat

Feature Flags

The workspace uses Cargo feature flags to control optional functionality:

  • quiche-backend (default) -- Cloudflare quiche QUIC backend
  • quinn-backend -- Pure Rust Quinn QUIC backend
  • fec -- Reed-Solomon Forward Error Correction
  • kcp -- KCP ARQ fallback transport
  • metrics -- Prometheus metrics endpoint
  • logging -- Structured logging + SSE
  • dpi -- Deep Packet Inspection
  • dpi-storage -- PostgreSQL DPI persistence