audit-go/audit/api/api.go

package api

import (
	"context"
	"time"

	auditV1 "dev.azure.com/schwarzit/schwarzit.stackit-core-platform/common-audit.git/gen/go/audit/v1"

	"github.com/google/uuid"
	"google.golang.org/protobuf/proto"
)

// AuditApi is the interface to log audit events.
//
// It provides a Log method that can be used to validate and directly send events.
// If the transactional outbox patter should be used, the ValidateAndSerialize and Send methods
// can be called manually to decouple operations.
type AuditApi interface {

	// Log is a convenience method that validates, serializes and sends data over the wire.
	// If the transactional outbox patter should be used, the ValidateAndSerialize method
	// and Send method can be called manually.
	//
	//  Parameters:
	//  * ctx - the context object
	//  * event - the auditV1.AuditEvent
	//  * visibility - route the event only internally or to the customer (not evaluated in the legacy solution)
	//  * routingIdentifier - the identifier for the AMQP-Topic selection (optional)
	//    * auditV1.ObjectType_OBJECT_TYPE_ORGANIZATION
	//    * auditV1.ObjectType_OBJECT_TYPE_PROJECT
	//  * objectIdentifier - the identifier of the object (optional - if not folder must be identical to routingIdentifier)
	//    * auditV1.ObjectType_OBJECT_TYPE_ORGANIZATION
	//    * auditV1.ObjectType_OBJECT_TYPE_FOLDER
	//    * auditV1.ObjectType_OBJECT_TYPE_PROJECT
	//
	// It may return one of the following errors:
	/*
		- ErrEventNil - if event is nil
		- ErrObjectIdentifierVisibilityMismatch - if object identifier and visibility are not in a valid state
		- ErrRoutableIdentifierMissing - if routing identifier type and object identifier type do not match
		- ErrRoutableIdentifierTypeMismatch - if routing identifier type and object identifier types are not compatible
		- ErrUnsupportedObjectIdentifierType - if an unsupported object identifier type was provided
		- ErrUnsupportedResourceReferenceType - if an unsupported resource reference type was provided
		- protovalidate.ValidationError - if schema validation errors have been detected
		- protobuf serialization errors - if the event couldn't be serialized
	*/
	Log(
		ctx context.Context,
		event *auditV1.AuditLogEntry,
		visibility auditV1.Visibility,
		routingIdentifier *RoutingIdentifier,
		objectIdentifier *auditV1.ObjectIdentifier,
	) error

	// ValidateAndSerialize validates and serializes the event into a byte representation.
	// The result has to be sent explicitly by calling the Send method.
	ValidateAndSerialize(
		event *auditV1.AuditLogEntry,
		visibility auditV1.Visibility,
		routingIdentifier *RoutingIdentifier,
		objectIdentifier *auditV1.ObjectIdentifier,
	) (*CloudEvent, error)

	// Send the serialized content as byte array to the audit log system.
	Send(
		ctx context.Context,
		routingIdentifier *RoutingIdentifier,
		serializedPayload *CloudEvent,
	) error
}

// ProtobufValidator is an abstraction for validators.
// Concrete implementations are e.g. protovalidate.Validator
type ProtobufValidator interface {
	Validate(msg proto.Message) error
}

// CloudEvent is a representation of a cloudevents.io object.
//
// More information about the schema and attribute semantics can be found here:
// https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#required-attributes
type CloudEvent struct {

	// The version of the CloudEvents specification which the event uses.
	// This enables the interpretation of the context. Compliant event producers MUST use a value of 1.0
	// when referring to this version of the specification.
	//
	// Currently, this attribute will only have the 'major' and 'minor' version numbers included in it.
	// This allows for 'patch' changes to the specification to be made without changing this property's
	// value in the serialization.
	specVersion string

	// The source system uri-reference. Producers MUST ensure that source + id is unique for each distinct event.
	source string

	// Identifier of the event. Producers MUST ensure that source + id is unique for each distinct event.
	// If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id.
	// Consumers MAY assume that Events with identical source and id are duplicates.
	id string

	// The time when the event happened
	time time.Time

	// The content type of the payload
	// Examples could be:
	//  - application/cloudevents+json
	//  - application/cloudevents+json; charset=UTF-8
	//  - application/cloudevents-batch+json
	//  - application/cloudevents+protobuf
	//  - application/cloudevents+avro
	// Source: https://github.com/cloudevents/spec/blob/main/cloudevents/formats/protobuf-format.md
	dataContentType string

	// The object type (i.e. the fully qualified protobuf type name)
	dataType string

	// The identifier of the referring object.
	subject string

	// The serialized payload
	data []byte
}

// RoutingIdentifierType is an enumeration of allowed identifier types.
type RoutingIdentifierType int

// RoutingIdentifierType enumeration values.
const (
	RoutingIdentifierTypeOrganization RoutingIdentifierType = 0
	RoutingIdentifierTypeProject      RoutingIdentifierType = 1
)

// RoutingIdentifier is a representation for identifiers of allowed types.
type RoutingIdentifier struct {
	Identifier uuid.UUID
	Type       RoutingIdentifierType
}

// TopicNameResolver is an abstraction for dynamic topic name resolution
// based on event data or api parameters.
type TopicNameResolver interface {

	// Resolve returns a topic name for the given routing identifier
	Resolve(routingIdentifier *RoutingIdentifier) (string, error)
}