Crosscutting Concerns¶
This document describes the crosscutting concerns addressed by the geOrchestra Gateway architecture, which span multiple components and layers of the system.
Overview¶
Crosscutting concerns are aspects of a system that affect multiple components and cannot be cleanly decomposed into a single module or layer. In the geOrchestra Gateway, several important crosscutting concerns have been identified and addressed through architectural patterns and design decisions.
Security¶
Security is a primary crosscutting concern that affects every part of the Gateway.
Authentication¶
Authentication is implemented through several mechanisms:
- LDAP Authentication: For username/password authentication against an LDAP directory.
- OAuth2/OpenID Connect: For delegated authentication using external identity providers.
- Header Pre-authentication: For integration with upstream authentication proxies.
Key classes involved:
GatewaySecurityConfiguration
: Central configuration for all security components.LdapAuthenticationConfiguration
: LDAP-specific authentication.OAuth2Configuration
: OAuth2/OpenID Connect authentication.HeaderPreAuthenticationConfiguration
: Header-based pre-authentication.
Authorization¶
Authorization is enforced at multiple levels:
- Role-Based Access Control: Rules defined in the configuration determine which roles can access which paths.
- Spring Security Integration: Leverages Spring Security's authorization framework.
- GeorchestraUserRolesAuthorizationManager: Custom authorization manager that enforces access rules.
Secure Communication¶
The Gateway ensures secure communication:
- TLS Termination: Typically handled at the load balancer or Gateway level.
- Secure Headers: Added to responses to enforce browser security policies.
- Header Sanitization: Removes potentially dangerous headers from incoming requests.
User Information Management¶
User information is standardized and made available:
GeorchestraUser
model encapsulates all user information.- User details are propagated to backend services via HTTP headers.
- Role mappings allow dynamic extension of user roles.
Logging and Monitoring¶
Logging and monitoring are essential for observability and troubleshooting.
Structured Logging¶
The Gateway implements structured logging:
- JSON Log Format: Enables machine-readable logs in production.
- Configurable Log Levels: Different components can have different log verbosity.
- MDC Propagation: Context information is preserved across asynchronous boundaries.
Key components:
ReactorContextHolder
: Ensures MDC context is maintained in reactive code.AccessLogFilter
: Records HTTP requests with pattern-based filtering.MdcLogEnhancerFilter
: Adds context information to logs.
Metrics Collection¶
Application metrics are collected and exposed:
- Spring Boot Actuator provides metrics endpoints.
- Custom metrics can be added for domain-specific measurements.
- Health checks provide system status information.
Correlation IDs¶
Request tracing is supported through correlation IDs:
- Each request receives a unique identifier.
- The ID is propagated through the filter chain.
- The ID is included in logs for easier troubleshooting.
Configuration Management¶
Configuration management is another important crosscutting concern.
Externalized Configuration¶
Configuration is externalized from the application:
- Data Directory: External directory for configuration files.
- YAML Files: Configuration is primarily in YAML format.
- Environment Variables: Override capability via environment variables.
Configuration Validation¶
Configuration is validated to ensure correctness:
- Spring Validation: Bean validation for configuration properties.
- Custom Validators: Domain-specific validation rules.
- Fail-Fast Approach: Application fails to start with invalid configuration.
Feature Toggles¶
Features can be enabled or disabled:
- Spring Profiles: Activate specific functionality.
- Conditional Beans: Components are conditionally created based on configuration.
- Feature Flags: Configuration properties that enable/disable features.
Internationalization (i18n)¶
The Gateway supports internationalization:
- Message Bundles: Localized messages for UI elements.
- Language Selection: Based on browser preferences.
- UTF-8 Support: Throughout the application.
Key files:
messages/login_*.properties
: Localized messages for the login page.
Error Handling¶
Error handling is standardized across the application:
- Global Error Handlers: Catch and process errors consistently.
- Friendly Error Pages: Custom error pages for different HTTP status codes.
- Error Attributes: Standardized error response format.
Key components:
CustomErrorAttributes
: Enhances error information for responses.ApplicationErrorGatewayFilterFactory
: Handles errors in the Gateway filter chain.
Reactive Programming¶
As a reactive application, several patterns are applied:
- Non-Blocking Operations: All I/O operations are non-blocking.
- Backpressure Handling: Controls the flow of data through the system.
- Reactive Context Propagation: Carries contextual information across threads.
Dependency Injection¶
Spring's dependency injection is used throughout:
- Constructor Injection: Primary method for dependencies.
- Configuration Classes: Define beans and their relationships.
- Component Scanning: Automatic discovery of components.
Event-Driven Architecture¶
For loose coupling between components:
- Event Publishers: Components that emit events.
- Event Listeners: Components that react to events.
- RabbitMQ Integration: For cross-service communication.
Key components:
RabbitmqEventsConfiguration
: Configures event publishing via RabbitMQ.RabbitmqAccountCreatedEventSender
: Sends account creation events.RabbitmqEventsListener
: Listens for events from other services.
Testing Utilities¶
Testing support is provided across layers:
- Integration Test Base Classes: Common setup for integration tests.
- Test Fixtures: Reusable test data and configurations.
- Mock Services: Simplify testing of individual components.
Cross-Origin Resource Sharing (CORS)¶
CORS is handled globally:
- Configurable CORS Rules: Define allowed origins, methods, and headers.
- Spring CORS Support: Leverages Spring's CORS handling.
- Pre-flight Handling: Correctly responds to OPTIONS requests.
Implementation¶
These crosscutting concerns are implemented through a combination of:
- Aspect-Oriented Programming: For concerns that can be modularized.
- Decorators and Wrappers: For enhancing existing functionality.
- Middleware Patterns: Filters and interceptors in the request processing pipeline.
- Common Base Classes: For shared functionality across components.
- Service Abstractions: For consistent access to common services.
Best Practices¶
To maintain clean handling of crosscutting concerns:
- Single Responsibility: Each component should handle one primary concern.
- Consistent Patterns: Use the same patterns for similar concerns.
- Configuration Over Code: Prefer configuration for crosscutting behavior.
- Interface-Based Design: Define clear interfaces for crosscutting services.
- Documentation: Document how crosscutting concerns are addressed.