Files
KART-SERVER-JAVA/.agent-harness/references/kri-common/platform-capabilities.md

5.4 KiB

KriCommon Platform Capabilities

Dependency and Configuration Boundary

  • Include the matching Spring starter for any optional Web, Security, JPA, Redis, AOP, or Swagger integration the service enables; KriCommon intentionally declares many integrations as compile-only.
  • KriCommon configuration uses only kri.*. Established groups include kri.auth.jwt, kri.auth.apikey, kri.crypto, kri.security, kri.swagger, kri.web, kri.web.mdc, kri.http.bypass, kri.redis, kri.scheduling, and kri.error.expose.
  • Read the version-matched README and configuration-property classes before setting a property; do not infer a property name or default from an older service.
  • Supply production JWT secrets, API keys, credentials, allowlists, and service URLs through the consumer's approved secret and configuration system. Never rely on library example or default secrets in production.
  • Preserve consumer override points. KriCommon's default security chain is created only when the consumer does not provide one, and overridable beans should remain explicit.
  • Adding a path to API-key allowed paths scopes where API-key authentication is attempted; it does not make the path public or grant authorization.

Optional Capabilities

  • JWT and API-key authentication integrate with Spring Security. API-key JPA preload requires Spring Data JPA; a consumer-provided claims provider can be used without JPA.
  • Common Web may register error handling, tracing/MDC, request-user resolution, enum conversion, and CORS behavior. Check for overlap before defining consumer-local equivalents.
  • Swagger support requires springdoc and defines the shared Bearer/API-key schemes and grouped paths.
  • When Swagger auto-configuration is active (kri.swagger.enabled=true, default), RequestUserContext controller arguments are ignored as request inputs globally, including their authenticated, clientIp, and userRole properties. Runtime argument resolution is 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.
  • Redis and scheduling are opt-in through their kri.*.enabled settings and matching runtime dependencies.
  • HTTP bypass targets are server-configured. Never accept an arbitrary full target URL from a frontend; retain allowed-path checks and do not forward hop-by-hop headers.
  • The external API client returns response bodies as documented, while bypass responses preserve raw bytes and target Content-Type.
  • Bypass filters all HTTP/2 pseudo headers (names starting with :) in addition to existing hop-by-hop headers; use the response status accessor instead of forwarding :status.
  • kri.http.bypass.targets.<target>.throw-on-error defaults to false. When enabled, the final response after response customizers throws public com.kri.common.feature.http.ExternalApiResponseException for non-2xx status; existing targets retain response-return behavior by default.
  • BypassResponse.requireSuccess() and ExternalApiResponse.requireSuccess() explicitly enforce the same non-2xx guard. ExternalApiClient keeps its existing default behavior and decoded getBody() API, and getBodyBytes() exposes a defensive copy of the original received bytes, including compressed and binary error bodies.
  • A response customizer's ExternalApiResponseException, including one thrown by requireSuccess(), propagates unchanged; other customizer failures keep the existing BYPASS_RESPONSE_CUSTOMIZE_FAILED behavior. Response charset parsing ignores charset-like text inside other quoted Content-Type parameters and retains the UTF-8 fallback.
  • With Spring MVC and Servlet API present and kri.web.enabled=true (default), ExternalApiErrorAutoConfiguration registers a handler for this dedicated exception before the general error advice. It relays the original status, body bytes, Content-Type, and Content-Encoding, including empty bodies; authentication, cookie, and transport headers are not relayed by the error handler. Enable this policy only for targets whose raw errors may be exposed to clients. Connection failures remain distinct from upstream HTTP errors.
  • A consumer-provided error handler bean named externalApiResponseAdvice replaces the default without importing runtime types; explicitly caught/controller-handled exceptions also remain under the consumer's control.
  • ExternalApiClient multipart requests generate their own boundary and ignore a caller-supplied Content-Type. Multipart headers and formField values use UTF-8, while file bodies preserve the supplied bytes.
  • Multipart filenames, including non-ASCII names, are sent unchanged in the quoted filename parameter as raw UTF-8. No ASCII fallback or filename* parameter is added; CR/LF rejection and quote/backslash escaping still apply.
  • JsonUtil requires the consumer's explicit ObjectMapper; shared date/time helpers define KST as Asia/Seoul and also expose UTC semantics.