servicediscovery

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: MIT Imports: 23 Imported by: 0

README

Cloud Map

Parity grade: A · SDK aws-sdk-go-v2/service/servicediscovery@v1.39.24 · last audited 2026-07-13 (6bf60b6f)

Coverage
Operations audited 30 (30 ok)
Feature families 3 (3 ok)
Known gaps 3
Deferred items 2
Resource leaks clean
Known gaps
  • ListNamespaces/ListServices/ListOperations Filters only implement the most common Name values (TYPE/NAME, NAMESPACE_ID, STATUS/TYPE respectively); HTTP_NAME, RESOURCE_OWNER (cross-account sharing, not emulated at all), NAMESPACE_ID/SERVICE_ID/UPDATE_DATE on ListOperations, and Condition (EQ/IN/BETWEEN/BEGINS_WITH, always treated as EQ-on-first-value) are unimplemented
  • UpdateServiceAttributes has no attribute-count/size quota enforcement (real AWS: ServiceAttributesLimitExceededException); no documented exact limit found in the SDK comments to implement against with confidence
  • GetInstancesHealthStatus/DiscoverInstances never surface HealthStatus=UNKNOWN; real Cloud Map instances backed by an AWS-managed HealthCheckConfig start UNKNOWN until the Route53 health check propagates. Gopherstack has no Route53 health-check subsystem to drive this, so all instances are HEALTHY until explicitly marked UNHEALTHY via UpdateInstanceCustomHealthStatus (which itself requires HealthCheckCustomConfig, now correctly enforced)
Deferred
  • CreateService (namespaceID, name) uniqueness / ServiceAlreadyExists: current backend allows duplicate (namespaceID, name) pairs with documented last-write-wins semantics for DiscoverInstances/DiscoverInstancesRevision lookup (see serviceNsNameKeyFn / DiscoverInstances comments in backend.go). Real AWS types/errors.go defines ServiceAlreadyExists but its exact trigger condition (name collision vs CreatorRequestId retry) isn't unambiguous from SDK doc comments alone; left as-is to avoid an unverified behavior change on top of an already load-bearing design decision from a prior audit pass
  • Cross-account/shared-namespace support (ResourceOwner, OwnerAccount, ARN-as-Id acceptance for shared services) -- not emulated anywhere in this backend; single-account model throughout

More

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNamespaceNotFound is returned when a namespace does not exist.
	ErrNamespaceNotFound = awserr.New("NamespaceNotFound", awserr.ErrNotFound)
	// ErrServiceNotFound is returned when a service does not exist.
	ErrServiceNotFound = awserr.New("ServiceNotFound", awserr.ErrNotFound)
	// ErrInstanceNotFound is returned when an instance does not exist.
	ErrInstanceNotFound = awserr.New("InstanceNotFound", awserr.ErrNotFound)
	// ErrOperationNotFound is returned when an operation does not exist.
	ErrOperationNotFound = awserr.New("OperationNotFound", awserr.ErrNotFound)
	// ErrNamespaceAlreadyExists is returned when a namespace with the same name already exists.
	ErrNamespaceAlreadyExists = awserr.New("NamespaceAlreadyExists", awserr.ErrAlreadyExists)
	// ErrServiceAttributesNotFound is returned when no attributes exist for a service.
	ErrServiceAttributesNotFound = awserr.New("ServiceAttributesNotFound", awserr.ErrNotFound)
	// ErrInvalidInput is returned when an input value is invalid.
	ErrInvalidInput = awserr.New("InvalidInput", awserr.ErrInvalidParameter)
	// ErrResourceNotFound is returned when a tagged resource ARN is not found.
	ErrResourceNotFound = awserr.New("ResourceNotFoundException", awserr.ErrNotFound)
	// ErrResourceInUse is returned when a delete is attempted on a non-empty namespace or service.
	ErrResourceInUse = awserr.New("ResourceInUse", awserr.ErrConflict)
	// ErrCustomHealthNotFound is returned when UpdateInstanceCustomHealthStatus is called on a
	// service that has no HealthCheckCustomConfig.
	ErrCustomHealthNotFound = awserr.New("CustomHealthNotFound", awserr.ErrNotFound)
	// ErrTooManyTags is returned when a request would leave a resource with more than
	// maxTagCount tags.
	ErrTooManyTags = awserr.New("TooManyTagsException", awserr.ErrInvalidParameter)
)
View Source 
var ErrNilAppContext = errors.New("nil AppContext passed to ServiceDiscovery Provider.Init")

