events

package
v1.0.26 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 7, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package events provides primitives to interact with the openapi HTTP API.

Index

Constants

View Source 
const (
	ErrNotMeshkitErrorCode   = "meshkit-11337"
	ErrInvalidEventErrorCode = "meshkit-11338"
	ErrInvalidEventCode      = "meshkit-11339"
	ErrMintTraceContextCode  = "meshkit-11340"
)
View Source 
const MetadataErrorKey = "error"

MetadataErrorKey is the Event.Metadata key that carries an EventError.

View Source 
const SpecVersion10 = eventv1beta3.SpecVersion10

SpecVersion10 is CloudEvents 1.0, the only version the contract defines.

Variables

This section is empty.

Functions

func ErrInvalidEvent added in v1.0.25 

func ErrInvalidEvent(err error) error

ErrInvalidEvent is returned by Event.Validate when an event's correlation, provenance or trace fields break the schemas event construct.

func ErrInvalidEventError added in v1.0.25 

func ErrInvalidEventError(code string, err error) error

ErrInvalidEventError is returned when an event's metadata.error would break the schemas event construct's EventError contract.

func ErrMintTraceContext added in v1.0.25 

func ErrMintTraceContext(err error) error

ErrMintTraceContext is returned when a trace or span id cannot be minted.

func ErrNotMeshkitError added in v1.0.25 

func ErrNotMeshkitError(err error) error

ErrNotMeshkitError is returned when an event's metadata.error is built from an error that carries no MeshKit error code.

func NewSpanID added in v1.0.25 

func NewSpanID() (string, error)

NewSpanID mints a random W3C parent-id: 16 lowercase hex digits, never all zeros, naming one sub-operation.

func NewTraceID added in v1.0.25 

func NewTraceID() (string, error)

NewTraceID mints a random W3C trace-id: 32 lowercase hex digits, never all zeros. The client that starts an operation mints it once and sets it on every event of the operation.

Types

type CreatedAt 

type CreatedAt = time.Time

CreatedAt Timestamp when the resource was created.

type DeletedAt 

type DeletedAt = time.Time

DeletedAt Timestamp when the resource was deleted.

type Event 

type Event struct {
	// ActedUpon UUID of the entity on which the event was performed.
	ActedUpon core.Uuid `db:"acted_upon" json:"actedUpon"`

	// Action Action taken on the resource.
	Action string `db:"action" json:"action"`

	// Category Resource name on which the operation is invoked.
	Category string `db:"category" json:"category"`

	// CreatedAt Timestamp when the resource was created.
	CreatedAt CreatedAt `db:"created_at" json:"createdAt"`

	// DeletedAt Timestamp when the resource was deleted.
	DeletedAt *DeletedAt `db:"deleted_at" json:"deletedAt,omitempty"`

	// Description A summary/receipt of event that occurred.
	Description string `db:"description" json:"description"`
	ID          ID     `db:"id" json:"id"`

	// Metadata Contains meaningful information, specific to the type of event.
	// Structure of metadata can be different for different events.
	Metadata    map[string]interface{} `db:"metadata" json:"metadata" gorm:"type:bytes;serializer:json"`
	OperationID OperationID            `db:"operation_id" json:"operationId"`

	// Severity A set of seven standard event levels.
	Severity EventSeverity `db:"severity" json:"severity"`

	// Status Status for the event.
	Status   EventStatus `db:"status" json:"status"`
	SystemID SystemID    `db:"system_id" json:"systemId"`

	// UpdatedAt Timestamp when the resource was updated.
	UpdatedAt UpdatedAt `db:"updated_at" json:"updatedAt"`
	Owner     *Owner    `db:"owner" json:"owner,omitempty"`

	// CorrelationKey names the ongoing condition the event records, qualified by
	// source and component, for example
	// `meshery-server/k8s-connection/<id>/unreachable`. Never an error code alone.
	CorrelationKey *string `db:"correlation_key" json:"correlationKey,omitempty" gorm:"column:correlation_key"`
	// OccurrenceCount is how many occurrences of the condition the event reports
	// (on a create) or counts (on a stored event). At least 1.
	OccurrenceCount *int `db:"occurrence_count" json:"occurrenceCount,omitempty" gorm:"column:occurrence_count"`
	// FirstSeenAt is when the condition's first counted occurrence was seen.
	FirstSeenAt *time.Time `db:"first_seen_at" json:"firstSeenAt,omitempty" gorm:"column:first_seen_at"`
	// LastSeenAt is when the condition's latest counted occurrence was seen.
	LastSeenAt *time.Time `db:"last_seen_at" json:"lastSeenAt,omitempty" gorm:"column:last_seen_at"`
	// ResolvedAt is when the condition cleared; nil while it is open. An event
	// carrying CorrelationKey and ResolvedAt is a resolution event.
	ResolvedAt *time.Time `db:"resolved_at" json:"resolvedAt,omitempty" gorm:"column:resolved_at"`
	// Source is which surface emitted the event, for example `meshery-server`,
	// `meshery-ui`, `mesheryctl` or `meshery-adapter-istio` (a CloudEvents source).
	Source *string `db:"source" json:"source,omitempty" gorm:"column:source"`
	// Type is the CloudEvents-compatible type, for example `io.meshery.user.signup`.
	// It sits beside Category and Action and does not replace them.
	Type *string `db:"type" json:"type,omitempty" gorm:"column:type"`
	// SpecVersion is the CloudEvents version the event is compatible with (`1.0`).
	SpecVersion *EventSpecVersion `db:"specversion" json:"specversion,omitempty" gorm:"column:specversion"`
	// TraceID is the W3C Trace Context trace-id of the operation (32 lowercase hex).
	TraceID *string `db:"trace_id" json:"traceId,omitempty" gorm:"column:trace_id"`
	// ParentID is the W3C Trace Context parent-id of the sub-operation that
	// emitted the event (16 lowercase hex).
	ParentID *string `db:"parent_id" json:"parentId,omitempty" gorm:"column:parent_id"`
}

