Interceptor Framework Design Patterns and Implementation

An interceptor framework provides a clean mechanism for implementing cross-cutting concerns like logging, authentication, and validation across application layers while maintaining separation of concerns and system extensibility.

1. Problem Statement & Requirements

Clarifying questions

1. What is the scope of interception? Should this framework intercept HTTP requests/responses, database queries, method calls within the application, or all of the above?
2. What is the expected scale and throughput? Should we design for high-throughput microservices or low-throughput monoliths?
3. What consistency requirements exist? Do we need strong consistency for interception points, or eventual consistency acceptable?
4. What is the read/write ratio? Is this more of a write-heavy system where interception affects performance critical paths?
5. What latency sensitivity is expected? Are there strict SLA requirements for interception overhead (e.g., <5ms p99)?
6. What authentication and authorization model is in place? Should the interceptor framework support JWT, OAuth2, or custom auth?
7. What external integrations are expected? Will interception include external API calls, database connections, or just internal service calls?

Functional requirements

• Intercept and process cross-cutting concerns (logging, authentication, authorization, metrics)
• Allow registration of interceptors with specific priority levels
• Support both synchronous and asynchronous interception points
• Provide a mechanism to conditionally apply interceptors based on request context or metadata
• Allow interception of method calls, HTTP requests, and database operations
• Enable interception point chaining with configurable order
• Support interceptor lifecycle management (start, stop, reload)
• Allow interception point to modify or cancel request/response flow

Non-functional requirements

• Latency targets: p50 < 2ms, p95 < 5ms, p99 < 10ms for interception overhead
• Throughput: Support 10,000+ concurrent interception points with minimal impact
• Availability: 99.9% uptime for interception framework (99.99% for critical interceptors)
• Scalability: Support horizontal scaling across microservices with consistent interception behavior
• Resource usage: Max 5% CPU and memory overhead for interception framework

Constraints and assumptions

• Framework must be compatible with Spring Boot, Java EE, and standard Java applications
• Interceptors must support both synchronous and asynchronous interception patterns
• Assumption: Application code will not be modified to include interception logic directly
• Interceptors must be pluggable and dynamically loadable without restarting the application
• Framework will not manage external dependencies like database or cache connections directly

Out of scope

• Direct database query interception (e.g., SQL rewriting or query transformation)
• Interception of system-level calls like OS file I/O or native library calls
• Framework-specific UI for managing interceptors (monitoring dashboard)
• Interceptor configuration via GUI or web console
• Support for non-Java languages or frameworks (e.g., Go, Node.js)
• Interceptor dependency injection beyond standard DI containers (e.g., Spring's @Autowired)

2. API Design

API Style Selection

REST is selected for this interceptor framework design due to its:

• Widespread adoption and developer familiarity
• Clear HTTP verb semantics (GET/POST/PUT/DELETE)
• Built-in support for caching and stateless operations
• Natural fit for resource-based operations like interceptor registration, listing, and configuration management

Endpoint Definitions

Method	Path	Description	Auth
GET	/interceptors	List all registered interceptors	JWT
POST	/interceptors	Register a new interceptor	JWT
GET	/interceptors/{id}	Get interceptor by ID	JWT
PUT	/interceptors/{id}	Update interceptor configuration	JWT
DELETE	/interceptors/{id}	Remove interceptor	JWT
POST	/interceptors/{id}/enable	Enable interceptor	JWT
POST	/interceptors/{id}/disable	Disable interceptor	JWT
GET	/interceptors/{id}/config	Get interceptor configuration	JWT
PUT	/interceptors/{id}/config	Update interceptor config	JWT

Request and Response Schemas

Interceptor Registration Request:

{
  "name": "auth-interceptor",
  "description": "Handles authentication and authorization checks",
  "type": "REQUEST",
  "priority": 10,
  "config": {
    "authServiceUrl": "https://auth-service.internal",
    "tokenHeader": "Authorization"
  }
}

Interceptor Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "auth-interceptor",
  "description": "Handles authentication and authorization checks",
  "type": "REQUEST",
  "priority": 10,
  "enabled": true,
  "config": {
    "authServiceUrl": "https://auth-service.internal",
    "tokenHeader": "Authorization"
  },
  "createdAt": "2023-10-15T14:30:00Z",
  "updatedAt": "2023-10-15T14:30:00Z"
}

HTTP Status Codes and Error Response Format

Standard Status Codes:

• 200 OK - Successful GET, PUT, PATCH
• 201 Created - Successful POST
• 204 No Content - Successful DELETE
• 400 Bad Request - Invalid input data
• 401 Unauthorized - Missing or invalid auth token
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 422 Unprocessable Entity - Validation errors
• 500 Internal Server Error - Unexpected server error

Standardized Error Response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid interceptor configuration",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ],
    "timestamp": "2023-10-15T14:30:00Z",
    "requestId": "req-12345"
  }
}

API Versioning Strategy

Versioning will be done via the Accept header:

• Accept: application/vnd.interceptor.v1+json
• Future versions will use v2, v3 etc.

Pagination Design

Cursor-based pagination is selected because:

• It's more stable with data changes
• Provides better performance for large datasets
• Handles concurrent modifications gracefully

Pagination Response Format:

{
  "data": [/* interceptor objects */],
  "pagination": {
    "cursor": "eyJpZCI6IjEyMzQ1NiJ9",
    "hasNext": true,
    "hasPrevious": false
  }
}

Authentication and Authorization

Authentication:

• JWT tokens for API authentication
• Token validation via public key verification
• Token expiration handling

Authorization:

• RBAC model with roles: ADMIN, INTERCEPTOR_MANAGER
• ADMIN can manage all interceptors
• INTERCEPTOR_MANAGER can only manage interceptors they own

Rate Limiting Strategy

Per Endpoint Limits:

• /interceptors: 100 requests/minute
• /interceptors/{id}: 500 requests/minute
• /interceptors/{id}/config: 200 requests/minute

Implementation:

• In-memory rate limiter with sliding window algorithm
• Distributed implementation using Redis for multi-instance deployments

Idempotency Design

Idempotency Key Strategy:

• Clients send X-Idempotency-Key header with each request
• Server stores operation state for key duration (5 minutes)
• Duplicate requests with same key return same result
• Used primarily for interceptor registration and configuration updates

API Versioning Sample Request

POST /interceptors HTTP/1.1
Accept: application/vnd.interceptor.v1+json
Content-Type: application/json
Authorization: Bearer <jwt-token>
X-Idempotency-Key: req-123456789

{
  "name": "auth-interceptor",
  "description": "Handles authentication checks",
  "type": "REQUEST",
  "priority": 10,
  "config": {
    "authServiceUrl": "https://auth-service.internal"
  }
}

3. Data Model Design

Entity-Relationship diagram (Mermaid)

