Module de.cuioss.http

Package de.cuioss.http.security.exceptions

@NullMarked package de.cuioss.http.security.exceptions
Exception handling for HTTP security validation failures.

This package provides comprehensive exception types for representing security validation failures with detailed context information. All exceptions follow the fail-fast principle and provide rich information for debugging and monitoring.

Exception Types

Exception Features

  • Failure Type Classification - Detailed categorization via UrlSecurityFailureType
  • Validation Context - Information about what was being validated via ValidationType
  • Original Input - The input that caused the failure (for logging and debugging)
  • Sanitized Input - Partially processed input when available
  • Builder Pattern - Fluent construction with required and optional fields

Usage Example


 try {
     String validated = validator.validate(userInput);
     // Process validated input
 } catch (UrlSecurityException e) {
     // Rich exception context
     UrlSecurityFailureType failureType = e.getFailureType();
     ValidationType validationType = e.getValidationType();
     String originalInput = e.getOriginalInput();
     Optional<String> sanitized = e.getSanitizedInputOptional();

     // Log security event
     log.warn("Security violation: {} in {} for input: {}",
         failureType, validationType, originalInput);

     // Take appropriate action based on failure type
     switch (failureType) {
         case PATH_TRAVERSAL_DETECTED -> blockRequest();
         case INVALID_CHARACTER -> sanitizeAndRetry();
         case PATH_TOO_LONG -> rejectWithError();
     }
 }

Builder Pattern


 // Creating exceptions with builder
 throw UrlSecurityException.builder()
     .failureType(UrlSecurityFailureType.PATH_TRAVERSAL_DETECTED)
     .validationType(ValidationType.URL_PATH)
     .originalInput(maliciousInput)
     .detail("Directory traversal sequence found at position 15")
     .build();

Package Nullability

This package follows strict nullability conventions using JSpecify annotations:

  • All parameters and return values are non-null by default
  • Nullable parameters and return values are explicitly annotated with @Nullable
  • Optional fields use Optional<T> for safe access
Since:
1.0
See Also:
  • Exception Classes
    Class
    Description
    UrlSecurityException
    Main exception for HTTP security validation failures.