Event Defines model for event_trackers

func DesignDownloadEvent added in v0.8.46 

func DesignDownloadEvent(designID core.Uuid, designName string, userID core.Uuid, systemID core.Uuid) *Event

func DesignViewEvent added in v0.8.46 

func DesignViewEvent(designID core.Uuid, designName string, userID core.Uuid, systemID core.Uuid) *Event

func (*Event) BeforeCreate 

func (e *Event) BeforeCreate(tx *gorm.DB) (err error)

BeforeCreate keeps the ID the producer minted (NewEvent mints one) and assigns one only when the event was constructed without the builder.

func (*Event) BeforeUpdate 

func (e *Event) BeforeUpdate(tc *gorm.DB) (err error)

func (*Event) Validate added in v1.0.25 

func (ev *Event) Validate() error

Validate checks the event's optional correlation, provenance and trace fields, and its `metadata.error` when that is an EventError or a decoded object in the EventError shape, against the schemas event construct. An event that sets none of them is valid. It returns ErrInvalidEvent listing every violation.

type EventBuilder 

type EventBuilder struct {
	// contains filtered or unexported fields
}

func NewEvent 

func NewEvent() *EventBuilder

NewEvent starts an event with its ID and OperationID minted (uuid v4), CreatedAt set to now and Status Unread. The producer mints the ID here, at construction, so a copy broadcast before or instead of the stored row carries the same non-nil ID the row is persisted with.

func (*EventBuilder) ActedUpon 

func (e *EventBuilder) ActedUpon(resource core.Uuid) *EventBuilder

func (*EventBuilder) Build 

func (e *EventBuilder) Build() *Event

func (*EventBuilder) FromOwner added in v1.0.13 

func (e *EventBuilder) FromOwner(id core.Uuid) *EventBuilder

func (*EventBuilder) FromSystem 

func (e *EventBuilder) FromSystem(id core.Uuid) *EventBuilder

func (*EventBuilder) Resolves added in v1.0.25 

func (e *EventBuilder) Resolves(correlationKey string, at time.Time) *EventBuilder

Resolves makes the event the resolution of the condition named by correlationKey, cleared at the given time. Following the contract's resolution convention, also set the condition's category and a severity and description that say what cleared, for example Success and "Connection to cluster prod-1 restored". Send it only when the condition changes from present to cleared, never on every healthy check.

func (*EventBuilder) WithAction 

func (e *EventBuilder) WithAction(eventAction string) *EventBuilder

func (*EventBuilder) WithCategory 

func (e *EventBuilder) WithCategory(eventCategory string) *EventBuilder

