pangea 0.0.42 → 0.0.45

data/lib/pangea/resources/aws_kinesis_video_stream/CLAUDE.md

@@ -0,0 +1,595 @@
+# AWS Kinesis Video Stream - Technical Implementation
+
+## Video Streaming Architecture
+
+Kinesis Video Streams provides a fully managed service for streaming video and audio data from connected devices to AWS for analytics, machine learning, and storage. It supports multiple streaming protocols and integration patterns for real-time and archived video processing.
+
+## Core Streaming Concepts
+
+### Stream Components
+- **Producer**: Device or application that sends video/audio data
+- **Consumer**: Application that processes or plays back the stream
+- **Fragment**: Temporal unit of data containing multiple frames
+- **Frame**: Individual video/audio sample with timestamp
+- **Track**: Logical grouping of related media (video track, audio track)
+
+### Streaming Modes
+1. **Real-time Streaming**: Live video with minimal latency
+2. **Archival Streaming**: Video storage with configurable retention
+3. **WebRTC Signaling**: Bidirectional real-time communication
+4. **Batch Processing**: Offline analysis of stored video
+
+## Architecture Patterns
+
+### Multi-Camera Surveillance System
+```ruby
+template :video_surveillance_system do
+  # KMS key for video encryption
+  video_encryption_key = aws_kms_key(:video_encryption, {
+    description: "Encryption key for video surveillance data",
+    key_usage: "ENCRYPT_DECRYPT",
+    key_spec: "SYMMETRIC_DEFAULT",
+    enable_key_rotation: true
+  })
+  
+  aws_kms_alias(:video_encryption_alias, {
+    name: "alias/video-surveillance-encryption",
+    target_key_id: video_encryption_key.key_id
+  })
+  
+  # Central monitoring streams for different areas
+  surveillance_areas = [
+    { name: "entrance", retention_days: 30, quality: "1080p" },
+    { name: "parking-lot", retention_days: 14, quality: "720p" },
+    { name: "warehouse", retention_days: 90, quality: "1080p" },
+    { name: "office-floor-1", retention_days: 7, quality: "720p" },
+    { name: "server-room", retention_days: 365, quality: "4k" }
+  ]
+  
+  surveillance_streams = surveillance_areas.map do |area|
+    aws_kinesis_video_stream(:"surveillance_#{area[:name].tr('-', '_')}", {
+      name: "surveillance-#{area[:name]}",
+      device_name: "camera-#{area[:name]}-main",
+      media_type: "video/h264",
+      data_retention_in_hours: area[:retention_days] * 24,
+      kms_key_id: video_encryption_key.key_id,
+      tags: {
+        Location: area[:name],
+        Quality: area[:quality],
+        Purpose: "security-surveillance",
+        RetentionDays: area[:retention_days].to_s
+      }
+    })
+  end
+  
+  # Analytics processing stream for real-time alerts
+  analytics_stream = aws_kinesis_video_stream(:video_analytics, {
+    name: "video-analytics-processing",
+    media_type: "video/h264",
+    data_retention_in_hours: 0, # Real-time processing only
+    tags: {
+      Purpose: "real-time-analytics",
+      ProcessingType: "motion-detection"
+    }
+  })
+  
+  # Archive stream for long-term compliance storage
+  compliance_archive = aws_kinesis_video_stream(:compliance_archive, {
+    name: "compliance-video-archive",
+    media_type: "video/h265", # Better compression for long-term storage
+    data_retention_in_hours: 26280, # 3 years for compliance
+    kms_key_id: video_encryption_key.key_id,
+    tags: {
+      Purpose: "compliance-archival",
+      Retention: "3-years",
+      DataClassification: "confidential"
+    }
+  })
+end
+```
+
+### Smart City Traffic Management
+```ruby
+template :smart_city_traffic_system do
+  # Traffic monitoring infrastructure
+  traffic_intersections = [
+    { intersection: "main-1st", traffic_level: "high", ai_priority: true },
+    { intersection: "broadway-oak", traffic_level: "medium", ai_priority: true },
+    { intersection: "elm-park", traffic_level: "low", ai_priority: false },
+    { intersection: "highway-onramp", traffic_level: "high", ai_priority: true }
+  ]
+  
+  traffic_streams = traffic_intersections.map do |intersection|
+    retention_hours = intersection[:ai_priority] ? 168 : 72 # 7 days vs 3 days
+    
+    aws_kinesis_video_stream(:"traffic_#{intersection[:intersection].tr('-', '_')}", {
+      name: "traffic-#{intersection[:intersection]}",
+      device_name: "traffic-cam-#{intersection[:intersection]}",
+      media_type: "video/h264",
+      data_retention_in_hours: retention_hours,
+      kms_key_id: "alias/smart-city-traffic-encryption",
+      tags: {
+        Intersection: intersection[:intersection],
+        TrafficLevel: intersection[:traffic_level],
+        AIProcessing: intersection[:ai_priority].to_s,
+        Department: "traffic-management"
+      }
+    })
+  end
+  
+  # Emergency vehicle detection stream
+  emergency_detection = aws_kinesis_video_stream(:emergency_vehicle_detection, {
+    name: "emergency-vehicle-detection",
+    media_type: "video/h264", 
+    data_retention_in_hours: 24, # 24 hours for emergency response analysis
+    tags: {
+      Purpose: "emergency-response",
+      ProcessingType: "real-time-detection",
+      Priority: "critical"
+    }
+  })
+  
+  # Traffic pattern analysis archive
+  traffic_analytics_archive = aws_kinesis_video_stream(:traffic_analytics, {
+    name: "traffic-pattern-analytics",
+    media_type: "video/h265", # Efficient compression for analytics
+    data_retention_in_hours: 8760, # 1 year for pattern analysis
+    tags: {
+      Purpose: "traffic-analytics", 
+      AnalysisType: "pattern-detection",
+      DataRetention: "1-year"
+    }
+  })
+end
+```
+
+### Healthcare Video Monitoring
+```ruby
+template :healthcare_video_system do
+  # Patient monitoring streams with HIPAA compliance
+  patient_monitoring_areas = [
+    { area: "icu", retention_years: 7, critical: true },
+    { area: "emergency", retention_years: 5, critical: true },
+    { area: "surgery-or1", retention_years: 10, critical: true },
+    { area: "surgery-or2", retention_years: 10, critical: true },
+    { area: "recovery", retention_years: 3, critical: false }
+  ]
+  
+  # HIPAA-compliant KMS key
+  healthcare_kms_key = aws_kms_key(:healthcare_video_key, {
+    description: "HIPAA-compliant encryption for healthcare video streams",
+    key_usage: "ENCRYPT_DECRYPT",
+    deletion_window_in_days: 30,
+    enable_key_rotation: true
+  })
+  
+  healthcare_video_streams = patient_monitoring_areas.map do |area|
+    aws_kinesis_video_stream(:"healthcare_#{area[:area].tr('-', '_')}", {
+      name: "healthcare-#{area[:area]}",
+      device_name: "medical-camera-#{area[:area]}",
+      media_type: "video/h264",
+      data_retention_in_hours: area[:retention_years] * 365 * 24,
+      kms_key_id: healthcare_kms_key.key_id,
+      tags: {
+        Location: area[:area],
+        Compliance: "HIPAA",
+        Critical: area[:critical].to_s,
+        DataRetention: "#{area[:retention_years]}-years",
+        Department: "healthcare"
+      }
+    })
+  end
+  
+  # Telemedicine consultation stream
+  telemedicine_stream = aws_kinesis_video_stream(:telemedicine_consultation, {
+    name: "telemedicine-consultation-main",
+    media_type: "video/h264",
+    data_retention_in_hours: 2160, # 90 days for consultation records
+    kms_key_id: healthcare_kms_key.key_id,
+    tags: {
+      Purpose: "telemedicine",
+      Compliance: "HIPAA",
+      PatientInteraction: "true"
+    }
+  })
+end
+```
+
+### WebRTC Real-Time Communication
+```ruby
+template :webrtc_communication_platform do
+  # Video conferencing streams
+  conference_rooms = [
+    { room: "boardroom", capacity: 20, quality: "4k" },
+    { room: "meeting-room-a", capacity: 8, quality: "1080p" },
+    { room: "meeting-room-b", capacity: 8, quality: "1080p" },
+    { room: "training-room", capacity: 50, quality: "1080p" }
+  ]
+  
+  conference_streams = conference_rooms.map do |room|
+    # Main video stream for each room
+    main_stream = aws_kinesis_video_stream(:"webrtc_#{room[:room].tr('-', '_')}_main", {
+      name: "webrtc-#{room[:room]}-main-video",
+      media_type: "video/h264",
+      data_retention_in_hours: 0, # Real-time only for WebRTC
+      tags: {
+        Room: room[:room],
+        Capacity: room[:capacity].to_s,
+        Quality: room[:quality],
+        Protocol: "webrtc",
+        StreamType: "main-video"
+      }
+    })
+    
+    # Screen sharing stream
+    screen_share = aws_kinesis_video_stream(:"webrtc_#{room[:room].tr('-', '_')}_screen", {
+      name: "webrtc-#{room[:room]}-screen-share",
+      media_type: "video/h264",
+      data_retention_in_hours: 0,
+      tags: {
+        Room: room[:room],
+        Protocol: "webrtc",
+        StreamType: "screen-share"
+      }
+    })
+    
+    # Audio stream
+    audio_stream = aws_kinesis_video_stream(:"webrtc_#{room[:room].tr('-', '_')}_audio", {
+      name: "webrtc-#{room[:room]}-audio",
+      media_type: "audio/opus", # WebRTC optimized
+      data_retention_in_hours: 0,
+      tags: {
+        Room: room[:room],
+        Protocol: "webrtc",
+        StreamType: "audio"
+      }
+    })
+    
+    { main: main_stream, screen: screen_share, audio: audio_stream }
+  end
+  
+  # Recording stream for important meetings
+  meeting_recording = aws_kinesis_video_stream(:meeting_recording, {
+    name: "meeting-recording-archive",
+    media_type: "video/h264",
+    data_retention_in_hours: 2160, # 90 days for corporate meetings
+    kms_key_id: "alias/corporate-meeting-encryption",
+    tags: {
+      Purpose: "meeting-recording",
+      DataRetention: "90-days",
+      AccessLevel: "authorized-personnel-only"
+    }
+  })
+end
+```
+
+## Integration with AWS AI/ML Services
+
+### Real-Time Video Analytics
+```ruby
+template :video_ai_analytics do
+  # Video streams for AI processing
+  ai_processing_stream = aws_kinesis_video_stream(:ai_video_processing, {
+    name: "ai-video-processing-stream",
+    media_type: "video/h264",
+    data_retention_in_hours: 24, # Keep data for analysis verification
+    tags: {
+      Purpose: "ai-ml-processing",
+      ServiceIntegration: "rekognition"
+    }
+  })
+  
+  # Lambda function for real-time processing
+  video_processor = aws_lambda_function(:video_ai_processor, {
+    function_name: "video-ai-processor",
+    runtime: "python3.11",
+    handler: "index.handler",
+    filename: "video-processor.zip",
+    memory_size: 3008, # High memory for video processing
+    timeout: 300, # 5 minutes for complex processing
+    environment_variables: {
+      REKOGNITION_COLLECTION_ID: "video-faces-collection",
+      SNS_ALERT_TOPIC: alert_topic.arn,
+      CONFIDENCE_THRESHOLD: "85.0",
+      PROCESSING_MODE: "real-time"
+    }
+  })
+  
+  # SNS topic for alerts
+  alert_topic = aws_sns_topic(:video_alerts, {
+    name: "video-processing-alerts"
+  })
+  
+  # CloudWatch event for Lambda triggers
+  aws_eventbridge_rule(:video_processing_trigger, {
+    name: "video-processing-schedule",
+    description: "Trigger video processing every 30 seconds",
+    schedule_expression: "rate(30 seconds)",
+    targets: [{
+      arn: video_processor.arn,
+      id: "video-processor-target"
+    }]
+  })
+end
+```
+
+### Batch Video Analysis
+```ruby
+template :batch_video_analysis do
+  # Long-term storage stream for batch processing
+  batch_analysis_stream = aws_kinesis_video_stream(:batch_analysis, {
+    name: "batch-video-analysis-stream",
+    media_type: "video/h265", # Better compression for batch storage
+    data_retention_in_hours: 8760, # 1 year for analysis
+    kms_key_id: "alias/batch-analysis-encryption",
+    tags: {
+      Purpose: "batch-analysis",
+      ProcessingType: "scheduled",
+      AnalysisFrequency: "daily"
+    }
+  })
+  
+  # S3 bucket for processed results
+  analysis_results_bucket = aws_s3_bucket(:video_analysis_results, {
+    bucket: "video-analysis-results-#{random_id}",
+    versioning: { enabled: true },
+    server_side_encryption_configuration: {
+      rule: {
+        apply_server_side_encryption_by_default: {
+          sse_algorithm: "AES256"
+        }
+      }
+    }
+  })
+  
+  # Batch processing job definition
+  aws_batch_job_definition(:video_analysis_job, {
+    job_definition_name: "video-analysis-batch-job",
+    type: "container",
+    container_properties: {
+      image: "video-analysis:latest",
+      vcpus: 4,
+      memory: 8192,
+      environment: [
+        { name: "INPUT_STREAM_ARN", value: batch_analysis_stream.arn },
+        { name: "OUTPUT_BUCKET", value: analysis_results_bucket.bucket },
+        { name: "ANALYSIS_TYPE", value: "comprehensive" }
+      ]
+    }
+  })
+end
+```
+
+## Performance Optimization and Monitoring
+
+### Stream Health Monitoring
+```ruby
+template :video_stream_monitoring do
+  # CloudWatch alarms for stream health
+  aws_cloudwatch_metric_alarm(:stream_ingestion_rate, {
+    alarm_name: "kinesis-video-ingestion-rate-low",
+    alarm_description: "Video stream ingestion rate has dropped below threshold",
+    metric_name: "IncomingBytes",
+    namespace: "AWS/KinesisVideo",
+    statistic: "Average",
+    period: 300,
+    evaluation_periods: 3,
+    threshold: 1048576, # 1MB minimum per 5-minute period
+    comparison_operator: "LessThanThreshold",
+    dimensions: {
+      StreamName: video_stream.name
+    }
+  })
+  
+  aws_cloudwatch_metric_alarm(:fragment_age, {
+    alarm_name: "kinesis-video-fragment-age-high",
+    alarm_description: "Video fragments are aging too much (potential playback issues)",
+    metric_name: "GetMedia.OutgoingBytes",
+    namespace: "AWS/KinesisVideo",
+    statistic: "Average", 
+    period: 300,
+    evaluation_periods: 2,
+    threshold: 300000, # 5 minutes in milliseconds
+    comparison_operator: "GreaterThanThreshold"
+  })
+  
+  # Custom dashboard for video streaming metrics
+  aws_cloudwatch_dashboard(:video_streaming_dashboard, {
+    dashboard_name: "kinesis-video-streaming-metrics",
+    dashboard_body: {
+      widgets: [
+        {
+          type: "metric",
+          properties: {
+            metrics: [
+              ["AWS/KinesisVideo", "IncomingBytes", "StreamName", video_stream.name],
+              [".", "IncomingFrames", ".", "."],
+              [".", "OutgoingBytes", ".", "."],
+              [".", "GetMedia.Success", ".", "."]
+            ],
+            period: 300,
+            stat: "Average",
+            region: "us-east-1",
+            title: "Video Stream Metrics"
+          }
+        }
+      ]
+    }.to_json
+  })
+end
+```
+
+### Network Optimization
+```ruby
+template :video_network_optimization do
+  # Edge-optimized video streams using CloudFront
+  video_distribution = aws_cloudfront_distribution(:video_streaming_cdn, {
+    origins: [{
+      domain_name: video_stream_endpoint,
+      origin_id: "kinesis-video-origin",
+      custom_origin_config: {
+        http_port: 443,
+        https_port: 443,
+        origin_protocol_policy: "https-only",
+        origin_ssl_protocols: ["TLSv1.2"]
+      }
+    }],
+    default_cache_behavior: {
+      target_origin_id: "kinesis-video-origin",
+      viewer_protocol_policy: "redirect-to-https",
+      cache_policy_id: "streaming-optimized-policy",
+      compress: true
+    },
+    price_class: "PriceClass_All",
+    enabled: true
+  })
+  
+  # Regional edge caching configuration
+  regional_video_streams = [
+    { region: "us-east-1", edge_location: "virginia" },
+    { region: "eu-west-1", edge_location: "ireland" },
+    { region: "ap-southeast-1", edge_location: "singapore" }
+  ].map do |config|
+    aws_kinesis_video_stream(:"regional_stream_#{config[:region].tr('-', '_')}", {
+      name: "regional-video-#{config[:edge_location]}",
+      media_type: "video/h264",
+      data_retention_in_hours: 168, # 7 days
+      tags: {
+        Region: config[:region],
+        EdgeLocation: config[:edge_location],
+        Purpose: "regional-optimization"
+      }
+    })
+  end
+end
+```
+
+## Security and Compliance Architecture
+
+### Access Control and Encryption
+```ruby
+template :video_security_compliance do
+  # Customer-managed KMS key with key rotation
+  video_master_key = aws_kms_key(:video_master_encryption, {
+    description: "Master encryption key for video streaming infrastructure",
+    key_usage: "ENCRYPT_DECRYPT",
+    key_spec: "SYMMETRIC_DEFAULT",
+    key_rotation_status: "Enabled",
+    deletion_window_in_days: 30,
+    policy: {
+      Version: "2012-10-17",
+      Statement: [
+        {
+          Sid: "VideoStreamEncryption",
+          Effect: "Allow",
+          Principal: { Service: "kinesisvideo.amazonaws.com" },
+          Action: ["kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*"],
+          Resource: "*"
+        }
+      ]
+    }
+  })
+  
+  # IAM role for video stream access
+  video_stream_role = aws_iam_role(:video_stream_access, {
+    name: "kinesis-video-stream-access-role",
+    assume_role_policy: {
+      Version: "2012-10-17",
+      Statement: [{
+        Effect: "Allow",
+        Principal: { 
+          Service: ["kinesisvideo.amazonaws.com", "lambda.amazonaws.com"] 
+        },
+        Action: "sts:AssumeRole"
+      }]
+    }
+  })
+  
+  # Least-privilege access policy
+  video_access_policy = aws_iam_policy(:video_stream_policy, {
+    name: "kinesis-video-stream-policy",
+    policy: {
+      Version: "2012-10-17",
+      Statement: [
+        {
+          Effect: "Allow",
+          Action: [
+            "kinesisvideo:CreateStream",
+            "kinesisvideo:PutMedia",
+            "kinesisvideo:GetMedia",
+            "kinesisvideo:GetDataEndpoint",
+            "kinesisvideo:DescribeStream"
+          ],
+          Resource: video_streams.map(&:arn)
+        },
+        {
+          Effect: "Allow",
+          Action: [
+            "kms:Encrypt",
+            "kms:Decrypt", 
+            "kms:ReEncrypt*",
+            "kms:GenerateDataKey*",
+            "kms:DescribeKey"
+          ],
+          Resource: video_master_key.arn
+        }
+      ]
+    }
+  })
+end
+```
+
+## Cost Optimization Strategies
+
+### Tiered Storage Architecture
+```ruby
+template :video_cost_optimization do
+  # Real-time streams (no storage cost)
+  realtime_streams = ["live-monitoring", "webrtc-calls", "real-time-alerts"].map do |purpose|
+    aws_kinesis_video_stream(:"realtime_#{purpose.tr('-', '_')}", {
+      name: "realtime-#{purpose}",
+      data_retention_in_hours: 0, # No storage costs
+      media_type: "video/h264",
+      tags: { Purpose: purpose, CostTier: "realtime-only" }
+    })
+  end
+  
+  # Short-term storage (cost-optimized)
+  shortterm_streams = [
+    { name: "security-buffer", days: 7, codec: "h264" },
+    { name: "incident-review", days: 14, codec: "h264" }
+  ].map do |config|
+    aws_kinesis_video_stream(:"shortterm_#{config[:name].tr('-', '_')}", {
+      name: "shortterm-#{config[:name]}",
+      data_retention_in_hours: config[:days] * 24,
+      media_type: "video/#{config[:codec]}",
+      tags: { 
+        Purpose: config[:name], 
+        CostTier: "short-term-storage",
+        RetentionDays: config[:days].to_s
+      }
+    })
+  end
+  
+  # Long-term archival (compression-optimized)
+  archival_streams = [
+    { name: "compliance-archive", years: 7, codec: "h265" },
+    { name: "legal-evidence", years: 10, codec: "h265" }
+  ].map do |config|
+    aws_kinesis_video_stream(:"archival_#{config[:name].tr('-', '_')}", {
+      name: "archival-#{config[:name]}",
+      data_retention_in_hours: config[:years] * 365 * 24,
+      media_type: "video/#{config[:codec]}", # H.265 for better compression
+      kms_key_id: video_master_key.key_id,
+      tags: {
+        Purpose: config[:name],
+        CostTier: "long-term-archival",
+        RetentionYears: config[:years].to_s,
+        Codec: config[:codec]
+      }
+    })
+  end
+end
+```
+
+This comprehensive implementation provides enterprise-grade video streaming capabilities with AWS Kinesis Video Streams, supporting diverse use cases from real-time monitoring to compliance archival.

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

