Files
common-library/.agent/consumer.md

2.8 KiB

KriCommon Consumer Contract

  • Consume KriCommon as com.kri.common:starter:<approved-version> through the repository's established Gradle version-management convention.
  • Import service-facing APIs from com.kri.common.feature.*; treat com.kri.common.runtime.* as internal.
  • Prefer a shared feature or approved extension point over duplicating authentication, HTTP, error, enum, Excel, Redis, JSON, date/time, JPA, crypto, or utility behavior locally.
  • For HTTP/2 header safety and original upstream error propagation, use the shared HTTP/bypass features documented in the routed platform-capabilities reference instead of implementing consumer-local header filters and raw-response exception handlers.
  • Response customizers may call requireSuccess(); its upstream exception propagates unchanged. Response charset parsing ignores charset-like text inside other quoted header parameters.
  • When Swagger auto-configuration is active, RequestUserContext controller arguments are excluded from request input documentation; server-side authentication and client IP injection remain unchanged.
  • RequestUserContextProvider is a public injectable API for resolving the same request identity and client IP used by controller arguments. Its default registration requires Web integration and JwtService; a consumer provider overrides it. Existing principal/details/verified-Bearer fallback, empty-context behavior, resolver overrides and the JwtService resolver constructor remain unchanged. The provider does not enforce authentication or business authorization.
  • ExcelMapper's Path-based readStreaming and readHeaderStreaming use PackageAccess.READ, preserving source bytes, size, and modification time, including repeated reads and callback failures. Read-only files are supported, and file handles are released on success or failure; option validation, exception handling, and SAX streaming remain unchanged.
  • Do not modify KriCommon or another consumer repository unless it is explicitly included in the approved task scope.

Required Shared References

Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.

Task scope Required reference
Dependency, configuration, security, Web, Swagger, Redis, scheduling, HTTP, JSON, or date/time behavior .agent-harness/references/kri-common/platform-capabilities.md
Encryption, hashing, key material, or legacy crypto interoperability .agent-harness/references/kri-common/crypto-contract.md
KriCommon version upgrade or consumer verification .agent-harness/references/kri-common/upgrade-and-verification.md

If a task spans multiple scopes, read every matching reference. Generated files under .agent-harness/references/ are read-only copies; edit KriCommon's .agent/consumer.md or .agent/consumer-references/ and recompose instead.