diff --git a/docs/docs/en/getting-started/publishing/index.md b/docs/docs/en/getting-started/publishing/index.md index 412c65a57f3..a85d082fd1f 100644 --- a/docs/docs/en/getting-started/publishing/index.md +++ b/docs/docs/en/getting-started/publishing/index.md @@ -40,6 +40,34 @@ Content-Type can be: By the way, you can use `application/json` for all of your messages if they are not raw bytes. You can even omit using any header at all, but it makes serialization slightly slower. +### Raw Bytes + +`bytes` are the one payload **FastStream** doesn't touch: the body is sent as-is and **no content type is set**, because the framework can't know what those bytes are (**Kafka** and **NATS** send an empty `content-type` header, the other brokers send none). The same applies to a `#!python @broker.publisher(...)` handler that returns `bytes`. + +```python +await broker.publish(b"\x89PNG...", "images") +``` + +If the consumer needs to know the format, say so yourself through the message headers: + +```python +await broker.publish( + b"\x89PNG...", + "images", + headers={"content-type": "image/png"}, +) +``` + +**RabbitMQ** carries the content type as an AMQP message property instead of a header, so `RabbitBroker` and its publishers take it as a dedicated `content_type` argument: + +```python +await broker.publish(b"\x89PNG...", "images", content_type="image/png") +``` + +**MQTT** keeps the content type in a message property as well, and `MQTTBroker` has no argument to set it yet: a `content-type` entry in `headers` becomes a plain user property, so the consumer gets the bytes without a content type. + +On the receiving side, a handler annotated with `#!python body: bytes` gets the raw payload in both cases. Without a `content-type` header **FastStream** first tries to parse the body as JSON and falls back to the raw bytes if that fails, and with an unknown one (anything but `text/plain` and `application/json`) it hands the bytes over untouched. + ## Correlation ID By default, **FastStream** generates a random UUID4 string for `correlation_id` whenever a `#!python publish(...)`/`#!python request(...)` call doesn't set one explicitly.