feat(ec2): NAT Gateway, EIP, Egress IGW, SecurityGroups (#24)

Author: sam-goodwin

.oxfmtrc.json

@@ -5,7 +5,7 @@
   "useTabs": false,
   "printWidth": 80,
   "endOfLine": "lf",
-  "experimentalTernaries": true,
+  "ternaries": true,
   "experimental_sort_imports": {
     "order": "asc"
   }

.oxlintrc.json

@@ -2,6 +2,7 @@
   "$schema": "./node_modules/oxfmt/configuration_schema.json",
   "rules": {
     "no-misused-new": "off",
-    "require-yield": "off"
+    "require-yield": "off",
+    "no-non-null-asserted-optional-chain": "off"
   }
-}
+}

.vscode/settings.json

@@ -55,5 +55,5 @@
   "[jsx]": {
     "editor.indentSize": 2,
     "editor.defaultFormatter": "oxc.oxc-vscode"
-  },
-}
+  }
+}

AGENTS.md

@@ -4,37 +4,52 @@ Conduct each engagement with the user as follows:
 
 1. Read the [README](README.md) to get a high-level overview of the project.
 2. Read the following code files to familiarize yourself with the common tasks:
-  - Declaring a Resource (see [queue.ts](alchemy-effect/src/aws/sqs/queue.ts))
-  - Implementing a Resource Provider (see [queue.provider.ts](alchemy-effect/src/aws/sqs/queue.provider.ts) or [table.provider.ts](alchemy-effect/src/aws/dynamodb/table.provider.ts))
-  - Declaring a Capability (see [queue.consume.ts](alchemy-effect/src/aws/sqs/queue.consume.ts))
-  - Implementing a Capability's Binding:
-    - Push-based Binding (see [queue.send-message.ts](alchemy-effect/src/aws/sqs/queue.send-message.ts))
-    - Pull-based Binding using postattach (see [queue.event-source.ts](alchemy-effect/src/aws/sqs/queue.event-source.ts))
-    - Fine-grained IAM policy modelling in the type-system (see [table.get-item.ts](alchemy-effect/src/aws/dynamodb/table.get-item.ts))
-  - Declaring a Function (aka Runtime) see [function.ts](alchemy-effect/src/aws/lambda/function.ts)
-  - Creating a Client for an AWS scope (see [aws/lambda/client.ts](alchemy-effect/src/aws/lambda/client.ts) and [aws/sqs/client.ts](alchemy-effect/src/aws/sqs/client.ts))
-  - Compiling the AWS.live layer (see [aws/index.ts](alchemy-effect/src/aws/index.ts))
-  - Using resources (see [example/src/api.ts](example/src/api.ts) and [example/src/consumer.ts](example/src/consumer.ts))
-3. When implementing a Resource Provider, make sure to read the [itty-aws](./alchemy-effect/node_modules/itty-aws/dist/services/*/types.d.ts)  type defnitions for that service and come up with a plan for which errors to retry, which to consider fatal, and design the overall create, update, delete flow for each of the resource lifecycle handlers. We are using effect, so we gain the benefit of type-safe errors, delcarative retry behavior (declarative flow control).
+
+- Declaring a Resource (see [queue.ts](alchemy-effect/src/aws/sqs/queue.ts))
+- Implementing a Resource Provider (see [queue.provider.ts](alchemy-effect/src/aws/sqs/queue.provider.ts) and [table.provider.ts](alchemy-effect/src/aws/dynamodb/table.provider.ts) and [vpc.provider.ts](alchemy-effect/src/aws/ec2/vpc.provider.ts) and [subnet.provider.ts](alchemy-effect/src/aws/ec2/subnet.provider.ts))
+- Implementing tests for Resource Providers (see [queue.provider.test.ts](alchemy-effect/test/aws/sqs/queue.provider.test.ts) and [table.provider.test.ts](alchemy-effect/test/aws/dynamodb/table.provider.test.ts) and [vpc.provider.test.ts](alchemy-effect/test/aws/ec2/vpc.provider.test.ts))
+- Implementing a comprehensive smoke test, see [vpc.test.ts](alchemy-effect/test/aws/ec2/vpc.test.ts)
+- Declaring a Capability (see [queue.consume.ts](alchemy-effect/src/aws/sqs/queue.consume.ts))
+- Implementing a Capability's Binding:
+  - Push-based Binding (see [queue.send-message.ts](alchemy-effect/src/aws/sqs/queue.send-message.ts))
+  - Pull-based Binding using postattach (see [queue.event-source.ts](alchemy-effect/src/aws/sqs/queue.event-source.ts))
+  - Fine-grained IAM policy modelling in the type-system (see [table.get-item.ts](alchemy-effect/src/aws/dynamodb/table.get-item.ts))
+- Declaring a Function (aka Runtime) see [function.ts](alchemy-effect/src/aws/lambda/function.ts)
+- Creating a Client for an AWS scope (see [aws/lambda/client.ts](alchemy-effect/src/aws/lambda/client.ts) and [aws/sqs/client.ts](alchemy-effect/src/aws/sqs/client.ts))
+- Compiling the AWS.live layer (see [aws/index.ts](alchemy-effect/src/aws/index.ts))
+- Using resources (see [example/src/api.ts](example/src/api.ts) and [example/src/consumer.ts](example/src/consumer.ts))
+
+Provider Implementation Tips:
+
+- The `diff` function should return `undefined` (not `{ action: "noop" }`) when properties don't require replacement - this allows the `update` function to be called for in-place attribute changes.
+- Only include service-specific attributes conditionally (e.g., SQS FIFO attributes like `FifoQueue`, `ContentBasedDeduplication` should only be sent for FIFO queues, not standard queues).
 
 Restrictions:
+
 1. Never use `Effect.catchAll`, always use `Effect.catchTag` or `Effect.catchTags`
 1. Always use `bun` (never npm, pnpm, yarn, etc.)
 
 :::caution
 Never (ever!) delete .alchemy/
 
-Tests are designed ot be idempotent. 
-When making changes to providers, you should keep running the tests and fixing providers until the tests pass. 
-If you think the state is corrupted stop and let me know. 
-You can always add a `yield* destroy()` at the beginning of each test to clean up state. Do not delete .alchemy files or folders.
+Tests are designed ot be idempotent.
+When making changes to providers, you should keep running the tests and fixing providers until the tests pass.
+If you think the state is corrupted, stop and let me know.
+You should always add a `yield* destroy()` at the beginning of each test to clean up state. Do not delete `.alchemy` files or folders.
 
 Never manually delete resources with the aws cli or api calls. Tests must be designed to be idempotent and self-healing.
 :::
 
 # Testing
 
 To test, use the following command:
+
 ```
 bun vitest run ./alchemy-effect/test/<path>/<to>/<test>.test.ts
 ```
+
+Run with DEBUG=1 to see debug logs, e.g.
+
+```ts
+Effect.tapError(Effect.logDebug),
+```

CHANGELOG.md

@@ -92,4 +92,3 @@
 #####     [View changes on GitHub](https://github.com/alchemy-run/alchemy/compare/c46b447ca0d46a9e4dbf08a6789770a420d90be5...v0.1.0)
 
 ---
-

README.md

@@ -3,13 +3,15 @@
 # `alchemy-effect`
 
 `alchemy-effect` is an **Infrastructure-as-Effects (IaE)** framework that unifies business logic and infrastructure config into a single, type-safe program with the following benefits:
+
 1. Type-Checked IAM Policies
 2. Optimally Tree-Shaken Bundles
 3. Testable Business Logic
 4. Re-usable Components
-5. Reviewable Deployment Plans 
+5. Reviewable Deployment Plans
 
 ## Install
+
 ```bash
 bun add alchemy-effect
 ```
@@ -27,11 +29,13 @@ You will receive a type error if you mess up your Bindings:
 > This error means you are missing the `SendMessage<Messages>` binding (you provided `never` instead of `SendMessage<Messages>`).
 
 ## Plan & Deploy
+
 An `alchemy-effect` program produces a Plan that can be reviewed prior to deployment:
 
 <img src="./images/alchemy-effect-plan.gif" alt="alchemy-effect plan video" width="600"/>
 
-## Type-Level Plan 
+## Type-Level Plan
+
 All knowable information about the Plan is available at compile-time:
 
 <img src="./images/alchemy-effect-plan-type.png" alt="alchemy-effect plan type" width="600"/>
@@ -50,17 +54,19 @@ export default Api.handler.pipe(
 );
 ```
 
-## Pluggable Layers 
+## Pluggable Layers
+
 Everything (including the CLI) is provided as Effect layers:
 
 <img src="./images/alchemy-effect-layers.png" alt="alchemy-effect layers" width="600"/>
 
 ## Literally Typed Outputs
+
 The output of deploying a stack is totally known at compile-time, e.g. the `.fifo` suffix of a SQS FIFO Queue:
 
 <img src="./images/alchemy-effect-output.png" alt="alchemy-effect output" width="600"/>
 
-# Concepts 🔱 
+# Concepts 🔱
 
 <img src="./images/alchemy-effect-triple.png" alt="alchemy-effect logo" width="600"/>
 
@@ -78,7 +84,7 @@ Resources are declared along-side your business logic as classes, e.g. a FIFO SQ
 class Messages extends SQS.Queue("Messages", {
   fifo: true,
   schema: S.String,
-}) {} 
+}) {}
 ```
 
 ## Functions
@@ -122,7 +128,7 @@ class Api extends Lambda.serve("Api", {
 
 # Components
 
-Infrastructure and business logic can be encapsulated as a Component using a simple function. 
+Infrastructure and business logic can be encapsulated as a Component using a simple function.
 
 ```ts
 const Monitor = <const ID extends string, ReqAlarm, ReqResolved>(
@@ -176,4 +182,4 @@ const Monitor = <const ID extends string, ReqAlarm, ReqResolved>(
 # Building your own Resources, Capabilities, and Bindings
 
 > [!CAUTION]
-> WIP - docs coming soon!
+> WIP - docs coming soon!

alchemy-effect/package.json

@@ -1,114 +1,117 @@
 {
   "name": "alchemy-effect",
   "version": "0.5.0",
+  "homepage": "https://alchemy.run",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
-  "homepage": "https://alchemy.run",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alchemy-run/alchemy-effect.git",
     "directory": "alchemy"
   },
-  "type": "module",
-  "sideEffects": false,
+  "bin": {
+    "alchemy-effect": "bin/alchemy-effect.js"
+  },
   "files": [
     "bin",
     "lib",
     "src"
   ],
-  "bin": {
-    "alchemy-effect": "bin/alchemy-effect.js"
-  },
-  "scripts": {
-    "dev": "tsdown --watch",
-    "build": "bun bundle && bun pm pack",
-    "bundle": "tsdown",
-    "bundle:watch": "tsdown --watch",
-    "publish:npm": "cp ../README.md . && bun publish && rm README.md",
-    "test:benchmark": "tsx --tsconfig tsconfig.test.json test/types.benchmark.ts"
-  },
+  "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "bun": "./src/index.ts",
-      "import": "./lib/index.js",
-      "types": "./src/index.d.ts"
+      "import": "./lib/index.js"
     },
     "./Output": {
+      "types": "./lib/output.d.ts",
       "bun": "./src/output.ts",
-      "import": "./lib/output.js",
-      "types": "./lib/output.d.ts"
+      "import": "./lib/output.js"
     },
     "./aws": {
+      "types": "./lib/aws/index.d.ts",
       "bun": "./src/aws/index.ts",
-      "import": "./lib/aws/index.js",
-      "types": "./lib/aws/index.d.ts"
+      "import": "./lib/aws/index.js"
     },
     "./aws/dynamodb": {
+      "types": "./lib/aws/dynamodb/index.d.ts",
       "bun": "./src/aws/dynamodb/index.ts",
-      "import": "./lib/aws/dynamodb/index.js",
-      "types": "./lib/aws/dynamodb/index.d.ts"
+      "import": "./lib/aws/dynamodb/index.js"
     },
     "./aws/ec2": {
+      "types": "./lib/aws/ec2/index.d.ts",
       "bun": "./src/aws/ec2/index.ts",
-      "import": "./lib/aws/ec2/index.js",
-      "types": "./lib/aws/ec2/index.d.ts"
+      "import": "./lib/aws/ec2/index.js"
     },
     "./aws/lambda": {
+      "types": "./lib/aws/lambda/index.d.ts",
       "bun": "./src/aws/lambda/index.ts",
-      "import": "./lib/aws/lambda/index.js",
-      "types": "./lib/aws/lambda/index.d.ts"
+      "import": "./lib/aws/lambda/index.js"
     },
     "./aws/sqs": {
+      "types": "./lib/sqs/aws/index.d.ts",
       "bun": "./src/aws/sqs/index.ts",
-      "import": "./lib/aws/sqs/index.js",
-      "types": "./lib/sqs/aws/index.d.ts"
+      "import": "./lib/aws/sqs/index.js"
     },
     "./aws/sts": {
+      "types": "./lib/sts.d.ts",
       "bun": "./src/aws/sts.ts",
-      "import": "./lib/aws/sts.js",
-      "types": "./lib/sts.d.ts"
+      "import": "./lib/aws/sts.js"
     },
     "./aws/iam": {
+      "types": "./lib/iam.d.ts",
       "bun": "./src/aws/iam.ts",
-      "import": "./lib/aws/iam.js",
-      "types": "./lib/iam.d.ts"
+      "import": "./lib/aws/iam.js"
     },
     "./aws/credentials": {
+      "types": "./lib/aws/credentials.d.ts",
       "bun": "./src/aws/credentials.ts",
-      "import": "./lib/aws/credentials.js",
-      "types": "./lib/aws/credentials.d.ts"
+      "import": "./lib/aws/credentials.js"
     },
     "./cli": {
+      "types": "./lib/cli/index.d.ts",
       "bun": "./src/cli/index.ts",
-      "import": "./lib/cli/index.js",
-      "types": "./lib/cli/index.d.ts"
+      "import": "./lib/cli/index.js"
     },
     "./cloudflare": {
+      "types": "./lib/cloudflare/index.d.ts",
       "bun": "./src/cloudflare/index.ts",
-      "import": "./lib/cloudflare/index.js",
-      "types": "./lib/cloudflare/index.d.ts"
+      "import": "./lib/cloudflare/index.js"
     },
     "./cloudflare/assets": {
+      "types": "./lib/cloudflare/worker/assets.fetch.d.ts",
       "bun": "./src/cloudflare/worker/assets.fetch.ts",
-      "import": "./lib/cloudflare/worker/assets.fetch.js",
-      "types": "./lib/cloudflare/worker/assets.fetch.d.ts"
+      "import": "./lib/cloudflare/worker/assets.fetch.js"
     },
     "./cloudflare/worker": {
+      "types": "./lib/cloudflare/worker/index.d.ts",
       "bun": "./src/cloudflare/worker/index.ts",
-      "import": "./lib/cloudflare/worker/index.js",
-      "types": "./lib/cloudflare/worker/index.d.ts"
+      "import": "./lib/cloudflare/worker/index.js"
     },
     "./cloudflare/kv": {
+      "types": "./lib/cloudflare/kv/index.d.ts",
       "bun": "./src/cloudflare/kv/index.ts",
-      "import": "./lib/cloudflare/kv/index.js",
-      "types": "./lib/cloudflare/kv/index.d.ts"
+      "import": "./lib/cloudflare/kv/index.js"
     },
     "./cloudflare/r2": {
+      "types": "./lib/cloudflare/r2/index.d.ts",
       "bun": "./src/cloudflare/r2/index.ts",
-      "import": "./lib/cloudflare/r2/index.js",
-      "types": "./lib/cloudflare/r2/index.d.ts"
+      "import": "./lib/cloudflare/r2/index.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "bun bundle && bun pm pack",
+    "bundle": "tsdown",
+    "bundle:watch": "tsdown --watch",
+    "publish:npm": "cp ../README.md . && bun publish && rm README.md",
+    "test:benchmark": "tsx --tsconfig tsconfig.test.json test/types.benchmark.ts"
+  },
   "dependencies": {
     "@aws-sdk/credential-providers": "catalog:",
     "@effect/vitest": "^0.27.0",
@@ -160,8 +163,5 @@
     "effect": {
       "optional": true
     }
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }