Feature Proposal: Default PayloadEncoder via Environment

[o-nnerb]

Overview

Follow-up to #196 (implemented in #265). That proposal added Payload(_:encoder:contentType:), which takes a PayloadEncoder per call site. This proposes a way to set a default encoder once, mirroring how .charset(_:) and .urlEncoder(_:) already work for Payload — so a request tree (or a shared Property wrapper reused across an app) can default to Protobuf/MessagePack without repeating encoder: at every Payload(...) call site.

API

extension Property {
    public func payloadEncoder<Encoder: PayloadEncoder>(_ encoder: Encoder) -> some Property
}

Usage:

DataTask {
    BaseURL("apple.com")
    RequestMethod(.post)
    Payload(myProtoMessage, encoder: nil)   // falls back to the environment
}
.payloadEncoder(ProtobufPayloadEncoder())

Design note: encoder: needs to stay non-defaulted

The obvious-looking shape is:

public init<Value: Sendable>(
    _ value: Value,
    encoder: (any PayloadEncoder)? = nil,
    contentType: ContentType? = nil
)

But giving encoder a = nil default reopens overload resolution on the already-shipped Payload(_:encoder:contentType:) for Encodable: Payload(mock) — the single most common call site, used throughout every existing app — would become ambiguous between the Encodable + JSONEncoder initializer and this one, since both would be fully satisfied by zero extra arguments. That breaks source compatibility for anyone calling Payload(_:) on a Codable & Sendable value today.

Keeping encoder required but nilable (no default value) avoids that:

public init<Value: Sendable>(
    _ value: Value,
    encoder: (any PayloadEncoder)?,
    contentType: ContentType? = nil
)

• Payload(mock) — still resolves to the existing Encodable initializer, unchanged.
• Payload(myProtoMessage, encoder: ProtobufPayloadEncoder()) — explicit encoder, same as Feature Proposal: Payload Encoding #196.
• Payload(myProtoMessage, encoder: nil) — falls back to .payloadEncoder(_:) from the environment; throws EncodingPayloadError (a new context, e.g. .missingPayloadEncoder) if none was set.

It costs one extra , encoder: nil at the call site compared to the fully-implicit version, but every existing Payload(codableValue) call keeps compiling exactly as it does today — nothing about the Encodable/JSONEncoder initializer changes.

Where the fallback gets resolved

Same place charset/urlEncoder already get read off the environment: Payload._makeProperty(property:inputs:) has access to inputs.environment. PayloadEncoderFactory would carry the explicit encoder when one is passed, and otherwise defer to inputs.environment.payloadEncoder — the same plumbing PayloadInput.charset/.urlEncoder already use.

Scope decisions

• No implicit resolution for a fully bare Payload(_:) — that is exactly the ambiguity case above. The call site has to write encoder: nil to opt in explicitly.
• Doesn't touch the Encodable/JSONEncoder initializer at all — JSON stays the unaffected default.
• Same non-goals as Feature Proposal: Payload Encoding #196: no .file(URL) source, no chunked/streamed encode, compression/encryption out of scope.

Milestone: 4.1.0, alongside #196.

[o-nnerb]

Implementado em #273 — .payloadEncoder(_:) (environment-scoped default) disponível na main. Fechando como resolvido.