eventsapi

README

PagerDuty Agent: Eventsapi Package

A minimal client library for PagerDuty's Events API V1 and V2.

The basic API consists of sending an EventV1 or EventV2 to Enqueue which then automatically determines how and where to send the corresponding event based on version.

For example usage see:

• The eventsapi package.

Documentation

Index

• Variables
• type AgentContext
• type BaseResponse
  • func (br *BaseResponse) GetHTTPResponse() *http.Response
  • func (br *BaseResponse) SetHTTPResponse(resp *http.Response)
• type ContextV1
• type DetailsV1
• type EnqueueOption
  • func WithHTTPClient(client *http.Client) EnqueueOption
• type Event
• type EventContainer
  • func (ec *EventContainer) UnmarshalEvent() (Event, error)
• type EventV1
  • func (e *EventV1) GetRoutingKey() string
  • func (e *EventV1) Validate() error
  • func (e *EventV1) Version() EventVersion
• type EventV2
  • func (e *EventV2) GetRoutingKey() string
  • func (e *EventV2) Validate() error
  • func (e *EventV2) Version() EventVersion
• type EventVersion
  • func (ev EventVersion) String() string
• type ImageV2
• type LinkV2
• type PayloadV2
• type Response
  • func Enqueue(context context.Context, eventContainer *EventContainer, ...) (Response, error)
• type ResponseV1
  • func CreateV1(context context.Context, client *http.Client, event *EventV1) (*ResponseV1, error)
• type ResponseV2
  • func EnqueueV2(context context.Context, client *http.Client, event *EventV2) (*ResponseV2, error)

Variables

var DefaultHTTPClient *http.Client

var ErrAPIError = errors.New("an API error was encountered while processing events")

var ErrInvalidRoutingKey = errors.New("invalid routing key")

var ErrUnrecognizedEventType = errors.New("unrecognized event type")

ErrUnrecognizedEventType occurs when an event isn't supported by the events API.

var StringToEventVersion = map[string]EventVersion{
	"v1": EventVersion1,
	"v2": EventVersion2,
}

Types

type AgentContext

type AgentContext struct {
	QueuedBy string `json:"queued_by"`
	QueuedAt string `json:"queued_at"`
	AgentId  string `json:"agent_id"`
}

AgentContext is used for pdagent integrations

type BaseResponse

type BaseResponse struct {
	HTTPResponse *http.Response
	// contains filtered or unexported fields
}

BaseResponse is a minimal implementation of the `Response` interface.

func (*BaseResponse) GetHTTPResponse

func (br *BaseResponse) GetHTTPResponse() *http.Response

func (*BaseResponse) SetHTTPResponse

func (br *BaseResponse) SetHTTPResponse(resp *http.Response)

SetHTTPResponse sets `HTTPResponse` on a response.

type ContextV1

type ContextV1 struct {
	Type   string `json:"type"`
	Href   string `json:"href"`
	Text   string `json:"text,omitempty"`
	Source string `json:"src"`
	Alt    string `json:"alt,omitempty"`
}

ContextV1 corresponds to a V1 context object.

Technically this can either be a `link` or `image` context type, but currently representing as a single type for convenience.

type DetailsV1

type DetailsV1 map[string]interface{}

DetailsV1 corresponds to a V1 details object.

type EnqueueOption

type EnqueueOption func(*enqueueConfig)

func WithHTTPClient

func WithHTTPClient(client *http.Client) EnqueueOption

WithHTTPClient is an option for use in conjunction with Enqueue allowing a user to override our default HTTP client with their own.

type Event

type Event interface {
	GetRoutingKey() string
	Validate() error
	Version() EventVersion
}

type EventContainer

type EventContainer struct {
	EventVersion EventVersion
	EventData    json.RawMessage
}

func (*EventContainer) UnmarshalEvent

func (ec *EventContainer) UnmarshalEvent() (Event, error)

type EventV1

