Add data_base64 support with minimal API

- CloudEvent[A]: add DataBase64 field; unmarshal/marshal both data and data_base64
- RawEvent = CloudEvent[json.RawMessage]: same type alias, supports data_base64
- BytesForSignature(RawEvent) for signature verification
- DecodeHeader(data) for header-only parse (scaling)
- IsJSONDataContentType(ct) for wire-form choice
- Single unmarshal path (unmarshalCloudEventWithPayload), setHeaderField
- No RawCloudEvent type; no validation/constructors/conversion helpers

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: zer0stars

cloudevent.go

@@ -3,6 +3,8 @@ package cloudevent
 
 import (
 	"encoding/json"
+	"mime"
+	"strings"
 	"time"
 )
 
@@ -95,11 +97,30 @@ type CloudEvent[A any] struct {
 	CloudEventHeader
 	// Data contains domain-specific information about the event.
 	Data A `json:"data"`
+
+	DataBase64 string `json:"data_base64,omitempty"`
 }
 
 // RawEvent is a cloudevent with a json.RawMessage data field.
+// It supports both "data" and "data_base64" (CloudEvents JSON spec).
 type RawEvent = CloudEvent[json.RawMessage]
 
+// BytesForSignature returns the bytes that were signed (wire form of data or data_base64) for a RawEvent.
+// Use for signature verification; not the same as Data when the CE used data_base64.
+func BytesForSignature(ev RawEvent) []byte {
+	if ev.DataBase64 != "" {
+		return []byte(ev.DataBase64)
+	}
+	return ev.Data
+}
+
+// IsJSONDataContentType returns true if the MIME type indicates a JSON payload.
+// Matches "application/json" and any "+json" suffix type (e.g. "application/cloudevents+json").
+func IsJSONDataContentType(ct string) bool {
+	parsed, _, err := mime.ParseMediaType(strings.TrimSpace(ct))
+	return err == nil && (parsed == "application/json" || strings.HasSuffix(parsed, "+json"))
+}
+
 // Equals returns true if the two CloudEventHeaders share the same IndexKey.
 func (c *CloudEventHeader) Equals(other CloudEventHeader) bool {
 	return c.Key() == other.Key()

cloudevent_json.go

@@ -1,32 +1,99 @@
 package cloudevent
 
 import (
+	"encoding/base64"
 	"encoding/json"
+	"fmt"
 	"reflect"
 	"strings"
 
 	"github.com/tidwall/sjson"
 )
 
-var definedCloudeEventHdrFields = getJSONFieldNames(reflect.TypeOf(CloudEventHeader{}))
+var definedCloudeEventHdrFields = getJSONFieldNames(reflect.TypeFor[CloudEventHeader]())
 
 type cloudEventHeader CloudEventHeader
 
 // UnmarshalJSON implements custom JSON unmarshaling for CloudEvent.
+// It transparently handles both "data" and "data_base64" wire formats.
+// For RawEvent (CloudEvent[json.RawMessage]), Data is set to the raw payload bytes.
 func (c *CloudEvent[A]) UnmarshalJSON(data []byte) error {
-	var err error
-	c.CloudEventHeader, err = unmarshalCloudEvent(data, c.setDataField)
-	return err
+	var dataRaw json.RawMessage
+	var dataBase64 string
+	header, err := unmarshalCloudEventWithPayload(data, func(d json.RawMessage, b64 string) error {
+		dataRaw = d
+		dataBase64 = b64
+		return nil
+	})
+	if err != nil {
+		return err
+	}
+	c.CloudEventHeader = header
+	if dataRaw != nil && dataBase64 != "" {
+		return fmt.Errorf("cloudevent: both \"data\" and \"data_base64\" present; only one allowed")
+	}
+	// RawEvent: assign payload bytes directly to Data
+	if ptr, ok := (any)(&c.Data).(*json.RawMessage); ok {
+		if dataBase64 != "" {
+			decoded, err := base64.StdEncoding.DecodeString(dataBase64)
+			if err != nil {
+				return err
+			}
+			*ptr = decoded
+			c.DataBase64 = dataBase64
+		} else {
+			*ptr = dataRaw
+			c.DataBase64 = ""
+		}
+		return nil
+	}
+	// Typed CloudEvent: unmarshal into Data
+	if dataBase64 != "" {
+		decoded, err := base64.StdEncoding.DecodeString(dataBase64)
+		if err != nil {
+			return err
+		}
+		if err := json.Unmarshal(decoded, &c.Data); err != nil {
+			return err
+		}
+		c.DataBase64 = dataBase64
+	} else if dataRaw != nil {
+		if err := json.Unmarshal(dataRaw, &c.Data); err != nil {
+			return err
+		}
+	}
+	return nil
 }
 
-// MarshalJSON implements custom JSON marshaling for CloudEventHeader.
+// MarshalJSON implements custom JSON marshaling for CloudEvent[A].
+// When DataBase64 is set, emits "data_base64"; otherwise emits "data".
+// For RawEvent, uses DataContentType to choose wire form when DataBase64 is empty.
 func (c CloudEvent[A]) MarshalJSON() ([]byte, error) {
-	// Marshal the base struct
 	data, err := json.Marshal(c.CloudEventHeader)
 	if err != nil {
 		return nil, err
 	}
-	data, err = sjson.SetBytes(data, "data", c.Data)
+	// RawEvent: choose data vs data_base64 by content type when DataBase64 not set
+	if raw, ok := (any)(c.Data).(json.RawMessage); ok {
+		if len(raw) > 0 || c.DataBase64 != "" {
+			if c.DataBase64 != "" {
+				data, err = sjson.SetBytes(data, "data_base64", c.DataBase64)
+			} else if IsJSONDataContentType(c.DataContentType) || (c.DataContentType == "" && json.Valid(raw)) {
+				data, err = sjson.SetRawBytes(data, "data", raw)
+			} else {
+				data, err = sjson.SetBytes(data, "data_base64", base64.StdEncoding.EncodeToString(raw))
+			}
+			if err != nil {
+				return nil, err
+			}
+		}
+		return data, nil
+	}
+	if c.DataBase64 != "" {
+		data, err = sjson.SetBytes(data, "data_base64", c.DataBase64)
+	} else {
+		data, err = sjson.SetBytes(data, "data", c.Data)
+	}
 	if err != nil {
 		return nil, err
 	}
@@ -42,21 +109,18 @@ func (c *CloudEventHeader) UnmarshalJSON(data []byte) error {
 
 // MarshalJSON implements custom JSON marshaling for CloudEventHeader.
 func (c CloudEventHeader) MarshalJSON() ([]byte, error) {
-	// Marshal the base struct
 	aux := (cloudEventHeader)(c)
 	aux.SpecVersion = SpecVersion
 	data, err := json.Marshal(aux)
 	if err != nil {
 		return nil, err
 	}
-	// Add all extras using sjson]
 	for k, v := range c.Extras {
 		data, err = sjson.SetBytes(data, k, v)
 		if err != nil {
 			return nil, err
 		}
 	}
-
 	return data, nil
 }
 
@@ -90,50 +154,105 @@ func getJSONFieldNames(t reflect.Type) map[string]struct{} {
 
 // unmarshalCloudEvent unmarshals the CloudEventHeader and data field.
 func unmarshalCloudEvent(data []byte, dataFunc func(json.RawMessage) error) (CloudEventHeader, error) {
-	c := CloudEventHeader{}
-	aux := cloudEventHeader{}
-	// Unmarshal known fields directly into the struct
-	if err := json.Unmarshal(data, &aux); err != nil {
-		return c, err
-	}
-	aux.SpecVersion = SpecVersion
-	c = (CloudEventHeader)(aux)
-	// Create a map to hold all JSON fields
+	return unmarshalCloudEventWithPayload(data, func(dataRaw json.RawMessage, _ string) error {
+		return dataFunc(dataRaw)
+	})
+}
+
+// unmarshalCloudEventWithPayload unmarshals the CloudEventHeader and returns both
+// "data" and "data_base64" for CloudEvent payload. Single pass: parse once into
+// map[string]json.RawMessage, then fill header and payload from the map.
+func unmarshalCloudEventWithPayload(data []byte, payloadFunc func(dataRaw json.RawMessage, dataBase64 string) error) (CloudEventHeader, error) {
 	rawFields := make(map[string]json.RawMessage)
 	if err := json.Unmarshal(data, &rawFields); err != nil {
-		return c, err
+		return CloudEventHeader{}, err
 	}
 
-	// Separate known and unknown fields
-	for key, rawValue := range rawFields {
-		if _, ok := definedCloudeEventHdrFields[key]; ok {
-			// Skip defined fields
+	var c CloudEventHeader
+	for key, raw := range rawFields {
+		if key == "data" || key == "data_base64" {
 			continue
 		}
-		if key == "data" {
-			if err := dataFunc(rawValue); err != nil {
+		if _, defined := definedCloudeEventHdrFields[key]; defined {
+			if err := setHeaderField(&c, key, raw); err != nil {
 				return c, err
 			}
-			continue
+		} else {
+			if c.Extras == nil {
+				c.Extras = make(map[string]any)
+			}
+			var value any
+			if err := json.Unmarshal(raw, &value); err != nil {
+				return c, err
+			}
+			c.Extras[key] = value
 		}
-		if c.Extras == nil {
-			c.Extras = make(map[string]any)
+	}
+	c.SpecVersion = SpecVersion
+
+	var dataRaw json.RawMessage
+	var dataBase64 string
+	if raw, ok := rawFields["data_base64"]; ok && len(raw) > 0 {
+		if err := json.Unmarshal(raw, &dataBase64); err != nil {
+			return c, err
 		}
-		var value any
-		if err := json.Unmarshal(rawValue, &value); err != nil {
+	}
+	if raw, ok := rawFields["data"]; ok {
+		dataRaw = raw
+	}
+	if dataRaw != nil || dataBase64 != "" {
+		if err := payloadFunc(dataRaw, dataBase64); err != nil {
 			return c, err
 		}
-		c.Extras[key] = value
 	}
 	return c, nil
 }
 
+// setHeaderField unmarshals raw into the CloudEventHeader field for key.
+func setHeaderField(c *CloudEventHeader, key string, raw json.RawMessage) error {
+	switch key {
+	case "id":
+		return json.Unmarshal(raw, &c.ID)
+	case "source":
+		return json.Unmarshal(raw, &c.Source)
+	case "producer":
+		return json.Unmarshal(raw, &c.Producer)
+	case "specversion":
+		return json.Unmarshal(raw, &c.SpecVersion)
+	case "subject":
+		return json.Unmarshal(raw, &c.Subject)
+	case "time":
+		return json.Unmarshal(raw, &c.Time)
+	case "type":
+		return json.Unmarshal(raw, &c.Type)
+	case "datacontenttype":
+		return json.Unmarshal(raw, &c.DataContentType)
+	case "dataschema":
+		return json.Unmarshal(raw, &c.DataSchema)
+	case "dataversion":
+		return json.Unmarshal(raw, &c.DataVersion)
+	case "signature":
+		return json.Unmarshal(raw, &c.Signature)
+	case "tags":
+		return json.Unmarshal(raw, &c.Tags)
+	default:
+		return nil
+	}
+}
+
 // ignoreDataField is a function that ignores the data field.
 // It is used when unmarshalling the CloudEventHeader so that the data field is not added to the Extras map.
 func ignoreDataField(json.RawMessage) error { return nil }
 
-// setDataField is a function that sets the data field.
-// It is used to unmarshal the data field into the CloudEvent[A].Data field.
-func (c *CloudEvent[A]) setDataField(data json.RawMessage) error {
-	return json.Unmarshal(data, &c.Data)
+// DecodeHeader parses only the CloudEvent header fields from JSON, skipping the data payload.
+// More efficient than unmarshaling a full event when only metadata is needed (e.g. for scaling).
+//
+// Equivalent to json.Unmarshal(data, &header) since CloudEventHeader.UnmarshalJSON
+// already ignores the data field, but provided as an explicit API for discoverability.
+func DecodeHeader(data []byte) (CloudEventHeader, error) {
+	var hdr CloudEventHeader
+	if err := json.Unmarshal(data, &hdr); err != nil {
+		return CloudEventHeader{}, err
+	}
+	return hdr, nil
 }