Feature Proposal: Payload Encoding

[o-nnerb]

Overview

Adds PayloadEncoder, a public protocol that lets consumers plug in their own serialization format (e.g. Protobuf, MessagePack) for Payload, the same way Payload(_:encoder:contentType:) already does today for Encodable + JSONEncoder.

API

public protocol PayloadEncoder: Sendable {
    var contentType: ContentType { get }
    func encode<T: Sendable>(_ value: T) throws -> Data
}

extension Payload {
    public init<T: Sendable, Encoder: PayloadEncoder>(
        _ value: T,
        encoder: Encoder,
        contentType: ContentType? = nil
    )
}

Usage:

struct ProtobufPayloadEncoder: PayloadEncoder {
    var contentType: ContentType = .init("application/x-protobuf")

    func encode<T: Sendable>(_ value: T) throws -> Data {
        guard let message = value as? SwiftProtobuf.Message else {
            throw EncodingPayloadError.invalidValue
        }
        return try message.serializedData()
    }
}

Payload(myProtoMessage, encoder: ProtobufPayloadEncoder())

Scope decisions

• Value serialization only — no .file(URL) source. PayloadEncoder turns a typed Swift value into Data. Sending an existing file verbatim is already covered by Payload(url:contentType:). A serializer (Protobuf/MessagePack) never operates on an arbitrary file the way a byte-transform (gzip, encryption) would; an earlier draft tried a single PayloadSource<T> enum with both a .value(T) and a .file(URL) case to cover both, but the file case ended up carrying a meaningless generic T. That was the signal the two concerns don't belong in the same protocol.
• No chunked/streaming encode. A single Protobuf/MessagePack message is an atomic blob — there's no meaningful "encode this message in pieces" the way compressing a byte stream is. RequestBody already streams whatever Data this produces to the wire in chunks on its own (Internals.StreamWriterSequence), so nothing is lost by keeping encode a plain, one-shot throws -> Data.
• Compression / encryption are explicitly out of scope here. Those are byte-level transforms (HTTP's own Content-Encoding, orthogonal to Content-Type), not value serializers — mixing them into PayloadEncoder is what produced the awkward shape above. A genuinely streamed transform needs its own protocol (progressive output, not -> Data) and its own proposal; tracked separately and does not block this one.

Milestone: 4.1.0

[o-nnerb]

Scope defined — description above updated with the concrete PayloadEncoder API (pluggable value serialization, e.g. Protobuf/MessagePack).

Two things worth calling out that were deliberately left out of this proposal:

• A .file(URL) source — sending an existing file already has Payload(url:contentType:), and a value serializer doesn't operate on files the way a byte-transform would.
• Chunked/streamed encode — a single serialized message is atomic, and RequestBody already streams the resulting Data to the wire in chunks on its own.

Compression/encryption (byte-level transforms, not value serializers) stay out of scope for this proposal and would need their own streaming-shaped protocol if pursued later.

Milestone moved to 4.1.0.

[o-nnerb]

Implemented in #265 — PayloadEncoder available in main. Closing as resolved.