37 lines
5.4 KiB
Markdown
37 lines
5.4 KiB
Markdown
<!--
|
|
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
|
|
Contract: kri-common
|
|
Source: .agent/consumer-references/platform-capabilities.md
|
|
-->
|
|
|
|
# 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.
|