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:
packages/http-protocol/src/v1/{requests,responses}/ — server-side protocol parsing (production library)
packages/axum-http-server/tests/server/{requests,responses}/ — test helpers (test-only code)
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
Goal
Eliminate duplicate HTTP request/response type definitions across the workspace by consolidating them into
packages/http-protocol, and add thehttp-protocoldependency totracker-clientso both consumers import from a single source of truth.Background
Three crate locations define overlapping HTTP request and response types:
packages/http-protocol/src/v1/{requests,responses}/— server-side protocol parsing (production library)packages/axum-http-server/tests/server/{requests,responses}/— test helpers (test-only code)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-serverhashttp-protocolas a dependency, but its tests define their own types instead of using ittracker-clientdoes not depend onhttp-protocolat allThe duplication creates maintenance burden: any change to these types must be replicated in two or three places. Several types (especially
Error,Compact,CompactPeer,CompactPeerList, scrapeQuery/QueryBuilder/QueryParams,ByteArray20,InfoHash,percent_encode_byte_array) are byte-for-byte identical between locations (2) and (3).The
http-protocolcrate 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
packages/http-protocol(e.g., query builders, response structs withserde_bencodederives)packages/axum-http-server/tests/server/with imports fromhttp-protocolpackages/tracker-client/src/http/client/with imports fromhttp-protocolhttp-protocolas a dependency oftracker-clientuse-tracker-clientskill in.github/skills/usage/capturing the manual verification learningsOut of Scope
packages/http-protocolwith other protocol crateshttp-protocolbeyond what's needed for consolidationhttp-protocolaxum-http-serverproduction code useshttp-protocolReferences
docs/issues/drafts/1669-si-34-consolidate-duplicate-http-types-into-http-protocol.mddocs/issues/open/1669-overhaul-packages/DECISIONS.mddocs/adrs/20260527175600_keep_protocol_and_domain_types_decoupled.md