# Oshun SSM Parameter Store Module

This Terraform module manages configuration parameters in AWS Systems Manager
Parameter Store for all Oshun services across domains.

## Features

- **Centralized Configuration**: All application configuration in SSM Parameter
  Store
- **Hierarchical Organization**: Parameters organized by type and domain
- **Feature Flags**: Built-in support for feature flags with rollout percentages
- **Rate Limiting**: Pre-defined rate limit configurations
- **Cache Settings**: Configurable cache TTLs per use case
- **Connection Pools**: Database connection pool settings
- **Retry Policies**: Configurable retry policies with exponential backoff
- **AI Configuration**: Model-specific settings for AI/ML services
- **Domain Isolation**: Domain-specific configuration namespaces
- **Path-Based Access**: Efficient batch parameter retrieval by path

## Usage

```hcl
module "ssm" {
  source = "../ssm"

  environment = "production"
  region      = "us-east-1"
  name_prefix = "oshun"

  # Application configuration
  app_config = {
    log_level = {
      description = "Default log level"
      value       = "info"
    }
  }

  # Service endpoints
  service_endpoints = {
    api-gateway = {
      description = "API Gateway service"
      internal    = "http://api.oshun.local:3000"
      external    = "https://api.oshun.app"
      health      = "http://api.oshun.local:3000/health"
    }
  }

  # Feature flags
  feature_flags = {
    new_feature = {
      description = "Enable new feature"
      enabled     = true
      rollout     = 50  # 50% rollout
    }
  }

  # Rate limits
  rate_limits = {
    api_default = {
      description    = "Default API rate limit"
      requests       = 1000
      window_seconds = 60
      burst          = 100
    }
  }

  tags = {
    Environment = "production"
  }
}
```

## Parameter Types

### Application Configuration

General application settings stored as key-value pairs.

```hcl
app_config = {
  log_level = {
    description = "Application log level"
    value       = "info"
    type        = "String"  # String, StringList, or SecureString
    tier        = "Standard"  # Standard or Advanced
  }
}
```

### Service Endpoints

Service discovery configuration with multiple endpoint types.

```hcl
service_endpoints = {
  my-service = {
    description = "My service endpoints"
    internal    = "http://service.local:3000"  # Internal DNS/Service Connect
    external    = "https://api.example.com"    # Public endpoint
    grpc        = "service.local:50051"        # gRPC endpoint
    health      = "http://service.local:3000/health"  # Health check
  }
}
```

### Feature Flags

Feature toggles with percentage-based rollouts.

```hcl
feature_flags = {
  dark_mode = {
    description = "Enable dark mode"
    enabled     = true
    rollout     = 100  # Percentage of users (0-100)
  }
}
```

Parameter value structure:

```json
{
  "enabled": true,
  "rollout": 100
}
```

### Rate Limits

API rate limiting configuration.

```hcl
rate_limits = {
  auth = {
    description    = "Authentication rate limit"
    requests       = 10     # Max requests
    window_seconds = 60     # Time window
    burst          = 5      # Burst allowance
  }
}
```

### Cache Configuration

Cache TTL and size settings.

```hcl
cache_config = {
  session = {
    description = "Session cache settings"
    ttl_seconds = 3600   # TTL in seconds
    max_size    = 10000  # Max entries (0 = unlimited)
  }
}
```

### Database Connection Pools

Connection pool settings per database.

```hcl
db_pool_config = {
  primary = {
    description     = "Primary database pool"
    min_size        = 10
    max_size        = 50
    idle_timeout    = 30000    # ms
    acquire_timeout = 60000    # ms
  }
}
```

### Storage Configuration

S3-compatible storage settings.

```hcl
storage_config = {
  uploads = {
    description       = "User uploads storage"
    bucket            = "my-uploads-bucket"
    region            = "us-east-1"
    endpoint          = ""  # Leave empty for AWS S3
    max_upload_size   = 104857600  # 100MB
    allowed_mimetypes = ["image/jpeg", "image/png"]
  }
}
```

### Timeouts

Operation timeout settings.

```hcl
timeouts = {
  http_request = {
    description = "HTTP request timeout"
    value_ms    = 30000  # milliseconds
  }
}
```

### Concurrency Limits

Worker concurrency settings.

```hcl
concurrency_limits = {
  ai_processing = {
    description = "AI processing concurrency"
    max_workers = 8
    queue_size  = 200
  }
}
```

### Retry Policies

Retry behavior configuration.

```hcl
retry_policies = {
  ai = {
    description = "AI service retry policy"
    max_retries = 5
    base_delay  = 2000   # ms
    max_delay   = 30000  # ms
    exponential = true   # Exponential backoff
  }
}
```

### Domain Configuration

Domain-specific settings.

```hcl
domain_config = {
  yemaya = {  # Domain name
    max_projects = {
      description = "Max projects per user"
      value       = "100"
      type        = "String"
    }
  }
}
```

### AI Configuration

AI/ML service settings.

```hcl
ai_config = {
  text_generation = {
    description      = "Text generation settings"
    default_model    = "gpt-4"
    max_tokens       = 4096
    temperature      = 0.7
    timeout_seconds  = 120
    fallback_enabled = true
  }
}
```

## Outputs

### Parameter ARNs and Names

```hcl
# Access individual parameter ARNs
module.ssm.app_config_arns["log_level"]
module.ssm.feature_flag_arns["new_feature"]
module.ssm.rate_limit_arns["api_default"]

# Get all parameter ARNs
module.ssm.all_parameter_arns
```

### Path-Based Access