erDiagram
    INTERCEPTOR {
        string id PK
        string name
        string description
        string handler_class
        string priority
        boolean is_active
        timestamp created_at
        timestamp updated_at
        string created_by
        string updated_by
    }

    INTERCEPTOR_CONFIG {
        string id PK
        string interceptor_id FK
        string config_key
        string config_value
        timestamp created_at
    }

    INTERCEPTOR_LOG {
        string id PK
        string interceptor_id FK
        string request_id
        string status
        timestamp executed_at
        string error_message
        string trace_id
    }

    INTERCEPTOR_CONFIG ||--o{ INTERCEPTOR : "has"
    INTERCEPTOR_LOG ||--o{ INTERCEPTOR : "logs"

Table / Collection schema definitions with field types, constraints, indices

interceptor

CREATE TABLE interceptor (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    handler_class VARCHAR(500) NOT NULL,
    priority INTEGER NOT NULL DEFAULT 0,
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    created_by VARCHAR(255) NOT NULL,
    updated_by VARCHAR(255) NOT NULL,
    
    CONSTRAINT chk_priority_range CHECK (priority >= -1000 AND priority <= 1000),
    CONSTRAINT chk_name_not_empty CHECK (LENGTH(TRIM(name)) > 0)
);

CREATE INDEX idx_interceptor_priority ON interceptor(priority);
CREATE INDEX idx_interceptor_active ON interceptor(is_active);
CREATE INDEX idx_interceptor_created_at ON interceptor(created_at);

interceptor_config

CREATE TABLE interceptor_config (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    interceptor_id UUID NOT NULL REFERENCES interceptor(id) ON DELETE CASCADE,
    config_key VARCHAR(255) NOT NULL,
    config_value TEXT NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    
    CONSTRAINT chk_config_key_not_empty CHECK (LENGTH(TRIM(config_key)) > 0)
);

CREATE INDEX idx_interceptor_config_interceptor_id ON interceptor_config(interceptor_id);
CREATE UNIQUE INDEX idx_interceptor_config_unique_key ON interceptor_config(interceptor_id, config_key);

interceptor_log

CREATE TABLE interceptor_log (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    interceptor_id UUID NOT NULL REFERENCES interceptor(id) ON DELETE CASCADE,
    request_id VARCHAR(255) NOT NULL,
    status VARCHAR(50) NOT NULL,
    executed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    error_message TEXT,
    trace_id VARCHAR(255),
    
    CONSTRAINT chk_status_enum CHECK (status IN ('SUCCESS', 'FAILURE', 'PENDING')),
    CONSTRAINT chk_request_id_not_empty CHECK (LENGTH(TRIM(request_id)) > 0)
);

CREATE INDEX idx_interceptor_log_interceptor_id ON interceptor_log(interceptor_id);
CREATE INDEX idx_interceptor_log_executed_at ON interceptor_log(executed_at);
CREATE INDEX idx_interceptor_log_status ON interceptor_log(status);

Primary key strategy (UUID vs. auto-increment vs. ULID — with justification)

Using UUID as primary key for all tables:

• Justification: UUIDs provide globally unique identifiers without requiring coordination between services or databases
• Enables horizontal sharding and database replication without key conflicts
• Supports distributed systems where interceptors might be managed across different services or regions
• Provides better security by not exposing sequential patterns that could be exploited

Index design (composite, partial, covering indices — with justification per index)

1. idx_interceptor_priority:

   • Purpose: Efficient sorting and filtering by priority
   • Justification: Interceptors are processed in priority order, so this index supports O(1) lookup for the next interceptor to execute

2. idx_interceptor_active:

   • Purpose: Fast filtering of active interceptors
   • Justification: Most interceptor processing only needs to consider active interceptors

3. idx_interceptor_created_at:

   • Purpose: Audit trail and versioning support
   • Justification: Enables time-based queries for monitoring and debugging

4. idx_interceptor_config_interceptor_id:

   • Purpose: Fast lookup of all configurations for a given interceptor
   • Justification: Configuration is frequently accessed during interceptor execution

5. idx_interceptor_config_unique_key:

   • Purpose: Enforce uniqueness of config keys per interceptor
   • Justification: Prevents duplicate configuration entries for the same interceptor

6. idx_interceptor_log_interceptor_id:

   • Purpose: Fast querying of logs by interceptor
   • Justification: Required for audit trails and performance monitoring

7. idx_interceptor_log_executed_at:

   • Purpose: Time-based log queries
   • Justification: Enables time-range filtering for monitoring and debugging

8. idx_interceptor_log_status:

   • Purpose: Fast filtering by execution status
   • Justification: Required for monitoring and alerting on failed interceptors

Data partitioning / sharding strategy

Partition by interceptor type (based on handler_class prefix) or created_at date:

• For high-volume systems, partition by created_at monthly to support time-based retention policies
• Use hash-based sharding on interceptor_id for even distribution across database shards
• Consider application-level sharding key derivation from handler_class to group similar interceptors

Soft delete vs. hard delete decision with justification

Soft delete using is_active flag:

• Justification:
  • Allows for audit trail preservation and recovery capability
  • Interceptor configurations should remain accessible for historical analysis
  • Prevents data loss during accidental deletion or system errors
  • Supports rollback scenarios where interceptors need to be re-enabled

Audit trail design (who, what, when)

All tables include:

• created_by and updated_by: User or service identifier
• created_at and updated_at: Timestamps with timezone support
• trace_id in logs: Distributed tracing correlation

Data archival strategy and retention policy

Archival Strategy:

• Log entries older than 90 days are moved to cold storage (e.g., S3 with lifecycle policies)
• Configuration data is retained indefinitely as it's required for system operation
• Active interceptors are archived only when marked inactive and not referenced

Retention Policy:

• Interceptor logs: 90 days
• Configuration data: Indefinite (with versioning support)
• System metadata: 5 years

4. Class Design & Service Layer

UML Class Diagram

classDiagram
    class InterceptorFramework {
        +intercept(Request, Response)
        +register(Interceptor)
        +unregister(String)
    }
    
    class Interceptor {
        <<Interface>>
        +preProcess(Request, Response)
        +postProcess(Request, Response)
        +handleError(Request, Response, Exception)
    }
    
    class AbstractInterceptor {
        -priority: int
        -enabled: boolean
        +preProcess(Request, Response)
        +postProcess(Request, Response)
        +handleError(Request, Response, Exception)
        +getPriority()
        +isEnabled()
        +setEnabled(boolean)
    }
    
    class Request {
        -headers: Map~String, String~
        -body: String
        -method: String
        -uri: String
        +getHeader(String)
        +setHeader(String, String)
        +getBody()
        +setBody(String)
    }
    
    class Response {
        -statusCode: int
        -headers: Map~String, String~
        -body: String
        +getStatusCode()
        +setStatusCode(int)
        +getHeader(String)
        +setHeader(String, String)
        +getBody()
        +setBody(String)
    }
    
    class InterceptorChain {
        -interceptors: List~Interceptor~
        -currentPosition: int
        +execute(Request, Response)
        +addInterceptor(Interceptor)
        +removeInterceptor(String)
    }
    
    class LoggingInterceptor {
        +preProcess(Request, Response)
        +postProcess(Request, Response)
        +handleError(Request, Response, Exception)
    }
    
    class AuthenticationInterceptor {
        +preProcess(Request, Response)
        +postProcess(Request, Response)
        +handleError(Request, Response, Exception)
    }
    
    class MetricsInterceptor {
        +preProcess(Request, Response)
        +postProcess(Request, Response)
        +handleError(Request, Response, Exception)
    }
    
    InterceptorFramework --> InterceptorChain : uses
    InterceptorChain --> Interceptor : contains
    Interceptor <|-- AbstractInterceptor : implements
    Interceptor <|-- LoggingInterceptor : implements
    Interceptor <|-- AuthenticationInterceptor : implements
    Interceptor <|-- MetricsInterceptor : implements
    AbstractInterceptor --> Request : uses
    AbstractInterceptor --> Response : uses

State Machine Diagram for InterceptorChain

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : execute()
    Processing --> Completed : success
    Processing --> Error : exception
    Error --> Completed : handleError()
    Completed --> [*]

Service Class Structure and Responsibilities

The interceptor framework is designed as a pluggable system that allows for modular cross-cutting concerns to be applied to requests and responses. The key service classes are:

1. InterceptorFramework - Main entry point for the interceptor system, responsible for managing interceptor registration and orchestration.
2. InterceptorChain - Manages the execution order of interceptors, maintaining a list of active interceptors and their execution flow.
3. AbstractInterceptor - Base implementation providing common functionality for all interceptors, including priority management and enablement control.
4. Concrete Interceptor Implementations - Specific interceptors like LoggingInterceptor, AuthenticationInterceptor, and MetricsInterceptor that implement actual cross-cutting concerns.

Interface / Abstract Class Design

public interface Interceptor {
    void preProcess(Request request, Response response);
    void postProcess(Request request, Response response);
    void handleError(Request request, Response response, Exception exception);
}

public abstract class AbstractInterceptor implements Interceptor {
    protected int priority = 0;
    protected boolean enabled = true;

    public void preProcess(Request request, Response response) {
        // Default no-op implementation
    }

    public void postProcess(Request request, Response response) {
        // Default no-op implementation
    }

    public void handleError(Request request, Response response, Exception exception) {
        // Default no-op implementation
    }

    public int getPriority() {
        return priority;
    }

    public boolean isEnabled() {
        return enabled;
    }

    public void setEnabled(boolean enabled) {
        this.enabled = enabled;
    }
}

Business Logic Encapsulation Patterns

The framework uses the Strategy pattern to allow different interceptor behaviors to be implemented and composed dynamically. Each interceptor implements a specific cross-cutting concern (logging, authentication, metrics) while sharing the same interface contract.

Critical-Path Method Implementation

public class InterceptorFramework {
    private final Map<String, Interceptor> interceptors = new ConcurrentHashMap<>();
    private final InterceptorChain interceptorChain = new InterceptorChain();
    
    public Response intercept(Request request, Response response) {
        // Transaction boundary - all interceptor operations in single logical unit
        try {
            // Lock to prevent concurrent modification during execution
            synchronized (interceptorChain) {
                // Prepare the interceptor chain with current interceptors sorted by priority
                List<Interceptor> activeInterceptors = new ArrayList<>(interceptors.values())
                    .stream()
                    .filter(Interceptor::isEnabled)
                    .sorted(Comparator.comparingInt(Interceptor::getPriority))
                    .collect(Collectors.toList());
                
                interceptorChain.setInterceptors(activeInterceptors);
                
                // Execute pre-process phase
                for (Interceptor interceptor : interceptorChain.getInterceptors()) {
                    try {
                        interceptor.preProcess(request, response);
                    } catch (Exception e) {
                        // Log and continue with other interceptors
                        log.error("Pre-process failed for interceptor: {}", 
                                 interceptor.getClass().getSimpleName(), e);
                    }
                }
                
                // Execute the actual request processing (this is where the real work happens)
                // This would typically be a call to the actual service handler
                Response result = processRequest(request, response);
                
                // Execute post-process phase
                for (Interceptor interceptor : interceptorChain.getInterceptors()) {
                    try {
                        interceptor.postProcess(request, response);
                    } catch (Exception e) {
                        log.error("Post-process failed for interceptor: {}", 
                                 interceptor.getClass().getSimpleName(), e);
                    }
                }
                
                return result;
            }
        } catch (Exception e) {
            // Handle errors in interceptor chain
            for (Interceptor interceptor : interceptorChain.getInterceptors()) {
                try {
                    interceptor.handleError(request, response, e);
                } catch (Exception handleErrorException) {
                    log.error("Error handling failed for interceptor: {}", 
                             interceptor.getClass().getSimpleName(), handleErrorException);
                }
            }
            throw new InterceptorExecutionException("Failed to execute interceptor chain", e);
        }
    }
    
    private Response processRequest(Request request, Response response) {
        // This would be replaced with actual service logic
        return new Response();
    }
}

Transaction Boundary Design

The transaction boundary for the interceptor framework encompasses:

1. All interceptor pre-process and post-process operations
2. The actual request processing (service call)
3. Error handling for all interceptors
4. All state changes to the request and response objects

Service Interface Contracts

public interface InterceptorFrameworkService {
    Response intercept(Request request, Response response);
    void registerInterceptor(String name, Interceptor interceptor);
    void unregisterInterceptor(String name);
    List<Interceptor> getActiveInterceptors();
}

Saga / Orchestration Pattern

The interceptor framework does not require saga orchestration since it's a synchronous, cross-cutting concern system. Each interceptor operates independently and in sequence without distributed transaction requirements.

Domain Object / Value Object Design

public class Request {
    private final String method;
    private final String uri;
    private final Map<String, String> headers;
    private final String body;

    public Request(String method, String uri, Map<String, String> headers, String body) {
        this.method = method;
        this.uri = uri;
        this.headers = new HashMap<>(headers);
        this.body = body;
    }

    public String getMethod() { return method; }
    public String getUri() { return uri; }
    public Map<String, String> getHeaders() { return new HashMap<>(headers); }
    public String getBody() { return body; }

    public void setHeader(String key, String value) {
        headers.put(key, value);
    }

    public String getHeader(String key) {
        return headers.get(key);
    }
}

public class Response {
    private int statusCode;
    private final Map<String, String> headers;
    private String body;

    public Response(int statusCode, Map<String, String> headers, String body) {
        this.statusCode = statusCode;
        this.headers = new HashMap<>(headers);
        this.body = body;
    }

    public int getStatusCode() { return statusCode; }
    public void setStatusCode(int statusCode) { this.statusCode = statusCode; }
    public Map<String, String> getHeaders() { return new HashMap<>(headers); }
    public String getBody() { return body; }
    public void setBody(String body) { this.body = body; }

    public void setHeader(String key, String value) {
        headers.put(key, value);
    }

    public String getHeader(String key) {
        return headers.get(key);
    }
}

5. Concurrency & Thread Safety

Concurrency Model

The interceptor framework will operate in a multi-threaded environment where multiple concurrent requests may be processed simultaneously. The concurrency model leverages Java's thread-safe constructs and follows a shared-nothing approach where each request is handled in its own execution context.

Each interceptor invocation will run on a separate thread from the thread pool managed by the application server (e.g., Tomcat, Netty). The framework will not create new threads directly but rather rely on the underlying container's thread pool management.

Race Condition Prevention Strategy

Race conditions in interceptor execution can occur when:

1. Multiple interceptors modify shared state
2. Interceptors access mutable global configuration objects
3. Concurrent reads/writes to request-scoped attributes

To prevent race conditions:

• All interceptor state is request-scoped and immutable once processed
• Shared configuration objects are implemented as thread-safe immutable data structures (e.g., ConcurrentHashMap, AtomicReference)
• Use of synchronized blocks or locks only when absolutely necessary and for minimal code sections

Optimistic vs. Pessimistic Locking Selection

For the interceptor framework, optimistic locking is preferred over pessimistic locking because:

1. Interceptors typically don't modify shared database records or system-wide state
2. The framework operates on request-scoped data and metadata, which are isolated per request
3. Interceptor execution is generally fast and read-heavy with minimal write contention
4. Pessimistic locking would introduce unnecessary overhead and potential deadlocks in a high-concurrency environment

Deadlock Prevention Strategy

Deadlock prevention in the interceptor framework is achieved through:

1. Consistent ordering of resource acquisition: All interceptors follow a consistent order when accessing shared resources (e.g., configuration, logging context)
2. Timeout-based lock acquisition: When locks are required (e.g., for configuration updates), they use timeout mechanisms to prevent indefinite blocking
3. Avoiding nested locks: Interceptor chains do not nest lock acquisitions; each interceptor acquires and releases locks independently
4. Thread-local storage: Request-scoped state is stored in ThreadLocal variables to avoid cross-thread interference

Idempotency Implementation for Concurrent Duplicate Requests

Idempotency in interceptor execution is handled through:

1. Request-scoped unique identifiers: Each request gets a unique identifier that is propagated through the interceptor chain to detect duplicates
2. Idempotency key derivation: Interceptors can derive idempotency keys from request metadata (e.g., HTTP method + URL path + headers)
3. Caching of interceptor results: For read-only interceptors, the result can be cached with a TTL to avoid re-execution for concurrent requests
4. Atomic operation tracking: Use AtomicBoolean or similar to track whether an interceptor has already been executed for a given request context

public class IdempotencyInterceptor implements Interceptor {
    private static final Map<String, AtomicBoolean> executedRequests = new ConcurrentHashMap<>();
    
    @Override
    public void intercept(InterceptorContext context) {
        String idempotencyKey = generateIdempotencyKey(context);
        AtomicBoolean alreadyExecuted = executedRequests.computeIfAbsent(
            idempotencyKey, k -> new AtomicBoolean(false)
        );
        
        if (alreadyExecuted.compareAndSet(false, true)) {
            // Execute interceptor logic only once
            doIntercept(context);
        } else {
            // Skip execution for concurrent duplicate requests
            logger.debug("Skipping interceptor execution due to idempotency: {}", idempotencyKey);
        }
    }
    
    private String generateIdempotencyKey(InterceptorContext context) {
        return context.getRequest().getMethod() + ":" +
               context.getRequest().getRequestURI() + ":" +
               context.getRequest().getHeader("X-Request-ID");
    }
}

6. Sequence Diagrams for Key Flows

sequenceDiagram
    participant Client
    participant InterceptorFramework
    participant Interceptor1
    participant Interceptor2
    participant BusinessService

    Client->>InterceptorFramework: Request
    InterceptorFramework->>Interceptor1: Pre-process
    Interceptor1-->>InterceptorFramework: Continue/Abort
    InterceptorFramework->>Interceptor2: Pre-process
    Interceptor2-->>InterceptorFramework: Continue/Abort
    InterceptorFramework->>BusinessService: Forward to Business Service
    BusinessService-->>InterceptorFramework: Response
    InterceptorFramework->>Interceptor2: Post-process
    Interceptor2-->>InterceptorFramework: Continue/Abort
    InterceptorFramework->>Interceptor1: Post-process
    Interceptor1-->>InterceptorFramework: Continue/Abort
    InterceptorFramework-->>Client: Final Response

sequenceDiagram
    participant Client
    participant InterceptorFramework
    participant Interceptor1
    participant Interceptor2
    participant BusinessService

    Client->>InterceptorFramework: Request
    InterceptorFramework->>Interceptor1: Pre-process
    Interceptor1-->>InterceptorFramework: Abort with Error
    InterceptorFramework-->>Client: Error Response (403/401)

sequenceDiagram
    participant Client
    participant InterceptorFramework
    participant AsyncInterceptor
    participant EventPublisher
    participant MessageQueue

    Client->>InterceptorFramework: Request
    InterceptorFramework->>AsyncInterceptor: Async Pre-process
    AsyncInterceptor->>EventPublisher: Publish Event
    EventPublisher->>MessageQueue: Queue Event
    InterceptorFramework-->>Client: Immediate Response (202)

7. Caching Design

Cache-Aside vs Write-Through vs Write-Behind Strategy

For an interceptor framework, we'll use cache-aside pattern as the primary caching strategy. This approach gives us fine-grained control over when and how data is cached, allowing interceptors to selectively cache based on their specific needs. It also enables better handling of cache misses and provides flexibility in implementing custom caching logic for different interceptor types.

Write-through and write-behind patterns are more suitable for systems where cache consistency is paramount, but in an interceptor framework, we want to maintain the flexibility to selectively cache based on interceptor configuration and business logic.

Cache Key Design

Cache keys will follow a structured namespace pattern:

{cacheNamespace}:{entityType}:{entityId}:{version}:{contextHash}

Example:

interceptor:order:12345:v1:abc123

The namespace ensures proper segregation between different interceptor types and their caching requirements. The context hash allows for caching different versions of the same entity based on interceptor configuration or runtime context.

TTL Strategy

Data Type	TTL	Reason
Interceptor Configuration	1 hour	Configurations change infrequently, but need to be updated in a timely manner
Interceptor Metadata	30 minutes	Metadata changes less frequently than configuration but still need timely updates
Interceptor Execution Results	5 minutes	Short-lived results to ensure fresh data for subsequent requests
Interceptor Context Cache	15 minutes	Context data needs to be reasonably fresh but not too volatile

Cache Eviction Policy

We'll implement a hybrid LRU + TTL eviction policy:

• Primary eviction based on Least Recently Used (LRU) to maintain memory efficiency
• Secondary check for TTL expiration to ensure stale data is cleaned up even if recently accessed

This combination provides both memory efficiency and ensures that cached data doesn't persist beyond its useful lifetime.

Cache Stampede Prevention

To prevent cache stampedes:

1. Probabilistic Early Expiry: Cache entries will have a 20% chance of expiring 5 minutes early to prevent simultaneous cache hits
2. Distributed Locking: For high-traffic interceptor configurations, we'll use Redis distributed locks to serialize cache population
3. Cache Entry Validation: Cache entries will include a validation timestamp that prevents serving stale data during population

Distributed Cache Architecture

We'll use Redis Cluster with the following configuration:

• 3 master nodes with 3 replicas each for high availability
• Automatic failover capability
• Sharding based on cache key hash to distribute load evenly
• Redis Sentinel for monitoring and failover management

Cache Invalidation Strategy

We'll implement event-driven cache invalidation:

1. Cache Invalidation Events: When interceptor configurations change, we'll publish cache invalidation events
2. Pattern-based Invalidation: Cache keys will be invalidated using pattern matching (e.g., interceptor:*:order:*)
3. Explicit Purge: Direct cache purging for specific interceptor instances when needed
4. TTL-based Cleanup: Automatic cleanup of expired entries through Redis's built-in TTL mechanism

public class InterceptorCacheManager {
    private final RedisTemplate<String, Object> redisTemplate;
    private final ObjectMapper objectMapper;
    
    public void invalidateInterceptorCache(String interceptorType, String entityId) {
        String pattern = String.format("interceptor:%s:%s:*", interceptorType, entityId);
        Set<String> keys = redisTemplate.keys(pattern);
        
        if (keys != null && !keys.isEmpty()) {
            redisTemplate.delete(keys);
        }
    }
    
    public Object getCachedResult(String cacheKey) {
        return redisTemplate.opsForValue().get(cacheKey);
    }
    
    public void putCachedResult(String cacheKey, Object value, Duration ttl) {
        redisTemplate.opsForValue().set(cacheKey, value, ttl);
    }
    
    public boolean isCacheable(InterceptorConfig config) {
        return config.getCacheTtl() != null && config.getCacheTtl().toMillis() > 0;
    }
}

8. Repository / Data Access Layer

Repository Pattern Implementation

The repository pattern is implemented to abstract data access logic and provide a clean separation between domain logic and data persistence concerns. Each repository encapsulates the operations for a specific entity type.

public interface UserRepository {
    User findById(UUID id);
    List<User> findAll();
    User save(User user);
    void delete(UUID id);
    Optional<User> findByEmail(String email);
    List<User> findByRole(String role);
}

public class UserRepositoryImpl implements UserRepository {
    private final JdbcTemplate jdbcTemplate;
    private final ObjectMapper objectMapper;
    
    public UserRepositoryImpl(JdbcTemplate jdbcTemplate, ObjectMapper objectMapper) {
        this.jdbcTemplate = jdbcTemplate;
        this.objectMapper = objectMapper;
    }
    
    @Override
    public User findById(UUID id) {
        String sql = "SELECT * FROM users WHERE id = ?";
        return jdbcTemplate.queryForObject(sql, new Object[]{id}, this::mapRowToUser);
    }
    
    @Override
    public User save(User user) {
        if (user.getId() == null) {
            user.setId(UUID.randomUUID());
            String sql = "INSERT INTO users (id, email, name, metadata) VALUES (?, ?, ?, ?)";
            jdbcTemplate.update(sql, user.getId(), user.getEmail(), user.getName(), 
                               objectMapper.writeValueAsString(user.getMetadata()));
        } else {
            String sql = "UPDATE users SET email = ?, name = ?, metadata = ? WHERE id = ?";
            jdbcTemplate.update(sql, user.getEmail(), user.getName(), 
                               objectMapper.writeValueAsString(user.getMetadata()), user.getId());
        }
        return user;
    }
    
    private User mapRowToUser(ResultSet rs, int rowNum) throws SQLException {
        return User.builder()
                .id(rs.getObject("id", UUID.class))
                .email(rs.getString("email"))
                .name(rs.getString("name"))
                .metadata(objectMapper.readValue(rs.getString("metadata"), Map.class))
                .build();
    }
}

ORM vs. Raw Query Decisions

For this interceptor framework, raw SQL queries are preferred over ORM for several reasons:

1. Performance: Raw queries provide better performance for complex operations
2. Control: Full control over query execution and optimization
3. Flexibility: Ability to implement custom logic that ORM might not support
4. Debugging: Easier to debug and profile raw SQL queries

Read vs. Write Separation

The framework implements read-write separation using a CQRS pattern for better scalability:

public interface ReadUserRepository {
    User findById(UUID id);
    List<User> findAll();
    Optional<User> findByEmail(String email);
}

public interface WriteUserRepository {
    User save(User user);
    void delete(UUID id);
}

Connection Pool Configuration

Connection pool is configured with optimal settings for high-concurrency environments:

# application.yml
spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
      validation-timeout: 5000
      idle-timeout: 600000
      max-lifetime: 1800000
      leak-detection-threshold: 60000

N+1 Query Prevention Strategy

To prevent N+1 query problems, eager loading and batch operations are implemented:

public class UserBatchRepository {
    private final JdbcTemplate jdbcTemplate;
    
    public List<User> findUsersWithRoles(List<UUID> userIds) {
        if (userIds.isEmpty()) return Collections.emptyList();
        
        String sql = "SELECT u.*, r.name as role_name FROM users u " +
                    "LEFT JOIN user_roles ur ON u.id = ur.user_id " +
                    "LEFT JOIN roles r ON ur.role_id = r.id " +
                    "WHERE u.id IN (" + String.join(",", Collections.nCopies(userIds.size(), "?")) + ")";
        
        return jdbcTemplate.query(sql, userIds.toArray(), (rs, rowNum) -> {
            // Map user and roles in single query
            return mapUserWithRoles(rs);
        });
    }
}

Batch Operation Design

Batch operations are implemented to reduce database round trips:

public class BatchUserRepository {
    private final JdbcTemplate jdbcTemplate;
    
    public void batchSave(List<User> users) {
        String sql = "INSERT INTO users (id, email, name, metadata) VALUES (?, ?, ?, ?)";
        
        jdbcTemplate.batchUpdate(sql, new BatchPreparedStatementSetter() {
            @Override
            public void setValues(PreparedStatement ps, int i) throws SQLException {
                User user = users.get(i);
                ps.setObject(1, user.getId());
                ps.setString(2, user.getEmail());
                ps.setString(3, user.getName());
                ps.setString(4, objectMapper.writeValueAsString(user.getMetadata()));
            }
            
            @Override
            public int getBatchSize() {
                return users.size();
            }
        });
    }
}

Transaction Management

All repository operations are wrapped in appropriate transaction boundaries:

@Service
@Transactional
public class UserService {
    private final UserRepository userRepository;
    
    public User createUser(User user) {
        // Transaction boundary includes all repository operations
        return userRepository.save(user);
    }
    
    @Transactional(readOnly = true)
    public List<User> findUsersWithRoles(List<UUID> userIds) {
        // Read-only transaction for better performance
        return userRepository.findAllById(userIds);
    }
}

Repository Interface Contracts

Each repository interface follows a consistent contract pattern:

public interface BaseRepository<T, ID> {
    T findById(ID id);
    List<T> findAll();
    T save(T entity);
    void delete(ID id);
    boolean existsById(ID id);
}

Data Access Layer Design Summary

The repository layer provides:

1. Abstraction: Clean separation of data access logic
2. Performance: Raw SQL for optimal query execution
3. Scalability: Read-write separation and batch operations
4. Reliability: Proper transaction handling and connection pooling
5. Maintainability: Clear interfaces with consistent contracts

This design ensures that the interceptor framework can efficiently handle high-volume data operations while maintaining clean architecture and optimal performance characteristics.

9. Asynchronous Processing & Messaging

Event-driven boundaries in this feature — what triggers async vs. what stays synchronous, and why

The interceptor framework is primarily a synchronous request processing layer that can optionally trigger asynchronous operations. The key distinction for async processing:

• Synchronous: All interceptor execution happens within the request lifecycle, blocking until all interceptors complete. This ensures consistency and predictable response times for core business logic.
• Asynchronous: Post-processing or side-effect operations (e.g., logging, audit trails, notifications) are published as events for asynchronous handling. This decouples the core business logic from secondary operations, improving system resilience and scalability.

This design allows for synchronous interception of requests while enabling asynchronous processing of side effects without impacting the primary request flow.

Message schema design with a sample payload (Avro / Protobuf / JSON Schema — with versioning strategy)

{
  "type": "object",
  "title": "InterceptorEvent",
  "version": "1.0.0",
  "properties": {
    "eventId": {
      "type": "string",
      "description": "Unique identifier for this event"
    },
    "eventType": {
      "type": "string",
      "description": "Type of interceptor event (e.g., 'REQUEST_INTERCEPTED', 'RESPONSE_INTERCEPTED')"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "requestContext": {
      "type": "object",
      "properties": {
        "requestId": { "type": "string" },
        "method": { "type": "string" },
        "path": { "type": "string" },
        "headers": { "type": "object" }
      }
    },
    "interceptorMetadata": {
      "type": "object",
      "properties": {
        "interceptorId": { "type": "string" },
        "interceptorName": { "type": "string" },
        "executionOrder": { "type": "integer" }
      }
    },
    "payload": {
      "type": "object"
    }
  },
  "required": ["eventId", "eventType", "timestamp"]
}

Versioning strategy uses semantic versioning (MAJOR.MINOR.PATCH) with backward compatibility maintained through schema evolution. Major versions require new topic creation, while minor/patch versions can be handled within the same topic with schema registry validation.

Dead letter queue strategy and poison message handling

Poison messages are handled through a dead-letter queue (DLQ) pattern:

• Messages that fail more than 3 times are moved to a DLQ topic with a retention policy of 7 days.
• DLQ messages are tagged with metadata indicating the failure reason and number of retries.
• A manual review process is triggered for messages in DLQ to determine if they can be reprocessed or require operator intervention.
• A monitoring dashboard alerts on DLQ message volume and failure patterns.

At-least-once vs. exactly-once delivery — decision with justification for this feature

At-least-once delivery is chosen because:

1. Idempotency in interceptors: Interceptor logic is designed to be idempotent where possible, ensuring that reprocessing does not cause side effects.
2. Simplicity: The interceptor framework is primarily concerned with request processing, not transactional consistency across systems.
3. Performance: At-least-once is more performant than exactly-once, which requires additional coordination and state management.
4. Use case alignment: For logging and audit events, at-least-once provides sufficient reliability without the complexity of exactly-once semantics.

Retry policy for consumers (max attempts, backoff formula, non-retryable error classification)

Retry policy configuration:

• Max attempts: 3 retries
• Backoff formula: Exponential backoff with jitter (Jitter = random(0, 1) × baseDelay)
• Base delay: 500ms
• Max delay: 10 seconds

Non-retryable errors:

• ValidationException (input validation failures)
• UnauthorizedException (auth issues)
• ResourceNotFoundException (missing resources)
• BusinessLogicException (domain-specific errors)

Outbox pattern for reliable event publishing — include or explicitly justify omission

Outbox pattern is omitted in this design because:

1. The interceptor framework primarily emits events for logging and audit purposes, not for critical business operations.
2. These events are not part of a distributed transaction that requires atomicity.
3. The system uses a message broker (e.g., Kafka) with built-in durability guarantees.
4. For audit and logging events, eventual consistency is acceptable.

If the framework were to emit business-critical events (e.g., order creation, payment processing), then an outbox pattern would be implemented.

Sequence diagram for all async flows (Mermaid)

sequenceDiagram
    participant Client
    participant InterceptorFramework
    participant EventPublisher
    participant MessageBroker
    participant EventConsumer

    Client->>InterceptorFramework: Request with interceptors
    InterceptorFramework->>InterceptorFramework: Execute interceptors synchronously
    InterceptorFramework->>EventPublisher: Publish interceptor event
    EventPublisher->>MessageBroker: Send to topic (e.g., interceptor-events)
    MessageBroker->>EventConsumer: Deliver to consumer
    EventConsumer->>EventConsumer: Process event (log, audit, notify)

10. Error Handling Design

Error Classification Hierarchy

The interceptor framework must handle errors at multiple levels with clear classification:

• Validation Errors: Input validation failures (e.g., missing fields, invalid formats)
• Domain Errors: Business logic violations (e.g., insufficient permissions, invalid state transitions)
• Infrastructure Errors: System-level issues (e.g., database connection failures, timeout errors)
• External Service Errors: Third-party integration failures (e.g., HTTP 5xx from downstream services)

public abstract class InterceptorException extends RuntimeException {
    private final ErrorType errorType;
    private final String errorCode;

    protected InterceptorException(ErrorType errorType, String errorCode, String message) {
        super(message);
        this.errorType = errorType;
        this.errorCode = errorCode;
    }

    public enum ErrorType {
        VALIDATION, DOMAIN, INFRASTRUCTURE, EXTERNAL_SERVICE
    }

    // Getters
}

public class ValidationException extends InterceptorException {
    public ValidationException(String errorCode, String message) {
        super(ErrorType.VALIDATION, errorCode, message);
    }
}

public class DomainException extends InterceptorException {
    public DomainException(String errorCode, String message) {
        super(ErrorType.DOMAIN, errorCode, message);
    }
}

public class InfrastructureException extends InterceptorException {
    public InfrastructureException(String errorCode, String message) {
        super(ErrorType.INFRASTRUCTURE, errorCode, message);
    }
}

public class ExternalServiceException extends InterceptorException {
    public ExternalServiceException(String errorCode, String message) {
        super(ErrorType.EXTERNAL_SERVICE, errorCode, message);
    }
}

Error Propagation Strategy

Errors should be handled at the appropriate layer:

• Validation errors are caught and converted to ValidationException at the API boundary
• Domain logic errors are allowed to bubble up as DomainException from service layer
• Infrastructure errors are wrapped in InfrastructureException at repository/data access layer
• External service errors are wrapped in ExternalServiceException with retry logic

Retry Strategy with Exponential Backoff and Jitter

For infrastructure and external service errors, implement a retry strategy:

public class RetryConfig {
    private final int maxRetries;
    private final long initialDelayMs;
    private final double backoffMultiplier;
    private final long maxDelayMs;

    public RetryConfig(int maxRetries, long initialDelayMs, double backoffMultiplier, long maxDelayMs) {
        this.maxRetries = maxRetries;
        this.initialDelayMs = initialDelayMs;
        this.backoffMultiplier = backoffMultiplier;
        this.maxDelayMs = maxDelayMs;
    }

    public long getDelay(int attempt) {
        long delay = (long) (initialDelayMs * Math.pow(backoffMultiplier, attempt));
        return Math.min(delay, maxDelayMs);
    }
}

public class RetryableOperation<T> {
    private final RetryConfig config;
    private final Supplier<T> operation;

    public RetryableOperation(RetryConfig config, Supplier<T> operation) {
        this.config = config;
        this.operation = operation;
    }

    public T execute() throws Exception {
        Exception lastException = null;
        for (int attempt = 0; attempt <= config.maxRetries; attempt++) {
            try {
                return operation.get();
            } catch (Exception e) {
                lastException = e;
                if (attempt == config.maxRetries || !shouldRetry(e)) {
                    throw lastException;
                }
                
                long delay = config.getDelay(attempt);
                Thread.sleep(delay + (long) (Math.random() * 100)); // Add jitter
            }
        }
        throw lastException;
    }

    private boolean shouldRetry(Exception e) {
        return e instanceof InfrastructureException || e instanceof ExternalServiceException;
    }
}

Circuit Breaker Design

Implement circuit breaker pattern to prevent cascading failures:

public class CircuitBreaker {
    private final int failureThreshold;
    private final long timeoutMs;
    private final int successThreshold;

    private volatile CircuitState state = CircuitState.CLOSED;
    private volatile int failureCount = 0;
    private volatile long lastFailureTime = 0;

    public enum CircuitState {
        CLOSED, OPEN, HALF_OPEN
    }

    public boolean canExecute() {
        switch (state) {
            case CLOSED:
                return true;
            case HALF_OPEN:
                return failureCount == 0; // If no failures, allow one request
            case OPEN:
                if (System.currentTimeMillis() - lastFailureTime > timeoutMs) {
                    state = CircuitState.HALF_OPEN;
                    return true;
                }
                return false;
            default:
                throw new IllegalStateException("Unknown circuit state");
        }
    }

    public void recordSuccess() {
        if (state == CircuitState.HALF_OPEN) {
            failureCount = 0;
            state = CircuitState.CLOSED;
        }
    }

    public void recordFailure() {
        lastFailureTime = System.currentTimeMillis();
        failureCount++;

        if (state == CircuitState.CLOSED && failureCount >= failureThreshold) {
            state = CircuitState.OPEN;
        } else if (state == CircuitState.HALF_OPEN) {
            state = CircuitState.OPEN;
        }
    }
}

Fallback Behavior Design

Provide fallback behavior for external service calls:

public class InterceptorFallback {
    private final CircuitBreaker circuitBreaker;

    public InterceptorFallback(CircuitBreaker circuitBreaker) {
        this.circuitBreaker = circuitBreaker;
    }

    public <T> T withFallback(Supplier<T> operation, Supplier<T> fallback) {
        if (circuitBreaker.canExecute()) {
            try {
                T result = operation.get();
                circuitBreaker.recordSuccess();
                return result;
            } catch (Exception e) {
                circuitBreaker.recordFailure();
                return fallback.get();
            }
        } else {
            return fallback.get();
        }
    }
}

Error Logging Format and Alerting Thresholds

Structured logging with trace context:

public class InterceptorErrorLogger {
    private static final Logger logger = LoggerFactory.getLogger(InterceptorErrorLogger.class);

    public void logError(String traceId, String spanId, String userId, String entityId, 
                        InterceptorException exception) {
        logger.error("Interceptor error occurred",
            "trace_id", traceId,
            "span_id", spanId,
            "user_id", userId,
            "entity_id", entityId,
            "error_code", exception.getErrorCode(),
            "error_type", exception.getErrorType(),
            "message", exception.getMessage(),
            "stack_trace", exception.getStackTrace());
    }
}

// Example usage in interceptor
public class LoggingInterceptor implements Interceptor {
    private final InterceptorErrorLogger errorLogger;

    public LoggingInterceptor(InterceptorErrorLogger errorLogger) {
        this.errorLogger = errorLogger;
    }

    @Override
    public void intercept(InterceptorContext context) {
        try {
            // Process interceptor logic
            process(context);
        } catch (InterceptorException e) {
            errorLogger.logError(
                context.getTraceId(),
                context.getSpanId(),
                context.getUserId(),
                context.getEntityId(),
                e
            );
            throw e;
        }
    }
}

Alerting Thresholds

Configure alert thresholds for key metrics:

• Infrastructure errors: > 5 errors per minute → Critical alert
• External service errors: > 10 errors per minute → Warning alert
• Validation errors: > 100 errors per minute → Info alert (could indicate client-side issues)
• Domain errors: > 50 errors per minute → Info alert (could indicate business logic issues)

11. Security Design

Input Validation and Sanitization Strategy

All inputs are validated using a combination of:

• Regex-based validation for format constraints (e.g., email, phone number)
• Length limits to prevent buffer overflow attacks
• Type checking to ensure expected data types
• Whitelist-based sanitization for potentially dangerous characters (e.g., HTML tags, SQL keywords)
• Library choice: Apache Commons Validator for structured validation and OWASP Java HTML Sanitizer for XSS protection

SQL Injection Prevention

• Prepared statements are used exclusively for all database queries
• Parameter binding is enforced at the repository layer with no string concatenation
• Dynamic query building uses parameterized queries with named parameters (e.g., SELECT * FROM users WHERE id = :userId)
• Stored procedures are avoided in favor of parameterized queries for better control and security

Authentication Middleware Design

• JWT-based authentication with 2-hour expiration for session tokens
• Authentication filter intercepts all requests and validates JWT tokens
• Token refresh mechanism with 7-day refresh token validity (stored in secure, HTTP-only cookies)
• Middleware pipeline ensures authentication is checked before authorization
• Token revocation via Redis-based token blacklisting for immediate session termination

Authorization Enforcement

• Role-Based Access Control (RBAC) model with:
  • User roles: ADMIN, MODERATOR, USER, GUEST
  • Resource-based permissions (e.g., user:read, user:write)
• Permission checking at service layer using a centralized authorization service
• Fine-grained access control with resource ownership validation (e.g., only owner can delete their own posts)
• Authorization cache to reduce repeated permission lookups

Sensitive Data Encryption

• At-rest encryption: AES-256-GCM using AWS KMS for key management
• In-transit encryption: TLS 1.3 with HSTS header enforcement (max-age=31536000)
• Key rotation: 90-day automatic key rotation with seamless transition
• Data masking: PII fields (SSN, credit card numbers) are masked in logs and responses

PII Handling and Masking Strategy

• PII fields: SSN, email, phone, address, credit card details
• Masking rules:
  • SSN: XXX-XX-1234
  • Email: j***@gmail.com
  • Phone: XXX-XXX-1234
• Logging policy: PII never logged in plaintext; only masked versions or hashes
• Data retention: PII retained for 3 years, then securely deleted

Secrets Management

• Vault integration with dynamic secrets for database credentials and API keys
• Rotating secrets every 90 days with automatic rotation triggers
• Least privilege principle: Each service has minimal required secret access
• Secrets lifecycle managed through GitOps with encrypted secrets in version control

Audit Logging Design

• Events logged:
  • Authentication attempts (success/failure)
  • Authorization failures
  • Data access operations (read/write)
  • Admin actions (user creation, permission changes)
• Log format:

{
  "timestamp": "2023-10-15T14:30:00Z",
  "user_id": "user-123",
  "action": "user_create",
  "resource": "user",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "status": "success",
  "details": {
    "target_user_id": "user-456"
  }
}

• Retention policy: 90 days for audit logs with automatic archival to S3
• Compliance: Logs stored in compliance-ready format for regulatory audits

12. Testing Strategy

Unit Testing Scope and Coverage Targets (%)

• Service Layer: 85% code coverage with focus on business logic, error paths, and boundary conditions
• Repository Layer: 90% coverage with all CRUD operations and query patterns tested
• Interceptor Framework: 95% coverage including interceptor ordering, exception handling, and conditional execution
• Core Domain Logic: 90% coverage with edge cases and state transitions
• Test Data Generation: 100% coverage for all test scenarios with realistic data sets

Integration Testing Strategy

• Database Integration: Use Testcontainers with PostgreSQL/MySQL to test actual database interactions, including transaction boundaries and connection pooling
• External Service Mocking: WireMock for external API dependencies (e.g., auth service, notification service)
• Event System Integration: Embedded Kafka or RabbitMQ for testing event publishing and consumption flows
• Caching Layer Testing: Use embedded Redis to verify cache behavior, TTLs, and invalidation logic
• Authentication Integration: Test JWT token generation and validation with real key rotation scenarios

Contract Testing

• API Contract Testing: Implement Pact-based contract testing for external API boundaries (e.g., auth service, payment gateway)
• Event Contract Testing: Use Schema Registry with Avro schema validation for all published events
• Consumer-Provider Contract Testing: Define contract tests between services to ensure backward compatibility and prevent breaking changes

Performance Testing Tool

• Load Testing: Use k6 for load testing with scenarios covering:
  • Concurrent interceptor execution under high load (500+ concurrent requests)
  • End-to-end request processing with interceptor overhead
  • Memory usage under sustained load (GC pressure, memory leaks)
• Stress Testing: JMeter for stress testing with 10k+ concurrent requests to identify bottlenecks in interceptor chain execution
• Latency Targets:
  • p50: <5ms for single interceptor execution
  • p95: <20ms for interceptor chain execution
  • p99: <100ms for full request processing including interceptors

Test Data Management Strategy

• Fixtures: YAML-based fixtures for common test data (users, roles, permissions) with version control
• Factories: Factory pattern using builders for generating test data (e.g., UserFactory, OrderFactory) with configurable parameters
• Seeding: Database seeding scripts for integration tests to ensure consistent baseline data
• Test Data Isolation: Use separate test databases or schema per test suite to prevent cross-contamination
• Data Cleanup: Automated cleanup of test data after each test run with transaction rollback for unit tests and database truncation for integration tests

// Example of test data factory pattern for interceptors
public class InterceptorTestFactory {
    public static Interceptor createInterceptor(String name, int order) {
        return new Interceptor() {
            @Override
            public String getName() { return name; }
            
            @Override
            public int getOrder() { return order; }
            
            @Override
            public void preProcess(InterceptorContext context) {
                // Test implementation
            }
            
            @Override
            public void postProcess(InterceptorContext context) {
                // Test implementation
            }
        };
    }
}

13. Observability Design

Structured Logging Schema

The system will implement structured logging with consistent schema across all services to enable effective log analysis and correlation. The logging format will include the following required fields:

{
  "timestamp": "2023-10-27T14:30:45.123Z",
  "level": "INFO|WARN|ERROR",
  "service": "interceptor-service",
  "trace_id": "12345678-1234-1234-1234-123456789012",
  "span_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "user_id": "user-123",
  "request_id": "req-456",
  "component": "interceptor-engine",
  "event_type": "interceptor-executed",
  "interceptor_id": "interceptor-789",
  "status_code": 200,
  "duration_ms": 45,
  "error_code": "INTERNAL_ERROR",
  "error_message": "Failed to process interceptor",
  "payload_size_bytes": 1024,
  "method": "POST",
  "path": "/api/v1/interceptors",
  "ip_address": "192.168.1.1"
}

PII masking rules will be applied to sensitive fields:

• user_id will be masked in logs when not needed for debugging
• ip_address will be masked to IP subnet (e.g., 192.168.1.0/24)
• payload fields will be truncated or masked for sensitive content

Distributed Tracing Instrumentation

All interceptor operations will be instrumented with OpenTelemetry to enable end-to-end tracing. Custom spans will capture:

1. Interceptor Engine Span: Root span for interceptor execution lifecycle
2. Interceptor Execution Span: Individual interceptor processing
3. Pre-Processing Span: Before interceptor logic execution
4. Post-Processing Span: After interceptor logic execution

Key attributes captured per span:

// Example OpenTelemetry span instrumentation in Java
Span currentSpan = Span.current();
currentSpan.setAttribute("interceptor.id", interceptor.getId());
currentSpan.setAttribute("interceptor.type", interceptor.getType().toString());
currentSpan.setAttribute("interceptor.priority", interceptor.getPriority());
currentSpan.setAttribute("interceptor.status", "executed|failed");

Metrics Design

Service-level metrics will be collected using RED (Rate, Errors, Duration) methodology:

Metric Name	Type	Description	Labels
interceptor_requests_total	Counter	Total interceptor executions	type, status, priority
interceptor_errors_total	Counter	Failed interceptor executions	type, error_code, priority
interceptor_duration_seconds	Histogram	Execution duration per interceptor	type, priority, status
interceptor_queue_size	Gauge	Current queue size	type, priority
interceptor_processing_rate	Gauge	Current processing rate	type, priority

Example histogram bucket configuration:

// Histogram buckets for interceptor duration (in seconds)
double[] buckets = {0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0};

Health Check Endpoint Design

Comprehensive health check endpoints will be implemented:

// /health - Overall system health (critical dependencies)
// /ready - Service readiness for traffic (all components ready)
// /live - Process liveness check (no hang, memory issues)
// /startup - Startup completion status

@RestController
public class HealthController {
    
    @GetMapping("/health")
    public ResponseEntity<HealthStatus> health() {
        HealthStatus status = new HealthStatus();
        status.setOverall(HealthStatus.Status.HEALTHY);
        status.setDependencies(mapDependencies());
        return ResponseEntity.ok(status);
    }
    
    @GetMapping("/ready")
    public ResponseEntity<HealthStatus> ready() {
        HealthStatus status = new HealthStatus();
        status.setOverall(HealthStatus.Status.HEALTHY);
        status.setReadyComponents(mapReadyComponents());
        return ResponseEntity.ok(status);
    }
    
    @GetMapping("/live")
    public ResponseEntity<HealthStatus> live() {
        HealthStatus status = new HealthStatus();
        status.setOverall(HealthStatus.Status.HEALTHY);
        status.setProcessInfo(getProcessInfo());
        return ResponseEntity.ok(status);
    }
}

Alerting Thresholds

Critical alerting thresholds:

Metric	Warning Level	Critical Level	Alert Channel
interceptor_errors_total (rate)	> 5 errors/sec	> 20 errors/sec	On-call
interceptor_duration_seconds (p95)	> 100ms	> 500ms	Slack
interceptor_queue_size	> 100 items	> 500 items	Slack
interceptor_processing_rate (decrease)	< 50% of baseline	< 25% of baseline	On-call

Log Rotation and Retention

• Log rotation: 100MB size limit or 24h rotation
• Retention policy: 30 days for INFO logs, 7 days for DEBUG logs
• Archive strategy: Compress and store in S3 or equivalent cloud storage

Service Mesh Integration

For services that support it, integration with service mesh (Istio/Linkerd) will provide:

• Automatic tracing propagation
• Metrics collection at service mesh level
• Distributed tracing with enhanced context propagation

Metric Export Format

All metrics will be exported in Prometheus format for compatibility with monitoring systems:

# HELP interceptor_requests_total Total interceptor executions
# TYPE interceptor_requests_total counter
interceptor_requests_total{type="request",status="success",priority="high"} 1234.0
interceptor_requests_total{type="response",status="failed",priority="medium"} 56.0

Audit Trail Integration

All interceptor configuration changes and execution events will be logged to audit trail:

• Configuration updates (create, update, delete)
• Execution status and timing
• Error conditions with stack traces
• User context for auditability

Performance Monitoring

Key performance indicators:

• Latency: p50, p90, p95, p99 response times
• Throughput: Requests per second processed
• Resource utilization: CPU, memory, disk I/O
• Error rates: Failure percentage and error distribution

Observability Tooling Stack

• Tracing: OpenTelemetry Collector + Jaeger or Zipkin
• Metrics: Prometheus + Grafana dashboards
• Logging: ELK stack or CloudWatch + Loki
• Alerting: Alertmanager + PagerDuty/SMS integration
• Dashboarding: Grafana with pre-built dashboards for interceptor metrics

14. Open Questions, Risks & Trade-offs

Decisions requiring product / engineering alignment

• Interceptor ordering strategy: Should interceptors execute in a fixed order or allow dynamic configuration? The design assumes a static ordering, but in practice, teams may want to configure execution order per endpoint or feature flag.
• Cross-cutting concern scope: Should all interceptors be applied globally or only to specific services/endpoints? The current design applies to all requests, but some teams may prefer selective application.
• Performance impact tolerance: How much overhead is acceptable for interceptor execution? The design assumes minimal impact, but some interceptors (e.g., logging, validation) may introduce significant latency.

Known trade-offs and justifications

• Flexibility vs. Performance: The interceptor framework provides maximum flexibility by allowing any number of interceptors to be registered, but this introduces performance overhead due to multiple method calls per request. The design favors flexibility for extensibility but acknowledges the performance cost.
• Simplicity vs. Feature richness: The design uses a single interceptor interface with pre/post hooks, which is simpler than a complex pipeline with multiple hook types. This trade-off reduces complexity but may limit advanced use cases like conditional interception or request modification.
• Memory usage vs. concurrent execution: The framework maintains a copy of interceptors per request to support concurrent execution, which increases memory usage. This is acceptable for typical use cases but could be problematic in high-concurrency environments with many interceptors.
• Static vs. dynamic interception: The design uses compile-time registration of interceptors, which provides better type safety and performance but reduces runtime flexibility. Dynamic interception would allow runtime registration but introduces complexity in managing interceptor lifecycle.

Risks and mitigation strategies

• Performance degradation: Interceptor execution adds overhead to every request. Mitigation: Implement performance monitoring and alerting for interceptor execution times, provide performance guidelines to teams using interceptors.
• Deadlock risk: If interceptors acquire locks or make blocking calls, they can cause deadlocks. Mitigation: Enforce interceptor design guidelines that prohibit long-running operations or blocking calls within interceptors.
• Error propagation: An interceptor failure can affect the entire request lifecycle. Mitigation: Implement proper error handling and fallback mechanisms in interceptors, provide error logging and alerting for interceptor failures.
• Memory leaks: If interceptors hold references to large objects or don't clean up properly, they can cause memory leaks. Mitigation: Implement proper resource cleanup in interceptors and provide guidelines for interceptor lifecycle management.
• Security vulnerabilities: Interceptors that handle sensitive data or perform authentication/authorization can introduce security issues. Mitigation: Implement strict security guidelines for interceptor development and regular security reviews.

Technical debt acknowledged

• Limited interceptor introspection: The current design provides minimal introspection capabilities for interceptors. Teams may want to inspect interceptor execution status or metrics, which would require additional infrastructure.
• No built-in circuit breaker pattern: Interceptors that make external calls don't have circuit breaker support built-in, which could lead to cascading failures. This would require additional design work to integrate circuit breaker patterns.
• Hardcoded interceptor execution order: The framework currently executes interceptors in a fixed order, which may not support all use cases where dynamic ordering is required. This could be addressed with a more sophisticated interceptor registration system.
• No built-in rate limiting or throttling: While interceptors can implement rate limiting, the framework doesn't provide built-in support for this common concern, requiring teams to implement their own solutions.
• Limited testing support: The interceptor framework doesn't provide built-in testing utilities or mock capabilities, which could make it harder for teams to unit test their interceptor implementations.