Payload Size Limiting Filter

Overview

The PayloadLimitFilter is a servlet filter that intercepts all incoming API requests to enforce a maximum payload size. Its primary purpose is to protect the platform from resource exhaustion caused by excessively large request bodies. It acts as a safeguard at the entry point of the request processing pipeline.

For every request, the filter checks the payload size against a configurable limit. If the request body is too large, the filter rejects it immediately with an HTTP 413 Payload Too Large status and terminates processing. If the size is within the limit, the request is passed to the next component in the processing chain.

This component is crucial for maintaining platform stability and ensuring fair resource allocation among all tenants and services.

How It Works

The filter employs a two-pronged strategy to enforce the payload limit, efficiently handling both requests with a declared content length and those using chunked transfer encoding where the size is not known in advance.

flowchart TD
    subgraph "PayloadLimitFilter Logic"
        A[Incoming HTTP Request] --> B{Has `Content-Length` header?};
        B -- Yes --> C{Is `Content-Length` > Limit?};
        C -- Yes --> D[Reject with HTTP 413];
        C -- No --> E[Pass request to next filter];

        B -- No (e.g., Chunked Encoding) --> F[Wrap request in a counting stream];
        F --> G[Pass wrapped request to next filter];
        G -- "Downstream component reads body" --> H{Bytes read > Limit?};
        H -- No --> G;
        H -- Yes --> I[Write and commit HTTP 413 response];
        I --> J[Throw exception to stop processing];
    end

Request Processing

1. Fast-Path Rejection: For requests that include a Content-Length header, the filter performs an immediate check. If the declared length exceeds the configured maximum (maxBytes), the request is rejected instantly without reading any of the request body. This is a highly efficient check for the common case of non-chunked requests.

2. Streaming Byte Counting: If a request does not have a Content-Length header (indicated by a value of -1), it typically uses chunked transfer encoding. To handle this, the filter wraps the request's input stream in a CountingServletInputStream. This special stream does not buffer the body, but rather counts the bytes as they are read by downstream components (e.g., a request body deserializer).

3. Streaming Rejection: As the body is being streamed, if the total number of bytes read surpasses the limit, the counting stream triggers a rejection. It immediately writes and commits the HTTP 413 response. Committing the response at this stage is critical, as it prevents other framework components from overwriting this specific error with a more generic 400 or 500 status code. After sending the response, the stream throws a PayloadTooLargeException to halt further processing of the request. The filter catches and swallows this exception, as the response has already been finalized.

Multipart Request Handling

The filter includes a defensive guard for multipart requests (e.g., file uploads). Container-level multipart parsing can potentially bypass the filter's counting stream. To prevent this:

• Calls to getParts() or getPart() on a chunked-encoded request are blocked, resulting in a PayloadTooLargeException.
• For requests with a declared Content-Length that has already passed the fast-path check, multipart parsing is allowed to proceed safely.

Rejection Response

When a request is rejected, the rejectOversized method is invoked to generate a standardized error response.

• A log entry is created in the RuntimeLogRepository with the error code S2R-RUN-0413.
• A debug trace, including redacted request headers, is also persisted. Sensitive headers like Authorization have their values replaced with a placeholder.
• The response format depends on the API path:
  • For CONSUME and GATEWAY paths, which are SOAP-inbound, a SOAP Fault XML envelope is returned to comply with SOAP client expectations.
  • For all other paths (e.g., PUBLISH), a standard JSON error object is returned.
• The X-Correlation-Id header is included in the response.

Configuration Precedence and Refresh

The payload limit is determined by the following order of precedence:

1. Database Setting: A value set for the key max_sync_payload_mb in the RuntimeSettingRepository. This value is checked and refreshed every 60 seconds.
2. Environment Variable: The value of the S2R_MAX_SYNC_PAYLOAD_MB environment variable, used as a fallback if the database setting is absent.
3. Code Default: A hardcoded default of 30 MB if neither of the above is set.

The effective limit is always at least 1 MB, regardless of the configured value.

Configuration

The payload limit can be configured via an environment variable or a database setting. The database setting takes precedence and is refreshed dynamically at runtime.

Rejection Responses

When a request payload exceeds the configured limit, the filter responds with an HTTP 413 Payload Too Large status. The body of the response varies based on the request path.

JSON Error Response

For most API paths, such as PUBLISH, the filter returns a JSON error object.

{
  "error": {
    "code": "S2R-RUN-0413",
    "message": "Payload too large",
    "details": {
      "maxPayloadMb": 30
    },
    "correlationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
}

SOAP Fault Response

For SOAP-inbound paths, specifically CONSUME and GATEWAY, the filter returns a SOAP 1.1 Fault envelope to maintain protocol correctness.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>Payload exceeds limit (S2R-RUN-0413)</faultstring>
      <detail>
        <errorCode>S2R-RUN-0413</errorCode>
        <maxPayloadMb>30</maxPayloadMb>
        <correlationId>a1b2c3d4-e5f6-7890-1234-567890abcdef</correlationId>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Troubleshooting

Error: S2R-RUN-0413 - Payload too large

• Trigger: An API consumer sends an HTTP request where the body size exceeds the configured max_sync_payload_mb limit.
• Meaning: The request was intentionally blocked by the platform to prevent excessive resource consumption. The faultcode of soap:Client in the SOAP response indicates the issue originates from the client-side request.
• Resolution: The API consumer must reduce the size of the request payload to be at or below the configured limit and retry the request. The current limit is reported in the maxPayloadMb field of the error response body. API publishers can adjust this limit via the max_sync_payload_mb runtime setting.

All SOAP-to-REST docs