GraphQL synthetic health and resolver canary probe

id: graphql-synthetic-canary-and-resolver-health-probe
namespace: company.monitoring

inputs:
  - id: graphql_endpoint_url
    type: STRING
    displayName: GraphQL Endpoint URL
    defaults: "https://spacex-production.up.railway.app/"
    description: Production or staging GraphQL HTTP endpoint to probe (e.g.
      'https://api.mycompany.com/graphql').

  - id: custom_canary_query
    type: STRING
    displayName: Synthetic Canary Query
    defaults: "query SyntheticCanary { __typename }"
    description: Minimal typed GraphQL query executed to validate parser, schema
      validation, and resolver execution path.

  - id: expected_typename
    type: STRING
    displayName: Expected Typename
    defaults: "Query"
    description: Expected root schema type returned by the introspection field
      __typename (typically 'Query').

  - id: fail_on_unhealthy
    type: BOOL
    displayName: Fail on Unhealthy Canary
    defaults: true
    description: Whether to fail execution when canary checks fail to trigger
      downstream incident alerts and status page monitors.

triggers:
  - id: periodic_canary_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: High-frequency 5-minute synthetic health sweep to catch resolver
      outages immediately. Shipped disabled by default.
    cron: "*/5 * * * *"
    disabled: true

tasks:
  - id: execute_canary_probe
    type: io.kestra.plugin.graphql.Request
    description: Fire synthetic GraphQL probe query against the target endpoint with
      relaxed error tolerance to inspect error payloads.
    uri: "{{ inputs.graphql_endpoint_url }}"
    headers:
      Authorization: "Bearer {{ secret('GRAPHQL_API_TOKEN') }}"
      Content-Type: "application/json"
      User-Agent: "Kestra-GraphQL-Canary-Probe/1.0"
    failOnGraphQLErrors: false
    query: "{{ inputs.custom_canary_query }}"
    options:
      allowFailed: true

  - id: evaluate_canary_health
    type: io.kestra.plugin.core.flow.If
    description: Validate whether HTTP response succeeded, returned expected root
      typename, and contains no uncaught resolver errors.
    condition: "{{ outputs.execute_canary_probe.code == 200 and
      outputs.execute_canary_probe.body is defined and
      outputs.execute_canary_probe.body.__typename == inputs.expected_typename
      and (outputs.execute_canary_probe.error is not defined or
      outputs.execute_canary_probe.error == null) }}"
    then:
      - id: log_canary_healthy
        type: io.kestra.plugin.core.log.Log
        description: Log verified operational state when probe succeeds and returns
          expected schema typename.
        message: "HEALTHY: GraphQL canary query executed successfully on {{
          inputs.graphql_endpoint_url }}. Root __typename returned '{{
          inputs.expected_typename }}' with zero resolver errors."
    else:
      - id: alert_canary_failure
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Dispatch high-priority Slack outage alert with HTTP status code,
          returned payload, and error diagnostics.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "text": "🚨 *GRAPHQL SYNTHETIC CANARY OUTAGE ALERT* 🚨\n\n*Endpoint:* `{{ inputs.graphql_endpoint_url }}`\n*HTTP Status:* {{ outputs.execute_canary_probe.code }}\n*Returned Root Typename:* `{{ outputs.execute_canary_probe.body is defined and outputs.execute_canary_probe.body.__typename is defined ? outputs.execute_canary_probe.body.__typename : 'UNDEFINED' }}`\n*GraphQL Errors:* `{{ outputs.execute_canary_probe.error is defined and outputs.execute_canary_probe.error != null ? outputs.execute_canary_probe.error : 'Resolver or payload mismatch' }}`\n\n*Execution ID:* {{ execution.id }}\n*Action Required:* Check GraphQL gateway pod logs, downstream microservice resolvers, and database connection pools immediately."
          }

      - id: check_fail_policy
        type: io.kestra.plugin.core.flow.If
        description: Terminate pipeline with failure when fail_on_unhealthy is enabled.
        condition: "{{ inputs.fail_on_unhealthy }}"
        then:
          - id: fail_canary_execution
            type: io.kestra.plugin.core.execution.Fail
            description: Fail execution to trip Kestra dashboard monitors and alert external
              status page integrations.

  - id: log_probe_metrics
    type: io.kestra.plugin.core.log.Log
    description: Record probe summary and HTTP status code.
    message: "GraphQL canary probe finished. Endpoint: {{
      inputs.graphql_endpoint_url }}, HTTP Status: {{
      outputs.execute_canary_probe.code }}."

errors:
  - id: alert_on_probe_exception
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert Site Reliability Engineering if DNS resolution fails or
      connection times out completely.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "⚠️ *GraphQL Canary Probe Failure*: Execution `{{ execution.id }}` failed to connect to `{{ inputs.graphql_endpoint_url }}`. Check edge CDN routing and network connectivity."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ outputs.execute_canary_probe.code == 200 and
      outputs.execute_canary_probe.body is defined and
      outputs.execute_canary_probe.body.__typename == inputs.expected_typename
      and (outputs.execute_canary_probe.error is not defined or
      outputs.execute_canary_probe.error == null) ? 'HEALTHY' : 'UNHEALTHY' }}"
  - id: http_status_code
    type: INT
    value: "{{ outputs.execute_canary_probe.code }}"
  - id: root_typename
    type: STRING
    value: "{{ outputs.execute_canary_probe.body is defined and
      outputs.execute_canary_probe.body.__typename is defined ?
      outputs.execute_canary_probe.body.__typename : 'NONE' }}"