async

package
v0.20.0 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package async provides interfaces for async infrastructure provisioning.

Index

Constants

View Source 
const (
	// DefaultKafkaRetentionMs is the default topic retention (24h in milliseconds) for ephemeral preview topics.
	DefaultKafkaRetentionMs = "86400000"
	// AnnotationKafkaRetentionMs allows overriding the preview Kafka topic retention.ms in milliseconds.
	AnnotationKafkaRetentionMs = "divergedev.com/kafka-retention-ms"
)
View Source 
const (
	AnnotationRedisAddr = "divergedev.com/redis-addr"
	AnnotationRedisDB   = "divergedev.com/redis-db"
)
View Source 
const (
	AnnotationStorageEndpoint = "divergedev.com/storage-endpoint"
	AnnotationStorageBucket   = "divergedev.com/storage-bucket"
)

Variables

View Source 
var ErrNilProvisionResult = errors.New("provisioner returned nil result")

ErrNilProvisionResult is returned when a provisioner returns nil result without an error.

View Source 
var Providers = registry.New[Provisioner]("async-provisioner")

Providers is the registry for async provisioners.

Functions

func FormatNamespacedStorageKeyPrefix added in v0.19.0 

func FormatNamespacedStorageKeyPrefix(namespace, target, envName string) string

FormatNamespacedStorageKeyPrefix returns the namespace-scoped object key prefix for an environment and route target.

func FormatRedisKeyPrefix added in v0.17.0 

func FormatRedisKeyPrefix(target, envName string) string

FormatRedisKeyPrefix returns the deterministic key prefix for an environment and route target.

func FormatStorageKeyPrefix added in v0.19.0 

func FormatStorageKeyPrefix(target, envName string, namespace ...string) string

FormatStorageKeyPrefix returns the deterministic object key prefix for an environment, route target, and optional namespace.

Types

type KafkaAdmin 

type KafkaAdmin interface {
	CreateTopics(ctx context.Context, partitions int32, replication int16, configs map[string]*string, topics ...string) (kadm.CreateTopicResponses, error)
	AlterTopicConfigs(ctx context.Context, configs []kadm.AlterConfig, topics ...string) (kadm.AlterConfigsResponses, error)
	DeleteTopics(ctx context.Context, topics ...string) (kadm.DeleteTopicResponses, error)
	Close()
}

KafkaAdmin abstracts the Kafka admin operations for testability.

type KafkaAdminFactory 

type KafkaAdminFactory func(brokers []string) (KafkaAdmin, error)

KafkaAdminFactory creates KafkaAdmin instances. Defaults to real kadm.Client.

type KafkaProvisioner 

type KafkaProvisioner struct {
	Brokers           []string
	NumPartitions     int32
	ReplicationFactor int16
	AdminFactory      KafkaAdminFactory // nil = use real kadm
}

KafkaProvisioner provisions Kafka topics and consumer groups for preview environments using the Kafka AdminClient API. Compatible with Apache Kafka, AutoMQ, Redpanda, MSK, and any Kafka-protocol broker.

func (*KafkaProvisioner) Name 

func (k *KafkaProvisioner) Name() string

Name returns the provisioner name.

func (*KafkaProvisioner) Provision 

func (k *KafkaProvisioner) Provision(ctx context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) (*ProvisionResult, error)

func (*KafkaProvisioner) Teardown 

func (k *KafkaProvisioner) Teardown(ctx context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) error

Teardown deletes the preview-scoped Kafka topic.

type NoopProvisioner 

type NoopProvisioner struct{}

NoopProvisioner is a no-op provisioner that returns the target unchanged.

func (*NoopProvisioner) Name 

func (n *NoopProvisioner) Name() string

Name returns the provisioner name.

func (*NoopProvisioner) Provision 

func (n *NoopProvisioner) Provision(_ context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) (*ProvisionResult, error)

Provision returns a resolved target of "<target>-<envName>" and populates default or custom environment variables without creating real infrastructure.

func (*NoopProvisioner) Teardown 

func (n *NoopProvisioner) Teardown(_ context.Context, _ *v1alpha1.Environment, _ v1alpha1.AsyncRouteSpec) error

Teardown is a no-op since no real infrastructure was created.

type ProvisionResult 

type ProvisionResult struct {
	// ResolvedTarget is the provisioned resource name (e.g., "preview-123-payments" task queue).
	ResolvedTarget string
	// EnvVars are environment variables to inject into preview pods.
	EnvVars map[string]string
}

ProvisionResult contains the result of provisioning an async route.

type Provisioner 

type Provisioner interface {
	// Provision creates async infrastructure for the given route spec.
	Provision(ctx context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) (*ProvisionResult, error)
	// Teardown removes async infrastructure for the given route spec.
	Teardown(ctx context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) error
	// Name returns the provisioner name.
	Name() string
}

Provisioner provisions and tears down async infrastructure for preview environments.

type RedisProvisioner added in v0.17.0 