func (*EventBuilder) WithCorrelationKey added in v1.0.25 

func (e *EventBuilder) WithCorrelationKey(key string) *EventBuilder

WithCorrelationKey sets the key of the ongoing condition this event records an occurrence of. Qualify it by source and component, then subject and kind of condition, for example `meshery-server/k8s-connection/<id>/unreachable`; never use an error code alone.

func (*EventBuilder) WithDescription 

func (e *EventBuilder) WithDescription(description string) *EventBuilder

func (*EventBuilder) WithError added in v1.0.25 

func (e *EventBuilder) WithError(err error, matched ...EventMatchedCause) (*EventBuilder, error)

WithError sets the event's `metadata.error` from err with NewEventError, naming matched as the likely causes. It returns the error NewEventError returns, leaving the event unchanged, so a producer decides what to do with an error it cannot attach (for example, keep err.Error() in the description).

func (*EventBuilder) WithEventError added in v1.0.25 

func (e *EventBuilder) WithEventError(ee EventError) *EventBuilder

WithEventError sets the event's `metadata.error`, keeping every other metadata key. Call it after WithMetadata, which replaces the whole map.

func (*EventBuilder) WithFirstSeenAt added in v1.0.25 

func (e *EventBuilder) WithFirstSeenAt(at time.Time) *EventBuilder

WithFirstSeenAt sets when the condition's first reported occurrence was seen.

func (*EventBuilder) WithLastSeenAt added in v1.0.25 

func (e *EventBuilder) WithLastSeenAt(at time.Time) *EventBuilder

WithLastSeenAt sets when the condition's latest reported occurrence was seen.

func (*EventBuilder) WithMetadata 

func (e *EventBuilder) WithMetadata(metadata map[string]interface{}) *EventBuilder

func (*EventBuilder) WithOccurrenceCount added in v1.0.25 

func (e *EventBuilder) WithOccurrenceCount(count int) *EventBuilder

WithOccurrenceCount sets how many occurrences of the condition this event reports (default 1 when unset). It must be at least 1; Validate checks it.

func (*EventBuilder) WithOperationID added in v1.0.25 

func (e *EventBuilder) WithOperationID(id core.Uuid) *EventBuilder

WithOperationID sets the id that groups the events of one operation, replacing the random one NewEvent mints. Every event of an operation carries the same OperationID.

func (*EventBuilder) WithResolvedAt added in v1.0.25 

func (e *EventBuilder) WithResolvedAt(at time.Time) *EventBuilder

WithResolvedAt sets when the condition cleared. Together with WithCorrelationKey it makes the event a resolution event; see Resolves.

func (*EventBuilder) WithSeverity 

func (e *EventBuilder) WithSeverity(severity EventSeverity) *EventBuilder

func (*EventBuilder) WithSource added in v1.0.25 

func (e *EventBuilder) WithSource(source string) *EventBuilder

WithSource sets which surface emitted the event, for example `meshery-server`, `meshery-ui`, `mesheryctl` or `meshery-adapter-istio`.

func (*EventBuilder) WithSpecVersion added in v1.0.25 

func (e *EventBuilder) WithSpecVersion(version EventSpecVersion) *EventBuilder

WithSpecVersion sets the CloudEvents version the event is compatible with. Set SpecVersion10 when the producer sets Source, Type and ID as CloudEvents attributes.

func (*EventBuilder) WithStatus 

func (e *EventBuilder) WithStatus(status EventStatus) *EventBuilder

func (*EventBuilder) WithTraceContext added in v1.0.25 

func (e *EventBuilder) WithTraceContext(traceID, parentID string) *EventBuilder

WithTraceContext sets the W3C Trace Context of the event: traceID (32 lowercase hex digits) names the user-level operation and is the same on every event of it, and parentID (16 lowercase hex digits) names the sub-operation that emitted this event. An empty parentID leaves ParentID unset. Mint them with NewTraceID and NewSpanID, or take them from an OpenTelemetry span with WithTraceContextFrom.

func (*EventBuilder) WithTraceContextFrom added in v1.0.25 

func (e *EventBuilder) WithTraceContextFrom(ctx context.Context) *EventBuilder

WithTraceContextFrom sets TraceID and ParentID from the OpenTelemetry span in ctx, so the event joins the trace the operation records. It leaves them unchanged when ctx carries no valid span context.