ErrNilAppContext is returned when a nil AppContext is passed to Provider.Init.

Functions

This section is empty.

Types

type DNSConfig 

type DNSConfig struct {
	NamespaceID   string      `json:"namespaceID,omitempty"`
	RoutingPolicy string      `json:"routingPolicy,omitempty"`
	DNSRecords    []DNSRecord `json:"dnsRecords,omitempty"`
}

DNSConfig holds the DNS configuration for a Cloud Map service.

type DNSProperties 

type DNSProperties struct {
	SOA          *SOA   `json:"soa,omitempty"`
	HostedZoneID string `json:"hostedZoneId,omitempty"`
}

DNSProperties holds the DNS-specific properties of a namespace.

type DNSRecord 

type DNSRecord struct {
	Type string `json:"type"`
	TTL  int64  `json:"ttl"`
}

DNSRecord represents a single DNS record configuration in a Cloud Map service.

type DiscoveredInstance 

type DiscoveredInstance struct {
	Attributes    map[string]string
	InstanceID    string
	NamespaceName string
	ServiceName   string
	HealthStatus  string
}

DiscoveredInstance is the richer per-instance response for DiscoverInstances.

type HTTPProperties 

type HTTPProperties struct {
	HTTPName string `json:"httpName,omitempty"`
}

HTTPProperties holds the HTTP-specific properties of a namespace.

type Handler 

type Handler struct {
	Backend   StorageBackend
	AccountID string
	Region    string
}

Handler is the HTTP handler for the AWS Cloud Map service discovery API.

func NewHandler 

func NewHandler(backend StorageBackend) *Handler

NewHandler creates a new Cloud Map 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 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 extracts the operation name from the X-Amz-Target header.

func (*Handler) ExtractResource 

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

ExtractResource extracts the primary resource ID from the request body.

func (*Handler) GetSupportedOperations 

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

GetSupportedOperations returns the list of supported Cloud Map operations.

func (*Handler) Handler 

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

Handler returns the Echo handler function for Cloud Map requests.

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 clears all backend state.

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 that matches Cloud Map API requests. Requests are identified by the X-Amz-Target header prefix "Route53AutoNaming_v20170314.".

func (*Handler) Snapshot 

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

Snapshot implements persistence.Persistable by delegating to the backend.

type HealthCheckConfig 

type HealthCheckConfig struct {
	Type             string `json:"type"`
	ResourcePath     string `json:"resourcePath,omitempty"`
	FailureThreshold int    `json:"failureThreshold,omitempty"`
}

HealthCheckConfig holds the configuration for an AWS-managed HTTP/TCP health check.

type HealthCheckCustomConfig 

type HealthCheckCustomConfig struct {
	FailureThreshold int `json:"failureThreshold,omitempty"`
}

HealthCheckCustomConfig holds the configuration for a custom health check.

type InMemoryBackend 

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

InMemoryBackend is the in-memory Cloud Map backend.

func NewInMemoryBackend 

func NewInMemoryBackend(accountID, region string) *InMemoryBackend

NewInMemoryBackend creates a new in-memory Cloud Map backend.

func (*InMemoryBackend) AccountID 

func (b *InMemoryBackend) AccountID() string

AccountID returns the AWS account ID this backend is configured for.

func (*InMemoryBackend) CreateHTTPNamespace 

func (b *InMemoryBackend) CreateHTTPNamespace(name, description string, tags map[string]string) (string, error)

CreateHTTPNamespace creates an HTTP namespace.

func (*InMemoryBackend) CreatePrivateDNSNamespace 

func (b *InMemoryBackend) CreatePrivateDNSNamespace(
	name, description, vpc string,
	soaTTL int64,
	tags map[string]string,
) (string, error)

CreatePrivateDNSNamespace creates a private DNS namespace. soaTTL defaults to 15 when zero.

func (*InMemoryBackend) CreatePublicDNSNamespace 

func (b *InMemoryBackend) CreatePublicDNSNamespace(
	name, description string,
	soaTTL int64,
	tags map[string]string,
) (string, error)

CreatePublicDNSNamespace creates a public DNS namespace. soaTTL defaults to 15 when zero.

