CloudEvents

Produce and consume webhook / pubsub / queue payloads in the framework-neutral CNCF CloudEvents v1.0 schema (cloudevents.io/spec/v1.0). The spec is adopted by AWS EventBridge, Azure Event Grid, Google Eventarc, Knative, Datadog, and the wider CNCF ecosystem — wrapping outbound events at b.webhook / b.pubsub / b.queue boundaries lets operators interop with these consumers without each consumer learning a bespoke shape.

wrap produces a structured-mode envelope from operator-supplied source / type / subject / data (and optional extensions), auto-filling id (UUID v4) and time (ISO 8601). Buffer payloads are routed to the data_base64 field with a default application/octet-stream content-type; non-Buffer payloads land in data with application/json. parse validates a received envelope against the §3.1 required-attribute set, refuses unknown specversion values and the illegal data + data_base64 simultaneous form, decodes base64-mode payloads back to a Buffer, and surfaces operator-defined extension attributes separately so consumers can route on them without grepping the envelope.

Extension-attribute names follow the §3.1 naming rules (lowercase ASCII alnum, 1..20 chars). Names that collide with a spec attribute are refused.

b.cloudEvents.wrap(opts) #

{
  {
    source:           string,         // required; URI-reference per §3.1
    type:             string,         // required; reverse-DNS recommended
    id?:              string,         // default UUID v4
    time?:            string,         // default new Date().toISOString()
    subject?:         string,
    datacontenttype?: string,         // auto: application/json | application/octet-stream
    dataschema?:      string,         // URI of payload schema
    data?:            object|Buffer,  // Buffer routes to data_base64
    extensions?:      object          // keys [a-z0-9]{1,20}, no spec collisions
  }
}

Produces a CloudEvents v1.0 structured-mode envelope from opts.source + opts.type (the only required inputs). id is auto-filled with a UUID v4 when absent; time is auto-filled with the current ISO 8601 timestamp. Buffer data is base64-encoded into data_base64 with application/octet-stream; non-Buffer data lands in the data attribute with application/json. Extension keys must match [a-z0-9]{1,20} and must not collide with a spec attribute — both refusals throw CloudEventsError at config time.

var b = require("blamejs");
var ce = b.cloudEvents.wrap({
  source:  "/services/orders",
  type:    "com.example.order.created",
  subject: "order/o-1234",
  data:    { id: "o-1234", total: 4250 }
});
ce.specversion;
// → "1.0"

b.cloudEvents.parse(envelope) #

Validates a received CloudEvents v1.0 envelope and returns a normalized record { specversion, id, source, type, time, subject, datacontenttype, dataschema, data, extensions }. Throws CloudEventsError for missing required attributes (§3.1), unsupported specversion, the illegal simultaneous data + data_base64 form (§3.1.1), and base64-decoding failures. Buffer-mode payloads (data_base64) are decoded back to a Buffer; operator-defined extension attributes are surfaced under .extensions so routing can branch on them without scanning the envelope.

var b = require("blamejs");
var record = b.cloudEvents.parse({
  specversion: "1.0",
  id:          "evt-1",
  source:      "/services/orders",
  type:        "com.example.order.created",
  data:        { id: "o-1234", total: 4250 }
});
record.type;
// → "com.example.order.created"

b.cloudEvents.validate(event) #

Check an in-memory CloudEvents v1.0 envelope against the §3.1 spec and return an array of { attribute, message } issues — an empty array means the event is conformant. Unlike parse (which throws and decodes), this never throws, so it suits inspecting events of unknown provenance before deciding what to do with them.

b.cloudEvents.validate({ specversion: "1.0", id: "1",
  source: "/x", type: "com.example.t" });
// → []

b.cloudEvents.isValid(event) #

Boolean convenience form of validate — true when the event has zero conformance issues.

b.cloudEvents.isValid(evt);   // → true

b.cloudEvents.toJSON(event, opts?) #

{
  space:   number | string,   // JSON.stringify indentation (default: none)
}