```hcl
# Get parameter paths for batch retrieval
module.ssm.parameter_paths.all          # /oshun/production
module.ssm.parameter_paths.features     # /oshun/production/features
module.ssm.parameter_paths.rate_limits  # /oshun/production/rate-limits
```

### IAM Policies

```hcl
# Attach read policy to ECS task role
resource "aws_iam_role_policy" "ssm_access" {
  role   = aws_iam_role.task.id
  policy = module.ssm.parameters_read_policy_json
}
```

## Accessing Parameters in Applications

### ECS Task Definition

```hcl
resource "aws_ecs_task_definition" "app" {
  container_definitions = jsonencode([{
    name = "app"
    environment = [
      {
        name  = "SSM_PARAMETER_PATH"
        value = module.ssm.parameter_paths.all
      }
    ]
  }])
}
```

### Application Code (Node.js)

```typescript
import {
  SSMClient,
  GetParametersByPathCommand,
  GetParameterCommand,
} from '@aws-sdk/client-ssm';

const client = new SSMClient({});

// Get all parameters by path
async function getConfigByPath(path: string): Promise<Record<string, string>> {
  const config: Record<string, string> = {};
  let nextToken: string | undefined;

  do {
    const response = await client.send(
      new GetParametersByPathCommand({
        Path: path,
        Recursive: true,
        WithDecryption: true,
        NextToken: nextToken,
      })
    );

    for (const param of response.Parameters || []) {
      const key = param.Name!.split('/').pop()!;
      config[key] = param.Value!;
    }

    nextToken = response.NextToken;
  } while (nextToken);

  return config;
}

// Get single parameter
async function getParameter(name: string): Promise<string> {
  const response = await client.send(
    new GetParameterCommand({
      Name: name,
      WithDecryption: true,
    })
  );
  return response.Parameter!.Value!;
}

// Usage
const featureFlags = await getConfigByPath('/oshun/production/features');
const rateLimit = JSON.parse(
  await getParameter('/oshun/production/rate-limits/api_default')
);
```

### Feature Flag Evaluation

```typescript
interface FeatureFlag {
  enabled: boolean;
  rollout: number;
}

function isFeatureEnabled(flag: FeatureFlag, userId: string): boolean {
  if (!flag.enabled) return false;
  if (flag.rollout >= 100) return true;

  // Consistent hashing for user
  const hash = hashCode(userId) % 100;
  return hash < flag.rollout;
}

function hashCode(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    hash = (hash << 5) - hash + str.charCodeAt(i);
    hash |= 0;
  }
  return Math.abs(hash);
}
```

## Parameter Naming Convention

All parameters follow this naming convention:

```
/{prefix}/{environment}/{category}/{name}
```

Examples:

- `/oshun/production/app/log_level`
- `/oshun/production/features/dark_mode`
- `/oshun/production/rate-limits/api_default`
- `/oshun/production/domains/yemaya/max_projects`

## Best Practices

1. **Use Path-Based Retrieval**: Fetch parameters by path for efficiency
2. **Cache Parameters**: Cache parameter values and refresh periodically
3. **SecureString for Sensitive Data**: Use SecureString type with KMS for
   sensitive values
4. **Environment Separation**: Use different parameter paths per environment
5. **Tagging**: Tag parameters for cost allocation and organization
6. **Validation**: Validate parameter values in application code

## Inputs

| Name               | Description                | Type        | Default     | Required |
| ------------------ | -------------------------- | ----------- | ----------- | :------: |
| environment        | Deployment environment     | string      | -           |   yes    |
| region             | AWS region                 | string      | "us-east-1" |    no    |
| name_prefix        | Prefix for parameter names | string      | "oshun"     |    no    |
| kms_key_arn        | KMS key for SecureString   | string      | ""          |    no    |
| app_config         | Application configuration  | map(object) | {}          |    no    |
| service_endpoints  | Service endpoint configs   | map(object) | {}          |    no    |
| feature_flags      | Feature flag configs       | map(object) | {}          |    no    |
| rate_limits        | Rate limit configs         | map(object) | {}          |    no    |
| cache_config       | Cache configuration        | map(object) | {}          |    no    |
| db_pool_config     | Database pool configs      | map(object) | {}          |    no    |
| storage_config     | Storage configs            | map(object) | {}          |    no    |
| timeouts           | Timeout configs            | map(object) | {}          |    no    |
| concurrency_limits | Concurrency limit configs  | map(object) | {}          |    no    |
| retry_policies     | Retry policy configs       | map(object) | {}          |    no    |
| domain_config      | Domain-specific configs    | map(map)    | {}          |    no    |
| ai_config          | AI service configs         | map(object) | {}          |    no    |
| pagination_config  | Pagination defaults        | object      | {}          |    no    |
| cors_config        | CORS configuration         | object      | {}          |    no    |
| monitoring_config  | Monitoring configuration   | object      | {}          |    no    |
| custom_parameters  | Custom parameters          | map(object) | {}          |    no    |

## Outputs

| Name                         | Description                        |
| ---------------------------- | ---------------------------------- |
| parameter_prefix             | Base path for all parameters       |
| app_config_arns              | Map of app config parameter ARNs   |
| feature_flag_arns            | Map of feature flag ARNs           |
| rate_limit_arns              | Map of rate limit ARNs             |
| all_parameter_arns           | Combined map of all parameter ARNs |
| parameters_read_policy_json  | IAM policy for read access         |
| parameters_write_policy_json | IAM policy for write access        |
| parameter_paths              | Map of parameter paths by category |
| parameters_summary           | Summary of created parameters      |
