From 60d8ab79d8a0a374c11cdd0bb4070de009d60b74 Mon Sep 17 00:00:00 2001 From: adam shamis Date: Tue, 11 Nov 2025 13:58:03 +0200 Subject: [PATCH 1/3] Added bianry cloudevent exmaples and explanation Signed-off-by: adam shamis --- .../pubsub/pubsub-cloudevents.md | 44 +++++++++++++++++++ .../content/en/reference/api/pubsub_api.md | 22 ++++++++++ 2 files changed, 66 insertions(+) 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). From de42db4bfb5afcf785168ad0ee4138ca73748496 Mon Sep 17 00:00:00 2001 From: adam shamis Date: Wed, 19 Nov 2025 14:36:35 +0200 Subject: [PATCH 2/3] tabpane line was missing Signed-off-by: adam shamis --- .../building-blocks/pubsub/pubsub-cloudevents.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 705fa28adc0..150efccd52f 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 @@ -260,11 +260,7 @@ into a broker that Dapr reads from): 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. +{{< tabpane text=true >}} {{% tab "HTTP API (Bash)" %}} @@ -283,6 +279,8 @@ curl -X POST http://localhost:3500/v1.0/publish/order-pub-sub/orders \ {{% /tab %}} +{{< /tabpane >}} + ## 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. From 690cc380a41dbe4407c420f364de1443da25562d Mon Sep 17 00:00:00 2001 From: adam shamis Date: Wed, 19 Nov 2025 14:37:55 +0200 Subject: [PATCH 3/3] topic was misproununced Signed-off-by: adam shamis --- .../building-blocks/pubsub/pubsub-cloudevents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 150efccd52f..cf4dd6b800c 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 @@ -264,7 +264,7 @@ into a broker that Dapr reads from): {{% tab "HTTP API (Bash)" %}} -Publish a Binary CloudEvent to orders toipic: +Publish a Binary CloudEvent to orders topic: ```bash curl -X POST http://localhost:3500/v1.0/publish/order-pub-sub/orders \