Kong gateway and deck header-based routing inconsistence - Analytics

[biswadas11]

Customer is currently using deck 1.60.0 in our APIOps to support header-based routing cases.

During this process, they observed several corner cases involving required headers and enum values, which result in unexpected or inconsistent generated configurations (routes).

They would like clarification on whether these behaviors are expected and whether there are any plans for improvement.

Observed Issues & Examples

1. Duplicate Enum Values with Different Case

Scenario

• A required header is defined in the OpenAPI spec.
• The header includes an enum with values that differ only by case.

Example
parameters:

• name: X-Region
  in: header
  required: true
  schema:
  type: string
  enum:
• us-east
• US-EAST

Current Behavior (decK)

decK generates multiple header routes, one for each enum value:

• us-east
• US-EAST

Gateway Behavior

• HTTP headers are case-insensitive (header name).
• In practice, routing behavior may treat these as equivalent, causing:
• Redundant routes
• Potential conflicts or ambiguity

Concern

• decK treats enum values as distinct even when they differ only by case.
• This may not align well with runtime routing behavior.

2### . Duplicate Header Names with Different Case (Using Enum)

Scenario:

• The operation defines two required headers with the same logical name but different casing.
• Each header includes an enum with valid values.

Example
parameters:

• name: X-Env
  in: header
  required: true
  schema:
  type: string
  enum:

• prod

• staging

• name: x-env
  in: header
  required: true
  schema:
  type: string
  enum:

• prod

• staging

Current Behavior (decK):

• decK generates a route that includes both headers as separate required conditions, each with its enum constraints.

Gateway Behavior

• Header names are case-insensitive per HTTP specification.
• At runtime, X-Env and x-env are effectively treated as the same header.

Concern:

• This leads to:
• Redundant or conflicting route conditions
• Ambiguity, since both constraints apply to what is effectively a single header
• decK does not normalize or deduplicate header names based on case-insensitivity

3. Empty String in Enum for Required Header

Scenario:

• A required header includes an enum that contains an empty string.

Example
parameters:

• name: X-Env
  in: header
  required: true
  schema:
  type: string
  enum:
• ""

Current Behavior (decK)

• A route is generated that matches an empty string header value.

Concern:

• It is unclear whether:
• An empty string is a valid practical value for a required header
• This should be supported or validated as invalid input

Current Mitigation (Our Side)

We are considering adding validation in our API application layer to:

• Reject duplicate enum values differing only by case
• Reject duplicate header names (case-insensitive comparison)
• Reject empty string enum values for required headers

1. Are these behaviors in decK expected?

• Case-sensitive enum handling
• Duplicate header names treated as distinct when casing differs
• Acceptance of empty string enum values

2. Does Kong Gateway intentionally differ from decK in how headers are interpreted?

• decK treats inputs strictly
• Gateway treats header names case-insensitively
• Are there plans to improve or align behavior?

3. Normalize header names (case-insensitive) during conversion

• Deduplicate enum values when differing only by case
• Validate and reject invalid header definitions (e.g., duplicates, empty enums)

4. What is the recommended best practice?

• Should validation be enforced at the OpenAPI spec level?
• Or is this something decK should handle during conversion?

Additional Context
According to HTTP standards:

• Header names are case-insensitive
• Header values are generally case-sensitive (no strict normalization rules)

This creates ambiguity when:

• decK generates case-sensitive configurations
• Gateway applies case-insensitive matching

Expected Outcome
Customers are looking for:

• Clarification on intended behavior
• Whether improvements or fixes are planned