Feature Proposal: cURL Description

[o-nnerb]

Overview

Full, bidirectional cURL support — not just a description string. Two new pieces:

1. CURLTask(String) — parse a cURL command line and execute it directly as a request.
2. .cURLDescription() on DataTask/DownloadTask/UploadTask — produce the cURL command line equivalent to a declared request, built with per-property fidelity rather than reconstructed after the fact.

Direction 1 — CURLTask(String).result()

@PropertyBuilder/Property composition is meant for compile-time trees, not for building one dynamically from a parsed string at runtime. So CURLTask doesn't route through the Property graph at all: it parses the string and constructs a RequestConfiguration directly — RequestDL's own module code can freely populate its internal(set) properties — then hands it straight to Internals.Session.execute(...), bypassing Resolve entirely.

"Total support" for curl (~250 flags across scripting/protocols/retries/etc.) isn't a realistic or useful target. Scoping the parser to a documented common subset, with everything else explicitly rejected rather than silently ignored:

• -X / --request
• -H / --header (repeatable)
• -d / --data / --data-raw / --data-binary
• -F / --form (repeatable)
• -u / --user (basic auth)
• --url, plus a bare trailing URL
• -G / --get (turns -d into query items)

Out of scope for v1: redirect-following flags, cookie jars, --resolve, HTTP/3, non-http(s) schemes, TLS/proxy flags (-k, --cacert, -x). Shell-quoting rules (the usual \'-escapes and $'...' ANSI-C quoting seen in "copy as cURL" output from browser devtools) need to be handled by the tokenizer, but only for arguments — not full POSIX shell semantics (no variable expansion, no command substitution).

Direction 2 — .cURLDescription()

Rather than serializing the already-resolved RequestConfiguration after the fact (which loses structure — a multipart body, by the time it's just RequestConfiguration.body, is already flattened into one byte stream with a boundary, so it could only be reproduced as a single --data-binary blob, not per-field -F flags), this builds the cURL string during the same graph walk every property already participates in:

• A CURLEncoder (reference type) becomes a new key on RequestEnvironmentValues, same pattern \.logger already uses (LoggerEnvironmentKey.swift).
• .cURLDescription() injects a fresh encoder via the existing .environment(_:_:) modifier mechanism.
• Each relevant PropertyNode.make(_ make: inout Make) (BaseURL, Headers, Query, Payload/Form, Authorization, ...) gets a small addition: after doing its real work, check RequestEnvironmentValues.current.curlEncoder and, if present, append its own fragment — Form's node appends one -F "field=value" per field, before those fields are ever flattened into multipart bytes. This works with zero changes to Make's shape, because RequestEnvironmentValues.current is already a task-local, readable from inside any make() call today.
• RawTask gets a second method alongside .result() that calls Resolve(root:environment:).partiallyBuild() — the lighter internal variant that walks the tree and populates Make without constructing a real Internals.Session or resolving the system proxy, neither of which is needed just to describe a request. It then reads back the accumulated string from the encoder instead of touching the network.
• The encoder assembles fragments into a canonical flag order (-X, url, -Hs, -Fs/-d) at description time, rather than in graph-visitation order, since @PropertyBuilder declaration order isn't necessarily the order flags should print in.

This is a cross-cutting addition, not a single new file — every property type that should be curl-representable needs its own small contribution. It can be built incrementally: start with BaseURL, Headers, Query, Payload, Authorization, extend to others later. TLS/proxy/session-level flags on this direction are deferred the same way as direction 1.

Milestone: 4.3.0

[o-nnerb]

Repurposed this from a simple description helper into full bidirectional cURL support: CURLTask(String) to parse and execute a cURL command directly, and .cURLDescription() on the existing task types to go the other way, built with per-property fidelity (a CURLEncoder threaded through the task-local RequestEnvironmentValues, so each property contributes its own flag during the same resolution pass, rather than reconstructing one after the fact and losing structure on things like multipart bodies). Both directions are scoped to a documented common subset of curl flags, not full coverage. Ready to be picked up as an implementation task.

[o-nnerb]

Implemented in #320 — both directions from the proposal:

• CURLTask(String) parses a curl command line and performs it as a request, built directly against RequestConfiguration (bypassing @PropertyBuilder) but still routed through the same RawTask/Resolve pipeline DataTask uses, so caching/tracing/executor requirements apply the same way.
• TaskDescriptor + .description(_:) on DataTask/DownloadTask/UploadTask — a generic mechanism (mirroring RequestTaskModifier/RequestTaskInterceptor) for describing a resolved request without performing it, with CURLTaskDescriptor (.cURL) as the built-in conformance. Form fields round-trip individually as -F flags via TaskDescriptorContext, captured before FormNode flattens them into the multipart body — the one place a resolved RequestConfiguration alone can't be read back from.

Both directions cover the flag subset from the proposal (-X, -H, -d/--data-raw/--data-binary, -F, -u, --url, -G) plus the session-level flags that turned out to matter for real fidelity: -L/--max-redirs, -k, -x/--proxy, --resolve, --compressed, --cacert, --cert/-E/--key — wired into the same Session/SecureConnection/Proxy machinery a declared request already reaches. Cookie jars, HTTP/3, and non-http(s) schemes stay out of scope, documented in <doc:CURL-support> along with why.

Closing this out — further review happens on the PR.