Admin Service Control: API Endpoint Implementation

Introduction to Service Control and Health Monitoring

Service control and health monitoring are essential components of a robust API. They empower administrators to manage the lifecycle of various services, ensuring they are running smoothly and efficiently. This document outlines the implementation of a service control router, providing admin-only endpoints for starting, stopping, restarting, and checking the status of critical services within the Fullon Master API. This implementation is a crucial step in Phase 6 of the project, focusing on API implementation and laying the groundwork for effective service management. The endpoints developed will provide administrators with a centralized control panel for managing the services, ticker, ohlcv, and account. These services are vital for the proper operation of the Fullon system, ensuring the accurate collection, processing, and display of financial data.

Why Service Control is Important

Implementing a robust service control system is paramount for maintaining the stability and reliability of any API. The ability to start, stop, and restart services remotely provides administrators with the necessary tools to address issues such as service failures, resource exhaustion, or the need for updates. Health monitoring complements service control by providing real-time insights into the status of each service. This allows administrators to quickly identify and resolve problems, minimizing downtime and ensuring a seamless user experience. Furthermore, centralized control simplifies the management process, making it easier to maintain and update the various components of the API.

Project Goals

The primary goals of this implementation are to create secure, admin-only endpoints for service management. This includes creating a series of API endpoints that allow administrators to effectively manage the services. The system is designed to provide immediate feedback on the status of each service, including whether it is running, stopped, or experiencing errors. Moreover, the project aims to integrate robust error handling and logging to ensure that all actions are tracked and that any issues are promptly identified and addressed. This approach will contribute to the overall stability, and maintainability of the Fullon Master API.

Implementation Strategy: Creating the Services Router

The core of the service control functionality resides within src/fullon_master_api/routers/services.py. This file houses all the admin-only service control endpoints. These endpoints will use the FastAPI framework, allowing for efficient routing and easy integration with existing API infrastructure. The implementation strategy involves defining the necessary dependencies, such as the ServiceManager and the get_admin_user function. The ServiceManager handles the actual start, stop, and restart operations. This allows the API to interact with the underlying services. The get_admin_user function ensures that only authorized administrators can access the endpoints. This is critical for maintaining the security of the API.

Step-by-Step Implementation

1. Create routers/services.py: This file will be the central hub for service control. Within this file, you will define the FastAPI router and implement all the endpoints required for service management. This includes importing necessary modules, setting up the router, and defining the API endpoints.
2. Define Dependencies: The key dependencies include the ServiceManager and get_admin_user. The ServiceManager will be responsible for starting, stopping, and restarting services, while get_admin_user ensures that only authenticated administrators have access to these actions.
3. Implement Endpoints: The endpoints to implement are: POST /api/v1/services/{service_name}/start, POST /api/v1/services/{service_name}/stop, POST /api/v1/services/{service_name}/restart, GET /api/v1/services/{service_name}/status, and GET /api/v1/services. Each endpoint should perform a specific action and return appropriate responses. For each action, consider error handling and logging.
4. Error Handling: Implement robust error handling to gracefully manage potential issues. This involves returning appropriate HTTP status codes (e.g., 400 for bad requests, 403 for unauthorized access) and providing informative error messages.
5. Logging: Implement structured logging to track all service control operations. This will help with debugging and monitoring the API's behavior.
6. Admin Authentication: All endpoints require admin authentication via the get_admin_user() dependency.

Code Snippets and Examples

Here's a code snippet outlining how to create the routers/services.py file:

from fastapi import APIRouter, Depends, HTTPException, Request
from fullon_log import get_component_logger
from fullon_orm.models import User

from ..auth.dependencies import get_admin_user
from ..services.manager import ServiceManager, ServiceName

router = APIRouter(prefix="/services", tags=["services"])

logger = get_component_logger("fullon.master_api.routers.services")


def get_service_manager(request: Request) -> ServiceManager:
    if not hasattr(request.app.state, 'service_manager'):
        logger.error("ServiceManager not found in app state")
        raise RuntimeError("ServiceManager not initialized")
    
    return request.app.state.service_manager


@router.post("/{service_name}/start")
async def start_service(
    service_name: ServiceName,
    admin_user: User = Depends(get_admin_user),
    manager: ServiceManager = Depends(get_service_manager)
):
    try:
        result = await manager.start_service(service_name)
        logger.info(
            "Service started by admin",
            service=service_name,
            user_id=admin_user.uid,
            admin_email=admin_user.mail
        )
        return result
    except ValueError as e:
        logger.warning(
            "Service start failed",
            service=service_name,
            error=str(e),
            user_id=admin_user.uid
        )
        raise HTTPException(status_code=400, detail=str(e))

This snippet provides a starting point for implementing the start_service endpoint. Similar implementations are needed for stop, restart, status, and all_status endpoints.

Integration Tests: Ensuring Functionality

