appsyncevents

Documentation

Overview

Package appsyncevents routes AWS Lambda AppSync Events invocations.

New constructs a Resolver. Register channel handlers with Router.OnPublish and Router.OnSubscribe, then call Resolver.Resolve from the Lambda handler. PublishOptions selects individual or aggregate publication.

Concurrency and errors

Individual publication executes handlers concurrently and preserves input order in the response. Handlers share the original Event envelope and must treat it as read-only. Undefined omits a payload rather than encoding JSON null.

Subscription authorization and publication error behavior follow the documented resolver contract. Invalid events return nil after diagnostics. The application owns AppSync namespace setup, authorization policy and diagnostic callbacks.

For usage and compatibility details, see the user guide.

Index

• Constants
• type Event
• type NamedError
  • func (e *NamedError) Error() string
  • func (e *NamedError) ErrorName() string
  • func (e *NamedError) Unwrap() error
• type Options
• type PublishHandler
• type PublishOptions
• type Resolver
  • func New(options Options) *Resolver
  • func (r *Resolver) Resolve(ctx context.Context, input any) (any, error)
• type Router
  • func NewRouter(options Options) *Router
  • func (r *Router) OnPublish(path string, handler PublishHandler, options ...PublishOptions)
  • func (r *Router) OnSubscribe(path string, handler SubscribeHandler)
• type SubscribeHandler
• type UnauthorizedError
• type UnauthorizedException
  • func (e *UnauthorizedException) Error() string
  • func (e *UnauthorizedException) ErrorName() string
  • func (e *UnauthorizedException) Unwrap() error
• type Undefined

Examples

• Resolver.Resolve

Constants

const MaxEventSize = 240 * 1024

Types

type Event

type Event = map[string]any

Event retains the original JSON envelope, including unknown identity and request fields. Handlers share this envelope during individual publication and must treat it as read-only.

type NamedError

type NamedError struct {
	Name, Message string
	Cause         error
}

NamedError supplies the JavaScript error name used in response envelopes.

func (*NamedError) Error

func (e *NamedError) Error() string

func (*NamedError) ErrorName

func (e *NamedError) ErrorName() string

func (*NamedError) Unwrap

func (e *NamedError) Unwrap() error

type Options

type Options struct {
	WarnOnLargePayload bool
	// Diagnostic may be called concurrently. Registration uses context.Background;
	// resolution and handler errors retain the invocation context. Callbacks run unlocked.
	Diagnostic func(ctx context.Context, level, message string, err error)
}

type PublishHandler

type PublishHandler func(context.Context, any, Event) (any, error)

type PublishOptions

type PublishOptions struct{ Aggregate bool }

type Resolver

type Resolver struct{ *Router }

func New

func New(options Options) *Resolver

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, input any) (any, error)

Resolve accepts a JSON-decoded Lambda event. The context is passed unchanged to handlers and diagnostics. Per-item handlers run concurrently; output order is stable. Invalid events and successful subscriptions return nil (JSON null in Go Lambda).

Example

package main

import (
	"context"
	"fmt"

	"github.com/rambow-cloud/powertools-lambda-go/eventhandler/appsyncevents"
)

func main() {
	app := appsyncevents.New(appsyncevents.Options{})
	app.OnPublish("/orders/*", func(_ context.Context, payload any, _ appsyncevents.Event) (any, error) {
		return payload, nil
	})
	event := map[string]any{
		"identity": nil, "result": nil, "error": nil, "prev": nil,
		"stash": map[string]any{}, "outErrors": []any{},
		"request": map[string]any{"headers": map[string]any{}, "domainName": nil},
		"info": map[string]any{"operation": "PUBLISH",
			"channel":          map[string]any{"path": "/orders/created", "segments": []any{"orders", "created"}},
			"channelNamespace": map[string]any{"name": "orders"}},
		"events": []any{map[string]any{"id": "event-1", "payload": "order-123"}},
	}
	value, err := app.Resolve(context.Background(), event)
	if err != nil {
		panic(err)
	}
	items := value.(map[string]any)["events"].([]any)
	item := items[0].(map[string]any)
	fmt.Println(item["id"], item["payload"])
}

Output:
event-1 order-123

type Router

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

Router stores separate publish and subscribe registries. Register routes before serving requests: successful lookup caches intentionally retain old registrations.

func NewRouter

func NewRouter(options Options) *Router

func (*Router) OnPublish

func (r *Router) OnPublish(path string, handler PublishHandler, options ...PublishOptions)

func (*Router) OnSubscribe

func (r *Router) OnSubscribe(path string, handler SubscribeHandler)

type SubscribeHandler

type SubscribeHandler func(context.Context, Event) error

type UnauthorizedError

type UnauthorizedError = UnauthorizedException

UnauthorizedError is the Go-style alias; it retains the runtime exception type name.

type UnauthorizedException

type UnauthorizedException struct {
	Message string
	Cause   error
}

UnauthorizedException preserves the Go Lambda SDK's reflected errorType as well as the reference response name. All publish and subscribe handlers propagate it.

func (*UnauthorizedException) Error

func (e *UnauthorizedException) Error() string

func (*UnauthorizedException) ErrorName

func (e *UnauthorizedException) ErrorName() string

func (*UnauthorizedException) Unwrap

func (e *UnauthorizedException) Unwrap() error

type Undefined

type Undefined struct{}

Undefined omits the immediate payload/events property instead of encoding JSON null.