Markdown# 🚀 Python-Native Reactive Infrastructure SDK

"Infrastructure should not just exist — it should listen, think, and react."

---

📖 Overview

This project introduces a paradigm shift from Static Infrastructure as Code (IaC) to Reactive Systems. Unlike Terraform or Pulumi which define a "desired state" at deployment time, this SDK builds infrastructure that remains runtime-aware.

It allows you to declare AWS resources, embedded observability (Prometheus), and reactive behaviors (Scaling/Standby) in a single, unified Python DSL.

✨ Key Capabilities

• 🐍 Pure Python DSL: No YAML, no HCL. Full IDE support (Type hinting, Autocomplete, Refactoring).
• 🧠 Embedded Observability: Define Prometheus alerts inside your infrastructure code.
• ⚡ Reactive Hooks: Infrastructure that self-modifies based on real-time metrics (e.g., Trigger standby EC2 when Primary CPU > 80%).
• 🧪 Simulation-First: Built-in stress testing primitives to validate system behavior before production.

---

🏗️ Architecture

The system closes the loop between Provisioning, Monitoring, and Action.

┌──────────────────────────┐
│   Developer Environment  │
│    (Python Infra DSL)    │
└────────────┬─────────────┘
             │ Provisions
             ▼
┌───────────────────────────────────────┐
│           AWS VPC (10.0.0.0)          │
│                                       │
│  ┌─────────────┐    ┌─────────────┐   │
│  │  Subnet A   │    │  Subnet B   │   │
│  └──────┬──────┘    └──────┬──────┘   │
│         │                  │          │
│         ▼                  ▼          │
│    EC2 Primary        EC2 Standby     │
│   (MySQL + Exp)       (Planned)       │
│         │                  ▲          │
│         └─► [Metrics] ─────┘          │
│                 │                     │
│           [Reactive Hook]             │
└───────────────────────────────────────┘
📦 The Code (DSL Showcase)1. Networking (No more YAML hell)Define complex networking logic using standard Python classes.Pythonfrom provider import aws

DSL

# Define VPC
vpc = aws.VPC(
    aws.IVPCProps(
        region="ap-south-1",
        cidr_block="10.0.0.0/16",
        auto_attach_igw=True,
        tags={"Name": "production-vpc"}
    )
)

# Define Subnet with dependency injection
subnet_1 = aws.Subnet(
    aws.ISubnetProps(
        resource_name="public-subnet-1",
        cidr_block="10.0.0.0/24",
        availability_zone="ap-south-1a",
        vpc_id=vpc.output("id"),  # <--- Dependency Resolution
        map_public_ip_on_launch=True
    )
)
2. Security Groups (Runtime-Aware)Explicitly define ingress rules, allowing specific monitoring IPs.Pythonsg_ssh = aws.SecurityGroup(
    aws.ISecurityGroupProps(
        group_name="sg_group_ssh",
        vpc_id=vpc.output("id"),
        rules=[
            # Standard SSH
            aws.ISecurityGroupRuleProps(type="ingress", from_port=22, to_port=22, protocol="tcp", cidr_blocks=["0.0.0.0/0"]),
            
            # Prometheus Scraper (Whitelisted)
            aws.ISecurityGroupRuleProps(type="ingress", from_port=9100, to_port=9100, protocol="tcp", cidr_blocks=["100.106.196.60/32"]),
        ]
    )
)
3. The "Killer Feature": Reactive EC2This is where the magic happens. We define an EC2 instance that knows how to monitor itself and what to do when it gets stressed.Pythonfrom provider import simulate

ec2_primary = aws.EC2(
    aws.IEC2Props(
        instance_type="t3a.medium",
        image_id="ami-06a644026f43160a5",
        subnet_id_azs=[subnet_1.output("id")],
        security_group_ids=[sg_ssh.output("id")],
        
        # 📈 Embedded Observability
        prometheus_rules=[
            aws.IPrometheusRuleProps(
                threshold="50",
                metric_query=simulate.sample_cpu_query_2m,
                mail_owner="admin@platform.com"
            ),
        ],

        # ⚡ Reactive Behavior: Auto-spawn Standby
        standby_timeline=aws.IStandbyTimelineProps(
            standby_prop=aws.IEC2StandbyProps(
                instance_type="t3a.large" # Scale up on reaction
            ),
            reactive_hook=aws.standard_reactive_hook,
            listen_metric_queries=simulate.sample_cpu_query_2m
        )
    )
)

# Simulation & ValidationDon't just hope it works. Test it. The SDK includes primitives to generate load and verify the reactive hooks.Python# Inject stress test to verify Autoscaling / Standby activation
simulate.Stress(
    simulate.IStressProps(
        ip=ec2_primary.output("public_ip"),
        user="ubuntu",
        key_path="gcp_key",
        cpu_core=2,
        timeout=300 # Sustain load for 5 minutes
    )
)

🔥 Paradigm Shift: Static vs. Reactive

We stand on the shoulders of giants. Tools like Terraform and Pulumi are the industry standard for Static Infrastructure. This project explores a new frontier: Reactive Infrastructure.

Feature	Standard IaC (Terraform/Pulumi)	This SDK (Reactive Approach)
Best For	Stable, predictable production environments	Self-healing, adaptive, and experimental systems
State Model	"Desired State" stored in a file	"Runtime State" derived from live metrics
Dependency	Resolved at Planning phase (Plan/Apply)	Resolved at Execution phase (Timeline Gravity)
Observability	External (CloudWatch/Datadog)	Embedded (Prometheus rules in Python code)
Philosophy	Immutable Infrastructure	Living Infrastructure

🧩 Use Cases

1. Self-Healing Databases: Automatically provision a read-replica when the primary experiences high read-latency.
2. Cost-Aware Computing: Switch to Spot Instances automatically when on-demand prices spike (via metric query).
3. Chaos Engineering: Programmatically inject failure scenarios and define automated recovery paths in the same file.

---

🚧 Status

This project is currently a Technical Proof of Concept (PoC) demonstrating the power of the "Timeline Gravity" pattern. It is designed for SREs, Platform Engineers, and Architects who want to push the boundaries of Infrastructure automation.