cloudcontrol

package
v0.22.0 Latest Latest
Warning

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

 Go to latest Published: May 26, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package cloudcontrol provides AWS Cloud Control API emulation. Cloud Control is AWS's unified CRUD interface that exposes any CloudFormation-modeled resource type through the same six operations (Create / Read / Update / Delete / List / status polling). Implementing it lets clients that target Cloud Control — most notably the terraform-provider-awscc — drive a kumo-modeled resource without per-service handler implementations on the kumo side.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports whether err is (or wraps) a NotFoundError.

Types

type CreateResourceInput 

type CreateResourceInput struct {
	TypeName     string `json:"TypeName"`
	DesiredState string `json:"DesiredState"`
	ClientToken  string `json:"ClientToken,omitempty"`
}

CreateResourceInput is the JSON body Cloud Control's CreateResource receives. Only the fields kumo actually uses are modeled.

type DeleteResourceInput 

type DeleteResourceInput struct {
	TypeName    string `json:"TypeName"`
	Identifier  string `json:"Identifier"`
	ClientToken string `json:"ClientToken,omitempty"`
}

DeleteResourceInput is the JSON body for DeleteResource.

type GetResourceInput 

type GetResourceInput struct {
	TypeName   string `json:"TypeName"`
	Identifier string `json:"Identifier"`
}

GetResourceInput is the JSON body for GetResource.

type GetResourceOutput 

type GetResourceOutput struct {
	TypeName            string                  `json:"TypeName"`
	ResourceDescription ResourceDescriptionWire `json:"ResourceDescription"`
}

GetResourceOutput is the response for GetResource.

type GetResourceRequestStatusInput 

type GetResourceRequestStatusInput struct {
	RequestToken string `json:"RequestToken"`
}

GetResourceRequestStatusInput is the JSON body for status polling.

type Handler 

type Handler interface {
	// TypeName returns the resource type the handler serves, e.g.
	// "AWS::S3::Bucket".
	TypeName() string

	// Create provisions a new resource from the supplied desired-state
	// JSON. Returns the primary identifier (the value Cloud Control uses
	// to address the resource on subsequent calls) and the read-back
	// state, which may differ from desired (server-assigned fields, etc.).
	Create(ctx context.Context, desiredState []byte) (identifier string, state []byte, err error)

	// Read returns the current state of the resource addressed by
	// identifier, or NotFoundError when it doesn't exist.
	Read(ctx context.Context, identifier string) (state []byte, err error)

	// Update applies a JSON Patch (RFC 6902) document to the existing
	// resource and returns the updated state. Patch documents are how
	// Cloud Control conveys updates on the wire.
	Update(ctx context.Context, identifier string, patchDocument []byte) (state []byte, err error)

	// Delete removes the resource. Returning NotFoundError is acceptable —
	// Cloud Control surfaces it as the resource already being absent.
	Delete(ctx context.Context, identifier string) error

	// List returns identifiers + state for every resource of this type.
	// kumo doesn't paginate Cloud Control responses today; pagination can
	// be added later through a separate List(ctx, after) signature without
	// breaking existing handlers.
	List(ctx context.Context) ([]ResourceDescription, error)
}

Handler implements Cloud Control CRUD for one CloudFormation-style resource type (e.g. "AWS::S3::Bucket"). Each method takes and returns the JSON-serialised resource state — Cloud Control's wire format is "DesiredState as a JSON string", so handlers operate on string-typed JSON to avoid double encode/decode.

type ListResourcesInput 

type ListResourcesInput struct {
	TypeName   string `json:"TypeName"`
	MaxResults int    `json:"MaxResults,omitempty"`
	NextToken  string `json:"NextToken,omitempty"`
}

ListResourcesInput is the JSON body for ListResources.

type ListResourcesOutput 

type ListResourcesOutput struct {
	TypeName             string                    `json:"TypeName"`
	ResourceDescriptions []ResourceDescriptionWire `json:"ResourceDescriptions"`
	NextToken            string                    `json:"NextToken,omitempty"`
}

ListResourcesOutput is the response for ListResources.

type NotFoundError 

type NotFoundError struct{ Message string }

NotFoundError is returned by Handler.Read / Update / Delete when the resource doesn't exist. The dispatcher translates it into Cloud Control's "ResourceNotFoundException".

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

type ProgressEvent 

type ProgressEvent struct {
	TypeName        string  `json:"TypeName,omitempty"`
	Identifier      string  `json:"Identifier,omitempty"`
	RequestToken    string  `json:"RequestToken,omitempty"`
	Operation       string  `json:"Operation,omitempty"`
	OperationStatus string  `json:"OperationStatus,omitempty"`
	EventTime       float64 `json:"EventTime,omitempty"`
	ResourceModel   string  `json:"ResourceModel,omitempty"`
	StatusMessage   string  `json:"StatusMessage,omitempty"`
	ErrorCode       string  `json:"ErrorCode,omitempty"`
}

