POC CloudEvents - Padronização de Eventos

Objetivo

Demonstrar a viabilidade de adotar o padrão CloudEvents (CNCF) para padronizar a comunicação assíncrona entre serviços, independente da linguagem ou plataforma.

---

O que é CloudEvents?

CloudEvents é uma especificação da CNCF (Cloud Native Computing Foundation) que define um formato padrão para descrever eventos. É agnóstico a:

• Linguagem (C#, Node.js, Python, Java, Go, etc.)
• Transporte (HTTP, Kafka, AMQP, NATS, etc.)
• Cloud Provider (AWS, Azure, GCP, on-premises)

Atributos obrigatórios de um CloudEvent

Atributo	Tipo	Descrição
specversion	String	Versão da spec (atualmente 1.0)
id	String	Identificador único do evento
type	String	Tipo do evento (ex: com.example.order.created)
source	URI-ref	Origem do evento (quem produziu)

Atributos opcionais (mas recomendados)

Atributo	Tipo	Descrição
time	Timestamp	Quando o evento ocorreu
datacontenttype	String	MIME type do data (ex: application/json)
data	Any	Payload do evento
subject	String	Assunto do evento dentro do source

Extension Attributes

CloudEvents permite extensões customizadas para necessidades específicas:

{
  "correlationid": "order-123",
  "partitionkey": "order-123",
  "traceparent": "00-abc123-def456-01"
}

Extension	Propósito
correlationid	Rastreamento de fluxos distribuídos entre serviços
partitionkey	Roteamento/ordenação em brokers (Kafka, etc.)
traceparent	Integração com OpenTelemetry/Jaeger/Zipkin

---

Arquitetura da POC

                    ┌──────────────────────────┐
                    │     Producer C#          │
                    │     (ASP.NET :5001)      │
                    │                          │
                    │  order.created           │
                    │  order.shipped           │
                    └────────┬─────────────────┘
                             │
                             │  CloudEvents HTTP
                             │  (Structured Mode)
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│  Consumer C#     │ │ Consumer     │ │ Consumer Python  │
│  (ASP.NET :5002) │ │ Node.js      │ │ (Flask :8000)    │
│                  │ │ (Express     │ │                  │
│  Recebe QUALQUER │ │  :3002)      │ │ Recebe QUALQUER  │
│  CloudEvent      │ │              │ │ CloudEvent       │
└──────────────────┘ │ Recebe       │ └──────────────────┘
                     │ QUALQUER     │
                     │ CloudEvent   │
                     └──────────────┘

Ponto-chave: O producer C# envia o mesmo evento para 3 consumers em linguagens diferentes, demonstrando que:

• O mesmo CloudEvent produzido em C# é consumido corretamente por C#, Node.js e Python
• O formato é auto-descritivo — o consumer não precisa conhecer o producer previamente
• Os SDKs oficiais da CNCF garantem interoperabilidade entre linguagens

---

Exemplo de um CloudEvent (HTTP Structured Mode)

Quando o Producer C# envia um evento order.created, o HTTP request fica:

POST /api/events HTTP/1.1
Content-Type: application/cloudevents+json

{
  "specversion": "1.0",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "com.example.order.created",
  "source": "/producer-dotnet/orders",
  "time": "2026-02-24T10:30:00Z",
  "datacontenttype": "application/json",
  "correlationid": "order-xyz-123",
  "partitionkey": "order-xyz-123",
  "data": {
    "orderId": "order-xyz-123",
    "customerId": "customer-4521",
    "items": [
      { "productId": "PROD-001", "name": "Notebook Dell", "quantity": 1, "price": 4599.90 },
      { "productId": "PROD-002", "name": "Mouse Logitech", "quantity": 2, "price": 149.90 }
    ],
    "total": 4899.70,
    "currency": "BRL",
    "createdAt": "2026-02-24T10:30:00Z"
  }
}

---

Como executar, SDKs e estrutura do projeto

Consulte o guia completo em docs/GETTING-STARTED.md.

---

Convenção de tipos de evento proposta

com.<empresa>.<dominio>.<ação>

Exemplos:

• com.example.order.created
• com.example.order.shipped
• com.example.user.registered
• com.example.user.updated
• com.example.payment.processed
• com.example.inventory.reserved