Runtime Applicative Error Marker Detection

Overview

The RuntimeErrorMarkerLoader is a runtime service that detects applicative (business logic) errors within backend SOAP responses. Its primary function is to support the "Manual SOAP Test" feature (available at the /_test endpoint) by classifying a response payload as either a success or an applicative failure.

This component operates by searching a given response payload for specific, predefined "error marker" strings. These markers are configured by API publishers and stored in the s2r_learned_example_error_marker database table. The component can check for both global markers and markers specific to a single service.

It is designed to be a minimal, read-only component. To ensure that the Manual SOAP Test is not blocked by transient issues, the loader is fail-open. If it fails to load markers from the database, it logs the error at a DEBUG level and proceeds as if no applicative error was found, allowing the test call to complete.

To optimize performance, markers are loaded from the database and cached in memory with a 60-second Time-to-Live (TTL).

How it Works

The component's logic involves loading markers from a database, caching them, and then matching them against a response payload. A key distinction is made between "deciding" markers, which can fail a test, and "advisory" markers, which are for informational purposes only.

Data Loading and Caching

Error markers are sourced from the s2r_learned_example_error_marker database table. The component executes a SQL query to fetch all rows where enabled = true.

select marker_text from s2r_learned_example_error_marker
 where enabled = true
   and ((?::uuid is null and service_id is null)
        or service_id = ?::uuid)
 order by marker_text

• If a service_id is provided, it loads markers specific to that service.
• If the service_id is null, it loads global markers (where service_id in the table is NULL).

Loaded markers are stored in an in-memory cache (ConcurrentHashMap) keyed by the serviceId. Global markers are cached under a dedicated key. Cache entries are considered stale and are reloaded from the database after 60,000 milliseconds (CACHE_TTL_MS).

Matching Logic

When checking a payload, the component follows a precise matching sequence:

1. Payload Length Check: If the payload is null or, after trimming whitespace, is shorter than 20 characters (MIN_PAYLOAD_LEN), the check is bypassed and no match is returned. This prevents false positives on short success messages.
2. Marker Type Check: The component determines if a marker string contains only ASCII characters.
3. Matching:
   • For ASCII markers, a case-insensitive substring search is performed. Both the payload and the marker are converted to lowercase for the comparison.
   • For non-ASCII markers, a case-sensitive substring search is performed against the original, unmodified payload.
4. Result: The first marker that matches is returned. The returned string is the original marker text from the database, not the lowercased version.

Deciding vs. Advisory Markers

To avoid false positives, especially from common XML tags, markers are categorized into two types based on their scope (global vs. per-service) and format.

Deciding Markers

These are markers that, if found, will definitively classify the test response as an applicative error. The firstMatch method uses this set. The set of deciding markers for a given serviceId includes:

• All markers configured specifically for that serviceId.
• All global markers, except for those that are formatted like an XML element tag (e.g., <fault>).

This exclusion prevents a global tag marker, which might appear in both success and error responses from some backends, from incorrectly failing tests for all services.

Advisory Markers

These are markers that suggest a potential issue but do not automatically fail the test. The firstAdvisoryMatch method uses this set. An advisory marker is a global marker that:

1. Is formatted like an XML element tag (e.g., <status>).
2. Is not also configured as a per-service marker for the service being tested.

A match on an advisory marker should be surfaced to the API publisher for review, as it may indicate an error condition that warrants creating a more specific, deciding marker for that service.

Request Flow

The following diagram illustrates the logic flow when the firstMatch method is called to find a deciding error marker.

flowchart TD
    subgraph "firstMatch(payload, serviceId)"
        A[Start] --> B{Payload length < 20?};
        B -->|Yes| C[Return null];
        B -->|No| D[Get Deciding Markers for serviceId];
        D --> E{Loop over each marker};
        E -->|No more markers| C;
        E -->|Next marker| F{Is marker ASCII?};
        F -->|Yes| G{Payload (lowercased) contains marker (lowercased)?};
        F -->|No| H{Payload (as-is) contains marker (as-is)?};
        G -->|Yes| I[Return original marker string];
        H -->|Yes| I;
        G -->|No| E;
        H -->|No| E;
        I --> Z[End];
        C --> Z;
    end

    subgraph "Get Deciding Markers"
        style D fill:#f9f,stroke:#333,stroke-width:2px
        D1[Load per-service markers from cache/DB] --> D4;
        D2[Load global markers from cache/DB] --> D3[Filter out global markers shaped like <tag>];
        D3 --> D4[Combine per-service and filtered global markers];
        D4 --> D;
    end

Example Walkthrough

Consider the following error markers configured in the s2r_learned_example_error_marker table:

Scenario 1: Deciding match for Service abc-123

• Call: firstMatch(payload, "abc-123")
• Payload: ... <soap:body><fault>Error Code 99</fault></soap:body> ...
• Deciding Markers:
  • Error Code 99 (per-service)
  • <fault> (per-service)
  • Transaction failed (global non-tag)
• Result: The method returns either "Error Code 99" or "<fault>" depending on which is found first. The test would be marked as failed.

Scenario 2: No deciding match for Service def-456

• Call: firstMatch(payload, "def-456")
• Payload: ... <soap:body><fault>Some other error</fault></soap:body> ...
• Deciding Markers:
  • Transaction failed (global non-tag)
  • The global <fault> marker is an XML tag and is excluded from the deciding set because it is not explicitly configured for service def-456.
• Result: The payload does not contain Transaction failed. The method returns null. The test would be marked as a success.

Scenario 3: Advisory match for Service def-456

• Call: firstAdvisoryMatch(payload, "def-456")
• Payload: ... <soap:body><fault>Some other error</fault></soap:body> ...
• Advisory Markers:
  • <fault> (global XML-tag marker not configured for service def-456)
• Result: The payload contains <fault>. The method returns "<fault>". This result should be displayed to the user as a warning, suggesting they might want to configure this as a deciding error marker for their service.

API Reference

The component exposes the following public Java methods for use by the runtime.

Configuration Reference

The behavior of the RuntimeErrorMarkerLoader is controlled by data in the s2r_learned_example_error_marker table and by two internal constants.

Database Table: s2r_learned_example_error_marker

API publishers configure error markers by inserting or updating rows in this table.

Internal Constants

These values are compiled into the component and are not configurable at runtime.

Troubleshooting

The most common operational issue is a failure to connect to or query the database.

Fail-Open Behavior

• Condition: Any RuntimeException occurs during the database load operation.
• Cause: This can be triggered by database unavailability, network partitions, or invalid credentials.
• Effect: The component immediately returns an empty list of markers. It logs the failure at the DEBUG level but does not throw an exception.
• Impact: For the duration of the failure, the component will be unable to detect any applicative errors. All Manual SOAP Tests will appear to succeed from an applicative error perspective, even if the backend returns a known error message.
• Troubleshooting: To diagnose, check the application logs for DEBUG messages matching the following format:

  error-marker DB load failed (key=...); treating as no applicative error: ...
  

See Also

• Manual SOAP Test: The primary consumer of this component, used for service onboarding and testing.
• Learned Example Curation: The system responsible for managing and curating the s2r_learned_example_error_marker table. This component is a read-only client of that data.

All SOAP-to-REST docs