Skip to content

[refactor] security: retain canonical core Config in client module #425

Description

@foxzool

Problem Statement

OpenLark 的根 Client 已经以 canonical core Config 构造业务客户端,但 Security 仍在入口处把它降格为只含凭据和 base URL 的 SecurityConfig,随后又在 Security 内部重建 core Config;获取 token 时还会再次转换。token provider、headers、timeout、retry、response-size 和其他 canonical 配置知识因此可能在往返中丢失。SecurityClient 本身又以 Arc/Deref 壳包裹真实业务对象,interface 与 implementation 几乎等宽。使用者无法确信根 Client 的配置在 Security 叶子调用中原样生效。

Solution

让 Security client module 直接接收并保留 canonical core Config,把 ACS、security-and-compliance、token 使用和项目构造隐藏在同一 implementation。移除 SecurityConfig 往返转换和 Arc/Deref 浅壳;根 Client → security → leaf 调用链保持可用,并通过本地 HTTP adapter 验证完整配置传播。

User Stories

  1. As an OpenLark root-client user, I want Security requests to use the same canonical Config, so that configuration is not lost at a domain boundary.
  2. As an OpenLark Security user, I want custom base URLs to reach Security leaves, so that local testing and private gateways work consistently.
  3. As an OpenLark Security user, I want the configured token provider retained, so that authentication follows the same policy as other domains.
  4. As an OpenLark Security user, I want custom headers, timeout, retry, and response-size settings retained, so that root configuration applies uniformly.
  5. As an OpenLark ACS user, I want existing leaf calls and response types preserved, so that the migration does not change business behavior.
  6. As an OpenLark security-and-compliance user, I want the same configuration path as ACS, so that sibling projects cannot drift.
  7. As an OpenLark SDK maintainer, I want one configuration type inside Security, so that new core fields require no Security mirror updates.
  8. As an OpenLark SDK maintainer, I want project construction hidden behind one Security client interface, so that callers do not depend on Arc/Deref internals.
  9. As an OpenLark test author, I want to build the root Client and execute a Security leaf against wiremock, so that the highest seam proves propagation.
  10. As an OpenLark operator, I want core error context and request IDs preserved, so that Security diagnostics match other domains.
  11. As an OpenLark downstream user, I want a documented v0.18 migration path if direct SecurityConfig construction is removed, so that breaking changes are explicit.
  12. As an OpenLark maintainer, I want this work sequenced after canonical Client Config construction stabilizes, so that adjacent refactors do not conflict.

Implementation Decisions

  • The Security client module stores canonical core Config directly and does not reconstruct it from a domain mirror.
  • Root Client construction passes the same validated Config state into Security that it passes to other business domains.
  • ACS and security-and-compliance project construction, authentication behavior, and token-provider use are implementation details behind the Security client interface.
  • SecurityConfig is removed rather than expanded into another mirror of core state.
  • The Arc/Deref-only SecurityClient shell is removed or replaced by a client module with a small explicit interface and real implementation depth.
  • The root Client → security → leaf chain and existing leaf builder interfaces remain available.
  • Direct callers of the old SecurityConfig/SecurityClient constructor receive a v0.18 migration entry to canonical core Config; no compatibility shim is added for an interface that has not shipped in v0.18.
  • All core configuration behavior, including allowed custom base URL, headers, timeout, retry, token provider, response-size limits, and request options, propagates without field-by-field copying.
  • Work begins only after the refactor(client): deepen config construction and remove ClientBuildConfig #413fix(client): unify checked Client construction and remove ClientBuildConfig #416 canonical Client Config lane is stable; this issue does not modify that lane's decisions.

Testing Decisions

  • The highest test seam is root Client construction followed by a Security leaf execution against wiremock.
  • Tests cover custom base URL, injected token provider, authorization header, custom headers, timeout behavior, response-size limit, retry-relevant error propagation, and typed response extraction.
  • Separate Security-client tests cover direct canonical Config construction for users who consume the business crate independently.
  • Tests assert outgoing requests and returned results/errors; they do not inspect stored Config fields or Arc layout.
  • Existing ACS and security-and-compliance leaf contract tests remain prior art and are supplemented by one root-to-leaf propagation test.
  • Compile tests verify the documented v0.18 construction path and root meta chain.

Out of Scope

Further Notes

  • This candidate is adjacent to, but separate from, canonical Client Config construction and should be sequenced afterward.
  • The deletion test shows SecurityConfig and the Arc/Deref shell are shallow: deleting them removes conversion complexity instead of moving real behavior elsewhere; the real depth belongs in the Security client module.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified, ready for an AFK agenttype:refactor架构或接口收敛性重构

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions