pangea-aws 0.1.0

data/lib/pangea/resources/aws_api_gateway_rest_api/types.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'dry-struct'
+require 'pangea/resources/types'
+
+module Pangea
+  module Resources
+    module AWS
+      module Types
+        # API Gateway REST API attributes with validation
+        class ApiGatewayRestApiAttributes < Pangea::Resources::BaseAttributes
+          transform_keys(&:to_sym)
+          
+          # Core attributes
+          attribute? :name, Pangea::Resources::Types::String.optional
+          attribute? :description, Pangea::Resources::Types::String.optional
+          
+          # API type - EDGE (CloudFront), REGIONAL, or PRIVATE
+          attribute? :endpoint_configuration do
+            attribute? :types, Pangea::Resources::Types::Array.of(
+              Pangea::Resources::Types::String.constrained(included_in: ['EDGE', 'REGIONAL', 'PRIVATE'])
+            ).default(['REGIONAL'].freeze)
+            attribute? :vpc_endpoint_ids, Pangea::Resources::Types::Array.of(Pangea::Resources::Types::String).optional
+          end
+          
+          # API versioning
+          attribute? :version, Pangea::Resources::Types::String.optional
+          attribute? :clone_from, Pangea::Resources::Types::String.optional
+          
+          # Binary media types for file uploads
+          attribute :binary_media_types, Pangea::Resources::Types::Array.of(Pangea::Resources::Types::String).default([].freeze)
+          
+          # Minimum TLS version
+          attribute :minimum_tls_version, Pangea::Resources::Types::String.constrained(included_in: ['TLS_1_0', 'TLS_1_2']).default('TLS_1_2')
+          
+          # Compression settings
+          attribute? :minimum_compression_size, Pangea::Resources::Types::Coercible::Integer.optional
+          
+          # API Key source for authentication
+          attribute :api_key_source, Pangea::Resources::Types::String.constrained(included_in: ['HEADER', 'AUTHORIZER']).default('HEADER')
+          
+          # Policy document for resource policies
+          attribute? :policy, Pangea::Resources::Types::String.optional
+          
+          # OpenAPI/Swagger specification
+          attribute? :body, Pangea::Resources::Types::String.optional
+          
+          # Disable execute API endpoint
+          attribute :disable_execute_api_endpoint, Pangea::Resources::Types::Bool.default(false)
+          
+          # Custom domain settings
+          attribute? :custom_domain_name, Pangea::Resources::Types::String.optional
+          
+          # Tags
+          attribute :tags, Pangea::Resources::Types::Hash.default({}.freeze)
+          
+          # Custom validation
+          def self.new(attributes)
+            attrs = attributes.is_a?(::Hash) ? attributes : {}
+            
+            # Validate name follows API Gateway naming conventions
+            if attrs[:name] && !attrs[:name].match?(/^[a-zA-Z0-9._-]+$/)
+              raise Dry::Struct::Error, "API name must contain only alphanumeric characters, hyphens, underscores, and periods"
+            end
+            
+            # Validate VPC endpoint IDs are provided for PRIVATE APIs
+            if attrs[:endpoint_configuration] && 
+               attrs[:endpoint_configuration][:types]&.include?('PRIVATE') &&
+               attrs[:endpoint_configuration][:vpc_endpoint_ids].to_a.empty?
+              raise Dry::Struct::Error, "VPC endpoint IDs must be provided for PRIVATE API type"
+            end
+            
+            # Validate compression size is reasonable
+            if attrs[:minimum_compression_size] && 
+               (attrs[:minimum_compression_size] < 0 || attrs[:minimum_compression_size] > 10485760)
+              raise Dry::Struct::Error, "Minimum compression size must be between 0 and 10485760 bytes (10MB)"
+            end
+            
+            # Validate binary media types format
+            if attrs[:binary_media_types]
+              attrs[:binary_media_types].each do |media_type|
+                unless media_type.match?(%r{^[\w\-\+\.]+/[\w\-\+\.]+$})
+                  raise Dry::Struct::Error, "Invalid binary media type format: #{media_type}. Expected format: type/subtype"
+                end
+              end
+            end
+            
+            super(attrs)
+          end
+          
+          # Computed properties
+          def is_edge_optimized?
+            endpoint_configuration&.types&.include?('EDGE')
+          end
+
+          def is_regional?
+            endpoint_configuration&.types&.include?('REGIONAL')
+          end
+
+          def is_private?
+            endpoint_configuration&.types&.include?('PRIVATE')
+          end
+          
+          def supports_binary_content?
+            !binary_media_types.empty?
+          end
+          
+          def has_custom_domain?
+            !custom_domain_name.nil?
+          end
+          
+          def estimated_monthly_cost
+            # API Gateway pricing (rough estimates)
+            # $3.50 per million API calls for REST APIs
+            # Plus data transfer costs
+            
+            base_cost = 0.0
+            
+            # Base charge for REST API (assumed 1M calls/month for estimate)
+            base_cost += 3.50
+            
+            # Cache costs if enabled (not directly configurable here but common)
+            # $0.02 per GB-hour for 0.5 GB cache = ~$7.20/month
+            
+            # Data transfer costs vary by region
+            # Rough estimate: $0.09/GB for first 10TB
+            
+            base_cost
+          end
+          
+          # Common binary media types for APIs
+          def self.common_binary_types
+            [
+              'image/png',
+              'image/jpeg',
+              'image/gif',
+              'application/pdf',
+              'application/octet-stream',
+              'application/zip',
+              'multipart/form-data'
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/resources/aws_api_gateway_stage/resource/helpers/basic.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Pangea
+  module Resources
+    module AWS
+      module ApiGatewayStageResource
+        module HelpersModules
+          # Basic helper methods for API Gateway Stage resource reference
+          module Basic
+            def add_basic_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:has_caching?) { stage_attrs.has_caching? }
+              ref.define_singleton_method(:has_access_logging?) { stage_attrs.has_access_logging? }
+              ref.define_singleton_method(:has_canary?) { stage_attrs.has_canary? }
+              ref.define_singleton_method(:has_throttling?) { stage_attrs.has_throttling? }
+              ref.define_singleton_method(:has_method_settings?) { stage_attrs.has_method_settings? }
+              ref.define_singleton_method(:estimated_monthly_cost) { stage_attrs.estimated_monthly_cost }
+            end
+
+            def add_stage_type_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:stage_type) do
+                if stage_attrs.stage_name.match?(/^(prod|production)$/i)
+                  "production"
+                elsif stage_attrs.stage_name.match?(/^(dev|development)$/i)
+                  "development"
+                elsif stage_attrs.stage_name.match?(/^(stag|staging)$/i)
+                  "staging"
+                else
+                  "custom"
+                end
+              end
+
+              ref.define_singleton_method(:is_production_stage?) do
+                stage_attrs.stage_name.match?(/^(prod|production)$/i)
+              end
+
+              ref.define_singleton_method(:is_development_stage?) do
+                stage_attrs.stage_name.match?(/^(dev|development)$/i)
+              end
+
+              ref.define_singleton_method(:is_staging_stage?) do
+                stage_attrs.stage_name.match?(/^(stag|staging)$/i)
+              end
+            end
+
+            def add_variable_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:variable_count) { stage_attrs.variables.size }
+              ref.define_singleton_method(:has_stage_variables?) { !stage_attrs.variables.empty? }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/resources/aws_api_gateway_stage/resource/helpers/configuration.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Pangea
+  module Resources
+    module AWS
+      module ApiGatewayStageResource
+        module HelpersModules
+          # Configuration helper methods for API Gateway Stage resource reference
+          module Configuration
+            def add_cache_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:cache_configuration) do
+                if stage_attrs.has_caching?
+                  {
+                    enabled: true,
+                    cluster_size: stage_attrs.cache_cluster_size,
+                    estimated_cost: stage_attrs.estimated_monthly_cost,
+                    methods_with_caching: stage_attrs.method_settings.select { |ms| ms[:caching_enabled] }.map { |ms| "#{ms[:http_method]} #{ms[:resource_path]}" }
+                  }
+                else
+                  { enabled: false }
+                end
+              end
+            end
+
+            def add_throttling_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:throttling_configuration) do
+                config = {
+                  stage_level: stage_attrs.has_throttling?,
+                  method_level: stage_attrs.method_settings.any? { |ms| ms[:throttling_burst_limit] || ms[:throttling_rate_limit] }
+                }
+
+                if stage_attrs.has_throttling?
+                  config[:stage_limits] = {
+                    burst_limit: stage_attrs.throttle_burst_limit,
+                    rate_limit: stage_attrs.throttle_rate_limit
+                  }
+                end
+
+                method_throttling = stage_attrs.method_settings.select { |ms| ms[:throttling_burst_limit] || ms[:throttling_rate_limit] }
+                if method_throttling.any?
+                  config[:method_limits] = method_throttling.map do |ms|
+                    {
+                      path: "#{ms[:http_method]} #{ms[:resource_path]}",
+                      burst_limit: ms[:throttling_burst_limit],
+                      rate_limit: ms[:throttling_rate_limit]
+                    }
+                  end
+                end
+
+                config
+              end
+            end
+
+            def add_logging_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:logging_configuration) do
+                config = { enabled: stage_attrs.has_access_logging? }
+
+                if stage_attrs.has_access_logging?
+                  config[:access_logs] = stage_attrs.access_log_settings
+
+                  # Check if format is JSON
+                  format_str = stage_attrs.access_log_settings[:format]
+                  config[:format_type] = format_str&.start_with?('{') ? 'json' : 'text'
+                end
+
+                # Method-level logging
+                method_logging = stage_attrs.method_settings.select { |ms| ms[:logging_level] && ms[:logging_level] != 'OFF' }
+                if method_logging.any?
+                  config[:method_logging] = method_logging.map do |ms|
+                    {
+                      path: "#{ms[:http_method]} #{ms[:resource_path]}",
+                      level: ms[:logging_level],
+                      data_trace: ms[:data_trace_enabled]
+                    }
+                  end
+                end
+
+                config[:xray_tracing] = stage_attrs.xray_tracing_enabled
+                config
+              end
+            end
+
+            def add_canary_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:canary_configuration) do
+                if stage_attrs.has_canary?
+                  {
+                    enabled: true,
+                    percent_traffic: stage_attrs.canary_settings[:percent_traffic],
+                    deployment_id: stage_attrs.canary_settings[:deployment_id],
+                    variable_overrides: stage_attrs.canary_settings[:stage_variable_overrides] || {},
+                    use_stage_cache: stage_attrs.canary_settings[:use_stage_cache]
+                  }
+                else
+                  { enabled: false }
+                end
+              end
+
+              ref.define_singleton_method(:canary_percentage) do
+                stage_attrs.has_canary? ? stage_attrs.canary_settings[:percent_traffic] : 0.0
+              end
+            end
+
+            def add_security_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:security_configuration) do
+                {
+                  client_certificate: !stage_attrs.client_certificate_id.nil?,
+                  xray_tracing: stage_attrs.xray_tracing_enabled,
+                  access_logging: stage_attrs.has_access_logging?,
+                  cache_encryption: stage_attrs.method_settings.any? { |ms| ms[:cache_data_encrypted] },
+                  throttling_protection: stage_attrs.has_throttling?
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/resources/aws_api_gateway_stage/resource/helpers/method_settings.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Pangea
+  module Resources
+    module AWS
+      module ApiGatewayStageResource
+        module HelpersModules
+          # Method settings and optimization helper methods
+          module MethodSettings
+            def add_method_settings_helpers(ref, name, stage_attrs)
+              ref.define_singleton_method(:method_settings_count) { stage_attrs.method_settings.size }
+
+              ref.define_singleton_method(:methods_with_special_settings) do
+                stage_attrs.method_settings.map do |ms|
+                  settings = []
+                  settings << 'caching' if ms[:caching_enabled]
+                  settings << 'throttling' if ms[:throttling_burst_limit] || ms[:throttling_rate_limit]
+                  settings << 'logging' if ms[:logging_level] && ms[:logging_level] != 'OFF'
+                  settings << 'metrics' if ms[:metrics_enabled]
+
+                  {
+                    path: "#{ms[:http_method]} #{ms[:resource_path]}",
+                    settings: settings
+                  }
+                end
+              end
+
+              ref.define_singleton_method(:stage_url) do
+                "\${aws_api_gateway_stage.#{name}.invoke_url}"
+              end
+
+              ref.define_singleton_method(:common_log_formats) do
+                Types::ApiGatewayStageAttributes.common_log_formats
+              end
+
+              ref.define_singleton_method(:common_method_paths) do
+                Types::ApiGatewayStageAttributes.common_method_paths
+              end
+            end
+
+            def add_optimization_helpers(ref, stage_attrs)
+              ref.define_singleton_method(:optimization_recommendations) do
+                recommendations = []
+
+                # Caching recommendations
+                if !stage_attrs.has_caching? && ref.is_production_stage?
+                  recommendations << "Consider enabling caching for production workloads"
+                elsif stage_attrs.has_caching? && stage_attrs.cache_cluster_size == '0.5'
+                  recommendations << "Consider larger cache size for better performance"
+                end
+
+                # Throttling recommendations
+                if !stage_attrs.has_throttling?
+                  recommendations << "Consider adding throttling limits to protect backend services"
+                end
+
+                # Monitoring recommendations
+                if !stage_attrs.xray_tracing_enabled && ref.is_production_stage?
+                  recommendations << "Enable X-Ray tracing for production observability"
+                end
+
+                # Logging recommendations
+                if !stage_attrs.has_access_logging?
+                  recommendations << "Enable access logging for monitoring and debugging"
+                end
+
+                recommendations
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/resources/aws_api_gateway_stage/resource/helpers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'helpers/basic'
+require_relative 'helpers/configuration'
+require_relative 'helpers/method_settings'
+
+module Pangea
+  module Resources
+    module AWS
+      module ApiGatewayStageResource
+        # Helper methods for API Gateway Stage resource reference
+        module Helpers
+          include HelpersModules::Basic
+          include HelpersModules::Configuration
+          include HelpersModules::MethodSettings
+
+          # Add computed properties to the resource reference
+          def add_reference_helpers(ref, name, stage_attrs)
+            add_basic_helpers(ref, stage_attrs)
+            add_stage_type_helpers(ref, stage_attrs)
+            add_cache_helpers(ref, stage_attrs)
+            add_throttling_helpers(ref, stage_attrs)
+            add_logging_helpers(ref, stage_attrs)
+            add_canary_helpers(ref, stage_attrs)
+            add_variable_helpers(ref, stage_attrs)
+            add_method_settings_helpers(ref, name, stage_attrs)
+            add_security_helpers(ref, stage_attrs)
+            add_optimization_helpers(ref, stage_attrs)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/resources/aws_api_gateway_stage/resource/main.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Pangea
+  module Resources
+    module AWS
+      module ApiGatewayStageResource
+        # Core resource definition for API Gateway Stage
+        module Main
+          # Generate the Terraform resource block
+          def generate_stage_resource(name, stage_attrs)
+            resource :aws_api_gateway_stage, name do
+              # Core configuration
+              rest_api_id stage_attrs.rest_api_id
+              deployment_id stage_attrs.deployment_id
+              stage_name stage_attrs.stage_name
+
+              # Stage configuration
+              description stage_attrs.description if stage_attrs.description
+              documentation_version stage_attrs.documentation_version if stage_attrs.documentation_version
+
+              # Caching
+              cache_cluster_enabled stage_attrs.cache_cluster_enabled
+              cache_cluster_size stage_attrs.cache_cluster_size if stage_attrs.cache_cluster_size
+
+              # Variables
+              variables stage_attrs.variables unless stage_attrs.variables.empty?
+
+              # Monitoring
+              xray_tracing_enabled stage_attrs.xray_tracing_enabled
+
+              # Access logging - pass as hash to avoid Kernel#format conflict
+              if stage_attrs.access_log_settings
+                access_log_settings(stage_attrs.access_log_settings)
+              end
+
+              # Throttling
+              throttle_burst_limit stage_attrs.throttle_burst_limit if stage_attrs.throttle_burst_limit
+              throttle_rate_limit stage_attrs.throttle_rate_limit if stage_attrs.throttle_rate_limit
+
+              # Method settings
+              unless stage_attrs.method_settings.empty?
+                stage_attrs.method_settings.each do |method_setting|
+                  method_settings do
+                    resource_path method_setting[:resource_path]
+                    http_method method_setting[:http_method]
+                    metrics_enabled method_setting[:metrics_enabled] if method_setting.key?(:metrics_enabled)
+                    logging_level method_setting[:logging_level] if method_setting[:logging_level]
+                    data_trace_enabled method_setting[:data_trace_enabled] if method_setting.key?(:data_trace_enabled)
+                    throttling_burst_limit method_setting[:throttling_burst_limit] if method_setting[:throttling_burst_limit]
+                    throttling_rate_limit method_setting[:throttling_rate_limit] if method_setting[:throttling_rate_limit]
+                    caching_enabled method_setting[:caching_enabled] if method_setting.key?(:caching_enabled)
+                    cache_ttl_in_seconds method_setting[:cache_ttl_in_seconds] if method_setting[:cache_ttl_in_seconds]
+                    cache_data_encrypted method_setting[:cache_data_encrypted] if method_setting.key?(:cache_data_encrypted)
+                    require_authorization_for_cache_control method_setting[:require_authorization_for_cache_control] if method_setting.key?(:require_authorization_for_cache_control)
+                  end
+                end
+              end
+
+              # Canary settings
+              if stage_attrs.canary_settings
+                canary_settings do
+                  percent_traffic stage_attrs.canary_settings[:percent_traffic]
+                  deployment_id stage_attrs.canary_settings[:deployment_id] if stage_attrs.canary_settings[:deployment_id]
+                  stage_variable_overrides stage_attrs.canary_settings[:stage_variable_overrides] if stage_attrs.canary_settings[:stage_variable_overrides]
+                  use_stage_cache stage_attrs.canary_settings[:use_stage_cache] if stage_attrs.canary_settings.key?(:use_stage_cache)
+                end
+              end
+
+              # Client certificate
+              client_certificate_id stage_attrs.client_certificate_id if stage_attrs.client_certificate_id
+
+              # Tags
+              tags stage_attrs.tags unless stage_attrs.tags.nil? || stage_attrs.tags.empty?
+            end
+          end
+
+          # Create ResourceReference with standard outputs
+          def create_stage_reference(name, stage_attrs)
+            ResourceReference.new(
+              type: 'aws_api_gateway_stage',
+              name: name,
+              resource_attributes: stage_attrs.to_h,
+              outputs: {
+                id: "${aws_api_gateway_stage.#{name}.id}",
+                rest_api_id: "${aws_api_gateway_stage.#{name}.rest_api_id}",
+                stage_name: "${aws_api_gateway_stage.#{name}.stage_name}",
+                deployment_id: "${aws_api_gateway_stage.#{name}.deployment_id}",
+                arn: "${aws_api_gateway_stage.#{name}.arn}",
+                invoke_url: "${aws_api_gateway_stage.#{name}.invoke_url}",
+                execution_arn: "${aws_api_gateway_stage.#{name}.execution_arn}",
+                description: "${aws_api_gateway_stage.#{name}.description}",
+                documentation_version: "${aws_api_gateway_stage.#{name}.documentation_version}",
+                cache_cluster_enabled: "${aws_api_gateway_stage.#{name}.cache_cluster_enabled}",
+                cache_cluster_size: "${aws_api_gateway_stage.#{name}.cache_cluster_size}",
+                variables: "${aws_api_gateway_stage.#{name}.variables}",
+                xray_tracing_enabled: "${aws_api_gateway_stage.#{name}.xray_tracing_enabled}",
+                access_log_settings: "${aws_api_gateway_stage.#{name}.access_log_settings}",
+                throttle_burst_limit: "${aws_api_gateway_stage.#{name}.throttle_burst_limit}",
+                throttle_rate_limit: "${aws_api_gateway_stage.#{name}.throttle_rate_limit}",
+                client_certificate_id: "${aws_api_gateway_stage.#{name}.client_certificate_id}",
+                tags: "${aws_api_gateway_stage.#{name}.tags}",
+                tags_all: "${aws_api_gateway_stage.#{name}.tags_all}",
+                web_acl_arn: "${aws_api_gateway_stage.#{name}.web_acl_arn}"
+              }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/resources/aws_api_gateway_stage/resource.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'pangea/resources/base'
+require 'pangea/resources/reference'
+require_relative 'types'
+require_relative 'resource/main'
+require_relative 'resource/helpers'
+
+module Pangea
+  module Resources
+    module AWS
+      # AWS API Gateway Stage implementation
+      # Provides type-safe function for creating API stages
+      def aws_api_gateway_stage(name, attributes = {})
+        extend ApiGatewayStageResource::Main
+        extend ApiGatewayStageResource::Helpers
+
+        # Validate attributes using dry-struct
+        stage_attrs = Types::ApiGatewayStageAttributes.new(attributes)
+
+        # Generate the Terraform resource
+        generate_stage_resource(name, stage_attrs)
+
+        # Create ResourceReference with outputs and computed properties
+        ref = create_stage_reference(name, stage_attrs)
+
+        # Add computed properties via method delegation
+        add_reference_helpers(ref, name, stage_attrs)
+
+        ref
+      end
+    end
+  end
+end