Thorough testing is crucial to validate the functionality and security of the service control endpoints. This involves creating integration tests to verify that the endpoints behave as expected under various conditions. The integration tests will be designed to simulate different scenarios, such as starting a service, stopping a service, checking the status of a service, and restarting a service. The tests will also ensure that unauthorized users cannot access the endpoints, which is a key security requirement. The integration tests are designed to check the functionality of the service control endpoints.

Test Scenarios and Expected Outcomes

1. Admin Start Service Test: This test verifies that an admin user can successfully start a service. It sends a POST request to /api/v1/services/{service_name}/start with an admin token and checks for a successful response (status code 200) and the correct response data, such as {"service": "ticker", "status": "started"}.
2. Admin Stop Service Test: Tests if an admin can successfully stop a running service. It first starts a service (using the start test), and then sends a POST request to /api/v1/services/{service_name}/stop and validates a successful response and the correct response data, such as {"service": "ticker", "status": "stopped"}.
3. Admin Restart Service Test: Validates that an admin can restart a service. It sends a POST request to /api/v1/services/{service_name}/restart and checks for a successful response and the correct response data. The test confirms that the service is restarted as expected.
4. Admin Get Service Status Test: Verifies that an admin can retrieve the status of a specific service. It sends a GET request to /api/v1/services/{service_name}/status and checks for a successful response and the expected status information.
5. Admin Get All Services Status Test: Checks if an admin can retrieve the status of all services. It sends a GET request to /api/v1/services and verifies that the response includes the status of all managed services, such as ticker, ohlcv, and account.
6. Non-Admin Cannot Start Service Test: Tests that a non-admin user cannot start a service. It sends a POST request to /api/v1/services/{service_name}/start with a user token (instead of an admin token) and verifies that the response is a 403 Forbidden error.
7. Unauthenticated Cannot Access Test: Confirms that unauthenticated requests are rejected. It sends a POST request to /api/v1/services/{service_name}/start without any authentication headers and asserts that the response is a 401 Unauthorized error.

Test Execution and Verification

The integration tests are run using pytest tests/integration/test_service_control.py -v. The -v flag provides verbose output, making it easier to track the progress and results of each test. Before running these tests, ensure that the testing environment is correctly set up. This includes setting up the necessary dependencies and configurations. The tests must pass to meet the acceptance criteria.

Manual Testing and Example Usage

Besides automated integration tests, manual testing is crucial to ensure that the service control endpoints function as expected in a real-world scenario. The manual testing process will involve starting the API server, and then using a tool such as curl or Postman to send requests to the service control endpoints.

Step-by-Step Manual Testing

1. Start the Server: Start the API server using make run. This will launch the API and make it accessible. Before running the API, make sure to set up the appropriate environment variables.
2. Run the Example Script: Execute the example script using python examples/example_service_control.py --action demo. The script will interact with the service control endpoints to demonstrate their usage.
3. Verify the Results: Confirm that the example script correctly interacts with the services. Check that it can get the status of all services, start the ticker, check the ticker status, stop the ticker, and restart the ticker. This will help in validating the API's behavior.
4. Use curl or Postman: Use curl or Postman to send requests to the service control endpoints. This allows for detailed inspection of the requests and responses, which ensures the endpoints' functionality. For each endpoint, create requests with the proper authorization headers and verify the responses. This ensures that the endpoints are working correctly. Also, make sure to test different scenarios and inputs.

Expected Output and Behavior

The manual testing will confirm that the endpoints are functioning as designed. This involves checking the status codes, response data, and any error messages that may arise. The expected behavior includes the ability to start, stop, and restart services, and accurately retrieve the status information for each service. The example script is designed to automate this process. It provides a straightforward way to test all the endpoints. After running the script, verify that the services have started, stopped, and restarted as expected. Ensure all status checks report the correct state of each service.

Conclusion and Next Steps

Implementing the service control router is a significant step towards a more manageable and reliable API. It provides a solid foundation for managing services. The addition of service control endpoints enhances the operational capabilities of the API. These admin-only endpoints ensure secure access and management of the core services. By integrating these endpoints, the team can increase the API's reliability. The integration tests and the manual testing will ensure that the service control endpoints function correctly and securely. As the project continues, the focus will be on further integrating the service control router and enhancing the API's functionalities.

Future Enhancements

• Implement comprehensive monitoring: Integrate with monitoring tools to track service performance and health metrics. This involves providing information on resource consumption and any potential bottlenecks.
• Add automated alerts: Set up automated alerts for service failures or performance issues. Implement an alerting system to notify administrators of any issues. This will help maintain the stability of the system.
• Integrate with a dashboard: Create a user-friendly dashboard for visualizing service status and managing the services. A dashboard will provide an easy-to-use interface.

By following the implementation strategy and integrating the service control router, the API will be able to handle and manage its services efficiently. The comprehensive integration tests and the manual testing will ensure that the service control endpoints function correctly and securely. These will significantly improve the operational capabilities of the API and its overall reliability.

For more information on FastAPI and API development, you can check out the official FastAPI documentation. This documentation provides in-depth information and is essential for implementing the API service control router.