@@ -0,0 +1,76 @@
+# 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 'pangea/resources/aws_kinesis_video_stream/types'
+require 'pangea/resource_registry'
+
+module Pangea
+  module Resources
+    module AWS
+      # Create an AWS Kinesis Video Stream for real-time video and audio streaming
+      #
+      # @param name [Symbol] The resource name
+      # @param attributes [Hash] Kinesis Video Stream attributes
+      # @return [ResourceReference] Reference object with outputs and computed properties
+      def aws_kinesis_video_stream(name, attributes = {})
+        # Validate attributes using dry-struct
+        video_stream_attrs = Types::KinesisVideoStreamAttributes.new(attributes)
+        
+        # Generate terraform resource block via terraform-synthesizer
+        resource(:aws_kinesis_video_stream, name) do
+          name video_stream_attrs.name
+          data_retention_in_hours video_stream_attrs.data_retention_in_hours
+          device_name video_stream_attrs.device_name if video_stream_attrs.has_device_name?
+          media_type video_stream_attrs.media_type
+          kms_key_id video_stream_attrs.kms_key_id if video_stream_attrs.is_encrypted?
+          
+          # Apply tags if present
+          if video_stream_attrs.tags.any?
+            tags do
+              video_stream_attrs.tags.each do |key, value|
+                public_send(key, value)
+              end
+            end
+          end
+        end
+        
+        # Return resource reference with available outputs
+        ResourceReference.new(
+          type: 'aws_kinesis_video_stream',
+          name: name,
+          resource_attributes: video_stream_attrs.to_h,
+          outputs: {
+            id: "${aws_kinesis_video_stream.#{name}.id}",
+            name: "${aws_kinesis_video_stream.#{name}.name}",
+            arn: "${aws_kinesis_video_stream.#{name}.arn}",
+            version: "${aws_kinesis_video_stream.#{name}.version}",
+            creation_time: "${aws_kinesis_video_stream.#{name}.creation_time}",
+            data_retention_in_hours: "${aws_kinesis_video_stream.#{name}.data_retention_in_hours}",
+            device_name: "${aws_kinesis_video_stream.#{name}.device_name}",
+            media_type: "${aws_kinesis_video_stream.#{name}.media_type}",
+            kms_key_id: "${aws_kinesis_video_stream.#{name}.kms_key_id}",
+            tags_all: "${aws_kinesis_video_stream.#{name}.tags_all}"
+          }
+        )
+      end
+    end
+  end
+end
+
+# Auto-register this module when it's loaded
+Pangea::ResourceRegistry.register(:aws, Pangea::Resources::AWS)