refactor: make Session identity claims gateway-agnostic

[patrickleet]

Summary

• Stop treating Hasura claim names (x-hasura-user-id / x-hasura-role) as the framework protocol for Session
• Introduce neutral convenience keys x-user-id / x-role (USER_ID_KEY / ROLE_KEY) for Session::user_id() and Session::role()
• Reframe docs (README, rustdocs, usage skill, read-models) so Session is an opaque claim map and Hasura is one example query-layer gateway
• Gateway-specific claim names remain available via Session::get(...)

Breaking change

Session::user_id() / Session::role() now read x-user-id / x-role instead of x-hasura-user-id / x-hasura-role. Deployments that inject Hasura-native headers should either map claims at the edge or read them with session.get("x-hasura-user-id").

Test plan

• cargo test -p distributed --features 'http,grpc' --lib session
• cargo test -p distributed --features 'http,grpc' --test microsvc (32 passed)
• CI green on this PR

Summary by CodeRabbit

• New Features

  • Added public convenience keys for session user ID and role values.
  • Updated session helpers to use the x-user-id and x-role conventions.

• Documentation

  • Clarified authentication responsibilities, trusted proxy requirements, and session trust boundaries.
  • Documented that trusted transport metadata takes precedence over payload session values.
  • Updated examples and read-model guidance to reflect the current service and query patterns.

• Tests

  • Updated session and transport coverage for the revised identity-header conventions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1c410526-8ba1-4275-8a01-0466d140d4f0

📥 Commits

Reviewing files that changed from the base of the PR and between c49c005 and 23ac462.

📒 Files selected for processing (12)

• README.md
• distributed_cli/skills/distributed-usage/SKILL.md
• docs/read-models.md
• src/microsvc/grpc.rs
• src/microsvc/http.rs
• src/microsvc/mod.rs
• src/microsvc/service.rs
• src/microsvc/session.rs
• tests/microsvc/session.rs
• tests/microsvc/transport_grpc.rs
• tests/microsvc/transport_http.rs
• tests/microsvc/transport_listen.rs

---

📝 Walkthrough

Walkthrough

The PR replaces Hasura-specific session identity names with x-user-id and x-role conventions, exports convenience key constants, updates helper behavior and transport tests, and revises trust-boundary and query-gateway documentation.

Changes

Microsvc session identity conventions

Layer / File(s)	Summary
Session contract and public exports src/microsvc/session.rs, src/microsvc/mod.rs, src/microsvc/service.rs	Session helpers use exported USER_ID_KEY and ROLE_KEY constants, which are re-exported publicly; related API documentation and unit tests now describe deployment-convention keys.
Transport propagation and validation src/microsvc/http.rs, src/microsvc/grpc.rs, src/microsvc/service.rs, tests/microsvc/*	HTTP, gRPC, and listen transport documentation and tests use x-user-id, while preserving trusted metadata precedence and session propagation behavior.
Documentation and usage guidance README.md, distributed_cli/skills/distributed-usage/SKILL.md, docs/read-models.md	Documentation describes generic identity headers, trusted proxy requirements, convenience keys, and query-gateway usage for read models.

Estimated code review effort: 2 (Simple) | ~15 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title clearly summarizes the main change: making Session identity claims gateway-agnostic.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/session-gateway-agnostic-identity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}