===================================
maintenance_service_http_monitoring
===================================

This module provides automated HTTP availability monitoring for services
defined on maintenance equipment. It periodically checks the HTTP status of
service URLs and automatically creates maintenance requests when services
are detected as unavailable.

Key features:

- **Automated HTTP checks**: Scheduled cron job checks all active services
- **Maintenance mode**: Temporarily disable monitoring during planned maintenance
- **Automatic maintenance requests**: Creates corrective maintenance requests
  when services fail HTTP checks
- **Status tracking**: Records last HTTP status code and check date per service

# Installation

Use Odoo normal module installation procedure to install
`maintenance_service_http_monitoring`.

This module depends on:
- `maintenance`
- `maintenance_server_data`

**Python dependencies**: This module requires the `requests` library.

# Configuration

## Maintenance Mode Duration

By default, maintenance mode lasts 4 hours. To change this:

1. Go to Settings > Technical > System Parameters
2. Create or edit the parameter:
   - Key: `maintenance_service_http_monitoring.maintenance_mode_duration`
   - Value: Duration in hours (e.g., `8`)

## Cron Jobs

Three scheduled actions are installed:

1. **HTTP Service Monitoring: check all services**
   - Runs every 10 minutes
   - Discovery sweep: checks HTTP status of all active service instances with URLs
     and flags the start of a KO streak

2. **HTTP Service Monitoring: confirm KO services**
   - Runs every 2 minutes
   - Re-checks only the services currently flagged KO (without an open request) and
     creates a maintenance request once the outage is confirmed

3. **HTTP Service Monitoring: deactivate expired maintenance mode**
   - Runs every 15 minutes
   - Automatically disables maintenance mode when the end time is reached

## Webhook Notifications

Go to **Settings > Technical > Parameters > System Parameters** and configure:

+--------------------------------------------------------+----------------------------------------+
| Key                                                    | Description                            |
+========================================================+========================================+
| ``maintenance_service_http_monitoring.webhook_url``    | Webhook URL (POST endpoint)            |
+--------------------------------------------------------+----------------------------------------+
| ``maintenance_service_http_monitoring.webhook_user``   | Basic Auth username (optional)         |
+--------------------------------------------------------+----------------------------------------+
| ``maintenance_service_http_monitoring.webhook_password``| Basic Auth password (optional)        |
+--------------------------------------------------------+----------------------------------------+


# Usage

## Monitoring Services

Services are automatically monitored if they have:
- A service URL defined
- An associated equipment
- The equipment is not in maintenance mode
- The service instance is active

The monitoring checks HTTPS availability (HTTP URLs are automatically
upgraded to HTTPS). A service is considered OK if it returns HTTP 200.

## Using Maintenance Mode

When performing planned maintenance on a server:

1. Go to Maintenance > Equipments
2. Open the equipment record
3. Click "Activer le mode maintenance" (Activate maintenance mode)
4. HTTP monitoring is suspended for this equipment
5. The mode automatically expires after the configured duration
6. Or click "Désactiver le mode maintenance" to end it manually

## Viewing HTTP Status

On service instances, you can see:
- **Last HTTP Status Code**: The last received HTTP status (200, 404, 500, etc.)
- **Last HTTP Check Date**: When the last check was performed
- **HTTP Status OK**: Quick visual indicator of service health

## Automatic Maintenance Requests

When a service fails HTTP checks:
- The 10-minute discovery sweep flags the outage (``http_first_ko_at``) but does
  **not** create a request yet
- The 2-minute confirmation cron re-checks the flagged services only. A request is
  created once the service has been continuously KO for at least 2 minutes
  (``HTTP_KO_CONFIRMATION_DELAY``), so a short transient outage is not flagged
- A corrective maintenance request is created per failing service, named
  ``[HTTP KO] {service_url}``
- The request description includes the error detail: the HTTP status code,
  or a network error label (timeout / DNS / SSL) when no HTTP response was received
- No duplicate is created as long as an open request already exists for that service
- The confirmation cron skips services that already have an open request; those are
  handled by the discovery sweep

When a service recovers (returns HTTP 200 after having an open request):
- The open maintenance request is automatically moved to the first **done** stage
- A chatter note is posted on the request by OdooBot to record the automatic closure
- The link between the service and the request is cleared, allowing a new request to
  be created if the service fails again in the future

## Webhook notifications

When a new maintenance request is created (HTTP check failure), the module can
send a webhook notification to an external service (e.g., n8n, Rocket.Chat, Slack).

The webhook sends a JSON POST with the following structure::

    {
        "id": 42,
        "name": "[HTTP KO] Server Name",
        "priority": "2",
        "description": "Service KO: https://example.com",
        "equipment": "Server Name",
        "link": "https://odoo.example.com/web#id=42&model=maintenance.request&view_type=form"
    }


# Known issues / Roadmap

- Add configurable alert thresholds (e.g., alert after N consecutive failures)
- Add email/notification on service failure
- Support custom HTTP check endpoints (e.g., /health)
- Add support for basic authentication

# Bug Tracker

Bugs are tracked on
[our issues website](https://github.com/elabore-coop/maintenance-tools/issues). In
case of trouble, please check there if your issue has already been reported. If you
spotted it first, help us smashing it by providing a detailed and welcomed feedback.

# Credits

## Contributors

- Stéphan Sainléger

## Funders

The development of this module has been financially supported by:

- Elabore (https://elabore.coop)

## Maintainer

This module is maintained by Elabore.