Feature Proposal: Extract Internals into a RequestDLInternals Target

[o-nnerb]

Overview

Split the current single, monolithic RequestDL target into two: a new RequestDLInternals target hosting everything currently under Sources/RequestDL/Internals/ (the execution engine wrapping AsyncHTTPClient/SwiftNIO — Client, Session, Buffers, Stream, Secure Connection, Cache, Storage, Logger, per CLAUDE.md's own module description), with RequestDL (Properties/Tasks/Request) depending on it. Files physically move to Sources/RequestDLInternals/.

Not exposed as a public product. RequestDLInternals stays a plain .target, not wrapped in a .library(...) product entry — external consumers of import RequestDL are completely unaffected; they can't import RequestDLInternals at all (SwiftPM only exposes declared products to external dependents), and RequestDL's own public API surface (Property, DataTask, HTTPHeaders, ResponseHead, etc.) is byte-for-byte unchanged. This is purely a structural refactor, not an API change.

Why

1. An enforced module boundary instead of a naming convention. Today, "Internals isn't public API" is a documented convention (CLAUDE.md: "Nothing here is public API; it's namespaced under the Internals enum"), not something the compiler checks — any file anywhere in Properties/Tasks/Request can freely reach into any internal detail of Internals, since it's all one target today. Splitting into a real target makes the actual dependency surface between "the execution engine" and "the declarative API" explicit: anything Properties/Tasks needs from Internals has to be deliberately marked public on RequestDLInternals, auditable at the Package.swift/access-control level instead of by convention alone.
2. Incremental build-time improvement. Right now the entire RequestDL target (Properties + Internals + Tasks + Request, everything under Sources/RequestDL/) is one compilation unit. A change to any Properties/Tasks file (the bulk of day-to-day public-API work) currently has no way to avoid touching the same build unit as Internals. Splitting them means Swift's build system only recompiles RequestDLInternals when its own files change or when RequestDL changes something it depends on — not on every unrelated Properties/Tasks edit.
3. Clean-build parallelism across the two targets is a secondary benefit, smaller than the incremental-build win above.

Mechanics

• Package.swift gains .target(name: "RequestDLInternals", dependencies: [...]), and the existing RequestDL target depends on it.
• Dependency list has to be split, not just moved wholesale: anything Internals-only (NIOSSL, NIOTransportServices, NIOHTTPCompression, SystemPackage, ...) moves to RequestDLInternals alone. Anything used directly by both sides has to stay declared on both targets — Logging is the clear example: Internals.Log/Internals.TaskLogger need it, but so does RequestDL's own public surface (Modifiers.Logger exposes Logging.Logger directly in its public API). A target's dependency list doesn't transitively re-export importability to a target that depends on it, so this has to be explicit on both sides.
• Real, but purely mechanical migration cost: everything in Internals that's implicitly internal today but actually used from Properties/Tasks/Request needs auditing and marking public on the new target. No logic changes — access-modifier changes only, across most of the Internals tree.

Test suite consequence — checked, not assumed

@testable import RequestDL currently appears in 183 test files, and 69 of those directly reference Internals. symbols — including a whole dedicated Tests/RequestDLTests/Internals/ subtree mirroring the source layout (per CLAUDE.md's "test files mirror the Sources/ directory layout 1:1" convention). After the split, @testable import RequestDL no longer gives access to RequestDLInternals's non-public details, since RequestDL only depends on RequestDLInternals rather than absorbing its internal-level symbols. So this needs a new RequestDLInternalsTests target, @testable import RequestDLInternals, with the existing Tests/RequestDLTests/Internals/ subtree moved over to match — mechanical, well-scoped, but real work to account for, not a hidden risk.

Out of scope

• Any change to RequestDL's public API — none intended or expected.
• Exposing RequestDLInternals as an importable product for other packages — deliberately not part of this proposal.

Milestone: 4.1.0

[o-nnerb]

Implementado em #280 — target RequestDLInternals separado, disponível na main. Fechando como resolvido.