Gateway

{
  "overview": "# Gateway Service Documentation\n\nThe **Gateway Service** serves as a critical component in the Vivified platform, providing secure external API access and proxy functionality. This service is designed to ensure compliance with HIPAA regulations while offering robust security features such as rate limiting and domain allowlisting.\n\n!!! note\n    The Gateway Service is a HIPAA-compliant service, ensuring that all external communications adhere to the necessary privacy and security standards.\n\n## Architecture\n\n```mermaid\ngraph LR\n    A[Client Request] -->|HTTP Method| B[Gateway Service]\n    B -->|Proxy Request| C[External API]\n    B -->|Audit Logs| D[Audit Service]\n    B -->|Policy Decision| E[Policy Engine]\n```\n\n## Key Components\n- **ProxyHandler**: Manages external API requests with security checks and rate limiting.\n- **AuditService**: Logs all actions for compliance and monitoring.\n- **PolicyEngine**: Evaluates requests against predefined security policies.\n- **DomainAllowlist**: Controls which domains are accessible through the gateway.\n\n## Security Considerations\n- All requests are logged and monitored by the `AuditService` to ensure compliance.\n- The `PolicyEngine` enforces security policies on every request.\n- Rate limiting is implemented to prevent abuse and ensure fair usage.\n\n!!! warning\n    Ensure that all configurations comply with HIPAA rules to maintain data privacy and security.",
  "api": "# API Reference\n\nThe Gateway Service provides an API for managing proxy requests.\n\n## ProxyRequest\n\n| Field      | Type          | Description                                  |\n|------------|---------------|----------------------------------------------|\n| `id`       | `str`         | Unique identifier for the request.           |\n| `plugin_id`| `str`         | Identifier for the plugin making the request.|\n| `method`   | `ProxyMethod` | HTTP method (GET, POST, etc.).               |\n| `url`      | `HttpUrl`     | Target URL for the request.                  |\n| `headers`  | `Dict[str,str]`| Custom headers to include in the request.   |\n| `body`     | `Optional[bytes]`| Payload for the request.                   |\n| `timeout`  | `int`         | Request timeout in seconds.                  |\n| `retries`  | `int`         | Number of retry attempts.                    |\n\n## ProxyMethod\n\n| Method     | Description                        |\n|------------|------------------------------------|\n| `GET`      | Retrieve data from the server.     |\n| `POST`     | Send data to the server.           |\n| `PUT`      | Update data on the server.         |\n| `DELETE`   | Remove data from the server.       |\n| `PATCH`    | Partial update of data on the server. |\n| `HEAD`     | Retrieve headers from the server.  |\n| `OPTIONS`  | Describe communication options.    |",
  "config": "# Configuration Guide\n\nThe Gateway Service can be configured using various parameters to control its behavior and ensure compliance.\n\n| Parameter          | Type      | Default | Description                                    |\n|--------------------|-----------|---------|------------------------------------------------|\n| `audit_service`    | `AuditService` | N/A     | Service for logging and monitoring.            |\n| `policy_engine`    | `PolicyEngine` | N/A     | Service for evaluating security policies.     |\n| `config_service`   | `Any`     | `None`  | Optional service for additional configurations.|\n\n!!! tip\n    Customize the `DomainAllowlist` to restrict access to specific domains.\n\n### Rate Limiting\n\nThe Gateway Service implements rate limiting to manage request throughput and ensure compliance with HIPAA regulations.\n\n```yaml\nrate_limits:\n  default:\n    requests_per_minute: 60\n    burst_capacity: 10\n```\n\n### Domain Allowlisting\n\n```yaml\ndomain_allowlists:\n  - domain: \"api.example.com\"\n    allow: true\n  - domain: \"*.trusted.com\"\n    allow: true\n```\n\n!!! note\n    Ensure that the domains listed in `DomainAllowlist` comply with HIPAA privacy rules.",
  "examples": "# Usage Examples\n\n=== \"Python\"\n    ```python\n    from vivified.gateway.service import GatewayService\n    from vivified.audit.service import AuditService\n    from vivified.policy.engine import PolicyEngine\n\n    # Initialize services\n    audit_service = AuditService()\n    policy_engine = PolicyEngine()\n\n    # Create gateway service\n    gateway_service = GatewayService(audit_service, policy_engine)\n    \n    # Make a proxy request\n    proxy_request = ProxyRequest(\n        plugin_id=\"plugin123\",\n        method=ProxyMethod.GET,\n        url=\"https://api.example.com/data\"\n    )\n    response = gateway_service.proxy_handler.handle_request(proxy_request)\n    print(response)\n    ```\n\n=== \"curl\"\n    ```bash\n    curl -X GET \"https://api.example.com/data\" \\\n         -H \"Authorization: Bearer <token>\" \\\n         -H \"Content-Type: application/json\"\n    ```\n\n## Troubleshooting\n\n### Common Issues\n\n- **Timeout Errors**: Ensure the `timeout` parameter is set appropriately for long-running requests.\n- **Blocked Domains**: Verify that the target domain is included in the `DomainAllowlist`.\n\n### Debugging Steps\n\n1. Check the audit logs for any recorded errors.\n2. Verify the policy decisions using the `PolicyEngine` logs.\n3. Ensure rate limits are properly configured and being adhered to.\n\n!!! warning\n    Unauthorized attempts to access restricted domains will be logged and could result in service denial as part of security enforcement."
}