type RedisProvisioner struct {
	Addr     string // Optional Redis/Valkey host:port for active key eviction on Teardown
	Username string // Optional ACL username (Redis 6+ / Valkey)
	Password string // Optional AUTH password
	DB       int    // Optional logical DB number
	Provider string // "redis" or "valkey" (default "redis")
}

RedisProvisioner provisions key-prefix isolation for Redis and Valkey preview environments and evicts preview-scoped keys via non-blocking SCAN + UNLINK upon environment teardown.

func (*RedisProvisioner) Name added in v0.17.0 

func (r *RedisProvisioner) Name() string

Name returns the provisioner name ("redis" or "valkey").

func (*RedisProvisioner) Provision added in v0.17.0 

func (r *RedisProvisioner) Provision(_ context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) (*ProvisionResult, error)

Provision computes the preview Redis/Valkey key prefix and injects environment variables.

func (*RedisProvisioner) Teardown added in v0.17.0 

func (r *RedisProvisioner) Teardown(ctx context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) error

Teardown connects to Redis/Valkey (if configured) and evicts all keys matching the preview prefix using cursor-based SCAN and non-blocking UNLINK.

type StorageProvisioner added in v0.19.0 

type StorageProvisioner struct {
	Endpoint   string       // Optional S3/MinIO/GCS endpoint override
	Bucket     string       // Optional default bucket name
	Provider   string       // "s3", "gcs", or "minio" (default "s3")
	HTTPClient *http.Client // Optional HTTP client for Teardown API calls
	AccessKey  string       // Optional S3/MinIO access key ID
	SecretKey  string       // Optional S3/MinIO secret access key
	Region     string       // Optional S3 region (default "us-east-1")
	GCSToken   string       // Optional GCS Bearer token
}

StorageProvisioner provisions object key-prefix isolation for S3, GCS, and MinIO preview environments so preview uploads/mutations do not collide with baseline buckets.

func (*StorageProvisioner) Name added in v0.19.0 

func (s *StorageProvisioner) Name() string

Name returns the provisioner name ("s3", "gcs", or "minio").

func (*StorageProvisioner) Provision added in v0.19.0 

func (s *StorageProvisioner) Provision(_ context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) (*ProvisionResult, error)

Provision computes the preview object storage key prefix and injects environment variables.

func (*StorageProvisioner) Teardown added in v0.19.0 

func (s *StorageProvisioner) Teardown(ctx context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) error

Teardown validates the environment and deletes all objects under the preview key prefix when a storage endpoint and bucket are configured.

type TemporalProvisioner 

type TemporalProvisioner struct {
	// Namespace is the Temporal namespace to use.
	Namespace string
}

TemporalProvisioner provisions Temporal task queues for preview environments. Task queues in Temporal are lazy — they auto-create when a worker polls. This provisioner generates deterministic queue names and injects them as env vars.

func (*TemporalProvisioner) Name 

func (t *TemporalProvisioner) Name() string

Name returns the provisioner name.

func (*TemporalProvisioner) Provision 

func (t *TemporalProvisioner) Provision(_ context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) (*ProvisionResult, error)

Provision generates a preview-scoped task queue name. Temporal task queues auto-create on first worker poll, so no actual provisioning is needed.

func (*TemporalProvisioner) Teardown 

func (t *TemporalProvisioner) Teardown(_ context.Context, _ *v1alpha1.Environment, _ v1alpha1.AsyncRouteSpec) error

Teardown is a no-op for Temporal — stale task queues are harmless and are garbage-collected by Temporal when no workers are polling.

type WebhookProvisioner 

type WebhookProvisioner struct {
	Endpoint   string
	HTTPClient *http.Client
}

WebhookProvisioner calls an external webhook to provision async infrastructure.

func NewWebhookProvisioner 

func NewWebhookProvisioner(endpoint string) *WebhookProvisioner

NewWebhookProvisioner creates a WebhookProvisioner targeting the given endpoint URL.

func (*WebhookProvisioner) Name 

func (w *WebhookProvisioner) Name() string

Name returns the provisioner name.

func (*WebhookProvisioner) Provision 

func (w *WebhookProvisioner) Provision(ctx context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) (*ProvisionResult, error)

Provision calls the webhook endpoint to create async infrastructure and returns the resolved target and environment variables to inject into preview pods.

func (*WebhookProvisioner) Teardown 

func (w *WebhookProvisioner) Teardown(ctx context.Context, env *v1alpha1.Environment, route v1alpha1.AsyncRouteSpec) error

Teardown calls the webhook endpoint to remove async infrastructure for the given route.

type WebhookRequest 

type WebhookRequest struct {
	Action      string                  `json:"action"` // "provision" or "teardown"
	Environment string                  `json:"environment"`
	Namespace   string                  `json:"namespace"`
	Route       v1alpha1.AsyncRouteSpec `json:"route"`
}

WebhookRequest is sent to the provisioning webhook.

type WebhookResponse 

type WebhookResponse struct {
	ResolvedTarget string            `json:"resolvedTarget"`
	EnvVars        map[string]string `json:"envVars"`
}

WebhookResponse is returned by the provisioning webhook.

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.