diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md index b152d4541b9..705fa28adc0 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md @@ -239,6 +239,50 @@ Invoke-RestMethod -Method Post -ContentType 'application/cloudevents+json' -Body {{< /tabpane >}} +### Publish binary CloudEvents + +In binary mode, the transport payload only contains the event body, while +CloudEvent attributes are supplied via transport metadata that begins with the +`ce_` prefix (HTTP headers, Kafka headers, NATS headers, and so on). This is +useful when you already produce binary mode events or you want to send arbitrary +binary data without wrapping it in an additional JSON envelope. + +To publish a binary CloudEvent to Dapr (via HTTP/gRPC publish APIs or directly +into a broker that Dapr reads from): + +1. Set the transport’s native content-type metadata (for example the HTTP + `Content-Type` header or a Kafka `content-type` message header) to the MIME + type that represents binary data, which is `application/octet-stream`. + +2. Add the required CloudEvent attributes (`ce_specversion`, `ce_type`, + `ce_source`, `ce_id`) as transport metadata. Optional attributes such as + `ce_subject`, `ce_time`, or `ce_traceparent` are also honored. + +3. Send the payload bytes in the message body. + +Dapr reconstructs the CloudEvent envelope from those metadata values, adds any +missing tracing metadata (for example `traceid`, `traceparent`, `tracestate`, +`topic`, and `pubsubname`), and delivers the message to subscribers in the same +way as a structured CloudEvent. This applies equally to HTTP producers as well +as to brokers like Kafka that persist headers alongside payloads. + +{{% tab "HTTP API (Bash)" %}} + +Publish a Binary CloudEvent to orders toipic: + +```bash +curl -X POST http://localhost:3500/v1.0/publish/order-pub-sub/orders \ + -H "Content-Type: application/octet-stream" \ + -H "ce_specversion: 1.0" \ + -H "ce_type: com.example.order.created" \ + -H "ce_source: urn:example:/checkout" \ + -H "ce_id: 2a8bbf52-1222-4c2c-85f0-8a8875c7bc10" \ + -H "ce_subject: orders/100" \ + --data-binary $'\x01\x02\x03\x04' +``` + +{{% /tab %}} + ## Event deduplication When using cloud events created by Dapr, the envelope contains an `id` field which can be used by the app to perform message deduplication. Dapr does not handle deduplication automatically. Dapr supports using message brokers that natively enable message deduplication. diff --git a/daprdocs/content/en/reference/api/pubsub_api.md b/daprdocs/content/en/reference/api/pubsub_api.md index d2cc67ab03e..f09b549c851 100644 --- a/daprdocs/content/en/reference/api/pubsub_api.md +++ b/daprdocs/content/en/reference/api/pubsub_api.md @@ -300,6 +300,28 @@ HTTP Status | Description 404 | error is logged and all messages are dropped other | warning is logged and all messages to be retried +#### CloudEvents binary mode + +Supports publishing CloudEvents that use the binary mode defined by +the CloudEvents HTTP binding. In this mode, the HTTP body only contains the +payload bytes, and CloudEvent attributes are passed as headers with the `ce_` +prefix. Provide the required headers (`ce_specversion`, `ce_type`, `ce_source`, +`ce_id`) along with any optional ones (for example `ce_subject` or `ce_time`). +Dapr copies the HTTP `Content-Type` header into the CloudEvent's +`datacontenttype` attribute and forwards the resulting event to subscribers. + +Example sending four raw bytes: + +```bash +curl -X POST http://localhost:3500/v1.0/publish/pubsubName/deathStarStatus \ + -H "Content-Type: application/octet-stream" \ + -H "ce_specversion: 1.0" \ + -H "ce_type: com.example.deathstar.status.changed" \ + -H "ce_source: urn:example:/deathstar" \ + -H "ce_id: 3a58b9b8-24d2-4f62-84f4-6177c2fe0633" \ + --data-binary $'\x01\x02\x03\x04' +``` + ## Message envelope Dapr pub/sub adheres to [version 1.0 of CloudEvents](https://github.com/cloudevents/spec/blob/v1.0/spec.md).