Typesense Collection Drift and Zero-Hit Sentinel

id: typesense-collection-drift-and-zero-hit-sentinel
namespace: company.team

description: |
  Continuously probe Typesense search collections to detect zero-hit search outages,
  catalog depletion drift, and cluster connectivity failures before customer-facing
  applications are impacted. Evaluates document hit counts against configurable safety
  thresholds using Pebble, branches to Slack alerts on degradation, logs clean passes,
  and emits structured audit metrics.

inputs:
  - id: typesense_host
    type: STRING
    displayName: Typesense Host
    description: Hostname or IP address of the Typesense server (e.g., localhost or
      container name).
    defaults: "localhost"

  - id: typesense_port
    type: INT
    displayName: Typesense Port
    description: Port number for the Typesense HTTP REST API.
    defaults: 8108

  - id: typesense_https
    type: BOOL
    displayName: Use HTTPS
    description: Set to true if connecting to a Typesense cluster behind TLS/HTTPS.
    defaults: false

  - id: collection_name
    type: STRING
    displayName: Collection Name
    description: Name of the Typesense collection to audit.
    defaults: "products"

  - id: canary_query
    type: STRING
    displayName: Canary Search Query
    description: Representative query string that must consistently return documents
      in a healthy index.
    defaults: "shoes"

  - id: query_by_fields
    type: STRING
    displayName: Query By Fields
    description: Comma-separated list of document fields queried during the probe.
    defaults: "name,category,description"

  - id: facet_by_field
    type: STRING
    displayName: Facet Field
    description: Field used to audit facet distribution and index breadth across the
      collection.
    defaults: "category"

  - id: min_expected_hits
    type: INT
    displayName: Minimum Expected Hits
    description: Threshold below which catalog depletion drift is flagged as degraded.
    defaults: 5

triggers:
  - id: every_30_minutes
    type: io.kestra.plugin.core.trigger.Schedule
    description: Shipped disabled. Enable in production to continuously monitor
      search health.
    cron: "*/30 * * * *"
    disabled: true

tasks:
  - id: probe_search_canary
    type: io.kestra.plugin.typesense.Search
    description: Executes a canary query against the collection. allowFailure
      ensures timeouts or missing collections are caught for downstream
      classification rather than abruptly failing the workflow.
    allowFailure: true
    host: "{{ inputs.typesense_host }}"
    port: "{{ inputs.typesense_port }}"
    apiKey: "{{ secret('TYPESENSE_API_KEY') }}"
    collection: "{{ inputs.collection_name }}"
    https: "{{ inputs.typesense_https }}"
    query: "{{ inputs.canary_query }}"
    queryBy: "{{ inputs.query_by_fields }}"

  - id: probe_facet_distribution
    type: io.kestra.plugin.typesense.FacetSearch
    description: Evaluates facet distribution across the collection to ensure
      multi-category index breadth remains intact.
    allowFailure: true
    host: "{{ inputs.typesense_host }}"
    port: "{{ inputs.typesense_port }}"
    apiKey: "{{ secret('TYPESENSE_API_KEY') }}"
    collection: "{{ inputs.collection_name }}"
    https: "{{ inputs.typesense_https }}"
    query: "*"
    queryBy: "{{ inputs.query_by_fields }}"
    facetBy: "{{ inputs.facet_by_field }}"

  - id: classify_sentinel_status
    type: io.kestra.plugin.core.debug.Return
    description: Classify health state into PROBE_FAILED, ZERO_HITS,
      LOW_INVENTORY_DRIFT, or HEALTHY based on total hits returned.
    format: "{{ outputs.probe_search_canary is not defined or
      outputs.probe_search_canary.totalHits is not defined ? 'PROBE_FAILED' :
      (outputs.probe_search_canary.totalHits == 0 ? 'ZERO_HITS' :
      (outputs.probe_search_canary.totalHits < inputs.min_expected_hits ?
      'LOW_INVENTORY_DRIFT' : 'HEALTHY')) }}"

  - id: route_by_sentinel_status
    type: io.kestra.plugin.core.flow.Switch
    description: Route execution based on classified search collection health status.
    value: "{{ outputs.classify_sentinel_status.value }}"
    cases:
      ZERO_HITS:
        - id: alert_zero_hits
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Dispatch critical alert to Slack when canary query returns zero
            hits while the cluster responds.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "🚨 *Typesense Zero-Hit Outage Detected*\n• Collection: `" ~ inputs.collection_name ~ "`\n• Canary Query: `" ~ inputs.canary_query ~ "`\n• Measured Hits: 0 (Threshold: >= " ~ inputs.min_expected_hits ~ ")\n• Impact: Storefront search may be serving blank result pages."} | toJson }}

      LOW_INVENTORY_DRIFT:
        - id: alert_low_inventory
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Dispatch warning alert when active search documents drop below safe
            inventory floor.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "⚠️ *Typesense Catalog Depletion Warning*\n• Collection: `" ~ inputs.collection_name ~ "`\n• Canary Query: `" ~ inputs.canary_query ~ "`\n• Measured Hits: " ~ outputs.probe_search_canary.totalHits ~ " (Threshold: >= " ~ inputs.min_expected_hits ~ ")\n• Impact: Catalog size dropped significantly below expected operational baseline."} | toJson }}

      PROBE_FAILED:
        - id: alert_probe_failed
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Dispatch urgent alert when cluster is unreachable or target
            collection is missing.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "🚨 *Typesense Cluster Connectivity Failure*\n• Target Host: `" ~ inputs.typesense_host ~ ":" ~ inputs.typesense_port ~ "`\n• Collection: `" ~ inputs.collection_name ~ "`\n• Status: Probe task failed to execute or connect.\n• Action: Verify Typesense daemon status and network accessibility."} | toJson }}

      HEALTHY:
        - id: log_healthy_status
          type: io.kestra.plugin.core.log.Log
          description: Record clean health check pass with verified document and facet
            counts.
          message: "Typesense sentinel passed: collection '{{ inputs.collection_name }}'
            is healthy with {{ outputs.probe_search_canary.totalHits }} canary
            hits."

    defaults:
      - id: log_unexpected_status
        type: io.kestra.plugin.core.log.Log
        message: "Unexpected classify_sentinel_status value: {{
          outputs.classify_sentinel_status.value }}"

  - id: log_audit_summary
    type: io.kestra.plugin.core.log.Log
    description: Final immutable audit log confirming sentinel evaluation details
      across all branches.
    message: "Typesense sentinel audit completed. execution={{ execution.id }}
      status={{ outputs.classify_sentinel_status.value }} canary_hits={{
      outputs.probe_search_canary.totalHits ?? 'N/A' }} min_threshold={{
      inputs.min_expected_hits }}"

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Catch-all notification if workflow encounters fatal execution
      errors outside handled probe tasks.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {{ {"text": "❌ *Typesense Sentinel Flow Error*\nFlow `" ~ flow.id ~ "` failed during execution `" ~ execution.id ~ "`. Check Kestra execution logs."} | toJson }}