func (*EventBuilder) WithType added in v1.0.25 

func (e *EventBuilder) WithType(eventType string) *EventBuilder

WithType sets the CloudEvents-compatible type, a reverse-DNS name such as `io.meshery.user.signup`. Category and Action stay as they are.

type EventError added in v1.0.25 

type EventError = eventv1beta3.EventError

EventError is the schemas event construct's `metadata.error` shape: one occurrence of an error definition (docs/error-definition-contract.md in meshery/schemas). Build one from a MeshKit error with NewEventError.

func NewEventError added in v1.0.25 

func NewEventError(err error, matched ...EventMatchedCause) (EventError, error)

NewEventError builds the `metadata.error` of an event that reports err, a MeshKit error: its code, its severity, its short and long descriptions as rendered for this occurrence, and its causes. matched names the causes most likely this time, most likely first.

For an error created with errors.NewV3 it carries the nested probableCauses and the flat lists derived from them, and each matched cause must be one of them. For an errors.New or errors.NewV2 error it carries the flat lists alone (an unpaired error), and matched cause ids are kept as given.

The caller may then set Component, ReferenceURL and Details (instance values, never secrets, credentials, design contents or request bodies) before attaching it with EventBuilder.WithEventError.

It returns ErrNotMeshkitError when err carries no MeshKit error code, and ErrInvalidEventError when the result breaks the schemas contract.

type EventMatchedCause added in v1.0.25 

type EventMatchedCause = eventv1beta3.EventMatchedCause

EventMatchedCause names one cause of an EventError as likely for this occurrence. Build one with MatchCause or MatchCauseWithConfidence.

func MatchCause added in v1.0.25 

func MatchCause(causeID string) EventMatchedCause

MatchCause names the cause with the given id as likely for this occurrence.

func MatchCauseWithConfidence added in v1.0.25 

func MatchCauseWithConfidence(causeID string, confidence float32) EventMatchedCause

MatchCauseWithConfidence names the cause with the given id as likely for this occurrence, with how sure the producer is, from 0 (a guess) to 1 (certain).

type EventSeverity 

type EventSeverity string

EventSeverity A set of seven standard event levels. 

const (
	Alert         EventSeverity = "alert"
	Critical      EventSeverity = "critical"
	Debug         EventSeverity = "debug"
	Emergency     EventSeverity = "emergency"
	Error         EventSeverity = "error"
	Informational EventSeverity = "informational"
	Warning       EventSeverity = "warning"
	Success       EventSeverity = "success"
)

Defines values for EventSeverity.

type EventSpecVersion added in v1.0.25 

type EventSpecVersion = eventv1beta3.EventSpecVersion

EventSpecVersion is the schemas event construct's CloudEvents spec version.

type EventStatus 

type EventStatus string

EventStatus Status for the event. 

const (
	Read   EventStatus = "read"
	Unread EventStatus = "unread"
)

Defines values for EventStatus.

type EventsFilter 

type EventsFilter struct {
	Action   []string `json:"action"`
	Category []string `json:"category"`
	Limit    int      `json:"limit"`
	Offset   int      `json:"offset"`

	// Order order of sort asc/desc, default is asc
	Order    string      `json:"order"`
	Provider []string    `json:"provider"`
	Search   string      `json:"search"`
	Status   EventStatus `json:"status"`
	Severity []string    `json:"severity"`
	// SortOn Field on which records are sorted
	SortOn string `json:"sortOn"`

	// ActedUpon UUID of the entity on which the event was performed.
	ActedUpon []string `json:"actedUpon"`

	// Owner UUIDs of owners to filter events by.
	Owner []string `json:"owner"`

	// SystemID UUIDs of systems to filter events by.
	SystemID []string `json:"systemId"`
}

EventsFilter defines model for events_filter.

type ID 

type ID = core.Uuid

ID defines model for id.

type OperationID 

type OperationID = core.Uuid

OperationID defines model for operation_id.

type Owner added in v1.0.13 

type Owner = core.Uuid

Owner defines model for owner uuid.

type SystemID 

type SystemID = core.Uuid

SystemID defines model for system_id.

type Time 

type Time = time.Time

Time defines model for time.

type UpdatedAt 

type UpdatedAt = time.Time

UpdatedAt Timestamp when the resource was updated.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.