Appwrite Backend Health Gate

id: appwrite-backend-health-gate
namespace: company.team

description: |
  Probe an Appwrite backend's own health endpoints on a schedule , 
  database connectivity, in-memory cache connectivity, and clock drift
  against a trusted remote time source, classify the backend as
  HEALTHY, DEGRADED, or UNREACHABLE, log clean checks, and alert Slack
  the moment a subsystem fails or the server clock drifts too far.

inputs:
  - id: appwrite_url
    type: STRING
    defaults: "http://localhost/v1"
    displayName: "Appwrite API Base URL"
    description: "Base URL of the Appwrite API, including the /v1 suffix, no
      trailing slash."
  - id: project_id
    type: STRING
    displayName: "Appwrite Project ID"
    description: "ID of the Appwrite project to check, found in the project settings."
  - id: clock_drift_threshold_ms
    type: INT
    defaults: 5000
    displayName: "Clock Drift Threshold (ms)"
    description: "Absolute difference between the Appwrite server clock and a
      trusted remote time source, in milliseconds, above which the backend is
      classified DEGRADED."

triggers:
  - id: backend_health_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: "Check Appwrite's database, cache, and clock health every 10 minutes."
    cron: "*/10 * * * *"
    disabled: true
    inputs:
      appwrite_url: "http://localhost/v1"
      clock_drift_threshold_ms: 5000

tasks:
  - id: check_database_health
    type: io.kestra.plugin.core.http.Request
    description: "Check that Appwrite's database server is up and the connection
      from the API is successful."
    uri: "{{ inputs.appwrite_url }}/health/db"
    method: GET
    headers:
      X-Appwrite-Project: "{{ inputs.project_id }}"
      X-Appwrite-Key: "{{ secret('APPWRITE_API_KEY') }}"
    allowFailure: true

  - id: check_cache_health
    type: io.kestra.plugin.core.http.Request
    description: "Check that Appwrite's in-memory cache server is up and the
      connection from the API is successful."
    uri: "{{ inputs.appwrite_url }}/health/cache"
    method: GET
    headers:
      X-Appwrite-Project: "{{ inputs.project_id }}"
      X-Appwrite-Key: "{{ secret('APPWRITE_API_KEY') }}"
    allowFailure: true

  - id: check_clock_drift
    type: io.kestra.plugin.core.http.Request
    description: "Check that the Appwrite server's clock is synced with a trusted
      remote NTP time source."
    uri: "{{ inputs.appwrite_url }}/health/time"
    method: GET
    headers:
      X-Appwrite-Project: "{{ inputs.project_id }}"
      X-Appwrite-Key: "{{ secret('APPWRITE_API_KEY') }}"
    allowFailure: true

  - id: classify_backend_health
    type: io.kestra.plugin.core.debug.Return
    description: "Classify UNREACHABLE when any health check could not be fetched,
      DEGRADED when the database check, the cache check, or the clock drift
      crosses clock_drift_threshold_ms, otherwise HEALTHY."
    format: "{{ (outputs.check_database_health.body is defined and
      outputs.check_cache_health.body is defined and
      outputs.check_clock_drift.body is defined) ?
      (((outputs.check_database_health.body | jq('.status') | first) != 'pass'
      or (outputs.check_cache_health.body | jq('.status') | first) != 'pass' or
      ((outputs.check_clock_drift.body | jq('.diff | fabs') | first |
      default(0)) > inputs.clock_drift_threshold_ms)) ? 'DEGRADED' : 'HEALTHY')
      : 'UNREACHABLE' }}"

  - id: route_by_backend_health
    type: io.kestra.plugin.core.flow.Switch
    description: "Log a quiet confirmation when every subsystem is healthy, page
      Slack when the database, cache, or clock has degraded, or page Slack when
      the health checks could not be fetched at all."
    value: "{{ outputs.classify_backend_health.value }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "Appwrite project {{ inputs.project_id }} is healthy: database and
            cache both pass, clock drift within {{
            inputs.clock_drift_threshold_ms }}ms."
      "DEGRADED":
        - id: alert_degraded
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "text": "Appwrite sentinel DEGRADED for project {{ inputs.project_id }}: database status={{ outputs.check_database_health.body | jq('.status') | first }}, cache status={{ outputs.check_cache_health.body | jq('.status') | first }}, clock drift={{ outputs.check_clock_drift.body | jq('.diff') | first }}ms (threshold {{ inputs.clock_drift_threshold_ms }}ms). Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "text": "Appwrite sentinel UNREACHABLE for project {{ inputs.project_id }}: one or more health endpoints did not respond (invalid API key, wrong project ID, or the Appwrite instance is down). Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        message: "Completed Appwrite backend health check with status: {{
          outputs.classify_backend_health.value }}"

  - id: log_audit_status
    type: io.kestra.plugin.core.log.Log
    description: "Post-check status line recorded on every run regardless of branch,
      for a continuous backend-health trend in the execution history."
    message: "Appwrite audit: project={{ inputs.project_id }}, threshold={{
      inputs.clock_drift_threshold_ms }}ms, status={{
      outputs.classify_backend_health.value }}, execution={{ execution.id }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: "Alert Slack when the health gate flow itself fails, so a broken
      check never silently stops monitoring the Appwrite backend."
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "Appwrite backend health gate flow {{ flow.id }} FAILED (execution {{ execution.id }}). Backend health for project {{ inputs.project_id }} is now unknown; check the task logs and the Appwrite console manually."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ outputs.classify_backend_health.value }}"