Returns a specification to start this module under a supervisor.

See Supervisor.

@spec from_avro(avro :: binary(), ctx_attrs :: map()) ::
  {:ok, t()}
  | {:error,
     %Cloudevents.Format.Decoder.DecodeError{
       __exception__: term(),
       cause: term()
     }}

Decodes an Avro-encoded Cloudevent (requires Cloudevents.start_link/1).

TODO: tests/examples

@spec from_http_message(http_body(), http_headers()) :: {:ok, [t()]} | {:error, any()}

Parses a HTTP request as one or more Cloudevents.

Note that the HTTP request may contain more than one event (called a "batch"). Because of this, the function always returns a list of Cloudevents. Use pattern matching if you expect single events only:

with {:ok, [the_event]} = from_http_message(body, headers) do
  "do something with the_event"
else
  {:ok, events} -> "oops got a batch of events"
  {:error, error} -> "failed to parse HTTP request: #{inspect(error)}"
end

@spec from_json!(json :: binary()) :: t()

Decodes a JSON-encoded Cloudevent and panics otherwise.

@spec from_json(json :: binary()) ::
  {:ok, t()}
  | {:error,
     %Cloudevents.Format.Decoder.DecodeError{
       __exception__: term(),
       cause: term()
     }}

Decodes a JSON-encoded Cloudevent.

@spec from_kafka_message(kafka_body(), kafka_headers()) ::
  {:ok, t()} | {:error, any()}

Parses a Kafka message as a Cloudevent.

@spec from_map!(
  map :: %{required(atom()) => any()} | %{required(String.t()) => any()}
) :: t()

Converts an Elixir map into a Cloudevent and panics otherwise.

@spec from_map(map :: %{required(atom()) => any()} | %{required(String.t()) => any()}) ::
  {:ok, t()}
  | {:error,
     %Cloudevents.Format.ParseError{__exception__: term(), message: term()}}

Converts an Elixir map into a Cloudevent.

examples

Examples

iex> Cloudevents.from_map(%{"specversion" => "1.0", "type" => "test", "source" => "test", "id" => "1"})
{:ok,
 %Cloudevents.Format.V_1_0.Event{
   data: nil,
   datacontenttype: nil,
   dataschema: nil,
   extensions: %{},
   id: "1",
   source: "test",
   specversion: "1.0",
   subject: nil,
   time: nil,
   type: "test"
 }}

iex> Cloudevents.from_map(%{specversion: "1.0", type: "test", source: "test", id: "1"})
{:ok,
 %Cloudevents.Format.V_1_0.Event{
   data: nil,
   datacontenttype: nil,
   dataschema: nil,
   extensions: %{},
   id: "1",
   source: "test",
   specversion: "1.0",
   subject: nil,
   time: nil,
   type: "test"
 }}

@spec start_link(options()) :: {:ok, pid()} | {:error, any()}

Runs the cloudevents supervisor; needed for Avro support and its schema caching.

Stops the cloudevents supervisor.

@spec to_avro(t()) :: {:ok, binary()} | {:error, term()}

Encodes a Cloudevent using Avro binary encoding (requires Cloudevents.start_link/1).

TODO: tests/examples

@spec to_http_binary_message(t()) :: {http_body(), http_headers()}

Serialize an event in HTTP binary content mode.

Binary mode basically means: the payload is in the body and the metadata is in the header.

iex> event = Cloudevents.from_map!(%{
...>   specversion: "1.0",
...>   type: "some-type",
...>   source: "some-source",
...>   id: "1",
...>   data: %{"foo" => "bar"}})
iex> {_body, _headers} = Cloudevents.to_http_binary_message(event)
{
  "{\"foo\":\"bar\"}",
  [
    {"content-type", "application/json"},
    {"ce-specversion", "1.0"},
    {"ce-type", "some-type"},
    {"ce-source", "some-source"},
    {"ce-id", "1"}
  ]
}

@spec to_http_structured_message(t(), event_format :: :json | :avro_binary) ::
  {:ok, {http_body(), http_headers()}}

Serialize an event in HTTP structured content mode.

Structured mode basically means: the full event - payload and metadata - is in the body.

@spec to_json(t()) :: binary()

Encodes a Cloudevent using JSON format.

@spec to_kafka_binary_message(t()) :: {kafka_body(), kafka_headers()}

Serialize an event in Kafka binary content mode.

Binary mode basically means: the payload is in the body and the metadata is in the header.

iex> event = Cloudevents.from_map!(%{
...>   specversion: "1.0",
...>   type: "some-type",
...>   source: "some-source",
...>   id: "1",
...>   data: %{"foo" => "bar"}})
iex> {_body, _headers} = Cloudevents.to_kafka_binary_message(event)
{
  "{\"foo\":\"bar\"}",
  [
    {"content-type", "application/json"},
    {"ce_specversion", "1.0"},
    {"ce_type", "some-type"},
    {"ce_source", "some-source"},
    {"ce_id", "1"}
  ]
}

@spec to_kafka_structured_message(t(), event_format :: :json | :avro_binary) ::
  {:ok, {kafka_body(), kafka_headers()}} | {:error, term()}

Serialize an event in Kafka structured content mode.

Structured mode basically means: the full event - payload and metadata - is in the body.

iex> event = Cloudevents.from_map!(%{
...>   specversion: "1.0",
...>   type: "some-type",
...>   source: "some-source",
...>   id: "1",
...>   data: %{"foo" => "bar"}})
iex> {:ok, {body, headers}} = Cloudevents.to_kafka_structured_message(event, :json)
iex> {body, headers}
{
  "{\"data\":{\"foo\":\"bar\"},\"datacontenttype\":\"application/json\",\"id\":\"1\",\"source\":\"some-source\",\"specversion\":\"1.0\",\"type\":\"some-type\"}",
  [{"content-type", "application/cloudevents+json"}]
}

Note that Avro encoding requires a preceding call to Cloudevents.start_link/1.

@spec to_map(t()) :: %{required(atom()) => any()}

Converts a Cloudevent into an Elixir map. See also Cloudevents.from_map/1.

examples

Examples

iex> Cloudevents.to_map(Cloudevents.from_map!(%{"specversion" => "1.0", "type" => "test", "source" => "test", "id" => "1"}))
%{specversion: "1.0", type: "test", source: "test", id: "1"}