1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
//! Copyright (c) 2026 Kirky.X. All rights reserved.
//! See LICENSE for full license text.
//! gRPC 鉴权拦截器 + 健康检查服务模块。
//!
//! ## 设计
//!
//! - `GarrisonGrpcInterceptor`:实现 `tonic::Interceptor` trait
//! - 从 gRPC 请求 metadata 提取 `authorization: Bearer <token>` header
//! - 调用 `GarrisonUtil::check_login()` 鉴权
//! - 鉴权失败返回 `tonic::Status::UNAUTHENTICATED`(code = 16)
//! - `health_service`:返回 `tonic_health::server::HealthServer<impl Health>`
//! - gRPC 标准健康检查协议(grpc.health.v1.Health)
//! - 默认设置 ServingStatus::Serving,供 kubelet / 服务网格探针调用
//!
//! ## 使用示例
//!
//! ```ignore
//! use garrison::grpc::{GarrisonGrpcInterceptor, health_service};
//! use tonic::transport::Server;
//!
//! // 重要:interceptor 会拦截所有 service 请求(要求 Authorization Bearer token),
//! // 因此 health_service 必须注册到独立的 tonic Server(无 interceptor),
//! // 否则 kubelet / 服务网格探针因缺少 Authorization 头而被拒绝。
//! let health = health_service().await;
//! Server::builder()
//! .add_service(health)
//! .serve(health_addr)
//! .await?;
//!
//! Server::builder()
//! .interceptor(GarrisonGrpcInterceptor::new())
//! .add_service(my_service)
//! .serve(app_addr)
//! .await?;
//! ```
//!
//! ## Feature 门控
//!
//! 启用 `grpc` feature 时编译。未启用时模块不存在,不引入 tonic 依赖。
/// gRPC 标准健康检查服务模块(`health_service()`)。
/// gRPC 鉴权拦截器实现模块(`GarrisonGrpcInterceptor` impl 块)。
pub use health_service;
/// Garrison gRPC 鉴权拦截器。
///
/// 实现 `tonic::Interceptor` trait,从 gRPC 请求 metadata 提取 Authorization Bearer token
/// 并调用 `GarrisonUtil::check_login()` 鉴权。鉴权失败时返回 `Status::UNAUTHENTICATED`。
///
/// # 重要限制:仅提取 token,不执行 async 鉴权
///
/// `tonic::Interceptor::call` 是**同步** trait,无法直接调用异步的 `GarrisonUtil::check_login()`。
/// 本拦截器仅完成 token 提取与基本格式校验(非空、`Bearer ` 前缀正确),
/// **不**执行实际的登录态/权限校验。
///
/// 完整的 async 鉴权推荐方案:
/// - 使用 `tonic` 的 `tower::Layer` middleware(async),在 layer 中调用 `GarrisonContext`
/// 执行 `check_login` 等异步 API;
/// - 或在 tonic service handler 内通过 `task_local`(`with_current_token`)读取 token,
/// 显式调用 `GarrisonUtil::check_login()`。
///
/// # 使用
///
/// ```ignore
/// use garrison::grpc::GarrisonGrpcInterceptor;
/// use tonic::transport::Server;
///
/// Server::builder()
/// .interceptor(GarrisonGrpcInterceptor::new())
/// .add_service(my_service)
/// .serve(addr)
/// .await?;
/// ```
;