ProgressEvent is the wire shape Cloud Control returns from every asynchronous operation. kumo runs all operations synchronously, so we always return SUCCESS — the field is still populated for SDK compatibility. EventTime is encoded as Unix-epoch seconds (a float) because the AWS JSON 1.0 protocol decodes timestamps as numbers; an RFC3339 string trips the SDK's `expected Timestamp to be a JSON Number` check.

type ProgressEventOutput 

type ProgressEventOutput struct {
	ProgressEvent ProgressEvent `json:"ProgressEvent"`
}

ProgressEventOutput is the response envelope shared by CreateResource, UpdateResource and DeleteResource. All three actions return a single ProgressEvent on success.

type Registry 

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

Registry maps a resource type name to its Handler.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry returns an empty Registry.

func (*Registry) Get 

func (r *Registry) Get(typeName string) (Handler, bool)

Get returns the handler for typeName, or nil + false when no handler is registered. Callers translate the false case into Cloud Control's "TypeNotFoundException".

func (*Registry) Register 

func (r *Registry) Register(h Handler)

Register installs a handler for its declared TypeName. A previously registered handler with the same TypeName is replaced — this matters for tests that swap in fakes.

type ResourceDescription 

type ResourceDescription struct {
	Identifier string
	Properties []byte
}

ResourceDescription pairs an identifier with its serialised state, the shape Cloud Control returns from List and Get.

type ResourceDescriptionWire 

type ResourceDescriptionWire struct {
	Identifier string `json:"Identifier"`
	Properties string `json:"Properties"`
}

ResourceDescriptionWire is the wire shape for Get/List entries. Properties is a JSON document encoded as a string.

type Service 

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

Service implements the Cloud Control API service. It dispatches each operation to a per-resource-type Handler registered in the type registry.

func New 

func New(reg *Registry) *Service

New creates a new Cloud Control service backed by the given registry.

func (*Service) Close 

func (s *Service) Close() error

Close is a no-op — the registry holds no closable state of its own.

func (*Service) CreateResource 

func (s *Service) CreateResource(w http.ResponseWriter, r *http.Request)

CreateResource provisions a resource of the given type from a DesiredState JSON document. kumo runs the underlying storage call synchronously, so the returned ProgressEvent always reports SUCCESS with the read-back ResourceModel attached — pollers calling GetResourceRequestStatus afterwards just see the same SUCCESS.

func (*Service) DeleteResource 

func (s *Service) DeleteResource(w http.ResponseWriter, r *http.Request)

DeleteResource removes the resource. NotFound is reported as ResourceNotFoundException, matching real Cloud Control which surfaces "you tried to delete a resource that wasn't there" rather than silently succeeding.

func (*Service) DispatchAction 

func (s *Service) DispatchAction(w http.ResponseWriter, r *http.Request)

DispatchAction is invoked by the JSON protocol dispatcher after it confirms the X-Amz-Target prefix matches "CloudApiService". The action name is the part after the dot.

func (*Service) GetResource 

func (s *Service) GetResource(w http.ResponseWriter, r *http.Request)

GetResource returns the current state of the resource. Cloud Control uses Get for synchronous reads; status polling is GetResourceRequestStatus.

func (*Service) GetResourceRequestStatus 

func (s *Service) GetResourceRequestStatus(w http.ResponseWriter, r *http.Request)

GetResourceRequestStatus is invoked by clients polling an asynchronous operation. kumo executes everything synchronously, so by the time a caller asks, the operation is already done — we look up the original CreateResource / UpdateResource / DeleteResource ProgressEvent and re-emit it. Without echoing back the original Identifier + TypeName the awscc terraform provider can't follow the create with a GetResource and "unknown after apply" never resolves.

func (*Service) JSONProtocol 

func (s *Service) JSONProtocol()

JSONProtocol marks this service as using AWS JSON 1.0.

func (*Service) ListResources 

func (s *Service) ListResources(w http.ResponseWriter, r *http.Request)

ListResources returns every resource of the given type. Pagination is not implemented yet; MaxResults / NextToken are accepted but ignored.

func (*Service) Name 

func (s *Service) Name() string

Name returns the service name.

func (*Service) RegisterRoutes 

func (s *Service) RegisterRoutes(_ service.Router)

RegisterRoutes is a no-op — Cloud Control uses AWS JSON 1.0 over a single POST endpoint, dispatched via the X-Amz-Target header.

func (*Service) TargetPrefix 

func (s *Service) TargetPrefix() string

TargetPrefix returns the X-Amz-Target prefix the SDK uses for Cloud Control: every operation's target is "CloudApiService.<Action>".

func (*Service) UpdateResource 

func (s *Service) UpdateResource(w http.ResponseWriter, r *http.Request)

UpdateResource applies an RFC 6902 patch to the existing resource.

type UpdateResourceInput 

type UpdateResourceInput struct {
	TypeName      string `json:"TypeName"`
	Identifier    string `json:"Identifier"`
	PatchDocument string `json:"PatchDocument"`
	ClientToken   string `json:"ClientToken,omitempty"`
}

UpdateResourceInput is the JSON body for UpdateResource. PatchDocument is an RFC 6902 JSON Patch as a string.

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.