types

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2024 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package types provides the types used in the ARN service on the wire.

The basics are that you send an Event to the ARN service. That Event may carry the data inline or detail where to find the data in blob storage.

Any field with omitzero tag is optional, however depending other fields being set might be required.

EventMeta is the metadata of the event. This is inlined during Marshaling.

ArmResource is where you store the resource data from your service. You may need to have an agreed on schema with the ARN service. This object must serialize out a field called "id" that is the resource ID. During delete events, all object properties other than id will be missing.

Index

Constants

View Source 
const (
	// StatusCode is the HTTP status code of the operation. As a producer, this is always "OK".
	StatusCode = "OK"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Activity 

type Activity uint8

Activity is the type of activity that is being performed on ARN (not the resource itself). 

const (
	// ActUnknown indicates that the activity was not provided. This is a bug.
	ActUnknown Activity = 0 //
	// ActWrite indicates that the resource is being created or updated.
	// in ARN.
	ActWrite Activity = 1 // write
	// ActDelete indicates that the resource is being deleted in ARN.
	ActDelete Activity = 2 // delete
	// ActSnapshot indicates that the resource is being snapshotted. A snapshot
	// is when no update has been seen, but we want to ensure that the
	// resource is still present.
	ActSnapshot Activity = 3 // snapshot
)

func (Activity) MarshalJSON 

func (a Activity) MarshalJSON() ([]byte, error)

MarshalJSON marshals the value to its JSON string. This uses an unsafe conversion to avoid allocations. Do not change the []byte that is returned.

func (Activity) String 

func (i Activity) String() string

type AdditionalBatchProperties 

type AdditionalBatchProperties struct {
	// BatchCorrelationID is a unique identifier for the batch of notifications. This can be used by
	// ARN or ARG in traces. This is a GUID. Optional.
	BatchCorrelationID string `json:"batchCorrelationId"`
	// SDKVersion is the version of the SDK that is sending the notification.
	// This is automaticallly set by the SDK.
	SDKVersion string `json:"sdkVersion"`
	// BatchSize is the number of resources in the batch. These may be inline or in a blob. This is
	// automatically set by the SDK.
	BatchSize uint16 `json:"batchSize"`
	// Others is a map of additional properties that are provided by the user. These should not
	// include keys that are already defined in the struct. These entries are inlined into the
	// object when serialized.
	Others map[string]any `json:",inline"`
}

AdditionalBatchProperties is the additional properties that can be set on a batch of notifications.

type ArmResource 

type ArmResource struct {
	// Properties is the properties of the resource. This must serialize to a JSON dictionary that
	// stores the properties of the resource. This is where your specific resource data is stored.
	// This can be nil if the Activity that is being performed is a delete.
	// If we were storing AKS node data for this event, this would be the node data.
	Properties any `json:"properties,omitzero"`
	// Name is the name of the resource. This is the last segment of the resource ID.
	Name string `json:"name,omitzero"`
	// Type
	Type string `json:"type,omitzero"`
	// ID is the resource ID.
	ID string `json:"id"`
	// Location is the location of the resource, like "eastus".
	Location string `json:"location,omitzero"`
	// APIVersion is the API version of the resource data schema. This is in the format of "yyyy-MM-dd"
	// followed by an optional string like "-preview", "-privatepreview", etc.
	APIVersion string `json:"apiVersion,omitzero"`
	// contains filtered or unexported fields
}

ArmResource is the generic resource (even though it is named ArmResource). In the case of delete events, all object properties other than ID and Location will be missing. Properties is where you store your custom resource data that describes the resource in the format agreed to with the ARN service. Use NewArmResource to create a new ArmResource. Field-aligned.

func NewArmResource 

func NewArmResource(act Activity, id *arm.ResourceID, apiVersion string, props any) (ArmResource, error)

NewArmResource creates a new ArmResource. act is the activity that is being performed on the resource. id is the resource ID. apiVer is the API version of the resource data schema. props is the properties of the resource. See ArmResource for more details.

func (ArmResource) Activity 

func (a ArmResource) Activity() Activity

Activity returns the activity that is being performed on the resource.

func (ArmResource) ResourceID 

func (a ArmResource) ResourceID() *arm.ResourceID

ResourceID returns an arm.ResourceID object representing the resource.

func (ArmResource) Validate 

func (a ArmResource) Validate() error

Validate validates the ArmResource. act is the activity that is being performed on the resource.

type ChangeAction 

type ChangeAction uint8

ChangeAction is the type of change that is being performed on a resource, not on ARN (which is what is indicated by Activity). 

const (
	// CAUknownn indicates that the change action was not provided. This
	// is a bug.
	CAUnknown ChangeAction = 0 // ""
	// CACreate indicates that the resource is being created at source.
	CACreate ChangeAction = 1 // "Create"
	// CADelete indicates that the resource is being deleted at source.
	CADelete ChangeAction = 2 // "Delete"
	// CAMove indicates that the resource is being moved at source.
	CAMove ChangeAction = 3 // "Move"
	// CAUpdate indicates that the resource is being updated at source.
	CAUpdate ChangeAction = 4 // "Update"
)

func (ChangeAction) MarshalJSON 

func (c ChangeAction) MarshalJSON() ([]byte, error)

MarshalJSON marshals the value to its JSON string. This uses an unsafe conversion to avoid allocations. Do not change the []byte that is returned.

func (ChangeAction) String 

func (i ChangeAction) String() string

type Data 

type Data struct {
	// Data is where the serialized resources are stored. Do not populate this as it will be erased.
	// This is a JSON serialized version of the Resources field.
	Data json.RawMessage `json:"resources"`
	// AdditionalBatchProperties can contain the sdkversion, batchsize, subscription partition tag etc.
	AdditionalBatchProperties AdditionalBatchProperties `json:"additionalBatchProperties"`
	// ResourcesBlobInfo is the information about the storage blob used to store the payload of resources included in this notification.
	// Populated only when a blob is used, in which case ResourcesContainer is set to Blob.
	ResourcesBlobInfo ResourcesBlobInfo `json:"resourcesBlobInfo,omitzero"`
	// HomeTenantID is the Tenant ID of the tenant from which the resources in this notification are managed.
	HomeTenantID string `json:"homeTenantId,omitzero"`
	// ResourceHomeTenantID is the Tenant ID of the tenant in which the resources in this notification are located.
	ResourceHomeTenantID string `json:"resourceHomeTenantId,omitzero"`
	// ResourceLocation is the location of the resources in this notification. This is the normalized ARM location enum
	// like "eastus".
	ResourceLocation string `json:"resourceLocation"`
	// FrontdoorLocation is the ARM region that emitted the notification. Omitted for notifications not emitted by ARM.
	FrontdoorLocation string `json:"frontdoorLocation,omitzero"`
	// PublisherInfo is the Namespace of the publisher sending the data of this notification, for example Microsoft.Resources is be the publisherInfo for ARM.
	PublisherInfo string `json:"publisherInfo"`
	// Sign is set by ARN, do not populate as a publisher.
	Sign string `json:"-"`
	// RoutingType is set by ARN, do not populate as a publisher.
	RoutingType string `json:"-"`
	// APIVersion is the APIVersion in the format of "yyyy-MM-dd" follwed by an optional string like "-preview", "-privatepreview", etc.
	// This is optional, however, if not set here, must be set on
	APIVersion string `json:"apiVersion,omitzero"`
	// Resources is required for inline payload, only null if payload is in blob. While it
	// is not directly emitted as JSON, we serialize this and store it in the Data field.
	Resources []NotificationResource `json:"-"`
	// ResourcesContainer details if the resources are inline or in a blob.
	// This is either RCInline or RCBlob.
	ResourcesContainer ResourcesContainer `json:"resourcesContainer,omitzero"`
	// DataBoundary is the boundary for the resources included in the notification.
	DataBoundary string `json:"dataBoundary,omitzero"`
}

Data represents the data of the event. THIS IS NOT USED DIRECTLY, BUT INSTEAD IS CREATED BY msgs.Notification. THIS IS PUBLIC TO ALLOW FOR MARSHALING. NOT ALL FIELDS ARE CURRENTLY EXPOSED. There are two ways to send the data: 1. Inline: The resources being are included in the Resources field. 2. Blob: The resources are stored in a blob and the information about the blob is included in ResourcesBlobInfo. The ResourcesContainer field is used to determine if the resources are inline or in a blob. Any field with omitzero tag is optional, however depending on the ResourcesContainer field, some fields might be required. Field-aligned.

func (Data) Validate 

func (d Data) Validate() error

Validate validates the data. TODO: Add more validation for omitzero fields when they are set. TODO: Need to write some tests for this.

type DataBoundary 

type DataBoundary uint8

DataBoundary is the boundary of the data that is being processed. 

const (
	DBUnknown DataBoundary = 0 // ""
	// DataBoundary is the whole world.
	DBGlobal DataBoundary = 1 // "global"
	// DataBoundary is select locations in the EU.
	DBEU DataBoundary = 2 // "eu"
)

func (DataBoundary) MarshalJSON 

func (d DataBoundary) MarshalJSON() ([]byte, error)

MarshalJSON marshals the value to its JSON string. This uses an unsafe conversion to avoid allocations. Do not change the []byte that is returned.

func (DataBoundary) String 

func (i DataBoundary) String() string

type NotificationResource 

type NotificationResource struct {
	// ResourceEventTime is the time of the resource event.
	ResourceEventTime time.Time `json:"resourceEventTime,omitzero" format:"RFC3339"`
	// ArmResource is the ARM resource. This is where your specific resource data is stored.
	// While it says Arm, it can be other resource types.
	// For delete events all object properties other than id will be missing.
	ArmResource ArmResource `json:"armResource,omitzero"`
	// AdditionalResourceProperties is a dictionary of additional resource metadata.
	AdditionalResourceProperties map[string]string `json:"additionalResourceProperties,omitzero"`
	// ResourceID is the ARM resource ID.
	// This is in the form of "="/subscriptions/{subId}/resourceGroups/{rgName}/providers/{providerNamespace}/{resourceType}/{resourceName}".
	ResourceID string `json:"resourceId"`
	// APIVersion is the version of the resource schema used to encode the resource payload in armResource.
	// APIVersion in the format of "yyyy-MM-dd" follwed by an optional string like "-preview", "-privatepreview", etc.
	// When not specified here it must be specified in NotificationDataV3.
	APIVersion string `json:"apiVersion,omitzero"`
	// SourceResourceID has the resource ID of the source resource for the move event.
	SourceResourceID string `json:"sourceResourceId,omitzero"`
	// CorrelationID is the correlation identifier associated with the operation that resulted in the activity
	// reflected in the notification. This is normally a GUID.
	CorrelationID string `json:"correlationId,omitzero"`
	// StatusCode is the HTTP status code of the operation. As a producer, this is always "OK" set by StatusCode constant.
	// This is automatically set.
	StatusCode string `json:"statusCode,omitzero"` // "OK" or "BADRequest"
	// HomeTenantID is the tenant ID of the home tenant of the resource.
	// This is optional except for provider scoped resources. It can also be specified
	// at the Data level. If so, these should match.
	HomeTenantID string `json:"homeTenantId,omitzero"`
	// ResourceHomeTenantID is an optiona field with no definition.
	ResourceHomeTenantID string `json:"resourceHomeTenantId,omitzero"`
	// ResourceSystemProperties provides details about the change action, who created and modified the resource, and when.
	ResourceSystemProperties ResourceSystemProperties `json:"resourceSystemProperties,omitzero"`
	// OperationalInfo is operational information for this resource.
	OperationalInfo OperationalInfo `json:"operationalInfo,omitzero"`
}

NotificationResource is the resource payload. Note that HomeTenantID, ResourceHomeTenantID, APIVersion have been removed as they are just duplicates of the Data fields that are required to be the same. Field-aligned.

func (NotificationResource) Validate 

func (n NotificationResource) Validate() error

Validate validates the NotificationResource.

type OperationalInfo 

type OperationalInfo struct{}

OperationalInfo is operational information for this resource. It is defined in the schema but has no definition.

type ResourceSystemProperties 

type ResourceSystemProperties struct {
	// CreatedTime is the create time of the resource.
	CreatedTime time.Time `json:"createdTime,omitzero" format:"RFC3339"`
	// Modified time of the resource.
	ModifiedTime time.Time `json:"modifiedTime,omitzero" format:"RFC3339"`
	// CreatedBy is the entity that created this resource, can be object id, alias, display name etc.
	CreatedBy string `json:"createdBy"`
	// ModifiedBy is the entity that last modified this resource, can be object id, alias, display name etc.
	ModifiedBy string `json:"modifiedBy"`
	// ChangeAction is the type of event action for this resource event, currently supported ones are Create, Update, Delete, Move.
	ChangeAction ChangeAction `json:"changeAction"`
}

ResourceSystemProperties provides details about the change action, who created and modified the resource, and when. This is field-aligned.

func (ResourceSystemProperties) Validate 

func (r ResourceSystemProperties) Validate() error

Validate validates the ResourceSystemProperties.

type ResourcesBlobInfo 

type ResourcesBlobInfo struct {
	// BlobURI is the the Blob uri with SAS (shared access signature) for the reader to
	// be able to have access to download the data and parse into NotificationResourceData objects.
	BlobURI string `json:"blobUri"`
	// BlobSize is the size in bytes of the blob payload content.
	BlobSize int64 `json:"blobSize"`
}

ResourcesBlobInfo is the information about the storage blob used to store the payload of resources included in this notification.

func (*ResourcesBlobInfo) Validate 

func (r *ResourcesBlobInfo) Validate() error

Validate validates the ResourcesBlobInfo.

type ResourcesContainer 

type ResourcesContainer uint8

ResourcesContainer details if the resources are inline or stored in a blob. 

const (
	// RCUnknown is the default value, which tells the server to use inline.
	RCUnknown ResourcesContainer = 0 // ""
	// RCInline is the value to use when the resources are inline.
	RCInline ResourcesContainer = 1 // "inline"
	// RCBlob is the value to use when the resources are stored in a blob.
	RCBlob ResourcesContainer = 2 // "blob"
)

func (ResourcesContainer) MarshalJSON 

func (r ResourcesContainer) MarshalJSON() ([]byte, error)

MarshalJSON marshals the value to its JSON string. This uses an unsafe conversion to avoid allocations. Do not change the []byte that is returned.

func (ResourcesContainer) String 

func (i ResourcesContainer) String() string

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.