Raxol.Core.Events.CloudEvent (Raxol Core v2.6.0)

Copy Markdown View Source

CloudEvents v1.0 envelope (cloudevents.io).

Standardized event metadata so raxol events can interoperate with webhook receivers, pub/sub fabrics, and message brokers without bespoke serialization. Conversion to and from Raxol.Core.Events.Event is provided by that module.

Required fields

  • :specversion - "1.0"
  • :id - unique within the source
  • :source - URI-reference identifying the producer (e.g. "raxol://node-1")
  • :type - reverse-DNS style event type (e.g. "raxol.key")

Optional fields

  • :time - DateTime.t() when the event occurred
  • :data - event payload (any term)
  • :datacontenttype - MIME type of :data (e.g. "application/json")
  • :subject - subject of the event in the context of the source

Examples

ce = CloudEvent.new("raxol.key", "raxol://node-1",
  data: %{key: :enter, state: :pressed}
)

map = CloudEvent.to_map(ce)
# => %{specversion: "1.0", id: "...", source: "raxol://node-1",
#      type: "raxol.key", time: ~U[...], data: %{...}}

{:ok, ce2} = CloudEvent.from_map(map)

Summary

Types

t()

Functions

from_map(map)

Build a CloudEvent from a map (atom or string keys).

new(type, source, opts \\ [])

Construct a CloudEvent. type and source are required.

to_map(ce)

Returns the CloudEvent as a map suitable for JSON encoding. Nil-valued optional fields are dropped. Atom keys; convert to string keys at the serialization boundary if needed.

Types

t()

@type t() :: %Raxol.Core.Events.CloudEvent{
  data: term() | nil,
  datacontenttype: String.t() | nil,
  id: String.t(),
  source: String.t(),
  specversion: String.t(),
  subject: String.t() | nil,
  time: DateTime.t() | nil,
  type: String.t()
}

Functions

from_map(map)

@spec from_map(map()) :: {:ok, t()} | {:error, :missing_required_field}

Build a CloudEvent from a map (atom or string keys).

Returns {:error, :missing_required_field} if :id, :source, or :type is absent. Unknown fields are dropped silently.

new(type, source, opts \\ [])

@spec new(String.t(), String.t(), keyword()) :: t()

Construct a CloudEvent. type and source are required.

Options

  • :id - explicit id (default: random 16 hex chars)
  • :time - DateTime.t() (default: DateTime.utc_now/0)
  • :data - event payload
  • :datacontenttype - MIME type of :data
  • :subject - subject of the event

to_map(ce)

@spec to_map(t()) :: map()

Returns the CloudEvent as a map suitable for JSON encoding. Nil-valued optional fields are dropped. Atom keys; convert to string keys at the serialization boundary if needed.