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 ActorHop
- type AsyncEventable
- type Eventable
- type Extendable
- type Occurrence
- 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" // PolicyResultsKey is the CloudEvents extension name set on registry pull // events that contain policy results. PolicyResultsKey = "policyresults" // IdentityProviderKey is the CloudEvents extension name to store the // IdentityProvider (its UIDP) an event is scoped to, for per-IdP audit // attribution. Keyed by the bare resource noun like GroupKey/ClusterKey. IdentityProviderKey = "identityprovider" // EntitlementDomainKey is the CloudEvents extension name to store the // entitlement domain (e.g. "IMAGE") an entitlement change event applies to. EntitlementDomainKey = "entitlementdomain" // EntitlementOperationKey is the CloudEvents extension name to store the // operation (e.g. "WRITE") that produced an entitlement change event. EntitlementOperationKey = "entitlementoperation" // 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 ¶ added in v0.1.55
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 ¶ added in v0.1.55
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 ¶ added in v0.1.55
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"`
// Chain is the ordered lineage of credential exchanges — oldest first —
// that led to the identity in Subject, mirrored from the token's
// act_chain claim. Actor above records only the immediate input
// credential and is replaced on every exchange; Chain accumulates, so
// the originating principal survives chained identity assumption. It is
// attribution, never authorization. Empty on events whose token predates
// the chain claim or carries none.
Chain []ActorHop `json:"chain,omitempty"`
}
Actor is the event payload form of which identity was responsible for the event.
type ActorHop ¶ added in v0.1.265
type ActorHop struct {
// Sub is the subject of the hop's credential — a Chainguard identity
// UIDP when the credential was minted by the Chainguard issuer, the
// third-party subject for an origin hop, the attributed principal for
// asserted hops.
Sub string `json:"sub"`
// Kind records how the exchange this credential authorized sourced the
// minted token's authority: "bindings" (resolved from the assumed
// identity's role bindings) or "transferred" (a per-scope subset
// transferred from this hop's credential).
Kind string `json:"kind"`
// Provenance records how this hop's subject was established: "issuer"
// (built from the issuer's own verification of the hop's credential) or
// "asserted" (attributed by a trusted intermediary that verified
// something other than a Chainguard token).
Provenance string `json:"provenance"`
// Iss is the issuer of the hop's credential; empty for asserted hops,
// which have no credential.
Iss string `json:"iss,omitempty"`
// UpstreamSub optionally names the upstream principal an asserted hop
// was attributed from.
UpstreamSub string `json:"upstream_sub,omitempty"`
}
ActorHop is one credential exchange in an actor chain. Field names and values mirror the hops of the token's act_chain claim.
type AsyncEventable ¶ added in v0.1.138
type AsyncEventable interface {
CloudEventsAsync() bool
}
AsyncEventable opts an Eventable response into asynchronous delivery after the event has been fully constructed and redacted. Use this only when waiting for the event sink would make delivery of the primary response materially less safe, such as a reveal-once credential response.
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 ¶
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 ¶ added in v0.1.55
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 ¶ added in v0.1.2
type WebhookCustomClaims struct {
Webhook struct {
Digest string `json:"digest"`
} `json:"webhook"`
}
WebhookCustomClaims holds the custom claims embedded in the webhook's OIDC authorization token.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apk provides CloudEvents types for APK package registry operations.
|
Package apk provides CloudEvents types for APK package registry operations. |
|
Package entitlements defines the public CloudEvent emitted by the Centralized Entitlements Service when an entitlement or its bound resources change.
|
Package entitlements defines the public CloudEvent emitted by the Centralized Entitlements Service when an entitlement or its bound resources change. |
|
Package generator defines the CloudEvents event type and payload for on-demand vulnerability report generation requests.
|
Package generator defines the CloudEvents event type and payload for on-demand vulnerability report generation requests. |
|
Package receiver provides secure CloudEvent webhook receivers for Chainguard events.
|
Package receiver provides secure CloudEvent webhook receivers for Chainguard events. |
|
Package registry defines CloudEvents event types and payload structs for Chainguard registry pull, push, and repository lifecycle events.
|
Package registry defines CloudEvents event types and payload structs for Chainguard registry pull, push, and repository lifecycle events. |