[Enhancement]: Improve X-Response-Time middleware with high-resolution timing #60

🧭 Project Area

Backend / API

📝 Issue Summary and Problem Description

Issue summary:
The current responseTime middleware wraps both res.writeHead and res.end with a boolean guard flag to prevent double-header writes, and uses performance.now(). This dual-wrapping approach adds unnecessary complexity.

Problem description:
The middleware should use a single clean interception point (res.end only) and leverage Node.js-native process.hrtime.bigint() for nanosecond-precision timing.

Why this is important:
The X-Response-Time header supports the project's observability goals outlined in the Architecture Blueprint. A clean, reliable implementation ensures accurate timing data.

Who is affected:
Backend developers maintaining the middleware stack, and monitoring tooling consuming the X-Response-Time header.

🔍 Current and Expected Behaviour

Current behaviour:
Wraps both res.writeHead and res.end, uses headerSet boolean guard, relies on performance.now(). Output: X-Response-Time: 4.123ms

Current result:
Works but implementation is fragile with unnecessary complexity.

Expected behaviour:
Wrap only res.end with process.hrtime.bigint() for nanosecond precision.

Expected result:
X-Response-Time: 4ms (cleaner implementation, single interception point)

🧩 Reproduction and Evidence

Step 1: Review backend/src/middleware/responseTime.js
Step 2: Note the dual-wrapping pattern (writeHead + end) and boolean guard
Step 3: Compare with Node.js best practices for response timing
Step 4: N/A

Screenshots: N/A
Video (optional): N/A

🎯 Affected Scope

Affected files: backend/src/middleware/responseTime.js
Affected APIs: All API responses (X-Response-Time header format changes from float to integer ms)
Affected components: Response timing middleware
Database changes required? No

🖥 Environment

Operating system: Windows 11
Browser and version: N/A (backend middleware)
Node.js version: v22.x
Package manager and version: npm 10.x
Docker version: N/A
Deployment environment: Local development

💡 Solution, Alternatives, and Estimate

Priority: P2 Medium
Proposed solution: Rewrite the middleware to wrap only res.end using process.hrtime.bigint(). Remove the writeHead wrapper and boolean guard. Add JSDoc documentation.
Alternative solutions: Could use the on-headers npm package, but a zero-dependency approach is better.
Difficulty: Beginner
Estimated time: 1 hour
Dependencies or blockers: None

✅ Acceptance Criteria and Additional Notes

• X-Response-Time header is present on every API response
• Timing uses process.hrtime.bigint() for nanosecond precision
• Only res.end is wrapped (single interception point)
• Boolean guard and writeHead wrapper are removed
• JSDoc documentation explains the implementation
• All existing integration tests pass
• No new dependencies added

Additional notes:
res.end wrapping is chosen over the "finish" event because "finish" fires after headers are flushed, making it too late to call setHeader.

🤝 Contributor Checklist

• I have searched existing issues and pull requests for duplicates.
• I can reproduce the issue, or I have clearly explained why reproduction is not applicable.
• I will follow the contribution guidelines and target ecsoc-2026.
• I agree to follow the Code of Conduct.
• I have removed secrets, private documents, and personal data.