Serialize a CloudEvents envelope (as produced by wrap) to a JSON event-format string — media type application/cloudevents+json. The envelope is already in wire shape (JSON data inline, binary as a data_base64 string), so this validates it and renders the JSON. Throws CloudEventsError on a non-conformant event.

var json = b.cloudEvents.toJSON(b.cloudEvents.wrap({ source: "/x", type: "t" }));

b.cloudEvents.fromJSON(input, opts?) #

{
  maxBytes:   number,   // default: 1 MiB — reject larger inputs
}

Parse a single JSON event-format document (string or Buffer) into a validated CloudEvents envelope. Untrusted bytes route through the framework's bounded, prototype-pollution-safe JSON reader. The envelope is returned in wire shape (binary stays a data_base64 string); call parse instead when you want the Buffer-decoded record. Throws CloudEventsError on malformed or non-conformant input.

var evt = b.cloudEvents.fromJSON(req.rawBody);

b.cloudEvents.toJSONBatch(events, opts?) #

{
  space:   number | string,   // JSON.stringify indentation (default: none)
}

Serialize an array of CloudEvents envelopes to the JSON batch format (media type application/cloudevents-batch+json) — a JSON array of events, each rendered as by toJSON. An empty array yields "[]".

var body = b.cloudEvents.toJSONBatch([evtA, evtB]);

b.cloudEvents.fromJSONBatch(input, opts?) #

{
  maxBytes:   number,   // default: 1 MiB — reject larger inputs
}

Parse a JSON batch (a JSON array of events) from a string or Buffer into an array of validated CloudEvents envelopes. Each element is validated as by fromJSON; an empty array is valid. A non-array body, over-size input, or any non-conformant element throws CloudEventsError.

var events = b.cloudEvents.fromJSONBatch(req.rawBody);

b.cloudEvents.http.encodeBinary(event) #

Render a CloudEvents envelope in HTTP binary content mode: each context attribute (and extension) becomes a ce--prefixed header with a percent-encoded value, datacontenttype maps to the plain Content-Type header (never ce-datacontenttype), and the payload becomes the body. Returns { headers, body } where body is a Buffer (for data_base64 payloads) or a string.

var enc = b.cloudEvents.http.encodeBinary(evt);
// enc.headers["ce-id"], enc.headers["content-type"], enc.body

b.cloudEvents.http.encodeStructured(event) #

Render a CloudEvents envelope in HTTP structured content mode: the whole event is serialized via the JSON event format into the body, with Content-Type: application/cloudevents+json. Returns { headers, body }.

var enc = b.cloudEvents.http.encodeStructured(evt);

b.cloudEvents.http.encodeBatch(events) #

Render an array of CloudEvents in HTTP batched content mode: the JSON batch format in the body with Content-Type: application/cloudevents-batch+json. Returns { headers, body }.

var enc = b.cloudEvents.http.encodeBatch([evtA, evtB]);

b.cloudEvents.http.decodeBinary(headers, body, opts?) #

{
  maxBytes:   number,   // default: 1 MiB — reject larger bodies
}

Parse an HTTP binary-mode request into a CloudEvents envelope. Headers are matched case-insensitively; each ce-* header is percent-decoded into the matching attribute, Content-Type becomes datacontenttype, and the body becomes the payload (parsed as JSON when the content type is JSON, kept as a data_base64 string for opaque bytes). The result is validated. Binary-mode header values are strings, so extension types other than String are not recovered.

var evt = b.cloudEvents.http.decodeBinary(req.headers, req.rawBody);

b.cloudEvents.http.decode(headers, body, opts?) #

{
  maxBytes:   number,   // default: 1 MiB — reject larger bodies
}

Parse an HTTP request into a CloudEvents envelope (or array, for a batch), auto-detecting the content mode exactly as a conformant receiver does: a Content-Type beginning application/cloudevents-batch is batched, one beginning application/cloudevents is structured, and anything else is binary mode. Returns a single envelope for binary/structured modes and an array for batched mode.

var evt = b.cloudEvents.http.decode(req.headers, req.rawBody);

Last updated 2026-08-08T16:39:49.652Z by seeder.