DateHeaderHandler: Unsupported Time‑Zone Offsets in HTTP Date Header

Answer

Do not extend DateHeaderHandler to accept arbitrary time‑zone offsets. Keep the current GMT‑only behavior and, if your application receives non‑GMT Date headers, either drop the header before it reaches the handler or provide a custom handler that converts the value to UTC.

Explanation

The built‑in DateHeaderHandler uses a fixed DateTimeFormatter configured with ZoneOffset.UTC. Consequently, any header containing a numeric offset (e.g., +0200) triggers a DateTimeParseException, resulting in a 400 Bad Request (or the exception propagates per your error handling). This design preserves caching correctness and request‑routing semantics, which rely on a canonical UTC timestamp.

Steps to handle non‑GMT dates

1. Strip or rewrite the offending Date header in a preceding filter (e.g., RoutingContext.removeHeader("Date")).
2. If you need to keep the value, implement a custom handler:

public class FlexibleDateHandler implements Handler<RoutingContext> {
    private static final DateTimeFormatter RFC1123_WITH_OFFSET =
        DateTimeFormatter.RFC_1123_DATE_TIME;
    @Override
    public void handle(RoutingContext ctx) {
        String header = ctx.request().getHeader(HttpHeaders.DATE);
        if (header != null) {
            try {
                ZonedDateTime zdt = ZonedDateTime.parse(header, RFC1123_WITH_OFFSET);
                Instant instant = zdt.toInstant(); // normalize to UTC
                // store or use the instant as needed, e.g., ctx.put("dateInstant", instant);
            } catch (DateTimeParseException e) {
                ctx.fail(e);
                return;
            }
        }
        ctx.next();
    }
}

3. Place this handler before DateHeaderHandler in your router chain.

Effects on caching and routing

• Caching mechanisms (e.g., HTTP caches, CDNs) expect the Date header to be a UTC timestamp. Preserving the original offset would break cache validation and could lead to stale responses.
• Request‑routing or security checks that compare dates rely on a uniform time base. Converting to UTC ensures consistent comparisons across nodes; retaining offsets would introduce node‑specific discrepancies.