[RFD] Standards for X-Headers in Ochami Microservices

[alexlovelltroy]

Standards for X-Headers in Microservice Architecture

Status

Proposed

Context

In our microservice architecture, there's a need for consistent and standardized communication between services. This includes the propagation of context, authentication information, and operational metadata. We currently rely on custom HTTP headers, known as X-Headers, to achieve this. Additionally, we use a Bearer token in the Authorization header for authentication purposes. The content and handling of the Bearer token are covered in #11. Additionally, considering the implications of header size limits is crucial for ensuring compatibility and optimal performance.

Decision

We have decided to adopt a standardized set of X-Headers across our microservices. These headers will be used to propagate request context, traceability data, and other operational metadata between services. The standard headers we will use are:

1. X-Trace-ID: To carry a unique identifier for the entire request trace, facilitating distributed tracing across services.
2. X-Span-ID: To carry a unique identifier for the current operation or service call, to be used in conjunction with X-Trace-ID for detailed tracing.
3. X-Request-ID: To carry a unique identifier for the current request, useful for logging and correlating events related to a single request.
4. X-Request-Cancelled: To indicate whether a request has been cancelled upstream, allowing downstream services to abort processing early.
5. X-Deadline: To convey the deadline for a request, enabling downstream services to adjust their processing to meet the time constraints.
6. Authorization (Bearer Token): For authentication purposes, containing a token as defined in the separate ADR on Bearer Token Content.

These headers must be respected and appropriately handled by all services within our architecture. Furthermore, considering the typical limits imposed by common web servers (e.g., Apache, Nginx, IIS), we decide to adhere to a general guideline of keeping the total size of HTTP headers under 8 KB. This size limitation ensures compatibility across various servers and mitigates performance and security issues associated with large headers.

Consequences

1. Improved Traceability: With standardized trace and span IDs, we can efficiently trace requests across our distributed systems.
2. Better Context Propagation: These headers will ensure consistent propagation of request context, improving the management of cancellations and deadlines.
3. Enhanced Debugging and Monitoring: Standardized request IDs will aid in logging, monitoring, and debugging, allowing for better correlation of events and issues.
4. Consistency and Standardization: Establishing these standards will lead to a more consistent implementation across all services, reducing the complexity of inter-service communication.
5. Security Considerations: While these headers improve operational efficiency, we must ensure they do not inadvertently expose sensitive information. The security of these headers, especially the Authorization header, must be ensured in transit and in logging.
6. Header Size Limit Considerations: By limiting the header size, we reduce the risk of exceeding server default limits, which could result in rejected requests or server errors.

Open Questions

1. How will services be modified or refactored to support these new headers?
2. What is the strategy for rolling out these changes in a backward-compatible manner?
3. How will we monitor and ensure compliance with these standards across all services?

[alexlovelltroy]

In https://github.com/OpenCHAMI/smd/pull/11 we replaced mux in favor of chi which enabled middleware. It's likely easier to standardize on this pattern for our services than it would be to revisit this choice anew for each microservice. CHI should be our default router and X-Header handling should be dealt with via middleware.