func (*InMemoryBackend) CreateService 

func (b *InMemoryBackend) CreateService(
	name, namespaceID, description, svcType string,
	dnsConfig *DNSConfig,
	hcc *HealthCheckConfig,
	hccc *HealthCheckCustomConfig,
	tags map[string]string,
) (*Service, error)

CreateService creates a new Cloud Map service.

func (*InMemoryBackend) DeleteNamespace 

func (b *InMemoryBackend) DeleteNamespace(id string) (string, error)

DeleteNamespace deletes a namespace by ID. Returns ResourceInUse if the namespace still has services.

func (*InMemoryBackend) DeleteService 

func (b *InMemoryBackend) DeleteService(id string) error

DeleteService deletes a service by ID. Returns ResourceInUse if instances are still registered.

func (*InMemoryBackend) DeleteServiceAttributes 

func (b *InMemoryBackend) DeleteServiceAttributes(serviceID string) error

DeleteServiceAttributes removes all custom attributes for a service.

func (*InMemoryBackend) DeregisterInstance 

func (b *InMemoryBackend) DeregisterInstance(serviceID, instanceID string) (string, error)

DeregisterInstance deregisters an instance from a service.

func (*InMemoryBackend) DiscoverInstances 

func (b *InMemoryBackend) DiscoverInstances(
	namespaceName, serviceName, healthStatus string,
	queryParams map[string]string,
) ([]DiscoveredInstance, int64, error)

DiscoverInstances returns discovered instances with full per-instance metadata. Also returns the per-service revision counter.

func (*InMemoryBackend) DiscoverInstancesRevision 

func (b *InMemoryBackend) DiscoverInstancesRevision(namespaceName, serviceName string) (int64, error)

DiscoverInstancesRevision returns the current revision for the specified service. Revision is per-service, incremented on each RegisterInstance/DeregisterInstance.

func (*InMemoryBackend) GetInstance 

func (b *InMemoryBackend) GetInstance(serviceID, instanceID string) (*Instance, error)

GetInstance returns a registered instance.

func (*InMemoryBackend) GetInstancesHealthStatus 

func (b *InMemoryBackend) GetInstancesHealthStatus(serviceID string, instanceIDs []string) (map[string]string, error)

GetInstancesHealthStatus returns the health status for instances in a service. If instanceIDs is non-empty, only those instances are included. Instances without a recorded status default to HEALTHY.

func (*InMemoryBackend) GetNamespace 

func (b *InMemoryBackend) GetNamespace(id string) (*Namespace, error)

GetNamespace returns a namespace by ID.

func (*InMemoryBackend) GetOperation 

func (b *InMemoryBackend) GetOperation(id string) (*Operation, error)

GetOperation returns an operation by ID.

func (*InMemoryBackend) GetService 

func (b *InMemoryBackend) GetService(id string) (*Service, error)

GetService returns a service by ID.

func (*InMemoryBackend) GetServiceAttributes 

func (b *InMemoryBackend) GetServiceAttributes(serviceID string) (string, map[string]string, error)

GetServiceAttributes returns the custom attributes for a service.

func (*InMemoryBackend) ListInstances 

func (b *InMemoryBackend) ListInstances(serviceID string) ([]Instance, error)

ListInstances returns all instances registered to a service.

func (*InMemoryBackend) ListNamespaces 

func (b *InMemoryBackend) ListNamespaces(filter ListNamespacesFilter) []Namespace

ListNamespaces returns all namespaces sorted by name, optionally filtered.

func (*InMemoryBackend) ListOperations 

func (b *InMemoryBackend) ListOperations(filter ListOperationsFilter) []Operation

ListOperations returns all operations sorted by ID, optionally filtered.

func (*InMemoryBackend) ListServices 

func (b *InMemoryBackend) ListServices(filter ListServicesFilter) []Service

ListServices returns all services, optionally filtered.

func (*InMemoryBackend) ListTagsForResource 

func (b *InMemoryBackend) ListTagsForResource(arn string) (map[string]string, error)

ListTagsForResource returns tags for a resource ARN (namespace or service).

func (*InMemoryBackend) Region 

func (b *InMemoryBackend) Region() string

Region returns the AWS region this backend is configured for.

func (*InMemoryBackend) RegisterInstance 

