Skip to content

EPIC 1669 SI-34: Consolidate duplicate HTTP types into http-protocol #1965

Description

@josecelano

Parent EPIC: #1669 — Overhaul: Packages
EPIC spec: docs/issues/open/1669-overhaul-packages/EPIC.md

Goal

Eliminate duplicate HTTP request/response type definitions across the workspace by consolidating them into packages/http-protocol, and add the http-protocol dependency to tracker-client so both consumers import from a single source of truth.

Background

Three crate locations define overlapping HTTP request and response types:

  1. packages/http-protocol/src/v1/{requests,responses}/ — server-side protocol parsing (production library)
  2. packages/axum-http-server/tests/server/{requests,responses}/ — test helpers (test-only code)
  3. packages/tracker-client/src/http/client/{requests,responses}/ — tracker client library (production library)

Locations (2) and (3) define their own copies of types that semantically belong in (1):

  • axum-http-server has http-protocol as a dependency, but its tests define their own types instead of using it
  • tracker-client does not depend on http-protocol at all

The duplication creates maintenance burden: any change to these types must be replicated in two or three places. Several types (especially Error, Compact, CompactPeer, CompactPeerList, scrape Query/QueryBuilder/QueryParams, ByteArray20, InfoHash, percent_encode_byte_array) are byte-for-byte identical between locations (2) and (3).

The http-protocol crate is the canonical home for HTTP tracker protocol types. Client-side parsing/serialization types are a natural extension of this crate, not a separate concern.

Scope

In Scope

  • Add client-side request construction and response deserialization types to packages/http-protocol (e.g., query builders, response structs with serde_bencode derives)
  • Replace duplicate types in packages/axum-http-server/tests/server/ with imports from http-protocol
  • Replace duplicate types in packages/tracker-client/src/http/client/ with imports from http-protocol
  • Add http-protocol as a dependency of tracker-client
  • Create a use-tracker-client skill in .github/skills/usage/ capturing the manual verification learnings
  • Verify all tests pass and no functionality regresses

Out of Scope

  • Merging packages/http-protocol with other protocol crates
  • Changing the public API of http-protocol beyond what's needed for consolidation
  • Removing or refactoring the server-side types in http-protocol
  • Changing how axum-http-server production code uses http-protocol

References

  • Spec: docs/issues/drafts/1669-si-34-consolidate-duplicate-http-types-into-http-protocol.md
  • Parent EPIC: #1669
  • Decisions log: docs/issues/open/1669-overhaul-packages/DECISIONS.md
  • Related ADR: docs/adrs/20260527175600_keep_protocol_and_domain_types_decoupled.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions