apigatewaymanagementapi

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 3, 2026 License: MIT Imports: 16 Imported by: 0

README

API Gateway Management API

Parity grade: A · SDK aws-sdk-go-v2/service/apigatewaymanagementapi@v1.29.13 · last audited 2026-07-24 (be69d5ece)

Coverage

Metric Value
Operations audited 3 (3 ok)
Feature families 1 (1 ok)
Known gaps 3
Deferred items 0
Resource leaks clean
Known gaps
  • ForbiddenException (403, caller-not-authorized) is modeled by the real API for all 3 ops but never returned; gopherstack has no general IAM-authorization-check convention for this service (only eventbridge does something similar, for an unrelated resource-policy reason). Implementing would require a cross-cutting auth model, not a fix local to this service. Not filed as a bd issue by this pass -- flagging for triage.
  • LimitExceededException's rate-limiting half ("client sending more than the allowed number of requests per unit of time") is not modeled -- only the "WebSocket client-side buffer is full" half is implemented (that half is directly reachable through the real downstream-channel wiring from apigatewayv2, and is exercised by both PostToConnection and, as of this pass, admin Broadcast). Adding request-rate throttling would need a shared rate-limiter primitive; out of scope for this pass.
  • EventDisconnected (types.go) is a defined-but-unused LifecycleEvent constant: DeleteConnection/PruneIdle discard the whole connState (including its event timeline) rather than ever appending it. Cosmetic (timeline is a UI-only diagnostic, not AWS surface, and the connState -- including any event appended immediately before deletion -- is discarded in the same step regardless) -- not fixed.

More

Documentation

Overview

Package apigatewaymanagementapi provides an in-memory stub for the AWS API Gateway Management API, which is used to send data to connected WebSocket API clients and manage WebSocket connections.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrConnectionNotFound is returned when the requested connection does not exist.
	ErrConnectionNotFound = awserr.New("GoneException", awserr.ErrNotFound)
	// ErrPayloadTooLarge is returned when the payload exceeds the maximum allowed size.
	ErrPayloadTooLarge = errors.New("payload too large")
	// ErrConnectionExists is returned when attempting to create a duplicate connection.
	ErrConnectionExists = errors.New("connection already exists")
	// ErrLimitExceeded is returned when a frame cannot be queued for delivery
	// because the WebSocket connection's client-side buffer is full. Real AWS
	// documents this exact condition as a LimitExceededException.
	ErrLimitExceeded = errors.New("websocket client-side buffer is full")
)

Functions

This section is empty.

Types

type Connection 

type Connection struct {
	ConnectedAt    time.Time `json:"connectedAt"`
	LastActiveAt   time.Time `json:"lastActiveAt"`
	ConnectionID   string    `json:"connectionId"`
	SourceIP       string    `json:"sourceIp"`
	UserAgent      string    `json:"userAgent"`
	PostedMessages int       `json:"postedMessages"`
	BytesSent      int64     `json:"bytesSent"`
}

Connection represents an active WebSocket API connection.

type EventType 

type EventType string

EventType describes a lifecycle event recorded against a connection. 

const (
	// EventConnected marks the moment a connection was registered.
	EventConnected EventType = "connected"
	// EventMessage marks a successful PostToConnection.
	EventMessage EventType = "message"
	// EventDisconnected marks the moment a connection was terminated.
	EventDisconnected EventType = "disconnected"
	// EventPing marks a heartbeat that updates LastActiveAt without storing data.
	EventPing EventType = "ping"
	// EventBroadcast marks a broadcast send to all active connections.
	EventBroadcast EventType = "broadcast"
)

type Handler 

type Handler struct {
	Backend StorageBackend
}

Handler is the Echo HTTP handler for API Gateway Management API operations.

func NewHandler 

func NewHandler(backend StorageBackend) *Handler

NewHandler creates a new API Gateway Management API Handler.

func (*Handler) ChaosOperations 

func (h *Handler) ChaosOperations() []string

ChaosOperations returns all operations that can be fault-injected.

func (*Handler) ChaosRegions 

func (h *Handler) ChaosRegions() []string

ChaosRegions returns all regions this handler instance handles.

func (*Handler) ChaosServiceName 

