vokercfn

Documentation

Overview

Package vokercfn provides a type-safe entrypoint for AWS CloudFormation custom resource Lambda functions.

CloudFormation expects custom resources to report their result with an HTTP PUT to the presigned ResponseURL in the invocation event. Start and Wrap handle that protocol, including failure responses and physical resource ID fallbacks, so handlers can focus on provisioning logic.

Index

• func Start[P, D any](handler Handler[P, D], opts ...voker.Option)
• func Wrap[P, D any](handler Handler[P, D]) func(context.Context, jsontext.Value) (struct{}, error)
• type Event
• type Handler
• type RequestType
• type Result

Examples

• Wrap

Functions

func Start

func Start[P, D any](handler Handler[P, D], opts ...voker.Option)

Start starts the Lambda runtime loop for a CloudFormation custom resource. Handler errors are reported to CloudFormation as FAILED responses and do not become Lambda invocation errors. Failure to deliver the response does become a Lambda invocation error so it is visible in Lambda monitoring.

Panics are reported to CloudFormation on a best-effort basis and then re-panicked so Voker preserves its normal panic logging and runtime behavior.

func Wrap

func Wrap[P, D any](handler Handler[P, D]) func(context.Context, jsontext.Value) (struct{}, error)

Wrap adapts a CloudFormation custom resource Handler for voker.Start. Most programs should call Start directly; Wrap is useful when composing a custom entrypoint. It accepts the raw invocation so CloudFormation protocol metadata can be decoded before typed properties. If property decoding fails, Wrap can therefore still send the required FAILED response.

Example

package main

import (
	"context"
	"fmt"

	"github.com/hotsock/voker/vokercfn"
)

type exampleProperties struct {
	Name string `json:"Name"`
}

type exampleData struct {
	ARN string `json:"Arn"`
}

func main() {
	handler := func(_ context.Context, event vokercfn.Event[exampleProperties]) (vokercfn.Result[exampleData], error) {
		switch event.RequestType {
		case vokercfn.RequestCreate:
			return vokercfn.Result[exampleData]{
				PhysicalResourceID: event.ResourceProperties.Name,
				Data:               exampleData{ARN: "arn:example:" + event.ResourceProperties.Name},
			}, nil
		case vokercfn.RequestUpdate, vokercfn.RequestDelete:
			return vokercfn.Result[exampleData]{PhysicalResourceID: event.PhysicalResourceID}, nil
		default:
			return vokercfn.Result[exampleData]{}, fmt.Errorf("unknown request type %q", event.RequestType)
		}
	}

	// Pass the result to voker.Start when composing your own entrypoint. Most
	// applications can simply call vokercfn.Start(handler).
	_ = vokercfn.Wrap(handler)
}

Types

type Event

type Event[P any] struct {
	RequestType           RequestType `json:"RequestType"`
	RequestID             string      `json:"RequestId"`
	ResponseURL           string      `json:"ResponseURL"`
	ResourceType          string      `json:"ResourceType"`
	PhysicalResourceID    string      `json:"PhysicalResourceId,omitempty"`
	LogicalResourceID     string      `json:"LogicalResourceId"`
	StackID               string      `json:"StackId"`
	ResourceProperties    P           `json:"ResourceProperties"`
	OldResourceProperties P           `json:"OldResourceProperties,omitempty"`
}

Event is a CloudFormation custom resource request. P is the handler's type-safe representation of ResourceProperties.

type Handler

type Handler[P, D any] func(context.Context, Event[P]) (Result[D], error)

Handler is the signature accepted by Start and Wrap. A handler may return a Result together with an error; its PhysicalResourceID is retained in the FAILED response, while Data and NoEcho are ignored.

type RequestType

type RequestType string

RequestType identifies a CloudFormation custom resource operation.

const (
	RequestCreate RequestType = "Create"
	RequestUpdate RequestType = "Update"
	RequestDelete RequestType = "Delete"
)

type Result

type Result[D any] struct {
	PhysicalResourceID string
	Data               D
	NoEcho             bool
}

Result describes a successful custom resource operation.

PhysicalResourceID should be stable for the lifetime of a resource. If it is empty, Voker uses the request ID for Create and the existing physical ID for Update and Delete. Returning a new ID from an Update tells CloudFormation that the resource was replaced.

Data is exposed through Fn::GetAtt. Set NoEcho to mask Data values in the CloudFormation console and API responses.