func (b *InMemoryBackend) RegisterInstance(serviceID, instanceID string, attrs map[string]string) (string, error)

RegisterInstance registers an instance to a service.

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset clears all backend state, resetting to an empty store.

func (*InMemoryBackend) Restore 

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

Restore loads backend state from a JSON snapshot.

func (*InMemoryBackend) Snapshot 

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

Snapshot serialises the backend state to JSON.

func (*InMemoryBackend) TagResource 

func (b *InMemoryBackend) TagResource(arn string, tags map[string]string) error

TagResource adds tags to a resource (namespace or service).

func (*InMemoryBackend) UntagResource 

func (b *InMemoryBackend) UntagResource(arn string, tagKeys []string) error

UntagResource removes tags from a resource (namespace or service).

func (*InMemoryBackend) UpdateHTTPNamespace 

func (b *InMemoryBackend) UpdateHTTPNamespace(id, description string) (string, error)

UpdateHTTPNamespace updates the description of an HTTP namespace.

func (*InMemoryBackend) UpdateInstanceCustomHealthStatus 

func (b *InMemoryBackend) UpdateInstanceCustomHealthStatus(serviceID, instanceID, status string) error

UpdateInstanceCustomHealthStatus sets a custom health status for an instance. Returns CustomHealthNotFound if the service has no HealthCheckCustomConfig.

func (*InMemoryBackend) UpdatePrivateDNSNamespace 

func (b *InMemoryBackend) UpdatePrivateDNSNamespace(id, description string) (string, error)

UpdatePrivateDNSNamespace updates the description of a private DNS namespace.

func (*InMemoryBackend) UpdatePublicDNSNamespace 

func (b *InMemoryBackend) UpdatePublicDNSNamespace(id, description string) (string, error)

UpdatePublicDNSNamespace updates the description of a public DNS namespace.

func (*InMemoryBackend) UpdateService 

func (b *InMemoryBackend) UpdateService(
	id, description string,
	dnsConfig *DNSConfig,
	hcc *HealthCheckConfig,
) (string, error)

UpdateService updates the description and optionally DNSConfig/HealthCheckConfig of a service. Returns the operation ID, matching real AWS UpdateService behavior.

func (*InMemoryBackend) UpdateServiceAttributes 

func (b *InMemoryBackend) UpdateServiceAttributes(serviceARN string, attributes map[string]string) error

UpdateServiceAttributes sets or merges custom attributes for a service identified by ARN.

type Instance 

type Instance struct {
	Attributes map[string]string `json:"attributes,omitempty"`
	ID         string            `json:"id"`
	ServiceID  string            `json:"serviceID"`
}

Instance represents a registered instance in a Cloud Map service.

type ListNamespacesFilter 

type ListNamespacesFilter struct {
	Type string
	Name string
}

ListNamespacesFilter contains optional filter parameters for ListNamespaces.

type ListOperationsFilter 

type ListOperationsFilter struct {
	Status string
	Type   string
}

ListOperationsFilter contains optional filter parameters for ListOperations.

type ListServicesFilter 

type ListServicesFilter struct {
	NamespaceID string
}

ListServicesFilter contains optional filter parameters for ListServices.

type Namespace 

type Namespace struct {
	CreatedAt    time.Time            `json:"createdAt"`
	Tags         map[string]string    `json:"tags,omitempty"`
	Properties   *NamespaceProperties `json:"properties,omitempty"`
	ID           string               `json:"id"`
	ARN          string               `json:"arn"`
	Name         string               `json:"name"`
	Type         string               `json:"type"`
	Description  string               `json:"description,omitempty"`
	VPC          string               `json:"vpc,omitempty"`
	ServiceCount int                  `json:"serviceCount,omitempty"`
}

Namespace represents an AWS Cloud Map namespace.

type NamespaceProperties 

type NamespaceProperties struct {
	DNSProperties  *DNSProperties  `json:"dnsProperties,omitempty"`
	HTTPProperties *HTTPProperties `json:"httpProperties,omitempty"`
}

NamespaceProperties holds the type-specific properties of a namespace.

type Operation 

type Operation struct {
	CreateDate   time.Time         `json:"createDate"`
	UpdateDate   time.Time         `json:"updateDate"`
	Targets      map[string]string `json:"targets,omitempty"`
	ID           string            `json:"id"`
	Type         string            `json:"type"`
	Status       string            `json:"status"`
	ErrorCode    string            `json:"errorCode,omitempty"`
	ErrorMessage string            `json:"errorMessage,omitempty"`
}