func (h *Handler) ChaosServiceName() string

ChaosServiceName returns the lowercase AWS service name for fault rule matching.

func (*Handler) ExtractOperation 

func (h *Handler) ExtractOperation(c *echo.Context) string

ExtractOperation returns the operation name based on path / HTTP method.

func (*Handler) ExtractResource 

func (h *Handler) ExtractResource(c *echo.Context) string

ExtractResource extracts the connection ID from the URL path. For admin paths it returns the trailing segment after the admin prefix.

func (*Handler) GetSupportedOperations 

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations returns the list of supported operations.

func (*Handler) Handler 

func (h *Handler) Handler() echo.HandlerFunc

Handler returns the Echo handler function for API Gateway Management API operations.

func (*Handler) MatchPriority 

func (h *Handler) MatchPriority() int

MatchPriority returns the routing priority.

func (*Handler) Name 

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset 

func (h *Handler) Reset()

Reset implements service.Resettable by delegating to the backend.

func (*Handler) Restore 

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher 

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher returns a function matching API Gateway Management API requests. In addition to the AWS-shaped /@connections/* prefix it also claims the /_gopherstack/apigwmgmt/* prefix, which exposes diagnostic endpoints used by the gopherstack UI (list, broadcast, timeline, stats).

func (*Handler) Snapshot 

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

type InMemoryBackend 

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

InMemoryBackend implements the StorageBackend for API Gateway Management API.

func NewInMemoryBackend 

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates a new InMemoryBackend.

func (*InMemoryBackend) Broadcast 

func (b *InMemoryBackend) Broadcast(data []byte) (int, error)

Broadcast posts data to every active connection. It returns the number of connections that successfully received the message; oversized payloads return ErrPayloadTooLarge before any send.

Delivery to each connection's real downstream transport (if one is wired -- see connState.downstream / PostToConnection) is attempted before any accounting for that connection is committed, mirroring PostToConnection's semantics: a connection whose WebSocket client-side buffer is full is skipped entirely (not counted in the returned delivered count, no message recorded, no stats/timeline update for it) rather than being reported as delivered despite never having received the frame.

func (*InMemoryBackend) ClearMessages 

func (b *InMemoryBackend) ClearMessages(connectionID string) error

ClearMessages drops all stored messages for connectionID without touching the connection itself. Returns ErrConnectionNotFound if the connection is gone.

func (*InMemoryBackend) CreateConnection 

func (b *InMemoryBackend) CreateConnection(
	connectionID, sourceIP, userAgent string,
	downstream chan []byte,
) (*Connection, error)

CreateConnection creates a new simulated WebSocket connection.

func (*InMemoryBackend) DeleteConnection 

func (b *InMemoryBackend) DeleteConnection(connectionID string) error

DeleteConnection forcibly disconnects the connection with the given ID, matching real AWS semantics: the connection is torn down, not merely forgotten. If a real transport is wired (connState.downstream is non-nil), closing it here signals the owning transport goroutine to close the underlying socket.

func (*InMemoryBackend) FilterConnections 

func (b *InMemoryBackend) FilterConnections(query string) []Connection

FilterConnections returns connections whose ID, IP, or user-agent contain query. query is matched case-insensitively. An empty query returns all connections.

func (*InMemoryBackend) GetConnection 

func (b *InMemoryBackend) GetConnection(connectionID string) (*Connection, error)

GetConnection returns the connection metadata for the given connection ID.

func (*InMemoryBackend) GetMessages 

func (b *InMemoryBackend) GetMessages(connectionID string) []PostedMessage

GetMessages returns all messages posted to the given connection in arrival order.

func (*InMemoryBackend) GetTimeline 

func (b *InMemoryBackend) GetTimeline(connectionID string) []LifecycleEvent

GetTimeline returns lifecycle events for the given connection in chronological order.

func (*InMemoryBackend) ListConnections 

func (b *InMemoryBackend) ListConnections() []Connection

ListConnections returns all active connections sorted by ConnectedAt ascending.

func (*InMemoryBackend) PingConnection 

func (b *InMemoryBackend) PingConnection(connectionID string) error

PingConnection refreshes LastActiveAt and records a ping event without storing payload data. Useful for the UI's "mark active" button.

func (*InMemoryBackend) PostToConnection 

func (b *InMemoryBackend) PostToConnection(connectionID string, data []byte) error

PostToConnection sends data to an existing connection and records the message.

func (*InMemoryBackend) PruneIdle 

func (b *InMemoryBackend) PruneIdle(threshold time.Duration) []string

PruneIdle deletes every connection whose LastActiveAt is older than threshold. Returns the list of disconnected connection IDs.

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset clears all in-memory connection state.

func (*InMemoryBackend) Restore 

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads backend state from a JSON snapshot. It implements persistence.Persistable.

func (*InMemoryBackend) Snapshot 

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises the backend state to JSON. It implements persistence.Persistable.

func (*InMemoryBackend) Stats 

func (b *InMemoryBackend) Stats() Stats

Stats returns a snapshot of cumulative backend counters.

type LifecycleEvent 

type LifecycleEvent struct {
	At     time.Time `json:"at"`
	Type   EventType `json:"type"`
	Detail string    `json:"detail,omitempty"`
	Bytes  int       `json:"bytes,omitempty"`
}

LifecycleEvent records a notable moment in a connection's history.

type PostedMessage 

type PostedMessage struct {
	ReceivedAt   time.Time `json:"receivedAt"`
	ConnectionID string    `json:"connectionId"`
	Data         []byte    `json:"data"`
}

PostedMessage represents a message sent to a connection via PostToConnection.

type Provider 

type Provider struct{}

Provider implements service.Provider for the API Gateway Management API service.

func (*Provider) Init 

func (p *Provider) Init(_ *service.AppContext) (service.Registerable, error)

Init initialises the API Gateway Management API backend and handler.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the service provider name.

type Stats 

type Stats struct {
	ActiveConnections   int   `json:"activeConnections"`
	BufferedMessages    int   `json:"bufferedMessages"`
	TotalConnections    int64 `json:"totalConnections"`
	TotalDisconnections int64 `json:"totalDisconnections"`
	TotalMessages       int64 `json:"totalMessages"`
	TotalBroadcasts     int64 `json:"totalBroadcasts"`
	TotalBytesSent      int64 `json:"totalBytesSent"`
	TotalRejected       int64 `json:"totalRejected"`
}

Stats summarises backend-wide activity.

type StorageBackend 

type StorageBackend interface {
	// PostToConnection sends data to the specified WebSocket connection.
	PostToConnection(connectionID string, data []byte) error
	// GetConnection retrieves metadata for the specified WebSocket connection.
	GetConnection(connectionID string) (*Connection, error)
	// DeleteConnection deletes the specified WebSocket connection.
	DeleteConnection(connectionID string) error
	// CreateConnection creates a new simulated WebSocket connection.
	CreateConnection(connectionID, sourceIP, userAgent string, downstream chan []byte) (*Connection, error)
	// ListConnections returns all active WebSocket connections.
	ListConnections() []Connection
	// FilterConnections returns connections whose ID, IP, or user-agent contain query.
	FilterConnections(query string) []Connection
	// GetMessages returns all messages posted to the given connection.
	GetMessages(connectionID string) []PostedMessage
	// ClearMessages drops all stored messages for the connection.
	ClearMessages(connectionID string) error
	// GetTimeline returns lifecycle events for the given connection.
	GetTimeline(connectionID string) []LifecycleEvent
	// PingConnection refreshes LastActiveAt without storing payload data.
	PingConnection(connectionID string) error
	// Broadcast posts data to every active connection and returns the count delivered.
	Broadcast(data []byte) (int, error)
	// PruneIdle removes connections idle longer than threshold.
	PruneIdle(threshold time.Duration) []string
	// Stats returns cumulative counters and active state.
	Stats() Stats
	// Snapshot serialises backend state to JSON for persistence.
	Snapshot(ctx context.Context) []byte
	// Restore loads backend state from a JSON snapshot.
	Restore(ctx context.Context, data []byte) error
	// Reset clears all in-memory state for test isolation.
	Reset()
}

StorageBackend defines the operations supported by the API Gateway Management API in-memory backend.

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.