cloudemu

README

cloudemu

Zero-Cost In-Memory Cloud Emulation for Go

---

cloudemu is a Go library that emulates cloud services entirely in memory. No real cloud accounts, no Docker, no network calls. Import the package, create a provider, and test your cloud code instantly.

aws := cloudemu.NewAWS()
azure := cloudemu.NewAzure()
gcp := cloudemu.NewGCP()

Installation

go get github.com/stackshy/cloudemu

Requires Go 1.25.0+.

The Problem

Testing cloud-dependent code is painful. You either pay for real accounts, wrestle with heavy emulators that need Docker, or write incomplete mocks from scratch.

Approach	Cost	Speed	Offline
Real cloud (AWS/Azure/GCP)	$$$	Slow (seconds)	No
LocalStack / Emulators	$	Medium (100ms+)	Yes
cloudemu	Free	Fast (~10ms)	Yes

How It Works

cloudemu provides mock implementations of cloud services that behave like the real thing. Each provider (AWS, Azure, GCP) gives you typed access to all supported services. You call the same operations you'd call in production — create resources, read data, manage lifecycle — and cloudemu handles it in memory with realistic behavior.

Example: EC2 Compute

package main

import (
    "context"
    "fmt"

    "github.com/stackshy/cloudemu"
    "github.com/stackshy/cloudemu/compute/driver"
)

func main() {
    ctx := context.Background()
    aws := cloudemu.NewAWS()

    // Launch 2 instances — they start in "pending" and transition to "running"
    instances, _ := aws.EC2.RunInstances(ctx, driver.InstanceConfig{
        ImageID:      "ami-0abcdef1234567890",
        InstanceType: "t2.micro",
        Tags:         map[string]string{"env": "test"},
    }, 2)

    fmt.Println(instances[0].State) // "running"
    fmt.Println(instances[0].ID)    // "i-00000001"

    // Stop an instance — state machine enforces valid transitions
    _ = aws.EC2.StopInstances(ctx, []string{instances[0].ID})

    // Describe to check state
    desc, _ := aws.EC2.DescribeInstances(ctx, []string{instances[0].ID}, nil)
    fmt.Println(desc[0].State) // "stopped"

    // Terminate
    _ = aws.EC2.TerminateInstances(ctx, []string{instances[0].ID})

    // Trying to stop a terminated instance returns an error — just like real EC2
    err := aws.EC2.StopInstances(ctx, []string{instances[0].ID})
    fmt.Println(err) // "cannot stop instance: invalid transition"
}

This same pattern works across all services and all three providers. Replace aws.EC2 with azure.VirtualMachines or gcp.GCE and the code behaves identically.

What Makes It Realistic

cloudemu goes beyond basic CRUD mocks. It reproduces real cloud behaviors so your tests catch real issues:

• State Machines — VMs enforce valid lifecycle transitions (pending → running → stopped → terminated). Illegal transitions return errors.
• Auto-Metrics — Launching a VM automatically pushes CPU, Network, and Disk metrics to the monitoring service. Stop/start/terminate emit corresponding metric values.
• Alarm Evaluation — Push metric data and alarms automatically transition between OK and ALARM based on threshold comparison.
• IAM Policy Evaluation — Parses JSON policy documents with wildcard matching. Explicit Deny overrides Allow.
• FIFO Deduplication — FIFO queues enforce 5-minute deduplication windows.
• Dead-Letter Queues — Messages exceeding max receive count move to the DLQ automatically.
• TTL Expiry — Cached items and database records expire after their TTL. Lazy cleanup on read.
• Stream/Change Feed — Database mutations produce stream records (INSERT/MODIFY/REMOVE).
• Numeric-Aware Comparisons — Database filters compare "10" > "9" correctly using numeric ordering.

Cross-Cutting Features

Every service can be wrapped with a portable API layer that adds test-oriented features:

bucket := storage.NewBucket(aws.S3,
    storage.WithRecorder(rec),              // record every API call
    storage.WithMetrics(mc),                // track call counts and durations
    storage.WithErrorInjection(inj),        // simulate cloud failures
    storage.WithRateLimiter(limiter),       // simulate API throttling
    storage.WithLatency(5*time.Millisecond),// simulate network delay
)

Feature	What It Does
Call Recording	Capture every API call with inputs, outputs, errors, and timing
Error Injection	Simulate failures: always, every Nth call, probabilistic, or first N calls
Rate Limiting	Token bucket limiter that returns Throttled errors when exhausted
Metrics Collection	Track calls_total, call_duration, errors_total per operation
Fake Clock	Control time for deterministic testing of TTL, dedup, alarms
Latency Simulation	Add delays to test timeout handling

Configuration

aws := cloudemu.NewAWS(
    config.WithRegion("eu-west-1"),
    config.WithAccountID("999888777666"),
    config.WithClock(config.NewFakeClock(time.Now())),
)

Error Handling

All operations return errors with canonical codes. Use helper functions to check types:

import cerrors "github.com/stackshy/cloudemu/errors"

_, err := aws.S3.GetObject(ctx, "bucket", "missing-key")
if cerrors.IsNotFound(err) {
    // handle missing resource
}

// Codes: NotFound, AlreadyExists, InvalidArgument,
//        FailedPrecondition, PermissionDenied, Throttled

Architecture

Three-layer design inspired by Go CDK:

Portable API     →  recording, metrics, rate limiting, error injection
Driver Interface →  minimal Go interfaces per service
Provider Mocks   →  in-memory backends (AWS/Azure/GCP) using generic memstore

All mocks are backed by a generic, thread-safe memstore.Store[V]. Services emit cloud-native metrics to the monitoring service, so you can query metrics via GetMetricData the same way you would with real CloudWatch, Azure Monitor, or Cloud Monitoring.

Running Tests

go build ./...   # compile
go vet ./...     # static analysis
go test -v ./... # run all tests

License

MIT

Documentation

Overview

Package cloudemu provides zero-cost, in-memory cloud emulation of AWS, Azure, and GCP cloud services for Go.

cloudemu follows a three-layer architecture:

• Portable API: High-level types (storage.Bucket, compute.Compute, etc.) that wrap drivers with cross-cutting concerns like recording, metrics, rate limiting, and error injection.

• Driver Interfaces: Minimal contracts (storage/driver, compute/driver, etc.) that each provider must implement.

• Provider Implementations: In-memory backends (providers/aws/s3, providers/azure/blobstorage, providers/gcp/gcs, etc.) powered by a generic memstore.

10 cloud services are covered across all three providers: Storage, Compute, Database, Serverless, Networking, Monitoring, IAM, DNS, Load Balancer, and Message Queue.

Index

• func NewAWS(opts ...config.Option) *aws.Provider
• func NewAzure(opts ...config.Option) *azure.Provider
• func NewGCP(opts ...config.Option) *gcp.Provider

Functions

func NewAWS

func NewAWS(opts ...config.Option) *aws.Provider

NewAWS creates a new AWS mock provider.

func NewAzure

func NewAzure(opts ...config.Option) *azure.Provider

NewAzure creates a new Azure mock provider.

func NewGCP

func NewGCP(opts ...config.Option) *gcp.Provider

NewGCP creates a new GCP mock provider.