cloudevents（cloudevents 命令行）

CloudEvents

Build, validate, and serialize events conforming to the CNCF CloudEvents v1.0.2 specification. This skill ensures agents produce spec-compliant event structures, correct HTTP/Kafka bindings, and proper JSON serialization — details that agents consistently get wrong without guidance.

When to use

• The task explicitly involves CloudEvents v1.0 envelopes, attributes, or transport bindings.
• The user needs to build, validate, serialize, or parse events in structured or binary mode.
• The request mentions ce- headers, application/cloudevents+json, or CloudEvents interoperability.
• The event contract must be CNCF CloudEvents-compliant across HTTP, Kafka, AMQP, or similar transports.

Do NOT use when:

• The event format is proprietary or intentionally not CloudEvents.
• The task is generic pub/sub design without a CloudEvents requirement.
• The user only needs business-payload schema design with no event-envelope concern.

Response format

Always structure the final response with these top-level sections, in this order:

1. Summary — state the task, scope, and main conclusion in 1-3 sentences.
2. Decision / Approach — state the key classification, assumptions, or chosen path.
3. Artifacts — provide the primary deliverable(s) for this skill. Use clear subheadings for multiple files, commands, JSON payloads, queries, or documents.
4. Validation — state checks performed, important risks, caveats, or unresolved questions.
5. Next steps — list concrete follow-up actions, or write None if nothing remains.

Rules:

• Do not omit a section; write None when a section does not apply.
• If files are produced, list each file path under Artifacts before its contents.
• If commands, JSON, SQL, YAML, or code are produced, put each artifact in fenced code blocks with the correct language tag when possible.
• Keep section names exactly as written above so output stays predictable across skills.

Workflow

1. Determine the event shape

Identify the REQUIRED context attributes and which OPTIONAL/extension attributes apply. Every CloudEvent MUST have these four attributes:

OPTIONAL attributes:

Extension attributes follow the same naming rules (lowercase a-z, 0-9 only, max 20 chars) and are serialized as top-level properties in JSON or ce- prefixed headers in HTTP binary mode.

2. Choose the content mode

There are three content modes. Pick based on your transport and consumer needs:

3. Serialize the event

JSON Structured Mode

All attributes and data go in a single JSON object. Media type: application/cloudevents+json.

{
  "specversion": "1.0",
  "type": "com.example.order.created",
  "source": "https://example.com/orders",
  "id": "A234-1234-1234",
  "time": "2024-01-15T09:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "orderId": "12345",
    "amount": 99.99
  }
}

Data handling rules:

• JSON data (*/json or */*+json content type) → use data member, store as native JSON value (NOT a stringified JSON string)
• Binary data → use data_base64 member with Base64-encoded value
• data and data_base64 are mutually exclusive
• No datacontenttype → implied application/json

HTTP Binary Mode

Event data goes in HTTP body. All context attributes go in ce- prefixed headers. The Content-Type header carries the datacontenttype value (do NOT also send a ce-datacontenttype header).

POST /webhook HTTP/1.1
Host: example.com
ce-specversion: 1.0
ce-type: com.example.order.created
ce-source: https://example.com/orders
ce-id: A234-1234-1234
ce-time: 2024-01-15T09:30:00Z
Content-Type: application/json

{"orderId": "12345", "amount": 99.99}

Header value encoding: String values in headers MUST be percent-encoded for characters outside printable ASCII (U+0021-U+007E), plus space (U+0020), double-quote (U+0022), and percent (U+0025).

JSON Batch Mode

An array of CloudEvent JSON objects. Media type: application/cloudevents-batch+json.

[
  {
    "specversion": "1.0",
    "type": "com.example.order.created",
    "source": "/orders",
    "id": "evt-001",
    "data": { "orderId": "123" }
  },
  {
    "specversion": "1.0",
    "type": "com.example.order.shipped",
    "source": "/orders",
    "id": "evt-002",
    "data": { "orderId": "123", "trackingId": "TRK-456" }
  }
]

4. Validate the event

Check these rules against every CloudEvent you produce:

• specversion is exactly "1.0" (string, not number)
• id is a non-empty string
• source is a non-empty URI-reference
• type is a non-empty string with reverse-DNS prefix
• time (if present) is RFC 3339 format
• datacontenttype (if present) is a valid RFC 2046 media type
• dataschema (if present) is a non-empty absolute URI
• Extension attribute names are lowercase alphanumeric only, max 20 chars
• JSON mode: data and data_base64 are not both present
• HTTP binary mode: Content-Type matches datacontenttype, no ce-datacontenttype header
• Event wire size ≤ 64 KB for safe intermediary forwarding
• No sensitive data in context attributes (only in encrypted data)

5. Implement consumer detection

Consumers receiving HTTP messages distinguish content modes by inspecting Content-Type:

Checklist

• All four REQUIRED attributes present (specversion, id, source, type)
• specversion is the string "1.0", not a number
• type uses reverse-DNS prefix (e.g., com.example.object.created)
• source is a valid URI-reference (absolute URI recommended)
• Content mode chosen and correct Content-Type set
• Data serialized correctly for chosen mode (JSON value vs base64 vs raw body)
• HTTP binary mode: attributes in ce- headers, no ce-datacontenttype
• Extension attributes follow naming rules (lowercase, alphanumeric, ≤20 chars)

Examples

Producer: HTTP structured mode (TypeScript)

import { randomUUID } from "crypto";

interface CloudEvent<T = unknown> {
  specversion: "1.0";
  type: string;
  source: string;
  id: string;
  time?: string;
  datacontenttype?: string;
  dataschema?: string;
  subject?: string;
  data?: T;
  data_base64?: string;
  [extension: string]: unknown;
}

function createCloudEvent<T>(
  type: string,
  source: string,
  data: T,
  options?: {
    subject?: string;
    datacontenttype?: string;
    dataschema?: string;
    extensions?: Record<string, string | number | boolean>;
  },
): CloudEvent<T> {
  const event: CloudEvent<T> = {
    specversion: "1.0",
    id: randomUUID(),
    type,
    source,
    time: new Date().toISOString(),
    data,
  };

  if (options?.subject) event.subject = options.subject;
  if (options?.datacontenttype) event.datacontenttype = options.datacontenttype;
  if (options?.dataschema) event.dataschema = options.dataschema;

  // Extensions are top-level properties
  if (options?.extensions) {
    for (const [key, value] of Object.entries(options.extensions)) {
      if (!/^[a-z0-9]+$/.test(key) || key.length > 20) {
        throw new Error(
          `Extension "${key}" must be lowercase alphanumeric, max 20 chars`,
        );
      }
      event[key] = value;
    }
  }

  return event;
}

// Send as structured mode
async function sendStructured(url: string, event: CloudEvent): Promise<void> {
  await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/cloudevents+json" },
    body: JSON.stringify(event),
  });
}

// Send as binary mode
async function sendBinary(url: string, event: CloudEvent): Promise<void> {
  const { data, data_base64, datacontenttype, ...attrs } = event;
  const headers: Record<string, string> = {};

  for (const [key, value] of Object.entries(attrs)) {
    if (value !== undefined && value !== null) {
      headers[`ce-${key}`] = String(value);
    }
  }

  headers["Content-Type"] = datacontenttype ?? "application/json";

  await fetch(url, {
    method: "POST",
    headers,
    body: data_base64
      ? Buffer.from(data_base64, "base64")
      : JSON.stringify(data),
  });
}

Consumer: detecting and parsing (TypeScript)

function parseCloudEvent(
  headers: Record<string, string>,
  body: string | Buffer,
): CloudEvent {
  const contentType = headers["content-type"] ?? "";

  if (contentType.startsWith("application/cloudevents-batch")) {
    throw new Error("Use parseBatch() for batched events");
  }

  if (contentType.startsWith("application/cloudevents")) {
    // Structured mode: entire event is in the body
    return JSON.parse(typeof body === "string" ? body : body.toString("utf-8"));
  }

  // Binary mode: attributes in ce- headers, data in body
  const event: CloudEvent = {
    specversion: "1.0",
    id: "",
    type: "",
    source: "",
  };

  for (const [key, value] of Object.entries(headers)) {
    if (key.toLowerCase().startsWith("ce-")) {
      const attr = key.slice(3).toLowerCase();
      event[attr] = decodeURIComponent(value);
    }
  }

  event.datacontenttype = contentType;

  if (contentType.includes("json")) {
    event.data = JSON.parse(
      typeof body === "string" ? body : body.toString("utf-8"),
    );
  } else {
    event.data_base64 = Buffer.from(body).toString("base64");
  }

  return event;
}

Common mistakes

Quick reference

See references/spec-quick-ref.md for the complete type system, Kafka/AMQP bindings, and extension attribute details.

Key principles

1. Spec compliance is binary — An event either conforms to CloudEvents v1.0 or it doesn't. There is no "close enough." All four REQUIRED attributes must be present and correctly typed.
2. Context attributes are for routing, not data — Attributes like type, source, and subject exist so intermediaries can route events without deserializing the payload. Never put sensitive or domain-specific data in context attributes.
3. Content mode determines serialization — Binary and structured modes are not interchangeable format choices; they have different serialization rules, different Content-Type values, and different header requirements. Pick one and follow its rules exactly.
4. Extensions are top-level, not nested — Extension attributes sit alongside core attributes (in JSON) or as ce- headers (in HTTP binary). They are never nested under an extensions key.
5. Data format follows datacontenttype — The data member is a native JSON value when the content type is JSON-compatible, but a string when it's not. Binary data uses data_base64. These rules are not optional.