type EventV1 struct {
	ServiceKey  string       `json:"service_key"`
	EventType   string       `json:"event_type"`
	IncidentKey string       `json:"incident_key,omitempty"`
	Description string       `json:"description"`
	Details     DetailsV1    `json:"details,omitempty"`
	Client      string       `json:"client,omitempty"`
	ClientURL   string       `json:"client_url,omitempty"`
	Contexts    []ContextV1  `json:"contexts,omitempty"`
	Agent       AgentContext `json:"agent,omitempty"`
}

EventV1 corresponds to a V1 event object.

func (*EventV1) GetRoutingKey

func (e *EventV1) GetRoutingKey() string

func (*EventV1) Validate

func (e *EventV1) Validate() error

func (*EventV1) Version

func (e *EventV1) Version() EventVersion

type EventV2

type EventV2 struct {
	RoutingKey  string    `json:"routing_key"`
	EventAction string    `json:"event_action"`
	DedupKey    string    `json:"dedup_key,omitempty"`
	Payload     PayloadV2 `json:"payload"`
	Client      string    `json:"client,omitempty"`
	ClientUrl   string    `json:"client_url,omitempty"`
	Images      []ImageV2 `json:"images,omitempty"`
	Links       []LinkV2  `json:"links,omitempty"`
}

EventV2 corresponds to a V2 event object.

func (*EventV2) GetRoutingKey

func (e *EventV2) GetRoutingKey() string

func (*EventV2) Validate

func (e *EventV2) Validate() error

func (*EventV2) Version

func (e *EventV2) Version() EventVersion

type EventVersion

type EventVersion string

var EventVersion1 EventVersion = "v1"

var EventVersion2 EventVersion = "v2"

func (EventVersion) String

func (ev EventVersion) String() string

type ImageV2

type ImageV2 struct {
	Source string `json:"src"`
	Href   string `json:"href,omitempty"`
	Alt    string `json:"alt,omitempty"`
}

ImageV2 corresponds to a V2 image object.

type LinkV2

type LinkV2 struct {
	Href string `json:"href"`
	Text string `json:"text"`
}

LinkV2 corresponds to a V2 link object.

type PayloadV2

type PayloadV2 struct {
	Summary       string                 `json:"summary"`
	Source        string                 `json:"source"`
	Severity      string                 `json:"severity"`
	Timestamp     string                 `json:"timestamp,omitempty"`
	Component     string                 `json:"component,omitempty"`
	Group         string                 `json:"group,omitempty"`
	Class         string                 `json:"class,omitempty"`
	CustomDetails map[string]interface{} `json:"custom_details,omitempty"`
}

PayloadV2 corresponds to a V2 payload object.

type Response

type Response interface {
	GetHTTPResponse() *http.Response
	SetHTTPResponse(*http.Response)
}

Response defines a minimal interface for the events APIs' HTTP responses.

func Enqueue

func Enqueue(context context.Context, eventContainer *EventContainer, options ...EnqueueOption) (Response, error)

Enqueue an event to either the V1 or V2 events API depending on event type.

type ResponseV1

type ResponseV1 struct {
	BaseResponse

	Status      string   `json:"status,omitempty"`
	Message     string   `json:"message,omitempty"`
	IncidentKey string   `json:"incident_key,omitempty"`
	Errors      []string `json:"errors,omitempty"`
}

ResponseV1 corresponds to a V1 response.

func CreateV1

func CreateV1(context context.Context, client *http.Client, event *EventV1) (*ResponseV1, error)

CreateV1 sends an event to explicitly the Events API V1.

Keeping the `create` semantics versus `enqueue` to more closely match the service's own.

type ResponseV2

type ResponseV2 struct {
	BaseResponse

	Status   string   `json:"status,omitempty"`
	Message  string   `json:"message,omitempty"`
	DedupKey string   `json:"dedupkey,omitempty"`
	Errors   []string `json:"errors,omitempty"`
}

ResponseV2 corresponds to a V2 response object.

func EnqueueV2

func EnqueueV2(context context.Context, client *http.Client, event *EventV2) (*ResponseV2, error)

EnqueueV2 sends an event explicitly to the Events API V2.