This pull request introduces sub-second precision for the Enforced Timeout middleware. It adds a new timeout_duration field that accepts duration strings (e.g., "1.5s", "500ms"), allowing for more granular control over upstream request timeouts. The legacy timeout field, which accepts an integer in seconds, is deprecated but retained for backward compatibility.

To ensure older systems continue to function, when timeout_duration is set, the legacy timeout field is automatically populated with the duration rounded up to the nearest second. The core change is in the gateway's reverse proxy, which now uses time.Duration with context.WithTimeout to enable precise, sub-second timeout enforcement.

Files Changed Analysis

• Total Changes: 12 files modified, with 229 additions and 28 deletions.
• API Definitions (apidef/api_definitions.go, apidef/oas/middleware.go): The HardTimeoutMeta and EnforceTimeout structs are updated to include the new duration-based fields (TimeoutDuration, Timeout). Conversion logic is added to handle backward and forward compatibility.
• Gateway Logic (gateway/reverse_proxy.go): The primary change is in GetHardTimeoutEnforcedSettings (renamed from CheckHardTimeoutEnforced), which now returns a time.Duration. This allows WrappedServeHTTP to leverage context.WithTimeout with sub-second precision.
• Testing (gateway/reverse_proxy_test.go): Extensive tests (121 new lines) have been added to validate the new sub-second timeout functionality across various scenarios.
• Schema & Validation (apidef/oas/schema/*.json, apidef/schema.json, apidef/validator.go): The OpenAPI and internal JSON schemas are updated to recognize and validate the new duration-based timeout fields.
• Utilities (internal/time/duration.go): A SecondsCeil helper function has been added to facilitate the rounding-up logic for backward compatibility.

Architecture & Impact Assessment

• What this PR accomplishes: It enhances the Enforced Timeout middleware to support sub-second precision, giving API designers more granular control over upstream request timeouts.
• Key technical changes introduced:
  1. A new timeout_duration field (string) is added to the hard_timeouts configuration in the API definition.
  2. The gateway's reverse proxy now uses time.Duration for timeout calculations, enabling sub-second precision.
  3. Backward compatibility is preserved: if timeout_duration is set, the legacy timeout (integer) field is populated with the duration rounded up to the nearest second.
• Affected system components:
  • API Gateway: The core request-handling logic in the reverse proxy is directly impacted.
  • API Definition: The data structure is updated. While this change is non-breaking for the gateway, other components like the Tyk Dashboard and Tyk Operator will need to be updated to expose the new field in their respective UIs and controllers.

Request Flow with Sub-Second Timeout

sequenceDiagram
    participant Client
    participant Tyk Gateway
    participant Upstream Service

    Client->>+Tyk Gateway: HTTP Request
    Tyk Gateway->>Tyk Gateway: GetHardTimeoutEnforcedSettings()
    Note right of Tyk Gateway: Reads API spec for the matching path,<br/>retrieves timeout_duration (e.g., "500ms")
    Tyk Gateway->>Tyk Gateway: context.WithTimeout(req.Context(), 500ms)
    Tyk Gateway->>+Upstream Service: Forwards request with new timed context
    alt Upstream takes > 500ms
        Upstream Service-->>-Tyk Gateway: (No response within 500ms)
        Note left of Upstream Service: Gateway's context deadline is exceeded
        Tyk Gateway-->>-Client: HTTP 504 Gateway Timeout
    else Upstream takes < 500ms
        Upstream Service-->>-Tyk Gateway: HTTP 200 OK
        Tyk Gateway-->>-Client: HTTP 200 OK
    end

Scope Discovery & Context Expansion

• The primary impact is on the gateway's runtime and the API definition schema. The feature is fully functional within the gateway, but user-facing configuration will be limited to raw API definition edits until the Tyk Dashboard and Tyk Operator are updated to support the new timeout_duration field.
• The backward compatibility logic (rounding up to the nearest second) is a critical detail. This ensures that older systems reading the deprecated integer field will enforce a timeout that is at least as long as the intended duration, preventing unexpected failures. However, it also means sub-second precision can be lost if a configuration is round-tripped through an older system that only supports the integer field.
• The OpenAPI schema in apidef/oas/schema/x-tyk-api-gateway.json has been relaxed by removing value from the required list. This is necessary to allow the new timeout field to be used instead. However, the validation in apidef/validator.go only checks for negative timeouts, not whether a positive timeout is set when the middleware is enabled. This could allow a configuration where the middleware is enabled with a timeout of zero, rendering it ineffective.

Powered by Visor from Probelabs

Last updated: 2026-05-15T11:51:47.727Z | Triggered by: pr_updated | Commit: b7f550b

💡 TIP: You can chat with Visor using /visor ask <your question>

Security Issues (1)

✅ Performance Check Passed

No performance issues found – changes LGTM.

Powered by Visor from Probelabs

Last updated: 2026-05-15T11:51:27.689Z | Triggered by: pr_updated | Commit: b7f550b

💡 TIP: You can chat with Visor using /visor ask <your question>

🎯 Recommended Merge Targets

Based on JIRA ticket TT-12339: [BE] Implement sub-second timeout for the Enforced Timeout middleware

Fix Version: Tyk 5.14.0

⚠️ Warning: Expected release branches not found in repository

Required:

• master - No matching release branches found. Fix will be included in future releases.

📋 Workflow

1. Merge this PR to master first

🚨 Jira Linter Failed

Commit: b7f550b
Failed at: 2026-05-15 11:50:19 UTC

The Jira linter failed to validate your PR. Please check the error details below:

failed to validate Jira issue: jira ticket TT-12339 has status 'In Test' but must be one of: In Dev, In Code Review, Ready For Dev, Dod Check

Next Steps

• Ensure your branch name contains a valid Jira ticket ID (e.g., ABC-123)
• Verify your PR title matches the branch's Jira ticket ID
• Check that the Jira ticket exists and is accessible

This comment will be automatically deleted once the linter passes.

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud