taolib.github_app.token_manager

taolib.github_app.token_manager#

GitHub App 安装令牌生命周期管理器。

本模块是令牌获取的唯一接入点，负责策略解析、缓存存取与 Singleflight 并发控制，避免下游重复向 GitHub 发起令牌请求。

Classes#

GitHubInstallationTokenManager

安装令牌的生命周期管理器。

Module Contents#

class taolib.github_app.token_manager.GitHubInstallationTokenManager(client: taolib.github_app.client.GitHubAppClient, cache: taolib.github_app.cache.InMemoryInstallationTokenCache, settings: taolib.github_app.config.GitHubAppSettings, event_hook: taolib.github_app.events.TokenEventHook | None = None)#

安装令牌的生命周期管理器。

负责三项核心职责：

  1. 根据运行环境将调用方请求的策略转为实际生效策略；

  2. 读写外部注入的缓存，在提前刷新窗口内触发刷新；

  3. 以 Singleflight 机制避免同一缓存键同时刷新造成的重复请求。

初始化令牌管理器。

参数:

  • client -- 与 GitHub API 交互的客户端。

  • cache -- 外部注入的令牌缓存实现。

  • settings -- GitHub App 运行时配置。

  • event_hook -- 可选的事件回调，用于监听令牌刷新事件。

build_cache_key(request: taolib.github_app.models.InstallationTokenRequest, effective: taolib.github_app.models.EffectiveTokenStrategy | None = None) → str#

为一个令牌请求构建唯一缓存键。

键值由 installation_id 、排序后的 permissions 、 排序后的 repositories 与生效策略拼接，确保不同权限与仓库 组合的令牌隔离存储。

参数:

  • request -- 调用方传入的令牌请求。

  • effective -- 已推断出的生效策略，为 None 时内部调用 resolve_effective_strategy() 推断。

返回:

唯一识别本次请求的缓存键字符串。

async get_token(request: taolib.github_app.models.InstallationTokenRequest) → taolib.github_app.models.InstallationTokenResult#

获取安装令牌的主入口。

执行流程：

  1. 根据调用方策略推断生效策略。

  2. 构建缓存键并尝试读取缓存。

  3. 缓存命中且未进入提前刷新窗口时直接返回。

  4. 否则进入 Singleflight 刷新流程，刷新后写回缓存并返回。

参数:

request -- 调用方提供的令牌请求。

返回:

为本次请求量身填充了策略与降级信息的 InstallationTokenResult。

抛出:

GitHubAppClientError -- 需要刷新但调用 GitHub API 失败。

resolve_effective_strategy(requested: taolib.github_app.models.RequestedTokenStrategy) → taolib.github_app.models.EffectiveTokenStrategy#

将调用方请求的策略转换为实际生效的策略。

核心规则：

  • 运行环境为 EnvironmentKind.GHES 时，强制降级为 EffectiveTokenStrategy.NONE。

  • RequestedTokenStrategy.ENABLED → EffectiveTokenStrategy.ENABLED。

  • RequestedTokenStrategy.DISABLED → EffectiveTokenStrategy.DISABLED。

  • RequestedTokenStrategy.AUTO → EffectiveTokenStrategy.NONE。

参数:

requested -- 调用方表达的策略意图。

返回:

推断出的生效策略。

cache#
client#
settings#