alarmaction

Documentation

Overview

Package alarmaction delivers CloudWatch alarm state transitions to whatever the alarm's action ARNs name.

It is the "an alarm changed state → notify its actions" seam, extracted as a standalone package rather than buried inside internal/services/cloudwatch so that a second service can both consume transitions and own a target type without either service importing the other. Auto Scaling (#474) is the intended next consumer: a target-tracking or step-scaling policy ARN appears in an alarm's AlarmActions, and Auto Scaling claims it with Dispatcher.Register("autoscaling", …) — see the package example in alarmaction_test.go. This mirrors what internal/eventtarget does for EventBridge rule targets (#467).

Delivery goes through the emulator's own root router rather than through per-service Go interfaces, so an SNS notification takes exactly the path an SDK client's Publish would: a missing topic produces SNS's own AWS error instead of a silent no-op, which is what makes an undelivered action reportable at all.

Nothing here blocks or does I/O at construction time: NewDispatcher only stores handles.

Index

• Constants
• type Dispatcher
  • func NewDispatcher(router http.Handler, defaultRegion string, bus *events.Bus, log *zap.Logger) *Dispatcher
  • func (d *Dispatcher) Dispatch(ctx context.Context, t Transition) []Outcome
  • func (d *Dispatcher) Register(service string, h Handler)
• type Handler
• type Outcome
• type Transition

Constants

const TimestampLayout = "2006-01-02T15:04:05.000-0700"

TimestampLayout is the millisecond-precision UTC layout AWS uses in alarm notification bodies and StateReasonData documents.

Types

type Dispatcher

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

Dispatcher fans an alarm transition out to its action ARNs, and publishes the state-change event real CloudWatch publishes.

The zero value is not usable; construct one with NewDispatcher. A Dispatcher is safe for concurrent use.

func NewDispatcher

func NewDispatcher(router http.Handler, defaultRegion string, bus *events.Bus, log *zap.Logger) *Dispatcher

NewDispatcher returns a Dispatcher delivering through router — the emulator's root handler. defaultRegion is used when neither the request context nor the transition names one. bus and log may be nil; delivery still works, it is just not observable.

func (*Dispatcher) Dispatch

func (d *Dispatcher) Dispatch(ctx context.Context, t Transition) []Outcome

Dispatch publishes t's state-change event and delivers t to each of its action ARNs, returning one Outcome per ARN in the order they were configured. It never returns an error of its own: an alarm transition has already happened by the time this runs, so a failed action is reported, not unwound.

A nil Dispatcher is a no-op, which is what makes the CloudWatch service usable in unit tests that never wire one.

func (*Dispatcher) Register

func (d *Dispatcher) Register(service string, h Handler)

Register claims every action ARN whose service segment is service (e.g. "autoscaling") for h, replacing any previous claim. This is the extension point for a service that owns an alarm action type: it needs no import of the CloudWatch package, and CloudWatch needs no import of it.

type Handler

type Handler func(ctx context.Context, t Transition, arn string) error

Handler delivers a transition to one ARN of a service a consumer owns. Registered handlers run on the dispatching goroutine and should not block for long.

type Outcome

type Outcome struct {
	// ARN is the action target.
	ARN string
	// Unsupported is true when no sink claims this ARN's service. The
	// transition still happened; the action did not.
	Unsupported bool
	// Err is the sink's own error when delivery was attempted and failed.
	Err error
}

Outcome records what happened to one action ARN.

type Transition

type Transition struct {
	// AlarmName and AlarmARN identify the alarm.
	AlarmName string
	AlarmARN  string
	// Region and AccountID scope the EventBridge event this produces.
	Region    string
	AccountID string

	// OldState and NewState are AWS state values: OK, ALARM or
	// INSUFFICIENT_DATA.
	OldState string
	NewState string
	// Reason is the human-readable StateReason; ReasonData is the
	// StateReasonData JSON document (may be empty).
	Reason     string
	ReasonData string
	// Timestamp is when the transition happened, from the injected clock.
	Timestamp time.Time

	// Actions are the action ARNs configured for NewState. Empty when the
	// alarm configures none for that state.
	Actions []string
	// ActionsEnabled mirrors the alarm's flag. When false the transition is
	// still published as an event but no action is delivered, matching AWS.
	ActionsEnabled bool

	// AlarmDescription is echoed into the SNS notification body.
	AlarmDescription string

	// Namespace, MetricName, Statistic, Period, EvaluationPeriods, Threshold
	// and ComparisonOperator describe what was evaluated. They populate the
	// EventBridge event's detail.configuration block and the SNS
	// notification's Trigger.
	Namespace          string
	MetricName         string
	Statistic          string
	Period             int
	EvaluationPeriods  int
	Threshold          float64
	ComparisonOperator string
}

Transition is one alarm state change, and everything a consumer needs to react to it without calling back into CloudWatch.