Operation represents an async Cloud Map operation (e.g., create/delete namespace).

type Provider 

type Provider struct{}

Provider implements service.Provider for AWS Cloud Map (Service Discovery).

func (*Provider) Init 

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

Init initializes the Service Discovery backend and handler.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the provider name.

type SOA 

type SOA struct {
	TTL int64 `json:"ttl"`
}

SOA holds the Start of Authority TTL for a DNS namespace.

type Service 

type Service struct {
	CreatedAt               time.Time                `json:"createdAt"`
	Tags                    map[string]string        `json:"tags,omitempty"`
	DNSConfig               *DNSConfig               `json:"dnsConfig,omitempty"`
	HealthCheckConfig       *HealthCheckConfig       `json:"healthCheckConfig,omitempty"`
	HealthCheckCustomConfig *HealthCheckCustomConfig `json:"healthCheckCustomConfig,omitempty"`
	ID                      string                   `json:"id"`
	ARN                     string                   `json:"arn"`
	Name                    string                   `json:"name"`
	NamespaceID             string                   `json:"namespaceID"`
	Description             string                   `json:"description,omitempty"`
	Type                    string                   `json:"type,omitempty"`
	InstanceCount           int                      `json:"instanceCount,omitempty"`
}

Service represents an AWS Cloud Map service.

type StorageBackend 

type StorageBackend interface {
	// Namespace operations.
	CreateHTTPNamespace(name, description string, tags map[string]string) (string, error)
	CreatePrivateDNSNamespace(name, description, vpc string, soaTTL int64, tags map[string]string) (string, error)
	CreatePublicDNSNamespace(name, description string, soaTTL int64, tags map[string]string) (string, error)
	DeleteNamespace(id string) (string, error)
	GetNamespace(id string) (*Namespace, error)
	ListNamespaces(filter ListNamespacesFilter) []Namespace
	UpdateHTTPNamespace(id, description string) (string, error)
	UpdatePrivateDNSNamespace(id, description string) (string, error)
	UpdatePublicDNSNamespace(id, description string) (string, error)

	// Service operations.
	CreateService(
		name, namespaceID, description, svcType string,
		dnsConfig *DNSConfig,
		hcc *HealthCheckConfig,
		hccc *HealthCheckCustomConfig,
		tags map[string]string,
	) (*Service, error)
	DeleteService(id string) error
	GetService(id string) (*Service, error)
	ListServices(filter ListServicesFilter) []Service
	UpdateService(id, description string, dnsConfig *DNSConfig, hcc *HealthCheckConfig) (string, error)
	GetServiceAttributes(serviceID string) (string, map[string]string, error)
	UpdateServiceAttributes(serviceARN string, attributes map[string]string) error
	DeleteServiceAttributes(serviceID string) error

	// Instance operations.
	RegisterInstance(serviceID, instanceID string, attrs map[string]string) (string, error)
	DeregisterInstance(serviceID, instanceID string) (string, error)
	GetInstance(serviceID, instanceID string) (*Instance, error)
	ListInstances(serviceID string) ([]Instance, error)
	DiscoverInstances(
		namespaceName, serviceName, healthStatus string,
		queryParams map[string]string,
	) ([]DiscoveredInstance, int64, error)
	DiscoverInstancesRevision(namespaceName, serviceName string) (int64, error)
	GetInstancesHealthStatus(serviceID string, instanceIDs []string) (map[string]string, error)
	UpdateInstanceCustomHealthStatus(serviceID, instanceID, status string) error

	// Operation operations.
	GetOperation(id string) (*Operation, error)
	ListOperations(filter ListOperationsFilter) []Operation

	// Tag operations.
	ListTagsForResource(arn string) (map[string]string, error)
	TagResource(arn string, tags map[string]string) error
	UntagResource(arn string, tagKeys []string) error

	// Lifecycle methods.
	Reset()
	Region() string
	AccountID() string
	Snapshot(ctx context.Context) []byte
	Restore(ctx context.Context, data []byte) error
}

StorageBackend defines the operations required from the Cloud Map storage layer. All methods must be safe for concurrent use.

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.