events

Documentation

Overview

Package events defines CloudEvents extension keys and constants used across Chainguard platform event types, including delivery, registry, and audience classification extensions.

Index

• Constants
• Variables
• func Body(event cloudevents.Event) (proto.Message, error)
• func BodyAs[T proto.Message](event cloudevents.Event) (T, error)
• func DecodeInto(event cloudevents.Event, msg proto.Message) error
• type Actor
• type Eventable
• type Extendable
• type Occurrence
  • func Decode(event cloudevents.Event) (*Occurrence, error)
• type Redactable
• type WebhookCustomClaims

Constants

const (
	// DeliveryTypeKey is the CloudEvents extension name to filter on for kinds
	// of deliveries.
	DeliveryTypeKey = "chainguarddev1delivery"
	// DeliveryTypeWebhook defines webhook delivery type.
	DeliveryTypeWebhook = "webhook"

	// DeliveryWebhookTargetKey is the CloudEvents extension name to store the
	// target url for webhooks.
	DeliveryWebhookTargetKey = "chainguarddev1webhook"

	// DeliverySubscriptionKey is the CloudEvents extension name to store the
	// subscription id that caused the event.
	DeliverySubscriptionKey = "chainguarddev1subscription"

	// GroupKey is the CloudEvents extension name to store the group associated
	// to the event.
	GroupKey = "group"
	// ClusterKey is the CloudEvents extension name to store the cluster associated
	// to the event.
	ClusterKey = "cluster"
	// ImageKey is the CloudEvents extension name to store the image associated
	// to the event.
	ImageKey = "image"

	// DigestKey is the CloudEvents extension name to store the full digest
	// reference (e.g., "registry.example.com/repo@sha256:...") for registry events.
	DigestKey = "digest"

	// MediaTypeKey is the CloudEvents extension name to store the media type
	// of the object being pushed (e.g., "application/vnd.oci.image.manifest.v1+json").
	MediaTypeKey = "mediatype"

	// APKURLKey is the CloudEvents extension name to store the full APK URL
	// (e.g., "apk.cgr.dev/{uidp}/{arch}/{pkg}-{version}.apk") for APK events.
	APKURLKey = "apkurl"

	// BodyTypeKey is the CloudEvents extension name holding the fully-qualified
	// proto message name of the Occurrence body (e.g. "chainguard.platform.iam.v2beta1.Group").
	// Subscribers use it to resolve the body into a concrete proto.Message via
	// protoregistry.GlobalTypes, without having to sniff the JSON shape.
	BodyTypeKey = "bodytype"

	// AudienceKey labels an event for its intended audience ["internal", "customer"].
	AudienceKey = "audience"
	// AudienceInternal are events intended for the internal platform.
	AudienceInternal = "internal"
	// AudienceCustomer are events targeting outside the platform.
	AudienceCustomer = "customer"

	// ArrivalTimeKey is the CloudEvents extension name to store the Knative
	// arrival timestamp
	ArrivalTimeKey = "knativearrivaltime"
)

Variables

var ErrNoBodyType = errors.New("cloudevent missing bodytype extension")

ErrNoBodyType is returned when a CloudEvent has no BodyTypeKey extension. Events published before the emitter started setting the extension will hit this; callers that need to decode those can use DecodeInto with the proto type they expect.

Functions

func Body

func Body(event cloudevents.Event) (proto.Message, error)

Body decodes the Occurrence body into a concrete proto.Message resolved from the event's BodyTypeKey extension via protoregistry.GlobalTypes. Returns ErrNoBodyType if the extension is absent, and a descriptive error if the named type is not registered in the calling binary.

func BodyAs

func BodyAs[T proto.Message](event cloudevents.Event) (T, error)

BodyAs is Body with a compile-time type assertion. It returns an error if the event's bodytype does not resolve to T — useful for handlers that want to reject cross-version deliveries (e.g. a v2beta1-only subscriber that receives a v1 event).

func DecodeInto

func DecodeInto(event cloudevents.Event, msg proto.Message) error

DecodeInto populates msg from the Occurrence body embedded in event.Data. It handles the envelope unwrap and uses protojson.Unmarshal so that proto oneofs and enum string values round-trip correctly.

Use DecodeInto when you already know the expected proto type and do not want to rely on the BodyTypeKey extension (e.g., during a rollout window where some events are emitted without the extension).

Types

type Actor

type Actor struct {
	// Subject is the identity that triggered this event.
	Subject string `json:"subject"`

	// Actor contains the name/value pairs for each of the claims that were
	// validated to assume the identity whose UIDP appears in Subject above.
	Actor map[string]string `json:"act,omitempty"`
}

Actor is the event payload form of which identity was responsible for the event.

type Eventable

type Eventable interface {
	// CloudEventsSubject returns the subject to use for the cloudevent.
	CloudEventsSubject() string
}

Eventable allows us to define a set of methods that allow event metadata to be collected.

type Extendable

type Extendable interface {
	CloudEventsExtension(key string) (string, bool)
}

Extendable allows us to define a generic method to return extensions based on name.

type Occurrence

type Occurrence struct {
	Actor *Actor `json:"actor,omitempty"`

	// Body is the resource that was created.
	Body any `json:"body,omitempty"`
}

Occurrence is the CloudEvent payload for events.

func Decode

func Decode(event cloudevents.Event) (*Occurrence, error)

Decode returns the full Occurrence (Actor + Body) from event.Data. The returned Occurrence.Body is a concrete proto.Message resolved the same way as Body.

type Redactable

type Redactable interface {
	CloudEventsRedact() any
}

type WebhookCustomClaims

type WebhookCustomClaims struct {
	Webhook struct {
		Digest string `json:"digest"`
	} `json:"webhook"`
}

WebhookCustomClaims holds the custom claims embedded in the webhook's OIDC authorization token.