refactor: 백엔드 리펙토링 진행 중

This commit is contained in:
DongHyeonka
2026-09-25 17:57:07 +09:00
parent fe80bb3ff3
commit fcddab7e2a
7518 changed files with 3217541 additions and 21259 deletions
@@ -11,17 +11,6 @@ on:
required: true
default: false
type: boolean
# AwsS3DirectTransferQualificationTest requires a second, separate authority
# (OBJECT_STORAGE_AWS_DIRECT_MUTATION_ENABLED) before the direct-transfer lane may run, and
# the job never supplied it. objectStorageAwsQualificationTest is a strict qualification task
# that requires both of its classes, so the lane could not be run to a pass from any input:
# dispatching it always failed on the missing variable. The authority now exists as its own
# input rather than as a constant, which is what "separate" was supposed to mean.
run_protected_aws_direct_mutation:
description: Also authorize the direct-transfer mutation lane against the sandbox bucket
required: true
default: false
type: boolean
permissions:
contents: read
@@ -53,12 +42,10 @@ jobs:
if: >-
github.event_name == 'workflow_dispatch'
&& inputs.run_protected_aws
&& inputs.run_protected_aws_direct_mutation
environment: object-storage-aws-qualification
runs-on: ubuntu-latest
env:
OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED: "true"
OBJECT_STORAGE_AWS_DIRECT_MUTATION_ENABLED: ${{ inputs.run_protected_aws_direct_mutation }}
OBJECT_STORAGE_AWS_BUCKET: ${{ secrets.OBJECT_STORAGE_AWS_BUCKET }}
OBJECT_STORAGE_AWS_REGION: ${{ secrets.OBJECT_STORAGE_AWS_REGION }}
OBJECT_STORAGE_AWS_EXPECTED_OWNER: ${{ secrets.OBJECT_STORAGE_AWS_EXPECTED_OWNER }}
+3 -3
View File
@@ -196,7 +196,7 @@ jobs:
strategy:
fail-fast: false
matrix:
transport: [apache, jdk, reactor]
transport: [apache, jdk]
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
@@ -209,8 +209,8 @@ jobs:
--stacktrace
# Only the Spring 7.0 lane. httpClientSecurityTest, httpClientBlockHoundTest and
# spring62ApiSurfaceScan used to run here too; all three are `dependsOn` of this leaf's `check`
# Only the Spring 7.0 lane. httpClientSecurityTest and spring62ApiSurfaceScan used to run here
# too; both are `dependsOn` of this leaf's `check`
# (src/adapter/outbound/httpclient/build.gradle), so ci-quality-gates.yml already ran them on the
# same pull request. spring70CompatibilityTest is deliberately outside `check` and is what is left.
httpclient-security-and-compatibility:
-1
View File
@@ -177,7 +177,6 @@ jobs:
:adapter:outbound:httpclient:spring70CompatibilityTest
:adapter:outbound:httpclient:httpClientStableContractTest
:adapter:outbound:httpclient:httpClientSecurityTest
:adapter:outbound:httpclient:httpClientBlockHoundTest
:adapter:outbound:httpclient:httpClientFailureInjectionTest
:adapter:outbound:httpclient:httpClientPerformanceTest
--stacktrace
@@ -0,0 +1,25 @@
[ 17161ms] [WARNING] [GSI_LOGGER]: Your client application uses one of the Google One Tap prompt UI status methods that may stop functioning when FedCM becomes mandatory. Refer to the migration guide to update your code accordingly and opt-in to FedCM to test your changes. Learn more: https://developers.google.com/identity/gsi/web/guides/fedcm-migration?s=dc#display_moment and https://developers.google.com/identity/gsi/web/guides/fedcm-migration?s=dc#skipped_moment @ https://accounts.google.com/gsi/client:86
[ 17165ms] [ERROR] Not signed in with the identity provider. @ https://chatgpt.com/:0
[ 21046ms] [ERROR] [GSI_LOGGER]: FedCM get() rejects with NetworkError: Error retrieving a token. @ https://accounts.google.com/gsi/client:87
[ 1332529ms] ScopeDisposedError: Signal scope "application-composer" has been disposed.
at J (https://chatgpt.com/unauth-mweb/assets/octane-signals-engine-CuIUeV7M.js:1:17199)
at q.subscribe (https://chatgpt.com/unauth-mweb/assets/octane-signals-engine-CuIUeV7M.js:1:17022)
at Object.subscribe (https://chatgpt.com/unauth-mweb/assets/native-composer-submit-state-Cz1ZZwna.js:2:4302)
at Object.ut [as adopt] (https://chatgpt.com/unauth-mweb/assets/octane-signal-hydration-DuI8AKjg.js:1:35794)
at y (https://chatgpt.com/unauth-mweb/assets/native-composer-submit-state-Cz1ZZwna.js:2:2597)
at d (https://chatgpt.com/unauth-mweb/assets/native-composer-submit-state-Cz1ZZwna.js:2:4611)
at Object.setApplicationOwned (https://chatgpt.com/unauth-mweb/assets/native-composer-submit-state-Cz1ZZwna.js:2:5251)
at Object.setApplicationOwned (https://chatgpt.com/unauth-mweb/assets/octane-shell-shared-CUJ5XASS.js:1:103586)
at https://chatgpt.com/unauth-mweb/assets/application-composer-BlokDSOr.js:2:2696
at ye (https://chatgpt.com/unauth-mweb/assets/octane-signals-engine-CuIUeV7M.js:1:2669)
[ 1332530ms] ScopeDisposedError: Signal scope "application-composer" has been disposed.
at J (https://chatgpt.com/unauth-mweb/assets/octane-signals-engine-CuIUeV7M.js:1:17199)
at $.own (https://chatgpt.com/unauth-mweb/assets/octane-signals-engine-CuIUeV7M.js:1:30868)
at $.get (https://chatgpt.com/unauth-mweb/assets/octane-signals-engine-CuIUeV7M.js:1:31019)
at Gs.e [as body] (https://chatgpt.com/unauth-mweb/assets/application-presentation-runtime-ChfLzfu-.js:2:239588)
at tc (https://chatgpt.com/unauth-mweb/assets/runtime-PyVvaJ0Y.js:1:75262)
at K (https://chatgpt.com/unauth-mweb/assets/runtime-PyVvaJ0Y.js:1:72336)
at https://chatgpt.com/unauth-mweb/assets/runtime-PyVvaJ0Y.js:1:72216
at ye (https://chatgpt.com/unauth-mweb/assets/octane-signals-engine-CuIUeV7M.js:1:2669)
at K (https://chatgpt.com/unauth-mweb/assets/runtime-PyVvaJ0Y.js:1:72208)
at Ao (https://chatgpt.com/unauth-mweb/assets/runtime-PyVvaJ0Y.js:1:55581)
@@ -0,0 +1,91 @@
- generic [ref=e1]:
- main "ChatGPT" [ref=e4]:
- generic [ref=e8]:
- complementary "Sidebar" [ref=e9]:
- generic [ref=e11]:
- generic [ref=e12]:
- img "ChatGPT logo" [ref=e13]
- button "Close sidebar" [expanded] [ref=e16] [cursor=pointer]
- link "New chat" [ref=e20] [cursor=pointer]:
- /url: /?noauth_recent_chat_failed=1
- navigation "Sidebar" [ref=e27]:
- generic [ref=e28]:
- button "Search chats" [ref=e29] [cursor=pointer]
- link "Images" [ref=e34] [cursor=pointer]:
- /url: /images
- link "Plugins" [ref=e40] [cursor=pointer]:
- /url: https://chatgpt.com/plugins
- button "Deep research" [ref=e46] [cursor=pointer]
- generic [ref=e51]:
- link "See plans and pricing" [ref=e52] [cursor=pointer]:
- /url: https://openai.com/chatgpt/pricing/
- button "Settings" [ref=e61] [cursor=pointer]
- link "OpenAI Help" [ref=e66] [cursor=pointer]:
- /url: https://help.openai.com
- generic [ref=e67]: Help
- region [ref=e75]:
- heading "Get responses tailored to you" [level=2] [ref=e76]
- paragraph [ref=e77]: Log in to get answers based on saved chats, plus create images and upload files.
- button "Log in" [ref=e78] [cursor=pointer]
- generic [ref=e81]:
- generic [ref=e83]:
- generic [ref=e84]: ChatGPT
- generic [ref=e90]:
- button "Log in" [ref=e91] [cursor=pointer]
- button "Sign up for free" [ref=e92] [cursor=pointer]
- region "Conversation" [ref=e94]:
- region "Conversation chat-2c3fe94d-e038-46b5-9622-b7537c001bd1" [ref=e95]:
- generic [ref=e97]:
- generic:
- list "Conversation"
- generic:
- generic:
- generic [ref=e99]:
- heading "Where should we begin?" [level=1] [ref=e100]
- generic [ref=e105]:
- button [aria-hidden] [ref=e106]
- button [aria-hidden] [ref=e107]
- button [aria-hidden] [ref=e108]
- generic [ref=e110]:
- button "Add files and more" [ref=e112] [cursor=pointer]
- generic [ref=e116]:
- generic [ref=e117]: Chat with ChatGPT
- textbox "Chat with ChatGPT" [ref=e120]:
- /placeholder: Ask ChatGPT
- status [ref=e122]
- generic [ref=e123]:
- button "Start dictation" [ref=e124] [cursor=pointer]
- button "Send message" [disabled] [ref=e128]
- button "What can you do?" [ref=e132] [cursor=pointer]
- paragraph [ref=e135]:
- generic [ref=e136]:
- text: ChatGPT is AI. By using it, you agree to our
- link "Terms" [ref=e137] [cursor=pointer]:
- /url: https://openai.com/terms
- text: "&"
- link "Privacy Policy" [ref=e138] [cursor=pointer]:
- /url: https://openai.com/privacy
- text: and its
- link "Korea addendum" [ref=e139] [cursor=pointer]:
- /url: https://openai.com/ko/policies/kr-privacy-policy-addendum
- text: . Chats may be reviewed and used to improve our AI models.
- link "Learn more about how your data is used to improve AI models" [ref=e140] [cursor=pointer]:
- /url: https://help.openai.com/en/articles/5722486-how-your-data-is-used-to-improve-model-performance
- text: Learn more
- dialog [ref=e142]:
- generic [ref=e143]:
- button "Close" [active] [ref=e145] [cursor=pointer]
- heading "We use cookies" [level=1] [ref=e148]
- paragraph [ref=e149]:
- text: Cookies help this site function, measure usage, and support marketing.
- link "Manage" [ref=e150] [cursor=pointer]:
- /url: /privacy?returnTo=%2F
- text: your cookie preferences anytime. Learn more about our
- link "cookie policy" [ref=e151] [cursor=pointer]:
- /url: https://openai.com/policies/cookie-policy/
- text: .
- generic [ref=e152]:
- button "Accept all" [ref=e154] [cursor=pointer]
- button "Reject non-essential" [ref=e156] [cursor=pointer]
- link "Cookie preferences" [ref=e157] [cursor=pointer]:
- /url: /privacy?returnTo=%2F
@@ -0,0 +1,80 @@
- main "ChatGPT" [ref=e4]:
- generic [ref=e8]:
- complementary "Sidebar" [ref=e9]:
- generic [ref=e11]:
- generic [ref=e12]:
- img "ChatGPT logo" [ref=e13]
- button "Close sidebar" [expanded] [ref=e16] [cursor=pointer]
- link "New chat" [ref=e20] [cursor=pointer]:
- /url: /?noauth_recent_chat_failed=1
- navigation "Sidebar" [ref=e27]:
- generic [ref=e28]:
- button "Search chats" [ref=e29] [cursor=pointer]
- link "Images" [ref=e34] [cursor=pointer]:
- /url: /images
- link "Plugins" [ref=e40] [cursor=pointer]:
- /url: https://chatgpt.com/plugins
- button "Deep research" [expanded] [ref=e46] [cursor=pointer]
- dialog [ref=e159]:
- generic [ref=e161]:
- paragraph [ref=e162]: Turn questions into research
- paragraph [ref=e163]: Log in to run multi-step research, compare sources, and save cited reports to revisit later.
- generic [ref=e164]:
- button "Log in" [ref=e165] [cursor=pointer]
- button "Sign up for free" [ref=e166] [cursor=pointer]
- generic [ref=e51]:
- link "See plans and pricing" [ref=e52] [cursor=pointer]:
- /url: https://openai.com/chatgpt/pricing/
- button "Settings" [ref=e61] [cursor=pointer]
- link "OpenAI Help" [ref=e66] [cursor=pointer]:
- /url: https://help.openai.com
- generic [ref=e67]: Help
- region [ref=e75]:
- heading "Get responses tailored to you" [level=2] [ref=e76]
- paragraph [ref=e77]: Log in to get answers based on saved chats, plus create images and upload files.
- button "Log in" [ref=e78] [cursor=pointer]
- generic [ref=e81]:
- generic [ref=e83]:
- button "ChatGPT" [ref=e158] [cursor=pointer]
- generic [ref=e90]:
- button "Log in" [ref=e91] [cursor=pointer]
- button "Sign up for free" [ref=e92] [cursor=pointer]
- region "Conversation" [ref=e94]:
- region "Conversation chat-2c3fe94d-e038-46b5-9622-b7537c001bd1" [ref=e95]:
- generic [ref=e97]:
- generic:
- list "Conversation"
- generic:
- generic:
- generic [ref=e99]:
- heading "Where should we begin?" [level=1] [ref=e100]
- generic [ref=e105]:
- button [aria-hidden] [ref=e106]
- button [aria-hidden] [ref=e107]
- button [aria-hidden] [ref=e108]
- generic [ref=e110]:
- button "Add files and more" [ref=e112] [cursor=pointer]
- generic [ref=e116]:
- generic [ref=e117]: Chat with ChatGPT
- textbox "Chat with ChatGPT" [ref=e120]:
- /placeholder: Ask ChatGPT
- status [ref=e122]
- generic [ref=e123]:
- button "Start dictation" [ref=e124] [cursor=pointer]
- button "Send message" [disabled] [ref=e128]
- button "What can you do?" [ref=e132] [cursor=pointer]
- paragraph [ref=e135]:
- generic [ref=e136]:
- text: ChatGPT is AI. By using it, you agree to our
- link "Terms" [ref=e137] [cursor=pointer]:
- /url: https://openai.com/terms
- text: "&"
- link "Privacy Policy" [ref=e138] [cursor=pointer]:
- /url: https://openai.com/privacy
- text: and its
- link "Korea addendum" [ref=e139] [cursor=pointer]:
- /url: https://openai.com/ko/policies/kr-privacy-policy-addendum
- text: . Chats may be reviewed and used to improve our AI models.
- link "Learn more about how your data is used to improve AI models" [ref=e140] [cursor=pointer]:
- /url: https://help.openai.com/en/articles/5722486-how-your-data-is-used-to-improve-model-performance
- text: Learn more
Binary file not shown.

After

Width:  |  Height:  |  Size: 84 KiB

+1 -6
View File
@@ -5,7 +5,7 @@
# split into capability artifacts.
# Update only after review with:
# ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange
# types: 168
# types: 163
dev.caskeleton.adapter.inbound.graphql.HealthGraphqlController
dev.caskeleton.adapter.inbound.graphql.api.GraphQlClientProfile
dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationId
@@ -20,7 +20,6 @@ dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformSettings
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformStartupValidator
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRetiredSafetyAxis
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRootAutoConfiguration
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRuntimeTransport
dev.caskeleton.adapter.inbound.graphql.context.ActorRef
dev.caskeleton.adapter.inbound.graphql.context.GraphQlCommandAttribution
dev.caskeleton.adapter.inbound.graphql.context.GraphQlDeadline
@@ -67,8 +66,6 @@ dev.caskeleton.adapter.inbound.graphql.execution.GraphQlAnonymousOperationExcept
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipeline
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineValidator
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfileException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionStage
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlOperationSelection
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheKey
@@ -132,8 +129,6 @@ dev.caskeleton.adapter.inbound.graphql.pagination.HmacGraphQlCursorCodec
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlClientPolicy
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlOperationType
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBatchLoaderRegistrar
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBlockingBridge
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBlockingBridgeFullException
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlCostBudgetHandler
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDataFetcherExceptionResolver
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDocumentAuthorizationHandler
@@ -29,7 +29,7 @@ All capabilities are off by default. Flags are `ca-skeleton.grpc.advanced.<capab
| Custom load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — |
| Proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane |
| gRPC-Web | `grpc-web` | `ADVANCED_STABLE` | gRPC-Web proxy |
| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE` | Servlet container |
| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE` (flag only; no Servlet transport code since 2026-09-25) | Servlet container |
| Spring Integration bridge | `integration-bridge` | `ADVANCED_STABLE` | — |
| Reactor adapter | `reactor` | `ADVANCED_STABLE` | — |
| Kotlin coroutine / Flow | `kotlin` | `ADVANCED_STABLE` | Kotlin toolchain |
@@ -42,14 +42,12 @@ implemented and tested in this repository. What no capability has is evidence fr
`GrpcAdvancedPromotionEvidence` for each one is empty, and no promotion has been granted.
**Four capabilities cannot produce meaningful evidence here at all**, because the infrastructure they
need is absent. `GrpcAdvancedInfrastructureTestkit.missingInfrastructure` names them, and a suite that
runs without its infrastructure passes and establishes nothing.
need is absent (gRPC-Web proxy, Servlet container, xDS control plane, Kotlin toolchain), and a suite
that runs without its infrastructure passes and establishes nothing.
**Kotlin is the sharpest case.** This repository has no Kotlin toolchain, so
`GrpcKotlinCompatibilityGate.supportableHere()` returns false and always will until one exists. The
four contract requirements — one schema source shared with Java, coroutine cancellation propagated,
Flow backpressure inside the Stable buffer bounds, platform evidence types preserved — are checkable
without a toolchain and are checked. The compile lane is not.
**Kotlin is the sharpest case.** This repository has no Kotlin toolchain, so Kotlin is not
supportable here until one exists. Only the Java-side coroutine cancellation bridge
(`GrpcCoroutineContextBridge`) is implemented and tested; there is no compile lane.
## Promotion thresholds
+11 -2
View File
@@ -52,8 +52,17 @@ opens nothing.
## Authorization
Every public operation calls the injected `FileAccessPolicy` before any quota reservation or storage
mutation, so a denial leaves no record, no reservation, and no staging object. Startup refuses to
run a production profile with an allow-all policy.
mutation, so a denial leaves no record, no reservation, and no staging object. Finalize is
authorized as `FINALIZE`, and management-plane reads as `ADMIN_READ`. Startup refuses to run a
production profile with an allow-all policy.
Each file records its owner: the principal that created it and, when the transport resolved one,
its tenant (the `tenant` subject attribute). The default role policy grants an operation on an
existing file only to its owner in the same tenant, so two callers holding the same role cannot
read, download, finalize, delete, copy or move each other's files. An admin role does not bypass
this — acting on another caller's file is what the audited management plane is for. A file created
before ownership was recorded (migration V5) has no owner and is reachable only through the
management plane. Anonymous read, when enabled, publishes every file and skips the owner check.
## Delegation
+6 -12
View File
@@ -67,8 +67,7 @@ materialise a nameless client in every deployment, which the aggregate validatio
| `base-url` | URI | — | Required for a trusted profile; no userinfo, no query |
| `allowed-hosts` | list | empty | Required in production |
| `allowed-ports` | list | empty | Compared against the effective port |
| `api` | `REST_CLIENT` \| `WEB_CLIENT` | `REST_CLIENT` | Decides blocking or reactive runtime |
| `transport` | `APACHE` \| `JDK` \| `REACTOR_NETTY` \| `JETTY` \| `SIMPLE` | `APACHE` | `SIMPLE` is rejected in production |
| `transport` | `APACHE` \| `JDK` \| `JETTY` \| `SIMPLE` | `APACHE` | `SIMPLE` is rejected in production; `JETTY` needs a deployment-registered provider |
| `protocols` | list | `HTTP_1_1` | The default transport is Apache, whose classic client is HTTP/1.1 only; a profile that wants HTTP/2 declares it together with a transport that can deliver it. `HTTP_3` requires the experimental acknowledgement |
| `experimental-acknowledgement` | string | — | Must equal `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS` |
@@ -191,9 +190,9 @@ materialise a nameless client in every deployment, which the aggregate validatio
`HOSTNAME_VERIFICATION_REQUIRED`, `PLAINTEXT_FALLBACK_FORBIDDEN`, `TLS_PROTOCOL_FORBIDDEN`,
`RETRY_BACKOFF_REQUIRED`, `MISSING_PRODUCTION_SETTING`, `DUPLICATE_CLIENT_NAME`,
`HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`, `DYNAMIC_BASE_URL_REQUIRED`,
`DYNAMIC_TARGET_PROXY_UNSUPPORTED`, `REACTIVE_AUTHENTICATION_UNSUPPORTED`,
`DYNAMIC_TARGET_PROXY_UNSUPPORTED`,
`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`, `POOL_ROUTE_EXCEEDS_TOTAL`,
`TLS_PROTOCOL_SET_REQUIRED`, `REACTIVE_REDIRECT_UNSUPPORTED`,
`TLS_PROTOCOL_SET_REQUIRED`,
`RETRY_POLICY_CONTRADICTS_ATTEMPTS`, `FULL_URL_RECORDING_FORBIDDEN`, `BODY_LOGGING_FORBIDDEN`,
`DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED`, `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED`.
@@ -205,16 +204,11 @@ unaffected — only a deliberate, unmet request fails.
Three of these are about a guarantee that used to be silently unmet rather than refused:
- `HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED` — declaring `protocols: [HTTP_2]` alone states that HTTP/2
is required. Only `REACTOR_NETTY` can be configured to offer H2 and nothing else; the JDK client
treats it as a preference and negotiates HTTP/1.1, and Apache's classic client is HTTP/1.1 only.
- `POOL_ROUTE_EXCEEDS_TOTAL` — a per-route ceiling above the total is incoherent, and on Reactor,
where the per-route knob is the only one that exists, it silently becomes the effective limit.
is required. No transport can be configured to offer H2 and nothing else; the JDK client treats it
as a preference and negotiates HTTP/1.1, and Apache's classic client is HTTP/1.1 only.
- `POOL_ROUTE_EXCEEDS_TOTAL` — a per-route ceiling above the total is incoherent.
- `TLS_PROTOCOL_SET_REQUIRED` — an empty `tls.protocols` used to pass and then let the JVM choose,
so emptying the list to "tighten" a profile loosened it.
- `REACTIVE_REDIRECT_UNSUPPORTED` — engine redirect following is disabled on every transport and
only the blocking stack has a coordinator that follows hops with per-hop re-validation. A
`WEB_CLIENT` profile with `redirect.enabled=true` did not follow redirects; the caller received the
3xx as an ordinary response. Refused until the reactive coordinator exists.
- `RETRY_POLICY_CONTRADICTS_ATTEMPTS` — `retry.policy` was read by nothing on the execution path, so
the actuator could report `none` for a profile retrying three times. The two settings must now
agree: `policy: none` requires `max-attempts: 1`, and any other policy requires more than one.
-2
View File
@@ -39,8 +39,6 @@ fields:
env: APP_HTTPCLIENT_CLIENTS_N_ALLOWED_HOSTS_M
- field: clients[N].allowed-ports[M]
env: APP_HTTPCLIENT_CLIENTS_N_ALLOWED_PORTS_M
- field: clients[N].api
env: APP_HTTPCLIENT_CLIENTS_N_API
- field: clients[N].transport
env: APP_HTTPCLIENT_CLIENTS_N_TRANSPORT
- field: clients[N].protocols[M]
+2 -2
View File
@@ -79,8 +79,8 @@ a mesh retry policy changes.
## Error model
Every outbound failure is one of these stable types. The type is derived from the classified failure
category, not from whatever the engine happened to throw, so it means the same thing on Apache, JDK,
and Reactor Netty. Each carries `HttpFailureMetadata`: client, operation, method, URI **template**,
category, not from whatever the engine happened to throw, so it means the same thing on Apache and
JDK. Each carries `HttpFailureMetadata`: client, operation, method, URI **template**,
evidence, replayability, stage, retryability, attempt, elapsed, remaining deadline, status, trace id
— and nothing else.
-1
View File
@@ -29,7 +29,6 @@ never silently degrades into a pass.
| `RetryStormBudgetTest` | 10 000 logical calls against a failing upstream produce at most 11 000 physical attempts at a 10 % budget | structural |
| `LargeBodyResourceTest` | a 32 MiB streaming download consumes every byte without buffering the payload on the heap | structural + machine-dependent heap bound |
| `PoolSaturationPerformanceTest` | 24 concurrent calls against a 4-connection pool all reach a terminal outcome; none hang | structural |
| `Http2StreamSaturationTest` | 32 concurrent reactive streams share a 2-connection pool and complete | structural |
| `OAuthRefreshContentionTest` | 100 genuinely concurrent callers produce exactly one token request | structural |
| `RuntimeRotationDrainTest` | 50 rotations close all 50 retired generations and leave no drain thread | structural |
+1 -3
View File
@@ -9,7 +9,6 @@ cd src
./gradlew :adapter:outbound:httpclient:test --console=plain
./gradlew :adapter:outbound:httpclient:httpClientStableContractTest --console=plain
./gradlew :adapter:outbound:httpclient:httpClientSecurityTest --console=plain
./gradlew :adapter:outbound:httpclient:httpClientBlockHoundTest --console=plain
./gradlew :adapter:outbound:httpclient:spring62CompatibilityTest --console=plain
./gradlew :adapter:outbound:httpclient:spring70CompatibilityTest --console=plain
./gradlew :adapter:outbound:httpclient:httpClientFailureInjectionTest --console=plain # needs Docker
@@ -24,7 +23,7 @@ python3 ../scripts/verify-httpclient-docs.py
- [ ] Typed clients are the default entry point; H2 and H3 are separately authorised.
- [ ] H1–H4 cannot bypass timeout, host, TLS, auth, size, or observation policy.
- [ ] Apache, JDK, and Reactor produce identical result and exception metadata.
- [ ] Apache and JDK produce identical result and exception metadata.
- [ ] Pool, DNS, connect, TLS, and retry backoff all fit inside the effective deadline.
- [ ] Every extra attempt is explained by idempotency, replayability, evidence, deadline, and budget.
- [ ] Non-idempotent `SENT_NO_RESPONSE` surfaces as `HttpAmbiguousExecutionException`.
@@ -33,7 +32,6 @@ python3 ../scripts/verify-httpclient-docs.py
- [ ] Trust-all and hostname-verification bypass fail at startup.
- [ ] Canonicalisation, DNS/IP validation, redirect revalidation, and egress control all pass.
- [ ] No transparent retry occurs after the first delivered byte.
- [ ] No platform code blocks a Reactor event loop, proven by a BlockHound self-check.
- [ ] The negotiated wire protocol matches what the support matrix claims per transport.
- [ ] Logical calls and attempts are separate metrics with no forbidden label.
- [ ] DNS, pool, TLS, reset, partial response, and HTTP/2 GOAWAY are reproducible.
+2 -2
View File
@@ -48,8 +48,8 @@ Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbo
| `httpclient-auth` | `…httpclient.auth` | `…outbound.httpclient.auth` |
| `httpclient-security` | `…httpclient.security` | `…outbound.httpclient.security` |
| `httpclient-observability` | `…httpclient.observation` | `…outbound.httpclient.observation` |
| `httpclient-transport-reactor-netty` | `…httpclient.reactor` | `…outbound.httpclient.reactor` |
| `httpclient-webclient` | `…httpclient.webclient` | `…outbound.httpclient.webclient` |
| `httpclient-transport-reactor-netty` | `…httpclient.reactor` | removed (decision 9, 2026-09-25: blocking only) |
| `httpclient-webclient` | `…httpclient.webclient` | removed (decision 9, 2026-09-25: blocking only) |
| `httpclient-service-client` | `…httpclient.service` | `…outbound.httpclient.service` |
| `httpclient-dynamic-target` | `…httpclient.dynamic` | `…outbound.httpclient.dynamic` |
| `httpclient-jetty-http3-experimental` | `…httpclient.http3` | `…outbound.httpclient.http3` |
+13 -29
View File
@@ -2,13 +2,10 @@
## Response lifecycle
A blocking streaming download returns `BlockingStreamingResponse`, never a bare `InputStream`.
Closing is idempotent and always releases the connection — after a full read, a partial read, a
decode failure, or a size rejection. The status is validated before any body byte is delivered, so a
failed download never becomes a half-consumed stream the caller has to reason about.
A reactive download emits bounded `DataBuffer` values. Buffers are released on completion, error,
and cancellation; a dropped buffer is direct memory nobody returns.
A streaming download returns `BlockingStreamingResponse`, never a bare `InputStream`. Closing is
idempotent and always releases the connection — after a full read, a partial read, a decode failure,
or a size rejection. The status is validated before any body byte is delivered, so a failed download
never becomes a half-consumed stream the caller has to reason about.
Wire bytes and decoded bytes are bounded independently, because a compressed payload passes a wire
check and then expands. Limits are enforced while reading, not after buffering.
@@ -19,34 +16,21 @@ check and then expands. Limits are enforced while reading, not after buffering.
response headers received
→ nothing delivered yet
→ a read-only operation may still be retried
→ first InputStream read or first Flux onNext
→ transparent retry is permanently disabled
→ the response is handed to the caller
→ transparent retry is no longer possible
```
`FirstByteDeliveryGuard` latches once and never resets. Retrying after delivery would replay a
stream the caller has already partly consumed, producing duplicated or reordered data that no
downstream code can detect.
Retrying after delivery would replay a stream the caller has already partly consumed, producing
duplicated or reordered data that no downstream code can detect. The streaming gateway hands out
the response only after the attempt has finished, so there is no retry left to run once the caller
reads.
## Request bodies
A reopenable body is opened once per attempt, which is what makes it replayable; reusing the
previous stream would silently send an empty body on the retry. A one-shot stream or publisher
instance is never retried. `ReactiveBodySource` takes a publisher *factory* rather than a publisher
so a reactive body can honestly declare itself replayable.
A multipart body is exactly as replayable as its weakest part.
previous stream would silently send an empty body on the retry. A one-shot stream is never retried.
## Server-sent events
Three budgets stay separate:
- `setupDeadline` — establishing the stream
- `streamingIdleTimeout` — silence once it is open
- `maxStreamDuration` — optional total lifetime
Applying the request-shaped `total-call` timeout to an SSE subscription would terminate a perfectly
healthy stream on schedule, so it is not applied.
`Last-Event-ID` is opt-in. Replaying from an id is only correct when the producer guarantees it;
sending it blindly can skip or duplicate events. Reconnects consume the retry budget like any other
physical attempt, and cancelling the subscription stops both the stream and any pending reconnect.
The platform has no server-sent-event client. It was part of the reactive stack, which was removed
(decision 9, 2026-09-25): the platform runs blocking calls on the caller's thread only.
+15 -15
View File
@@ -7,8 +7,7 @@ proves it; anything the suite cannot prove is **Experimental** and says so.
| API | Grade | Role | Constraint |
|---|---|---|---|
| `RestClient` | Stable | Blocking execution | Bounded concurrency and an effective deadline are mandatory |
| `WebClient` | Stable | Reactive, streaming, SSE | No blocking work on the event loop |
| `RestClient` | Stable | Blocking execution (the only execution model) | Bounded concurrency and an effective deadline are mandatory |
| HTTP Service Client (`@HttpExchange`) | Default | Declarative typed client | Operation metadata is mandatory |
| Generic Exchange (H2) | Restricted | Dynamic method, path, body | Base URL and policy are immutable |
| Dynamic Target (H3) | Restricted | User-supplied URL | Separate SSRF policy; inherits no credential |
@@ -16,13 +15,16 @@ proves it; anything the suite cannot prove is **Experimental** and says so.
## Transports
| Transport | Blocking | Reactive | HTTP/1.1 | HTTP/2 | HTTP/3 | Grade | Verified by |
|---|---:|---:|---:|---:|---:|---|---|
| Apache HttpClient 5 (classic) | yes | no | yes | **no** | no | Stable (blocking default) | `httpClientStableContractTest`, `NegotiatedProtocolContractTest` |
| JDK HttpClient | yes | `sendAsync` | yes | yes (TLS/ALPN) | no | Stable (lightweight, blocking HTTP/2) | `NegotiatedProtocolContractTest` |
| Reactor Netty | limited | yes | yes | yes | experimental | Stable (reactive default) | `NegotiatedProtocolContractTest` |
| Jetty | facade | yes | yes | yes | yes | **Experimental** | `Http3OptInTest` only |
| Simple request factory | yes | no | limited | no | no | Local test only | rejected in production by `ClientProfileValidator` |
The platform is blocking only (decision 9, 2026-09-25): every call runs on the caller's thread —
a virtual thread in this template — through `RestClient`. There is no reactive execution path, no
`WebClient`, and no Reactor Netty transport.
| Transport | HTTP/1.1 | HTTP/2 | HTTP/3 | Grade | Verified by |
|---|---:|---:|---:|---|---|
| Apache HttpClient 5 (classic) | yes | **no** | no | Stable (default) | `httpClientStableContractTest`, `NegotiatedProtocolContractTest` |
| JDK HttpClient | yes | yes (TLS/ALPN) | no | Stable (lightweight, HTTP/2) | `NegotiatedProtocolContractTest` |
| Jetty | yes | yes | yes | **Experimental** | `Http3OptInTest` only |
| Simple request factory | limited | no | no | Local test only | rejected in production by `ClientProfileValidator` |
### Apache is HTTP/1.1 here, and why
@@ -33,8 +35,9 @@ classic client fails outright against a prior-knowledge h2c server.
So `ApacheBlockingTransportProvider.capabilities()` declares HTTP/1.1, and a profile that pairs
Apache with `HTTP_2` is rejected at startup instead of quietly running HTTP/1.1 while this table
claims otherwise. **Blocking HTTP/2 is served by the JDK transport**; reactive HTTP/2 by Reactor
Netty. Both are measured from the client after a real TLS handshake, not read from configuration.
claims otherwise. **HTTP/2 is served by the JDK transport**, measured from the client after a real
TLS handshake, not read from configuration. No transport can be restricted to HTTP/2 alone, so a
profile that declares only `HTTP_2` is refused (`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`).
The JDK transport declares `routeScopedPool=false`, `boundedPendingAcquireQueue=false`, and
`dynamicTargetStable=false`. A profile that needs any of those is rejected at startup rather than
@@ -45,7 +48,7 @@ gives route-scoped pooling and Dynamic Target pinning, JDK gives HTTP/2.
| Capability | Gate |
|---|---|
| Dynamic Target (H3) | Apache and Reactor Netty only; JDK and Jetty are rejected |
| Dynamic Target (H3) | Apache only; JDK and Jetty are rejected |
| HTTP/3 | `experimentalAcknowledgement` must equal `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS` |
| Cross-origin redirect | opt-in per profile; credentials are stripped on the hop |
| Retry | evidence-based; never enabled by HTTP method alone |
@@ -58,10 +61,8 @@ gives route-scoped pooling and Dynamic Target pinning, JDK gives HTTP/2.
| Spring Framework 6.2 API surface | every PR | required | `spring62CompatibilityTest` |
| Apache HC5 + RestClient | every PR | required | `httpClientStableContractTest -Phttpclient.contract.transports=apache` |
| JDK HttpClient + RestClient | every PR | required | `httpClientStableContractTest -Phttpclient.contract.transports=jdk` |
| Reactor Netty + WebClient | every PR | required | `httpClientStableContractTest -Phttpclient.contract.transports=reactor` |
| SSRF / cardinality suite | every PR | required | `httpClientSecurityTest` |
| Toxiproxy fault suite | nightly, release | required | `httpClientFailureInjectionTest` |
| Event-loop blocking (BlockHound) | every PR | required | `httpClientBlockHoundTest` |
| Performance certification | nightly, release | required | `httpClientPerformanceTest -Pperformance.assertions.enabled=true` |
| Jetty HTTP/3 | nightly | Experimental, non-blocking | `test -Phttp3.tests.enabled=true` |
@@ -82,6 +83,5 @@ Stated so the matrix is read as a measurement rather than an aspiration.
| Gap | Why | What is proven instead |
|---|---|---|
| HTTP/2 frame injection (`REFUSED_STREAM`, arbitrary `GOAWAY`) | The fixture server exposes no frame-level control, and a purpose-built h2 server is a larger dependency than the guarantee is worth here | `Http2EvidenceMapperTest` proves the frame → evidence mapping, and `NegotiatedProtocolContractTest` proves h2 is really negotiated |
| Netty buffer-leak detection | Netty reports a leak when an unreferenced buffer is collected, which the suite does not force | `NettyLeakDetectionExtension` asserts the PARANOID detector is live and reports nothing; explicit release assertions in the streaming suites are the primary guarantee |
| Spring 6.2 runtime | This repository's Boot 4.0 baseline pins Spring 7 | `spring62CompatibilityTest` confines the common packages to the 6.2 API surface |
| Performance latency baseline | Numbers measured on a build agent are not a certification | `httpClientPerformanceTest` asserts structural bounds unconditionally; latency and heap bounds run under `-Pperformance.assertions.enabled=true` |
+31 -6
View File
@@ -177,6 +177,8 @@ app:
consumer: { type: SASL_SCRAM, credential-id: kafka-consumer }
# admin은 application runtime에 설정하지 않는다
hostname-verification: true
# 사설 CA로 서명된 TLS 브로커면(tls-enabled: true일 때만):
# trust-store: { location: /etc/kafka/ca.p12, type: PKCS12, password-credential-id: kafka-truststore }
access:
publishable: [order-events]
consumable: []
@@ -191,13 +193,36 @@ app:
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
`SASL_SCRAM`·`USERNAME_PASSWORD`의 사용자 이름은 `CredentialProvider.username(credentialId)`가
준다. credential id를 사용자 이름으로 보내지 않는다. 비밀번호와 사용자 이름은 JAAS 문자열에 들어가지
않고, 연결이 인증할 때마다 provider에서 읽힌다. 그래서 provider가 만료 시각을 주는 credential은
재기동 없이 rotation된다(`security.md`).
`MUTUAL_TLS`는 클라이언트 인증서를 key store로 제출한다. `credential-id`는 key store 비밀번호를
가리킨다.
```text
producer:
type: MUTUAL_TLS
credential-id: kafka-producer-tls # key store 비밀번호
key-store: { location: /etc/kafka/producer.p12, type: PKCS12 }
```
`trust-store`를 생략하면 JVM 기본 trust store를 쓴다. 사설 CA 브로커는 `trust-store.location`
(PKCS12·JKS·PEM)과, 잠긴 store면 `password-credential-id`를 준다.
Kafka producer는 이 항목을 실제 클라이언트 설정(`security.protocol`, `sasl.mechanism`,
`sasl.jaas.config`, `ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로
조용히 넘어가지 않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나
`authentication-enabled`를 켰는데 `app.messaging.security.<broker>`가 없을 때, security 항목은
있는데 `CredentialProvider` bean이 없을 때, 같은 브로커에 맞는 항목이 둘 이상일 때.
한계: truststore/keystore 설정 키가 없어 TLS는 JVM 기본 truststore를 쓰고, `MUTUAL_TLS`는 클라이언트
인증서를 제출할 수 없다(미지원).
`sasl.jaas.config`, `sasl.client.callback.handler.class`, `ssl.truststore.*`, `ssl.keystore.*`,
`ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로 조용히 넘어가지
않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나 `authentication-enabled`를 켰는데
`app.messaging.security.<broker>`가 없을 때, security 항목은 있는데 `CredentialProvider` bean이 없을
때, 같은 브로커에 맞는 항목이 둘 이상일 때, provider가 SASL 사용자 이름을 주지 않을 때,
`MUTUAL_TLS`인데 `key-store`가 없거나 `tls-enabled`가 꺼져 있을 때, `trust-store`를 줬는데
`tls-enabled`가 꺼져 있을 때, store 파일을 열 수 없을 때.
`access.publishable`은 강제된다. security 항목이 있는 브로커의 destination은 이 목록에 있어야
publish된다. 목록 밖 publish는 `REJECTED`(`PUBLISH_FORBIDDEN`)이고, 빈 목록이면 아무것도 publish되지
않는다.
## Backpressure
+22 -6
View File
@@ -36,17 +36,30 @@ heap dump나 설정 출력에서 사용 가능한 credential이 나오지 않는
`CredentialIds`는 `bearer `, `sk-`, `-----begin`, `eyJ` 같은 접두사를 거부한다.
참조가 들어갈 자리에 secret 자체를 붙여넣는 가장 흔한 사고를 막는다.
SASL(PLAIN·SCRAM) 사용자 이름도 `CredentialProvider.username(credentialId)`가 준다. credential id는
저장소 안의 참조이지 broker가 아는 사용자 이름이 아니다. provider가 이름을 주지 않으면 기동에
실패한다.
key store·trust store는 경로만 설정에 둔다. 비밀번호는 credential id로 provider가 해석한다
(`configuration-reference.md` 보안 절).
## Rotation
`CredentialRotationPlan.isDue()`는 만료 **전에** 참이 된다.
broker가 연결을 거부하기 시작한 시점에는 이미 publish가 실패하고 consumer가 멈춰 있다.
rotation은 세대 교체다. `DefaultMessagingRuntimeRegistry.install()`이 새 세대를 원자적으로
게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다.
진행 중인 publish는 시작한 연결에서 confirm을 받는다.
Kafka SASL credential은 producer를 다시 만들지 않고 바뀐다. JAAS 설정에는 login module 이름만
있고, `KafkaCredentialCallbackHandler`가 연결이 인증할 때마다 `CredentialRuntimeRegistry`에서
사용자 이름과 비밀번호를 읽는다. registry는 provider가 준 만료 시각의 rotation lead(기본 30분)
안으로 들어오면 새로 가져오므로, 새 연결과 재인증(broker `connections.max.reauth.ms`)이 새 값을
쓴다. 만료 시각을 주지 않는 provider의 credential은 캐시된 값을 계속 쓴다.
drain deadline이 이 대기를 제한한다. 없으면 lease 하나가 새면 폐기된 credential이
무기한 열려 있고, rotation이 보안상 무의미해진다.
key store·trust store 비밀번호는 예외다. Kafka가 SSL context를 만들 때 한 번 읽으므로 바꾸려면
producer를 다시 만들어야 한다(재기동).
transport 세대 교체(`DefaultMessagingRuntimeRegistry.install()`)는 transport 자체를 바꿀 때 쓴다.
새 세대를 원자적으로 게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다.
drain deadline이 이 대기를 제한한다.
## Header
@@ -66,10 +79,13 @@ logical identity가 호출자 제어가 된다.
## ACL
`DestinationAccessValidator`가 broker ACL **이전에** 검사한다.
publisher가 broker ACL **이전에** 검사한다(`PUBLISH_FORBIDDEN`).
broker ACL 거부는 애플리케이션 컨텍스트가 없는 연결 수준 오류로 도착하므로
"어느 모듈이 어디에 publish하려 했는가"가 조사 대상이 된다.
publish 가능한 destination은 선언된 destination이다. broker에 `app.messaging.security.<broker>`
항목이 있으면 그중 `access.publishable`에 적힌 것만 남는다(빈 목록이면 publish 불가).
## 관측성 누출
`MessagingRedactor`는 denylist다.
+10 -4
View File
@@ -17,10 +17,16 @@ enables the capability; construction is refused otherwise.
## 1. CSFLE
`MongoCsfleProfile` binds a collection to its `MongoCsfleFieldPolicy` list, a key vault
`MongoCredentialReference` and the key vault namespace. `MongoCsfleClientFactory` builds the encrypted
client settings. Data-key selection is the adopter's: `MongoCsfleFieldPolicy.keyAlias()` is the
alias the driver resolves against the key vault.
`MongoCsfleProfile` binds a collection (`database` + `collection`) to its `MongoCsfleFieldPolicy`
list, a key vault `MongoCredentialReference` and the key vault namespace. `MongoCsfleClientFactory`
builds the encrypted client settings from it: the `$jsonSchema` is generated from the field policies
(a dotted path becomes nested `properties`) and keyed by the namespace `database.collection`, and the
key vault client is built from the profile's own credential through `MongoCredentialResolver`.
An automatic-encryption schema names a data key by id, not by alias. The adopter resolves each
`MongoCsfleFieldPolicy.keyAlias()` against the key vault (for example
`ClientEncryption.getKeyByAltName`) and passes the alias → key id map to `settingsFor`; an alias with
no id is refused. Deterministic fields are typed `string` in the schema.
`MongoCsfleMode`:
+1 -38
View File
@@ -2,7 +2,7 @@
# Every top-level public type under the platform packages. Growth is a reviewed change.
# Update only after review with:
# ./gradlew :adapter:outbound:notification:updateNotificationApiSurface -PapproveNotificationApiSurfaceChange
# types: 416
# types: 379
dev.caskeleton.adapter.outbound.notification.NotificationConfig
dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings
dev.caskeleton.adapter.outbound.notification.core.FailOpenNotificationProvider
@@ -61,20 +61,6 @@ dev.caskeleton.adapter.outbound.notification.platform.observation.NotificationSe
dev.caskeleton.adapter.outbound.notification.platform.provider.EmailAttachments
dev.caskeleton.adapter.outbound.notification.platform.provider.ProviderResults
dev.caskeleton.adapter.outbound.notification.platform.provider.UnconfiguredAttachmentResolver
dev.caskeleton.adapter.outbound.notification.platform.provider.apns.ApnsFailureClassifier
dev.caskeleton.adapter.outbound.notification.platform.provider.apns.ApnsNotificationProviderAdapter
dev.caskeleton.adapter.outbound.notification.platform.provider.apns.ApnsProviderProperties
dev.caskeleton.adapter.outbound.notification.platform.provider.apns.ApnsRequestMapper
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmBatchCoordinator
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmBatchResult
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmContactPointUpdater
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmFailureClassifier
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmGateway
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmMessageMapper
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmNotificationProviderAdapter
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmProviderProperties
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmTargetMapper
dev.caskeleton.adapter.outbound.notification.platform.provider.fcm.FcmWireTarget
dev.caskeleton.adapter.outbound.notification.platform.provider.http.JdkNotificationHttpGateway
dev.caskeleton.adapter.outbound.notification.platform.provider.http.NotificationEndpoints
dev.caskeleton.adapter.outbound.notification.platform.provider.http.NotificationHttpGateway
@@ -89,7 +75,6 @@ dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesFailureCla
dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesNotificationProviderAdapter
dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesProviderProperties
dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesRequestMapper
dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesSuppressionUpdater
dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SnsCertificateProvider
dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SnsSignatureVerifier
dev.caskeleton.adapter.outbound.notification.platform.provider.smtp.JavaMailSenderSmtpDispatch
@@ -99,28 +84,6 @@ dev.caskeleton.adapter.outbound.notification.platform.provider.smtp.SmtpFailureC
dev.caskeleton.adapter.outbound.notification.platform.provider.smtp.SmtpMimeMessageFactory
dev.caskeleton.adapter.outbound.notification.platform.provider.smtp.SmtpNotificationProviderAdapter
dev.caskeleton.adapter.outbound.notification.platform.provider.smtp.SmtpProviderProperties
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioCallbackAdapter
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioDeliveryProjector
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioFailureClassifier
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioProviderProperties
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioReconciliationCapability
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioRequestMapper
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioSignatureValidator
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioSmsProviderAdapter
dev.caskeleton.adapter.outbound.notification.platform.provider.twilio.TwilioStatusNormalizer
dev.caskeleton.adapter.outbound.notification.platform.provider.webhook.WebhookNotificationProviderAdapter
dev.caskeleton.adapter.outbound.notification.platform.provider.webhook.WebhookSignatureStrategy
dev.caskeleton.adapter.outbound.notification.platform.provider.webhook.WebhookSubscription
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.EncryptedWebPushPayload
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.Rfc8291Aes128GcmEncryptor
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.VapidAuthorizationProvider
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.VapidJwtSigner
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.VapidKeyRegistry
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushFailureClassifier
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushNotificationProviderAdapter
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushProviderProperties
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushReceiptCapability
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushRequestMapper
dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmCallbackPayloadProtection
dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmContactPointProtector
dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmNotificationPayloadProtection
+10 -18
View File
@@ -66,14 +66,11 @@ and `APP_NOTIFICATION_PLATFORM_SES_*` aliases so operators do not have to invent
| Field | Meaning |
|---|---|
| `type` | `APNS`, `FCM`, `SES`, `SMTP`, `TWILIO`, `WEB_PUSH`, `WEBHOOK` — a closed enum, so an unknown value fails binding rather than assembling into nothing |
| `type` | `SES`, `SMTP` — a closed enum, so an unknown value fails binding rather than assembling into nothing |
| `enabled` | A disabled profile is bound and validated but contributes no runtime |
| `primary-for-channel` | Exactly one primary per channel |
| `environment` | Required when enabled |
| `credential-profile` | Provider credential key id resolved through `SecretMaterialProvider`; never inline secret material |
| `topic` | APNs bundle id |
| `vapid-public-key` | Web Push application server key |
| `callback-signing-secret-ref` | Reference, not material |
| `timeout` | Positive and finite |
| `max-concurrency` | Positive |
| `rate-per-second` | Positive |
@@ -100,22 +97,19 @@ The shipped reference profile is `providers.ses` and is disabled by default. It
`APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY`, whose active key id must match
`APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID`.
`type` is the closed **provider model**, not a promise that the shipped composition contains a
dispatch assembler for every value. Current shipped reachability is:
`type` lists only the families the shipped composition can assemble. Current shipped
reachability is:
| Provider type | Contract/adapter code | Shipped dispatch assembler | Shipped callback assembler | What happens when enabled for dispatch |
|---|---|---|---|---|
| `SMTP` | yes | **yes** | no | assembles when Spring Mail relay settings are complete |
| `SES` | yes | **yes** | **yes** | assembles an EMAIL runtime from the typed `ses` block; SNS callback verification remains available in `INGEST_ONLY` |
| `TWILIO` | yes | no | no | dispatch fails startup by profile name |
| `FCM` | yes | no | no | dispatch fails startup by profile name |
| `APNS` | yes | no | no | dispatch fails startup by profile name |
| `WEB_PUSH` | yes | no | no | dispatch fails startup by profile name |
| `WEBHOOK` | yes | no | no | dispatch fails startup by profile name |
This distinction is deliberate: tested provider protocol code is not the same thing as a
composition-reachable provider. Adding a family to the shipped runtime requires a
`ProviderRuntimeAssembler` plus the settings/secret inputs that adapter actually needs.
APNs, FCM, Twilio, Web Push and Webhook adapters used to ship as protocol code with no assembler, so
enabling one failed startup. They were removed; the `docs/capability-status.md` "제거된 코드" table
names the last commit that had them. Adding a family back means adding its adapter, a
`ProviderRuntimeAssembler`, its `ProviderType` constant and the settings/secret inputs it actually
needs, together.
## SMTP relay
@@ -164,8 +158,7 @@ Startup fails rather than degrading when:
- a TTL-required profile has no expiry source
- a callback signing secret is missing
- a production profile enables trust-all
- an APNs profile is missing its environment or topic
- a Web Push profile is missing its VAPID key
- an SES profile is missing its `ses` block, or callbacks are on and `ses.allowed-topic-arns` is empty
- two provider profiles share an id
- a route points only at disabled providers
- `mode` is `SERVING` and no provider profile is enabled
@@ -177,7 +170,7 @@ All key material arrives through `SecretMaterialProvider`. Nothing is read from
committed file, or from a plaintext log. Contact point encryption and lookup HMAC keys must be
distinct, and the encryption key must be exactly 256 bits.
Eight purposes, eight keys. Each is base64 of at least 32 bytes and each must differ from every
Seven purposes, seven keys. Each is base64 of at least 32 bytes and each must differ from every
other; the platform decodes them at startup and refuses to boot if one is blank, short or shared. A
blank value used to be skipped, which meant the platform started without the key and found out on
the first contact point — in production, on a recipient's notification.
@@ -195,7 +188,6 @@ any example: a value that appears in the repository is a value that has been dis
| Provider credential encryption | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID` |
| Provider request lookup HMAC | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID` |
| Payload encryption | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID` |
| Web Push VAPID signing | `APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY` | `APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY_ID` |
A key id is not secret — an id identifies key material without revealing it — but it is required,
and it has no default on purpose. A constant id makes a rotation indistinguishable from the key it
+2 -8
View File
@@ -39,11 +39,6 @@ that owns its responsibility. No public contract, evidence rule, or reliability
| `notification-template-thymeleaf` (reference renderer) | `adapter:outbound:notification` | `…platform.template` |
| `notification-email-smtp` | `adapter:outbound:notification` | `…platform.provider.smtp` |
| `notification-email-ses` | `adapter:outbound:notification` | `…platform.provider.ses` |
| `notification-sms-twilio` | `adapter:outbound:notification` | `…platform.provider.twilio` |
| `notification-push-fcm` | `adapter:outbound:notification` | `…platform.provider.fcm` |
| `notification-push-apns` | `adapter:outbound:notification` | `…platform.provider.apns` |
| `notification-webpush` (transport + crypto) | `adapter:outbound:notification` | `…platform.provider.webpush` |
| `notification-webhook-extension` | `adapter:outbound:notification` | `…platform.provider.webhook` |
| `notification-observability` (Micrometer impl) | `adapter:outbound:notification` | `…platform.observation` |
| `notification-admin-runtime` | `adapter:outbound:notification` | `…platform.admin` |
| `notification-spring-boot-starter` | `adapter:outbound:notification` | `…platform.autoconfigure` |
@@ -71,9 +66,8 @@ adapter:outbound:notification adapter:outbound:persistence-jpa adapter:inb
Two plan edges cannot be expressed as project edges in this repository, and are replaced by ports:
1. `notification-email-ses`, `notification-sms-twilio`, `notification-push-fcm`,
`notification-push-apns`, `notification-webpush`, `notification-webhook-extension`
→ `httpclient platform`.
1. `notification-email-ses` → `httpclient platform`. (The Twilio, FCM, APNs, Web Push and
Webhook adapters that shared this edge were removed: none had an assembler.)
`adapter-outbound-notification` is not allowed to depend on `adapter-outbound-httpclient`.
The provider adapters therefore call
`dev.caskeleton.adapter.outbound.notification.platform.provider.http.NotificationHttpGateway`,
+4 -35
View File
@@ -27,39 +27,8 @@ send, so `MessageId` is never mapped to `DELIVERED`.
| `Reject` | `PROVIDER_REJECTED` |
| `RenderingFailure` | `TEMPLATE_FAILURE` |
## Twilio
## Removed provider families
`accepted`/`queued` is acceptance only. `sent` is carrier acceptance. `delivered` is device delivery.
Callbacks are not ordered. A `sent` arriving after `delivered` is stored and ignored by the
projection. Missing callbacks are corrected by status polling under the provider rate limit.
Signature verification uses the canonical external URL from the profile, not the URL the servlet
container reconstructed behind a proxy.
## FCM
| Error | Classification |
|---|---|
| `UNREGISTERED` | `INVALID_RECIPIENT`; invalidate the contact point, never retry |
| `INVALID_ARGUMENT` | `INVALID_PAYLOAD` |
| `QUOTA_EXCEEDED` | `THROTTLED`, exponential backoff |
| `UNAVAILABLE` | `TRANSIENT_PROVIDER`, honour `Retry-After`, add jitter |
| Credential failure | `AUTHENTICATION`; opens the provider route |
A batch is one transport call and many attempts. Partial results map back by input index; one
transport failure does not become one shared outcome unless the adapter can prove it.
## APNs
2xx is acceptance. Environment and topic mismatches are configuration failures, not delivery
failures. Sandbox and production tokens are separate namespaces.
## Web Push
`TTL` is mandatory by protocol. `201` is acceptance. `404` is an expired subscription per RFC 8030;
provider-documented `410` maps the same way. Payloads use `aes128gcm` per RFC 8291 and VAPID JWTs are
signed per RFC 8292 with the audience taken from the endpoint origin.
VAPID key rotation is not ordinary credential rotation: a restricted subscription may need to be
re-created, so it is a migration operation.
Twilio, FCM, APNs, Web Push and Webhook adapters were removed because nothing assembled them; their
runbooks went with them. The last commit that had both is named in `docs/capability-status.md`
(제거된 코드). A deployment that adds one of these providers back writes its runbook here with it.
+9 -20
View File
@@ -17,12 +17,11 @@ against real PostgreSQL; the wire and the crash are not. That is what the grade
| Channel | Reference implementation | Grade | Strongest evidence the platform records by default |
|---|---|---|---|
| Email | SMTP, Amazon SES API | Contract implemented / runtime unqualified | Provider acceptance; recipient mail-server delivery, bounce and complaint when the provider publishes events |
| SMS | Twilio Programmable Messaging | Contract implemented / runtime unqualified | `accepted`/`queued`, `sent`, and carrier-DLR `delivered`/`undelivered` |
| Mobile push (Android and cross-platform) | FCM, FID-first with legacy registration token compatibility | Contract implemented / runtime unqualified | FCM acceptance and explicit failures |
| Mobile push (Apple) | APNs HTTP/2 provider API | Contract implemented / runtime unqualified | APNs acceptance |
| Web Push | RFC 8030, RFC 8291, RFC 8292 | Contract implemented / runtime unqualified | Push-service acceptance; user-agent acknowledgement only where the service offers receipts |
| SMS | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
| Mobile push (FCM, APNs) | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
| Web Push | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
| In-app inbox | Own database | Optional stable | `PERSISTED`, `SEEN`, `READ` |
| Webhook | HTTP client platform | Extension | Whatever the receiving HTTP contract states |
| Webhook | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the receiving HTTP contract states |
## Shipped provider assembly reachability
@@ -33,13 +32,10 @@ implementation is selectable in the default composition. Dispatch reachability i
|---|---|---|---|
| SMTP | **yes** | no | EMAIL dispatch reference family |
| SES | **yes** | **yes** | EMAIL dispatch + SNS callback ingestion; disabled reference profile ships in `config/module-defaults/notification.yml` (`composition:notification-platform`) |
| Twilio | no | no | contract implementation / extension wiring |
| FCM | no | no | contract implementation / extension wiring |
| APNs | no | no | contract implementation / extension wiring |
| Web Push | no | no | contract implementation / extension wiring |
| Webhook | no | no | extension wiring |
An enabled dispatch profile with no assembler fails startup by profile/family; it never silently
APNs, FCM, Twilio, Web Push and Webhook adapters shipped as protocol code with no assembler and
were removed; `ProviderType` now lists only SES and SMTP, so such a profile fails binding as an
unknown type. An enabled dispatch profile with no assembler fails startup by profile/family; it never silently
assembles into an empty runtime. SMTP additionally names `spring.mail.host` when its shipped
assembler is absent because the relay was not configured.
@@ -73,21 +69,14 @@ The remaining unmet claim, and what would meet it:
| Internal queue commit | `PLATFORM_QUEUED` |
| SES `MessageId` | `PROVIDER_ACCEPTED` |
| SES `Delivery` | `NETWORK_OR_CARRIER_ACCEPTED` |
| Twilio `accepted` / `queued` | `PROVIDER_ACCEPTED` |
| Twilio `sent` | `NETWORK_OR_CARRIER_ACCEPTED` |
| Twilio `delivered` | `DEVICE_DELIVERED` |
| FCM send success | `PROVIDER_ACCEPTED` |
| APNs 2xx | `PROVIDER_ACCEPTED` |
| Web Push `201` | `PROVIDER_ACCEPTED` |
| Web Push receipt capability | `DEVICE_DELIVERED` |
| In-app row commit | `PROVIDER_ACCEPTED` |
| In-app `seen` endpoint | `USER_AGENT_DISPLAYED` |
| In-app `read` endpoint, authenticated app receipt | `USER_READ` |
Promotions the platform will not make, in code or in configuration:
- FCM send success is not `DEVICE_DELIVERED`.
- An APNs 2xx is not `DELIVERED`.
- A push or SMS acceptance, from any provider adapter a deployment adds, is not `DEVICE_DELIVERED`.
- A provider 2xx is not `DELIVERED`.
- An SES `MessageId` is not `DELIVERED`.
- An SMTP `250` is not inbox delivery.
+22 -62
View File
@@ -117,10 +117,12 @@ env_keys:
- name: APP_SERVER_FORWARD_HEADERS_STRATEGY
# source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification.
# Fail closed: forwarded headers are trusted only when a deployment opts in behind a
# sanitizing/trusted proxy.
# sanitizing/trusted proxy. native = Tomcat RemoteIpValve, which honours them only from
# peers matching server.tomcat.remoteip.internal-proxies. framework is not allowed: its
# ForwardedHeaderFilter believes every peer, and the rate limiter refuses to start on it.
type: enum
default: none
allowed_values: [none, native, framework]
allowed_values: [none, native]
classification: public-config
required: false
reload_policy: restart-only
@@ -1199,19 +1201,10 @@ env_keys:
compatibility_impact: additive
required_test: redis-rate-limit-contract:transport-provider-default-pair
- name: APP_RATE_LIMIT_CLIENT_IP_MODE
# source: feature-rate-limit-idempotency-contract — rate-limit client IP source policy.
# Use forwarded-headers-trusted only behind an ingress/LB that overwrites X-Forwarded-For.
type: enum
default: remote-addr-only
allowed_values: [remote-addr-only, forwarded-headers-trusted]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-rate-limit-idempotency-contract
validation: enum_in_allowed_values
compatibility_impact: behavior-change
required_test: rate-limit-contract:client-ip-mode
# APP_RATE_LIMIT_CLIENT_IP_MODE removed (2026-09-25, review follow-up I-5a): its
# forwarded-headers-trusted value keyed unauthenticated callers by the leftmost X-Forwarded-For
# entry, which the caller writes. The client IP is getRemoteAddr(); behind a proxy set
# APP_SERVER_FORWARD_HEADERS_STRATEGY=native and server.tomcat.remoteip.internal-proxies.
- name: APP_RATE_LIMIT_REDIS_ENABLED
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisSdkAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
@@ -3996,6 +3989,20 @@ env_keys:
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY
property: app.websocket.channel-queue-capacity
owner_module: adapter-inbound-websocket
type: integer
default: 10000
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: refactor/review-followup
validation: positive_integer
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_GRAPHQL_ENABLED
# 2026-09-25 capability packaging: the module is on when present (its own config yml maps
# this key with default true); false is the explicit off. Absent from the build is the
@@ -4028,21 +4035,6 @@ env_keys:
validation: enum
compatibility_impact: behavior-change
required_test: adapter-contract:graphql-deployment-mode
- name: APP_GRAPHQL_EXECUTION_PROFILE
property: backend.graphql.execution-profile
owner_module: adapter-inbound-graphql
type: enum
default: BLOCKING_MVC
allowed_values: [BLOCKING_MVC, REACTIVE_WEBFLUX, MIXED_CONTROLLED]
classification: public-config
required: false
required_when: APP_GRAPHQL_ENABLED=true
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-graphql-review-remediation
validation: enum
compatibility_impact: additive
required_test: graphql-contract:wired-operator-settings
- name: APP_GRAPHQL_VALIDATION_POLICY_VERSION
property: backend.graphql.validation-policy-version
owner_module: adapter-inbound-graphql
@@ -4318,22 +4310,6 @@ env_keys:
compatibility_impact: behavior-change
required_test: adapter-contract:notification-secret-material-required
- name: APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY
# source: NTF-INT-007 — Signs Web Push requests; the browser push service rejects anything else.
# Full row owned by secrets-classification.yaml. Bound by
# ca-skeleton.notification.platform.secrets.vapid-signing-key; the platform decodes it at startup and
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
type: string
default: null
allowed_values: null
classification: secret
required: false
reload_policy: restart-only
owner_branch: worktree-notification-platform
validation: base64_at_least_32_bytes_and_distinct_per_purpose
compatibility_impact: behavior-change
required_test: adapter-contract:notification-secret-material-required
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY
# source: NTF-INT-007 — Keyed hash of provider request ids, which are provider-side identifiers.
# Full row owned by secrets-classification.yaml. Bound by
@@ -4446,22 +4422,6 @@ env_keys:
compatibility_impact: behavior-change
required_test: adapter-contract:notification-secret-material-required
- name: APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY_ID
# source: NTF-INT-007 — the id written into every envelope the VAPID_SIGNING key produces.
# An identifier, not key material, so it is public-config; the material itself is the
# APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY row above. Bound into
# ca-skeleton.notification.platform.secrets.active-key-ids.VAPID_SIGNING.
type: string
default: null
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: worktree-notification-platform
validation: non_blank_when_platform_enabled
compatibility_impact: behavior-change
required_test: adapter-contract:notification-secret-material-required
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID
# source: NTF-INT-007 — the id written into every envelope the PROVIDER_REQUEST_LOOKUP_HMAC key produces.
# An identifier, not key material, so it is public-config; the material itself is the
+14 -30
View File
@@ -199,8 +199,8 @@ secrets:
- name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY
# Encrypts recipient contact points at rest — addresses and phone numbers.
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
# One of seven purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all seven, and the platform enforces
# the distinction at startup rather than trusting the deployment to have noticed.
classification: secret
source: secret-manager
@@ -215,8 +215,8 @@ secrets:
- name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY
# Blind index over contact points, so a lookup never needs the plaintext.
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
# One of seven purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all seven, and the platform enforces
# the distinction at startup rather than trusting the deployment to have noticed.
classification: secret
source: secret-manager
@@ -231,8 +231,8 @@ secrets:
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY
# Signs the callback URLs a provider posts delivery outcomes back to.
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
# One of seven purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all seven, and the platform enforces
# the distinction at startup rather than trusting the deployment to have noticed.
classification: secret
source: secret-manager
@@ -247,8 +247,8 @@ secrets:
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY
# Encrypts stored provider credentials, which are themselves secrets.
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
# One of seven purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all seven, and the platform enforces
# the distinction at startup rather than trusting the deployment to have noticed.
classification: secret
source: secret-manager
@@ -263,8 +263,8 @@ secrets:
- name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY
# Encrypts notification variables and retained callback bodies at rest.
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
# One of seven purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all seven, and the platform enforces
# the distinction at startup rather than trusting the deployment to have noticed.
classification: secret
source: secret-manager
@@ -277,26 +277,10 @@ secrets:
compatibility_impact: behavior-change
required_test: secrets-contract:notification-payload-encryption-no-leak
- name: APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY
# Signs Web Push requests; the browser push service rejects anything else.
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
# the distinction at startup rather than trusting the deployment to have noticed.
classification: secret
source: secret-manager
rotation_policy: dual-read-restart-only
prod_default: null
required_when: ca-skeleton.notification.platform.enabled=true
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: worktree-notification-platform
masking_rule: full
compatibility_impact: behavior-change
required_test: secrets-contract:notification-vapid-signing-no-leak
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY
# Keyed hash of provider request ids, which are provider-side identifiers.
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
# One of seven purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all seven, and the platform enforces
# the distinction at startup rather than trusting the deployment to have noticed.
classification: secret
source: secret-manager
@@ -311,8 +295,8 @@ secrets:
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY
# Keyed fingerprint of callback bodies, used to detect replays.
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
# One of seven purpose-scoped keys. They must all differ: a single key reused across purposes
# means a compromise of any one of them is a compromise of all seven, and the platform enforces
# the distinction at startup rather than trusting the deployment to have noticed.
classification: secret
source: secret-manager
+8 -11
View File
@@ -38,9 +38,9 @@ bound.
3. `NO_SNAPSHOT_YET` on a starting instance means it never reached the control plane. It fails after
the initial fetch timeout rather than starting with no routing.
**Do not** add application-level retry policy while xDS is enabled. `GrpcXdsStartupGuard` refuses it,
because retry defined in two places has a winner that depends on resolution order rather than on a
decision.
**Do not** add application-level retry policy while xDS is enabled. `GrpcXdsProfile` refuses an
`APPLICATION` retry owner, because retry defined in two places has a winner that depends on
resolution order rather than on a decision.
---
@@ -52,17 +52,15 @@ the proxy did not expose. Check that the proxy's CORS `expose_headers` includes
configuration in `envoy/envoy.yaml` shows it in place.
**If the method is client- or bidirectional-streaming**, it cannot work over gRPC-Web at all — a
browser has no way to send a stream of messages. `GrpcWebCompatibilityGate` reports such a method
before it is exposed.
browser has no way to send a stream of messages. `GrpcWebRpcSupport.require` refuses such a method.
---
## Servlet: a transport setting appears to be ignored
It is ignored. The container owns the socket, so keepalive tuning, maximum connection age and
flow-control window tuning belong to it. `GrpcServletStartupValidator` refuses those settings at
startup rather than accepting and dropping them, because a setting that is silently ignored sends the
investigation somewhere else.
flow-control window tuning belong to it. This repository has no Servlet transport code that would
refuse them, so configure them on the container.
A Servlet run never substitutes for Netty certification.
@@ -93,6 +91,5 @@ real-environment test and seven days of soak. A Stable default needs thirty.
Promotions are independent: promoting one capability changes no other's grade, and
`GrpcAdvancedSupportMatrix.apply` refuses a decision made against a different matrix state.
Before citing a suite as evidence, check `GrpcAdvancedInfrastructureTestkit.missingInfrastructure`.
A suite that ran without the proxy, the container, the control plane or the toolchain it needs passed
and established nothing.
Before citing a suite as evidence, check that it ran against the real infrastructure it needs (proxy,
container, control plane or toolchain). A suite that ran without it passed and established nothing.
+6 -5
View File
@@ -5,9 +5,9 @@ not interchangeable providers for one port.
| Question | Fileserver HTTP platform | Object Storage |
|---|---|---|
| Who serves bytes to the client? | This application, through Fileserver HTTP routes | The selected object store, often through direct/presigned transfer |
| Primary application contract | Upload/download/lifecycle HTTP workflow and Fileserver application ports | Provider-neutral managed/direct object-storage ports |
| Storage semantics | Application-owned staging, verification, publication, range/conditional delivery, upload leases | Managed object publication plus remote-store versioning/direct/multipart semantics |
| Who serves bytes to the client? | This application, through Fileserver HTTP routes | This application, streaming through the semantic transfer port (no direct/presigned transfer exists) |
| Primary application contract | Upload/download/lifecycle HTTP workflow and Fileserver application ports | Provider-neutral managed and staged object-storage ports |
| Storage semantics | Application-owned staging, verification, publication, range/conditional delivery, upload leases | Managed and staged object publication plus remote-store versioning semantics |
| Local filesystem role | Certified backing store for the application-owned Fileserver platform | `filesystem-local-dev` development/provider implementation |
| Remote S3-style semantics | Not its purpose | First-class capability |
@@ -18,8 +18,9 @@ and conditional requests, verification/quarantine, resumable upload state, lifec
and optional delegated serving such as X-Accel-Redirect.
Use **Object Storage** when the application needs an object-storage abstraction whose provider owns
the storage/transfer semantics, especially S3-compatible managed objects, presigned/direct transfer,
or multipart workflows.
the storage semantics, especially S3-compatible managed objects. Direct/presigned transfer and
multipart upload are not implemented: their unassembled code was removed (see
`docs/capability-status.md` 「제거된 코드」).
Do not enable both as two independent sources of truth for the same logical object. If a product
needs both, one capability must own the logical object/control record and the other must be an
@@ -219,4 +219,46 @@ W5 행 전부, `docs/study/*.ko.md`·`docs/*-superpowers-package/`를 현재 코
| Wave | 상태 | 검증 | 커밋 | 비고 |
|---|---|---|---|---|
| 준비 | 완료 (2026-09-25) | 기준 `./gradlew check --continue` 통과(481 task) | - | 현황표 812행(완료 161 / 해당 없음 106 / 남음 544 / 보류 1), 소유자 결정 20건 |
| 준비 | 완료 (2026-09-25) | 기준 `./gradlew check --continue` 통과(481 task) | `fe80bb3f` | 현황표 812행(완료 161 / 해당 없음 106 / 남음 544 / 보류 1), 소유자 결정 20건 |
| 1–2 | 진행 중 — 사용량 한도로 일시 중단 (2026-09-25) | 묶음별 leaf `check`·벤더 lane은 각 worktree에서 통과. main 통합 검증은 아직 | - | 아래 「중단 시점 상태」 |
### 중단 시점 상태 (재개용)
- 브랜치 `refactor/review-followup` @ `fe80bb3f`. **main 작업 트리에 커밋 안 된 변경이 있다**: 아래 표의 `D`·`W1` 커밋을 `git cherry-pick -n`으로 적용한 상태(충돌 0). 이 상태를 버리지 않는다.
- 묶음별 결과 파일·공통 지시·스크립트 사본: `.claude/review-followup/`(gitignore 대상, 디스크에 남음). `results/P*.md` = 행 결과·제거된 코드·새 결함, `agent-brief.md` = 구현 에이전트 공통 지시, `apply_results.py` = 결과 파일로 현황표 갱신(`--only-waves W1`), `by_area.py` = 남은 행을 영역·Wave별로 나열.
- 각 묶음의 커밋은 브랜치 `worktree-agent-*`(13개)에 있다. worktree 폴더는 모두 깨끗한 상태에서 정리했다(`git worktree remove`) — W2 커밋은 브랜치에서 `git cherry-pick -n <해시>`로 가져온다.
| 묶음 | 브랜치 | D·W1 커밋 (main에 적용됨) | W2 커밋 (Wave 2에서 적용) | 행 결과 |
|---|---|---|---|---|
| P1 messaging | `worktree-agent-ac82c0859f4fb76da` | `3ecef978` | `2ae3c960` | 완료 18, 남음 2(Wave 3 3-C) |
| P2 object storage | `worktree-agent-a0383097e74acaf1e` | `2c7b3d25` `69ca6565` `f8bf7b6d` | `11eac0c7` | 완료 20 |
| P3 notification | `worktree-agent-a9bbc66a423c4d1fa` | `38d31b98` `12adea6e` | `6db6214c` | 완료 17, 남음 1(X2-P2-7b → P10에서 완료) |
| P4 file server | `worktree-agent-a4be05fc0e42cb70c` | `433bacdb` | `ed2c0929` | 완료 24 |
| P5 realtime·gRPC | `worktree-agent-ab8fb70ea2e85b04c` | `9b296c7c` `b39d3de0` | `a498ad84` | 완료 24(+N-9c 완료, N-9b 해당 없음) |
| P6 Redis | `worktree-agent-a6ab0657d876ae6b9` | `22f28a3e` | `5761314d` | 완료 14 |
| P7 core·bootstrap | `worktree-agent-a50ffe5361b9ddd73` | `9a05d686` | `3a39b6b5` | 완료 11, 남음 1(X1-#1d = P9 E-5) |
| P8 GraphQL | `worktree-agent-ab74dd57027acdc42` | `6390bf89` `0392d8c9` | `aa5f4d90` | 완료 8, 해당 없음 1, 남음 2(Wave 3 3-D) |
| P9 JPA·durable op | `worktree-agent-adbb19427d5d1740b` | `21bcba8d` | `3152e50b` | 완료 14 |
| P10 web | `worktree-agent-afae86287ba980dfb` | `983cc832` | `5c08d3be` | 완료 13 |
| P11 httpclient | `worktree-agent-afdf5842812e13046` | `06764fcb` `c44030e8` | `52511391` | 완료 12, 해당 없음 4 |
| P12 Mongo | `worktree-agent-aa2a445bdd99d8bd7` | `ceddd6d1` | `3dc06bba` | 완료 11(+F-1c W5 사실상 해결) |
| P13 build/CI | `worktree-agent-a93a684bfe0982466` | `50cb2d9e` | `6b1cddc6` | 완료 5 |
13개 묶음 전부 끝남. 모든 `D`·`W1` 커밋이 main 작업 트리에 적용돼 있다(충돌 0, 커밋 전).
재개 순서:
1. (완료) 13개 묶음의 `D`·`W1` 커밋 적용.
2. migration 버전 충돌 확인: P9가 persistence-jpa `V18`, P4가 fileserver `V5`, P1이 messaging `V1005`를 추가했다.
3. lockfile 재생성(`resolveAndLockAll --write-locks`) → Wave 종료 검증 전체 → `apply_results.py --only-waves W1` → 「제거된 코드」 표에 결과 파일 행 추가 → 커밋 `review-followup Wave 1` → Slack 브리핑.
4. W2 커밋 적용 → 같은 검증 → 커밋 `review-followup Wave 2`.
5. 새로 발견한 결함(`P*-new-*`)을 현황표 행으로 추가하고 Wave 3 이후에 배정.
소유자에게 물을 것(모아 둔 것):
- P3-new-5: 알림 profile runtime이 사라진 경우 무한 재시도할지, FAILED로 닫을지.
- P2-new-2: sample poster 업로드에서 abort와 reconcile이 경합하면 게시된 객체가 붙지 않은 채 남는다. 어떻게 정리할지.
- P11-new-4: Dynamic Target이 cross-origin redirect될 때 호출자가 넣은 관례 밖 헤더(`X-Client-Key` 등)도 전부 버릴지.
- P6-new-2: 멱등성 `complete`가 연결 풀 포화로 `UNAVAILABLE`이면 executor가 재시도할지, 복구 경로에 맡길지.
- P8: DataLoader 키 실패 때 adopter가 준 에러 code를 client에 그대로 내보낼지.
- P9: durable operation 설계 선택 4개(서버 생성 id, payload fingerprint로 재제출 판정, 고정 outbox event type, 보존 1일) 승인 여부.
- P13-new-1: build-logic·build-tools를 main build가 plugin으로 불러올 때의 의존성도 잠글지(잠그면 Spring Boot plugin을 올릴 때마다 lock 갱신 필요).
File diff suppressed because one or more lines are too long
+1
View File
@@ -0,0 +1 @@
/home/donghyeon/.local/share/pipx/venvs/graphifyy/bin/python
+1
View File
@@ -0,0 +1 @@
/home/donghyeon/workspace/desktop-server-git/clean-architecture-backend-template/src
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
+12
View File
@@ -0,0 +1,12 @@
{
"runs": [
{
"date": "2026-09-24T02:31:39.845568+00:00",
"input_tokens": 825431,
"output_tokens": 0,
"files": 7049
}
],
"total_input_tokens": 825431,
"total_output_tokens": 0
}
File diff suppressed because one or more lines are too long
+3156773
View File
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+2 -2
View File
@@ -97,9 +97,9 @@ declare fails instead of running nothing, so run only the leaves listed for the
| Lane | `redis-runtime` | `redis-sdk` | `cache-redis` |
| --- | --- | --- | --- |
| standalone | `LiveRedisCompositionTest` | `RedisTopologyContractTest`, `LiveRedisGuardrailTest` | `LiveRedisSemanticPortsTest` |
| standalone | `LiveRedisCompositionTest` | `RedisTopologyContractTest`, `LiveRedisGuardrailTest` | `LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest` |
| sentinel | `LiveRedisCompositionTest` | `RedisTopologyContractTest`, `LiveRedisSentinelPromotionTest` | — |
| cluster | `LiveRedisCompositionTest` | `LiveRedisClusterTest`, `LiveRedisClusterTransactionTest` | `LiveRedisSemanticPortsTest` |
| cluster | `LiveRedisCompositionTest` | `LiveRedisClusterTest`, `LiveRedisClusterTransactionTest` | `LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest` |
| tls | `LiveRedisTlsTest` | — | — |
Tear a lane down with `docker compose -f infra/redis-sdk/<lane>/compose.yml down -v`.
+1 -1
View File
@@ -18,7 +18,7 @@ loads, had been fixed; a fork that copied one of them got an open account and a
| File | Account | Grants |
| --- | --- | --- |
| `application.acl` | `CommandAccess.APPLICATION` | the typed data-structure commands over `prod:*`, with the dangerous and deprecated names denied |
| `application-advanced.acl` | `APPLICATION_ADVANCED` | the above plus pub/sub, transactions, and the registered-script path. `EVAL` is absent: only `EVALSHA` of an already loaded digest is reachable |
| `application-advanced.acl` | `APPLICATION_ADVANCED` | the above plus pub/sub, transactions, and the registered-script path. `EVAL` is absent: only `EVALSHA` of an already loaded digest is reachable. `+time` is granted because the rate-limit and idempotency scripts read the server clock with `redis.call('TIME')`, and `TIME` is in no data category (`@read`/`@write`): without it every such script fails with an ACL error. The startup SCRIPT probe runs `TIME` so a template missing it fails at boot |
| `raw-gateway.acl` | `RAW_GATEWAY` | exactly the commands the catalog classifies `RAW_ONLY`, and nothing else |
| `all-accounts.acl` | – | the four accounts concatenated; Redis takes one `aclfile`, so this is what a deployment loads |
| `admin-readonly.acl` | `ADMIN_READONLY` | read-only diagnostics. Every destructive counterpart is denied here and blocked in the command policy catalog — two independent controls for the same rule |
+1 -1
View File
@@ -1,6 +1,6 @@
user default off
user ca-skeleton-application on >fixture-application sanitize-payload ~prod:* resetchannels &prod:* -@all +@connection +@pubsub +@transaction +@read +@write +@string +@hash +@list +@set +@sortedset +@bitmap +@hyperloglog +@geo +@stream -keys -flushdb -flushall -shutdown -debug -sort -sort_ro -smembers -randomkey -migrate -swapdb -select +cluster|slots +cluster|shards +cluster|nodes +cluster|info +cluster|myid
user ca-skeleton-application-advanced on >fixture-advanced sanitize-payload ~prod:* resetchannels &prod:* -@all +@read +@write +@string +@hash +@list +@set +@sortedset +@bitmap +@hyperloglog +@geo +@stream +@pubsub +@transaction +evalsha +evalsha_ro +script|load +script|exists +fcall +fcall_ro -keys -flushdb -flushall -shutdown -debug -eval -eval_ro -smembers -sort -sort_ro -randomkey -migrate -swapdb -select +cluster|slots +cluster|shards +cluster|nodes +cluster|info +cluster|myid
user ca-skeleton-application-advanced on >fixture-advanced sanitize-payload ~prod:* resetchannels &prod:* -@all +@read +@write +@string +@hash +@list +@set +@sortedset +@bitmap +@hyperloglog +@geo +@stream +@pubsub +@transaction +time +evalsha +evalsha_ro +script|load +script|exists +fcall +fcall_ro -keys -flushdb -flushall -shutdown -debug -eval -eval_ro -smembers -sort -sort_ro -randomkey -migrate -swapdb -select +cluster|slots +cluster|shards +cluster|nodes +cluster|info +cluster|myid
user ca-skeleton-raw-gateway on >fixture-raw sanitize-payload ~prod:* resetchannels -@all +smembers +sort +sort_ro
user ca-skeleton-admin-readonly on >fixture-admin ~* resetchannels -@all +info +dbsize +time +lastsave +memory|usage +memory|stats +slowlog|get +slowlog|len +latency|latest +latency|history +client|list +client|info +command|info +command|docs +command|count +command|getkeysandflags +config|get +acl|dryrun +acl|whoami +cluster|info +cluster|slots +cluster|shards +cluster|nodes +object|encoding +object|freq +object|idletime +pubsub|channels +pubsub|numsub +pubsub|shardchannels +xinfo|stream +xinfo|groups +xinfo|consumers +function|list +function|stats +cluster|keyslot +cluster|myid
user ca-skeleton-replication on >fixture-replication ~* resetchannels -@all +psync +replconf +ping
+1 -1
View File
@@ -1 +1 @@
user ca-skeleton-application-advanced on >fixture-advanced sanitize-payload ~prod:* resetchannels &prod:* -@all +@read +@write +@string +@hash +@list +@set +@sortedset +@bitmap +@hyperloglog +@geo +@stream +@pubsub +@transaction +evalsha +evalsha_ro +script|load +script|exists +fcall +fcall_ro -keys -flushdb -flushall -shutdown -debug -eval -eval_ro -smembers -sort -sort_ro -randomkey -migrate -swapdb -select
user ca-skeleton-application-advanced on >fixture-advanced sanitize-payload ~prod:* resetchannels &prod:* -@all +@read +@write +@string +@hash +@list +@set +@sortedset +@bitmap +@hyperloglog +@geo +@stream +@pubsub +@transaction +time +evalsha +evalsha_ro +script|load +script|exists +fcall +fcall_ro -keys -flushdb -flushall -shutdown -debug -eval -eval_ro -smembers -sort -sort_ro -randomkey -migrate -swapdb -select
+5 -5
View File
@@ -132,7 +132,7 @@ redact_in_place() {
random_secret() { head -c 32 /dev/urandom | base64 | tr -d '=+/' | cut -c1-32; }
# Key material, which is not the same thing as a password. The notification platform base64-decodes
# each of its eight keys and requires at least 32 bytes, so random_secret's alphanumeric 32
# each of its seven keys and requires at least 32 bytes, so random_secret's alphanumeric 32
# characters decode to 24 and are rejected. This keeps the padding and the full alphabet.
random_key() { head -c 32 /dev/urandom | base64 | tr -d '\n'; }
@@ -261,19 +261,19 @@ run_lane() {
export APP_HEALTH_PATH=/v1/healthcheck
fi
# The notification platform's eight purpose-scoped keys.
# The notification platform's seven purpose-scoped keys.
#
# All eight, always, for every lane — not only the notification ones. They cost nothing when the
# All seven, always, for every lane — not only the notification ones. They cost nothing when the
# capability is off, because the platform binds nothing at all then, and a lane that supplies only
# the keys it currently needs is a lane that breaks the moment a switch is added to it.
#
# Distinct by construction: the platform refuses to start if two purposes carry the same material,
# which is the check that stops one leaked key from being all eight. Each is redacted from the
# which is the check that stops one leaked key from being all seven. Each is redacted from the
# evidence like every other generated value.
local -a notification_keys=()
local purpose
for purpose in CONTACT_ENCRYPTION CONTACT_LOOKUP_HMAC CALLBACK_SIGNING PROVIDER_CREDENTIAL \
PAYLOAD_ENCRYPTION VAPID_SIGNING PROVIDER_REQUEST_LOOKUP_HMAC \
PAYLOAD_ENCRYPTION PROVIDER_REQUEST_LOOKUP_HMAC \
CALLBACK_FINGERPRINT_HMAC; do
local value; value="$(random_key)"
GENERATED_SECRETS+=("${value}")
+4 -7
View File
@@ -22,7 +22,7 @@ APP_SERVER_PORT=8080
MANAGEMENT_SERVER_PORT=9001
APP_SERVER_SHUTDOWN=graceful
APP_SERVER_SHUTDOWN_TIMEOUT=30s
APP_SERVER_FORWARD_HEADERS_STRATEGY=framework
APP_SERVER_FORWARD_HEADERS_STRATEGY=native
APP_SERVER_TOMCAT_MAX_THREADS=200
APP_SERVER_TOMCAT_MIN_SPARE_THREADS=10
APP_SERVER_TOMCAT_ACCEPT_COUNT=100
@@ -96,7 +96,6 @@ APP_SESSION_MAXIMUM_SCALAR_BYTES=8192
APP_SECURITY_JWT_ISSUER=
APP_SECURITY_JWT_AUDIENCE=
APP_RATE_LIMIT_ENABLED=false
APP_RATE_LIMIT_CLIENT_IP_MODE=remote-addr-only
APP_RATE_LIMIT_REDIS_ENABLED=false
APP_RATE_LIMIT_PROVIDER=disabled
APP_RATE_LIMIT_FAILURE_POLICY=fail-closed
@@ -277,7 +276,6 @@ SPRING_MONGODB_URI=
APP_MESSAGING_ENABLED=true
APP_GRAPHQL_ENABLED=true
APP_GRAPHQL_DEPLOYMENT_MODE=
APP_GRAPHQL_EXECUTION_PROFILE=BLOCKING_MVC
APP_GRAPHQL_VALIDATION_POLICY_VERSION=v1
APP_GRAPHQL_OBSERVED_OPERATION_NAMES=
APP_GRAPHQL_GRAPHIQL_ENABLED=false
@@ -294,6 +292,7 @@ APP_WEBSOCKET_ENABLED=true
APP_WEBSOCKET_ENDPOINT=/ws
APP_WEBSOCKET_ALLOWED_ORIGINS=http://localhost:3000
APP_WEBSOCKET_BROADCAST_DESTINATION=/topic/events
APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY=10000
APP_OUTBOX_ENABLED=false
APP_OUTBOX_RELAY_ENABLED=false
APP_OUTBOX_CANONICAL_TRANSPORT_ENABLED=false
@@ -376,8 +375,8 @@ APP_LEASE_REDIS_KEY_HMAC_SECRET=
APP_CACHE_REDIS_PASSWORD=
APP_CACHE_REDIS_KEY_HMAC_SECRET=
APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY=
# The notification platform's eight key purposes. Each is base64 of at least 32 bytes and must
# differ from the other seven; the platform decodes all eight at startup and refuses to boot if one
# The notification platform's seven key purposes. Each is base64 of at least 32 bytes and must
# differ from the other six; the platform decodes all seven at startup and refuses to boot if one
# is blank, short or shared. Only needed when the notification module is selected and not switched
# off with APP_NOTIFICATION_PLATFORM_ENABLED=false.
APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY=
@@ -385,7 +384,6 @@ APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY=
APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY=
APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY=
APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY=
APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY=
APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY=
APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY=
# The id each of those keys is active under — an identifier, not secret material, and required:
@@ -396,6 +394,5 @@ APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID=
APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID=
APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID=
APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID=
APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY_ID=
APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID=
APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID=
+6 -5
View File
@@ -223,9 +223,9 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로,
- **`APP_RATE_LIMIT_ENABLED`** — provider-neutral edge rate-limit interceptor 활성화
(429 + `Retry-After` + `X-RateLimit-*` 응답). 기본값은 `false`이며, `true`로 바꿀 때는
`APP_RATE_LIMIT_PROVIDER=redis`와 canonical coordination role을 함께 구성해야 합니다.
- **`APP_RATE_LIMIT_CLIENT_IP_MODE`** — 클라이언트 IP 판별 방식. `remote-addr-only` |
`forwarded-headers-trusted`. **신뢰된 ingress/LB 가 `X-Forwarded-For` 를 앱 도달 전에 덮어쓸 때만**
`forwarded-headers-trusted` 를 쓰세요. 아니면 IP 위조에 노출됩니다.
비인증 요청의 키는 `getRemoteAddr()` 입니다. 프록시 뒤라면
`APP_SERVER_FORWARD_HEADERS_STRATEGY=native` 와 `server.tomcat.remoteip.internal-proxies` 로 신뢰할
프록시를 지정하세요(`framework` 면 rate limit 이 기동을 거부합니다).
- **`APP_IDEMPOTENCY_PROVIDER`** — 요청 멱등성 store. `disabled`(기본) | `redis` | `postgresql`.
`postgresql` 은 PostgreSQL data source 가 아니면 기동을 거부하므로 `bootRunH2` 에서는
`disabled` 나 `redis` 를 씁니다.
@@ -469,8 +469,9 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니
- **`APP_SERVER_COMPRESSION_ENABLED`** — `true` | `false`.
- **`APP_SERVER_COMPRESSION_MIN_RESPONSE_SIZE`** — 이 크기 미만 payload 는 압축하지 않음(bytes 또는
단위, 예: `1024` | `1KB` | `2KB`).
- **`APP_SERVER_FORWARD_HEADERS_STRATEGY`** — `none` | `native` | `framework`. 기본값은 `none`.
LB/proxy가 외부 forwarded header를 제거·치환하는 배포에서만 명시적으로 활성화한다.
- **`APP_SERVER_FORWARD_HEADERS_STRATEGY`** — `none` | `native`. 기본값은 `none`.
LB/proxy 뒤 배포는 `native` 로 켜고 `server.tomcat.remoteip.internal-proxies` 로 신뢰할 프록시를
지정한다. `framework` 는 모든 peer 의 헤더를 믿으므로 쓰지 않는다.
- **`APP_SERVER_ERROR_INCLUDE_STACKTRACE`** — `always` | `never` | `on_param`.
- **`APP_SERVER_ERROR_INCLUDE_MESSAGE`** — `always` | `never` | `on_param`.
+5 -9
View File
@@ -96,15 +96,11 @@ application/platform namespace split.
- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`).
**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`·
`jakarta.servlet`·`org.springframework.http` 을 import 하는 것은 **하나도 없다**. 예전에는
`spring-boot-starter-web` 을 production `implementation` 으로 두어 모든 adopter 의
runtimeClasspath 에 Tomcat 을 올리면서, 동시에 같은 artifact 가 `REACTIVE_WEBFLUX` 실행
프로파일을 표방했다 — leaf 와 함께 servlet 컨테이너가 따라오므로 결코 성립할 수 없는 조합이었다.
이제 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를 고정한다
(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
`testCompileClasspath,testRuntimeClasspath` 만). `GraphQlRuntimeTransport` 가 실제 실행 중인
서버를 감지해 `backend.graphql.execution-profile` 과 어긋나면 **부팅을 거부**한다.
`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만
`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를
고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택(D4)이라 실행
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
게이트가 이 선언을 요구한다.
+1 -2
View File
@@ -104,7 +104,7 @@ gRPC 와 달리 spring-graphql / graphql-java 는 Spring Boot BOM 이 관리한
전송 계층 설정(path, graphiql, introspection, schema location)은 프레임워크 `spring.graphql.*`
가 소유한다. composition-root `application.yml` 에서 설정하며 모듈별 `yml` 은 없다.
플랫폼 정책은 `spring.graphql.*` 로 표현할 수 없다 — 실행 프로파일, cost/page 한계, preparsed
플랫폼 정책은 `spring.graphql.*` 로 표현할 수 없다 — cost/page 한계, preparsed
캐시 경계, 관측 label 로 허용할 operation 이름은 전부 이 leaf 의 결정이다. 그래서
`GraphQlPlatformProperties` 가 **`backend.graphql`** prefix 로 `@ConfigurationProperties` 를
바인딩한다(`spring.graphql.platform.*` 이 아니다 — 그 prefix 는 존재한 적이 없다).
@@ -113,7 +113,6 @@ gRPC 와 달리 spring-graphql / graphql-java 는 Spring Boot BOM 이 관리한
backend:
graphql:
deployment-mode: PRODUCTION_INTERNAL
execution-profile: BLOCKING_MVC
validation-policy-version: v1 # preparsed 캐시 키의 일부
console:
graphiql-enabled: false
@@ -114,7 +114,6 @@ public class GraphQlPlatformAutoConfiguration {
GraphQlExecutionPipeline pipeline,
GraphQlScalarWiringConfigurer scalarWiring,
GraphQlClientPolicy clientPolicy,
ObjectProvider<GraphQlRuntimeTransport> transport,
ObjectProvider<GraphQlProperties> frameworkProperties,
Environment environment) {
return () -> {
@@ -128,46 +127,17 @@ public class GraphQlPlatformAutoConfiguration {
pipeline,
scalarWiring,
clientPolicy,
transport.getIfAvailable(() -> GraphQlRuntimeTransport.NONE),
framework == null ? null : framework.getSchema().getIntrospection().isEnabled(),
framework == null ? null : framework.getGraphiql().isEnabled()));
};
}
/**
* Detects a servlet runtime.
*
* <p>Nested conditional configurations rather than a classpath probe in the validator: this is
* exactly the question {@code @ConditionalOnWebApplication} answers, and it answers it the same
* way Spring Boot decides which transport to wire.
*/
@Configuration(proxyBeanMethods = false)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
static class ServletRuntimeDetection {
@Bean
GraphQlRuntimeTransport graphQlRuntimeTransport() {
return GraphQlRuntimeTransport.SERVLET;
}
}
/** Detects a reactive runtime. */
@Configuration(proxyBeanMethods = false)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.REACTIVE)
static class ReactiveRuntimeDetection {
@Bean
GraphQlRuntimeTransport graphQlRuntimeTransport() {
return GraphQlRuntimeTransport.REACTIVE;
}
}
/**
* Caps the raw request body upstream of the JSON decoder, on a servlet stack.
*
* <p>Loaded only where servlets exist. The leaf takes the servlet API as {@code compileOnly}, so
* on a reactive or non-web application this class is simply not on the classpath and the
* condition never matches — which is why the guard is {@code @ConditionalOnClass} as well as
* on a non-web application this class is simply not on the classpath and the condition never
* matches — which is why the guard is {@code @ConditionalOnClass} as well as
* {@code @ConditionalOnWebApplication}.
*/
@Configuration(proxyBeanMethods = false)
@@ -624,8 +594,6 @@ public class GraphQlPlatformAutoConfiguration {
* longer supplies is the machinery around it.
*
* @param factory the loader factory
* @param blockingBridge the bounded hand-off, when a runtime provides one
* @param properties the platform settings, which declare the runtime the loaders will execute on
* @return the registrar
*/
@Bean
@@ -633,15 +601,8 @@ public class GraphQlPlatformAutoConfiguration {
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBatchLoaderRegistrar.class)
public dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBatchLoaderRegistrar
graphQlBatchLoaderRegistrar(
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderFactory factory,
ObjectProvider<dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBlockingBridge>
blockingBridge,
GraphQlPlatformSettings properties) {
// The profile decides where a chunk may run, so the registrar receives it rather than assuming
// the servlet answer. A reactive deployment that registers a blocking loader with no bridge is
// refused at startup instead of discovering it as event-loop starvation.
return new dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBatchLoaderRegistrar(
factory, blockingBridge.getIfAvailable(), properties.executionProfile());
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderFactory factory) {
return new dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBatchLoaderRegistrar(factory);
}
private static String schemaContractHash(ObjectProvider<GraphQlSource> graphQlSource) {
@@ -18,7 +18,6 @@ import java.util.Objects;
* @param pipeline the pipeline that will run, derived from the registered handler chain
* @param scalarWiring the scalar wiring that will be applied to the schema
* @param clientPolicy the limits a request will be measured against
* @param transport the server this context is actually running on
* @param frameworkIntrospectionEnabled {@code spring.graphql.schema.introspection.enabled}, or
* {@code null} when the framework properties are not on the classpath
* @param frameworkGraphiqlEnabled {@code spring.graphql.graphiql.enabled}, or {@code null} when the
@@ -29,7 +28,6 @@ public record GraphQlPlatformRuntime(
GraphQlExecutionPipeline pipeline,
GraphQlScalarWiringConfigurer scalarWiring,
GraphQlClientPolicy clientPolicy,
GraphQlRuntimeTransport transport,
Boolean frameworkIntrospectionEnabled,
Boolean frameworkGraphiqlEnabled) {
@@ -38,6 +36,5 @@ public record GraphQlPlatformRuntime(
Objects.requireNonNull(pipeline, "pipeline is required");
Objects.requireNonNull(scalarWiring, "scalar wiring is required");
Objects.requireNonNull(clientPolicy, "client policy is required");
transport = transport == null ? GraphQlRuntimeTransport.NONE : transport;
}
}
@@ -1,6 +1,5 @@
package dev.caskeleton.adapter.inbound.graphql.autoconfigure;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile;
import java.time.Duration;
import java.util.Set;
import org.springframework.boot.context.properties.ConfigurationProperties;
@@ -22,27 +21,21 @@ import org.springframework.boot.context.properties.bind.DefaultValue;
* internet-facing production endpoint while every protection reading the boolean behaved otherwise.
*
* @param deploymentMode the single safety posture; required, see {@link GraphQlDeploymentMode}
* @param executionProfile runtime execution profile
* @param console query console and introspection exposure
* @param limits page and cost ceilings
* @param unbridgedBlockingResolvers resolvers that block without an approved bridge
*/
@ConfigurationProperties("backend.graphql")
public record GraphQlPlatformSettings(
GraphQlDeploymentMode deploymentMode,
@DefaultValue("BLOCKING_MVC") GraphQlExecutionProfile executionProfile,
@DefaultValue Console console,
@DefaultValue Limits limits,
@DefaultValue("v1") String validationPolicyVersion,
@DefaultValue Set<String> observedOperationNames,
@DefaultValue Set<String> unbridgedBlockingResolvers) {
@DefaultValue Set<String> observedOperationNames) {
public GraphQlPlatformSettings {
// Belt and braces for programmatic construction: the binder honours @DefaultValue, but this
// record is also built directly in tests and by adopters composing a policy in Java.
// deploymentMode is deliberately not defaulted here — see the class Javadoc.
executionProfile =
executionProfile == null ? GraphQlExecutionProfile.BLOCKING_MVC : executionProfile;
console = console == null ? Console.disabled() : console;
limits = limits == null ? Limits.defaults() : limits;
// Part of the preparsed cache key: bumping it invalidates every cached validation, which is
@@ -55,8 +48,6 @@ public record GraphQlPlatformSettings(
// safe default: a cardinality bound that has to be switched on is one nobody has switched on.
observedOperationNames =
observedOperationNames == null ? Set.of() : Set.copyOf(observedOperationNames);
unbridgedBlockingResolvers =
unbridgedBlockingResolvers == null ? Set.of() : Set.copyOf(unbridgedBlockingResolvers);
}
/**
@@ -115,24 +106,16 @@ public record GraphQlPlatformSettings(
public static GraphQlPlatformSettings productionDefaults() {
return new GraphQlPlatformSettings(
GraphQlDeploymentMode.PRODUCTION_INTERNAL,
GraphQlExecutionProfile.BLOCKING_MVC,
Console.disabled(),
Limits.defaults(),
"v1",
Set.of(),
Set.of());
}
/** Returns a copy running under a different deployment mode. */
public GraphQlPlatformSettings withDeploymentMode(GraphQlDeploymentMode mode) {
return new GraphQlPlatformSettings(
mode,
executionProfile,
console,
limits,
validationPolicyVersion,
observedOperationNames,
unbridgedBlockingResolvers);
mode, console, limits, validationPolicyVersion, observedOperationNames);
}
/** Returns a copy with GraphiQL enabled or disabled. */
@@ -148,48 +131,12 @@ public record GraphQlPlatformSettings(
/** Returns a copy with a different console policy. */
public GraphQlPlatformSettings withConsole(Console replacement) {
return new GraphQlPlatformSettings(
deploymentMode,
executionProfile,
replacement,
limits,
validationPolicyVersion,
observedOperationNames,
unbridgedBlockingResolvers);
deploymentMode, replacement, limits, validationPolicyVersion, observedOperationNames);
}
/** Returns a copy with different limits. */
public GraphQlPlatformSettings withLimits(Limits replacement) {
return new GraphQlPlatformSettings(
deploymentMode,
executionProfile,
console,
replacement,
validationPolicyVersion,
observedOperationNames,
unbridgedBlockingResolvers);
}
/** Returns a copy declaring resolvers that block without an approved bridge. */
public GraphQlPlatformSettings withUnbridgedBlockingResolvers(Set<String> coordinates) {
return new GraphQlPlatformSettings(
deploymentMode,
executionProfile,
console,
limits,
validationPolicyVersion,
observedOperationNames,
Set.copyOf(coordinates));
}
/** Returns a copy running a different execution profile. */
public GraphQlPlatformSettings withExecutionProfile(GraphQlExecutionProfile profile) {
return new GraphQlPlatformSettings(
deploymentMode,
profile,
console,
limits,
validationPolicyVersion,
observedOperationNames,
unbridgedBlockingResolvers);
deploymentMode, console, replacement, validationPolicyVersion, observedOperationNames);
}
}
@@ -1,6 +1,5 @@
package dev.caskeleton.adapter.inbound.graphql.autoconfigure;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile;
import dev.caskeleton.shared.runtime.RuntimeEnvironment;
import java.util.ArrayList;
import java.util.Arrays;
@@ -53,13 +52,6 @@ public final class GraphQlPlatformStartupValidator {
if (properties.limits().maximumComplexity() < 1) {
problems.add("maximum complexity must be positive");
}
if (properties.executionProfile() == GraphQlExecutionProfile.REACTIVE_WEBFLUX
&& !properties.unbridgedBlockingResolvers().isEmpty()) {
problems.add(
"blocking resolvers without an executor bridge cannot run on the reactive profile: "
+ new java.util.TreeSet<>(properties.unbridgedBlockingResolvers()));
}
return List.copyOf(problems);
}
@@ -119,25 +111,6 @@ public final class GraphQlPlatformStartupValidator {
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineValidator.problems(
runtime.pipeline()));
if (!runtime.transport().supports(runtime.properties().executionProfile())) {
problems.add(
"backend.graphql.execution-profile is "
+ runtime.properties().executionProfile()
+ " but this context runs on "
+ runtime.transport()
+ "; the composition root chooses the server and the two must agree");
}
// Independent of the declared profile: on an event loop, a resolver that blocks without a
// bridge stalls every other request sharing the thread. MIXED_CONTROLLED is accepted on a
// reactive transport precisely because the crossings are declared, so an undeclared one is the
// condition that makes the profile a lie.
if (runtime.transport() == GraphQlRuntimeTransport.REACTIVE
&& !runtime.properties().unbridgedBlockingResolvers().isEmpty()) {
problems.add(
"resolvers block without an executor bridge on a reactive transport: "
+ new java.util.TreeSet<>(runtime.properties().unbridgedBlockingResolvers()));
}
try {
runtime.scalarWiring().wiredScalars();
} catch (RuntimeException unwirable) {
@@ -1,44 +0,0 @@
package dev.caskeleton.adapter.inbound.graphql.autoconfigure;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile;
/**
* The server this context is actually running on, as opposed to the one it was configured for.
*
* <p>The two used to be unable to disagree, because the leaf shipped an embedded servlet container
* itself — which made {@code REACTIVE_WEBFLUX} a profile nobody could ever run. Now the composition
* root chooses the server, so the two can disagree, and something has to notice.
*/
public enum GraphQlRuntimeTransport {
/** A servlet application: Spring MVC owns the {@code /graphql} route. */
SERVLET,
/** A reactive application: WebFlux owns the {@code /graphql} route. */
REACTIVE,
/** No web server — a plain application context, a test slice, or a batch process. */
NONE;
/**
* Whether an execution profile can run on this transport.
*
* <p>{@link #NONE} accepts every profile: a context with no server has no route to contradict,
* and failing there would break every non-web test that assembles the platform.
*
* <p>{@code MIXED_CONTROLLED} runs on both by definition — it is the profile for a deployment
* that crosses between blocking and reactive work through declared bridges. Accepting it here is
* not a loophole: a reactive context still refuses to start with resolvers that block without a
* bridge, whichever profile is declared.
*/
public boolean supports(GraphQlExecutionProfile profile) {
if (this == NONE || profile == GraphQlExecutionProfile.MIXED_CONTROLLED) {
return true;
}
return switch (this) {
case SERVLET -> profile == GraphQlExecutionProfile.BLOCKING_MVC;
case REACTIVE -> profile == GraphQlExecutionProfile.REACTIVE_WEBFLUX;
case NONE -> true;
};
}
}
@@ -1,21 +0,0 @@
package dev.caskeleton.adapter.inbound.graphql.execution;
/**
* The runtime execution profile (design §10).
*
* <p>{@code MIXED_CONTROLLED} is explicitly not "accept any return type". Mixing blocking and
* reactive work is legitimate, but only across a declared bridge — without one, the same code path
* either blocks an event loop or blocks a request thread waiting on a publisher, and which one it
* does depends on where it happened to be called from.
*/
public enum GraphQlExecutionProfile {
/** Servlet stack with virtual threads or a bounded pool; blocking resolvers are expected. */
BLOCKING_MVC,
/** Reactive stack; blocking work must be bridged off the event loop. */
REACTIVE_WEBFLUX,
/** Both, with every crossing declared through an approved bridge. */
MIXED_CONTROLLED
}
@@ -1,22 +0,0 @@
package dev.caskeleton.adapter.inbound.graphql.execution;
/**
* Raised when a resolver's execution type cannot be served by the active runtime profile.
*
* <p>Thrown at startup or at the transport boundary rather than under load: a blocking repository
* call on a WebFlux event loop does not fail, it starves the loop, and that is far harder to
* diagnose than a refused registration.
*/
public class GraphQlExecutionProfileException extends RuntimeException {
private static final long serialVersionUID = 1L;
/**
* Creates the failure.
*
* @param message description naming the resolver and the conflict
*/
public GraphQlExecutionProfileException(String message) {
super(message);
}
}
@@ -6,13 +6,12 @@ import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchExecutor;
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchTimeoutException;
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderFactory;
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderName;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfileException;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.function.BiFunction;
import org.springframework.graphql.execution.BatchLoaderRegistry;
import reactor.core.publisher.Mono;
/**
* Registers the platform's batch loaders with Spring, so they are the ones a field actually uses.
@@ -27,48 +26,20 @@ import org.springframework.graphql.execution.BatchLoaderRegistry;
* as something the adopter has to remember. What the adopter supplies is the downstream call; what
* this adds is everything that makes it safe to run on a shared request budget.
*
* <p>Where the chunk actually runs is a property of the runtime, so the registrar is told which one
* it is. On a servlet stack the answer is "here": Spring already put the request on a thread, and a
* second pool would only add a queue and a wait. On a reactive stack the same inline call runs on
* the event loop, where one slow downstream stalls every request the loop is serving — so a
* reactive deployment either supplies the bounded bridge or does not get to register a blocking
* loader at all. Refusing at registration makes that a startup failure rather than a latency
* mystery under load.
* <p>The chunk runs on the calling thread. The template is servlet-only (D4): Spring has already
* put the request on a thread, and a second pool would only add a queue and a wait.
*/
public final class GraphQlBatchLoaderRegistrar {
private final GraphQlDataLoaderFactory factory;
private final GraphQlBlockingBridge blockingBridge;
private final GraphQlExecutionProfile profile;
/**
* Creates a registrar that runs loaders on the calling thread.
*
* <p>No scheduler of its own. Spring has already put the request on a thread; handing the work to
* a second pool adds a queue, a wait and a context hop, and buys nothing on a servlet stack.
* Creates the registrar.
*
* @param factory supplies the per-loader batch policy and executor
* @param profile the runtime this deployment declared
*/
public GraphQlBatchLoaderRegistrar(
GraphQlDataLoaderFactory factory, GraphQlExecutionProfile profile) {
this(factory, null, profile);
}
/**
* Creates a registrar that hands blocking loads to a bounded bridge.
*
* @param factory supplies the per-loader batch policy and executor
* @param blockingBridge the bounded hand-off, for a runtime where blocking in place is unsafe
* @param profile the runtime this deployment declared
*/
public GraphQlBatchLoaderRegistrar(
GraphQlDataLoaderFactory factory,
GraphQlBlockingBridge blockingBridge,
GraphQlExecutionProfile profile) {
public GraphQlBatchLoaderRegistrar(GraphQlDataLoaderFactory factory) {
this.factory = Objects.requireNonNull(factory, "data loader factory is required");
this.blockingBridge = blockingBridge;
this.profile = Objects.requireNonNull(profile, "execution profile is required");
}
/**
@@ -89,12 +60,6 @@ public final class GraphQlBatchLoaderRegistrar {
GraphQlDataLoaderName loaderName,
BiFunction<List<K>, GraphQlBatchContext, Map<K, V>> loadChunk) {
if (profile != GraphQlExecutionProfile.BLOCKING_MVC && blockingBridge == null) {
throw new GraphQlExecutionProfileException(
"loader "
+ loaderName.value()
+ " would block the event loop; declare a bounded blocking bridge");
}
GraphQlBatchExecutor executor = factory.executorFor(loaderName);
registry
@@ -108,21 +73,11 @@ public final class GraphQlBatchLoaderRegistrar {
if (context == null) {
// Fail closed. A loader running without the platform context has no deadline, no
// tenant and no actor, and would happily batch across whatever the caller was.
return reactor.core.publisher.Mono.error(
new GraphQlBatchTimeoutException(loaderName.value()));
return Mono.error(new GraphQlBatchTimeoutException(loaderName.value()));
}
GraphQlBatchContext batchContext = factory.batchContext(context);
reactor.core.publisher.Mono<Map<K, V>> load =
reactor.core.publisher.Mono.fromCallable(
() -> executor.load(List.copyOf(keys), batchContext, loadChunk));
// Inline unless an adopter asked for the bridge. `supplyAsync` would have used the
// common ForkJoinPool: a shared, unbounded-admission scheduler with no relationship
// to the request budget, which is the second queue this platform exists to avoid.
return blockingBridge == null
? load
: load.subscribeOn(
reactor.core.scheduler.Schedulers.fromExecutor(
blockingBridge.executorFor(context)));
return Mono.fromCallable(
() -> executor.load(List.copyOf(keys), batchContext, loadChunk));
});
}
}
@@ -1,93 +0,0 @@
package dev.caskeleton.adapter.inbound.graphql.runtime;
import dev.caskeleton.adapter.inbound.graphql.context.GraphQlRequestContext;
import dev.caskeleton.adapter.inbound.graphql.security.GraphQlContextPropagator;
import java.util.Objects;
import java.util.concurrent.ArrayBlockingQueue;
import java.util.concurrent.Executor;
import java.util.concurrent.RejectedExecutionException;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;
/**
* An opt-in, bounded hand-off for blocking work, carrying the request context with it.
*
* <p>Bounded on both axes, because a pool is only half of it. A virtual-thread-per-task executor
* limits nothing: it accepts every task and the bound becomes whatever the downstream system will
* tolerate. A fixed pool bounds threads and then queues without limit, which converts an overload
* into unbounded memory and latency rather than into a refusal. Here both the pool and the queue
* are finite and a full bridge refuses immediately, which is the answer a caller can act on.
*
* <p>Opt-in on purpose. The platform schedules nothing by default: work runs on the thread Spring
* already gave it, so there is one scheduler and one queue rather than two of each with a wait
* between them. A bridge exists for the case an adopter genuinely has — blocking work that must
* leave an event loop — and then it is explicit, sized, and visible.
*
* <p>The context travels through {@link GraphQlContextPropagator}, so the thread local is bound on
* the bridge thread and unbound afterwards. Reading the thread local is what a blocking library
* does; the GraphQL context remains the source of truth, and this only mirrors it for the duration
* of the hand-off.
*/
public final class GraphQlBlockingBridge implements AutoCloseable {
private final ThreadPoolExecutor executor;
private GraphQlBlockingBridge(ThreadPoolExecutor executor) {
this.executor = executor;
}
/**
* Creates a bridge with a finite pool and a finite queue.
*
* @param threads how many blocking calls may run at once
* @param queueDepth how many may wait; beyond this the bridge refuses
*/
public static GraphQlBlockingBridge bounded(int threads, int queueDepth) {
if (threads < 1 || queueDepth < 1) {
throw new IllegalArgumentException("a blocking bridge needs a positive pool and queue");
}
ThreadPoolExecutor executor =
new ThreadPoolExecutor(
threads,
threads,
0,
TimeUnit.MILLISECONDS,
new ArrayBlockingQueue<>(queueDepth),
runnable -> Thread.ofVirtual().name("graphql-blocking-bridge-", 0).unstarted(runnable),
new ThreadPoolExecutor.AbortPolicy());
return new GraphQlBlockingBridge(executor);
}
/** How many blocking calls may run at once. */
public int threads() {
return executor.getMaximumPoolSize();
}
/** How many may wait before the bridge refuses. */
public int queueDepth() {
return executor.getQueue().remainingCapacity() + executor.getQueue().size();
}
/**
* The executor, with the context bound around every task.
*
* @param context the request context to bind on the bridge thread
*/
public Executor executorFor(GraphQlRequestContext context) {
Objects.requireNonNull(context, "request context is required");
return task -> {
try {
executor.execute(() -> GraphQlContextPropagator.wrap(context, task).run());
} catch (RejectedExecutionException full) {
// Refusing is the point. Growing the queue here would turn an overload into latency that
// the request deadline has to discover later, by which time the work is already queued.
throw new GraphQlBlockingBridgeFullException(threads(), queueDepth());
}
};
}
@Override
public void close() {
executor.shutdownNow();
}
}
@@ -1,28 +0,0 @@
package dev.caskeleton.adapter.inbound.graphql.runtime;
/**
* Raised when the blocking bridge has no capacity left.
*
* <p>A refusal rather than a wait. An unbounded queue turns an overload into latency that only the
* request deadline discovers, by which time the work is already queued behind everything else and
* the client has been waiting for all of it.
*
* <p>Carries the configured bounds, never a key, an actor or a tenant.
*/
public class GraphQlBlockingBridgeFullException extends RuntimeException {
private static final long serialVersionUID = 1L;
/** Stable error code clients and operators see. */
public static final String CODE = "GRAPHQL_BLOCKING_BRIDGE_FULL";
/**
* Creates the failure.
*
* @param threads configured concurrency
* @param queueDepth configured queue depth
*/
public GraphQlBlockingBridgeFullException(int threads, int queueDepth) {
super(CODE + ": threads=" + threads + ", queue=" + queueDepth);
}
}
@@ -13,6 +13,8 @@ import graphql.language.InlineFragment;
import graphql.language.OperationDefinition;
import graphql.language.Selection;
import graphql.language.SelectionSet;
import graphql.schema.GraphQLObjectType;
import graphql.schema.GraphQLSchema;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
@@ -63,7 +65,7 @@ public final class GraphQlDocumentAuthorizationHandler implements GraphQlExecuti
analyzer.verifyIntrospection(
context.requireDocument(), operation, policy.introspectionAllowed());
String rootTypeName = rootTypeName(operation);
String rootTypeName = rootTypeName(context.schema(), operation);
for (String fieldName : rootFieldNames(context, operation, analyzer.maximumVisitedNodes())) {
authorization.authorize(
context.requestContext(), new GraphQlSchemaCoordinate(rootTypeName, fieldName));
@@ -71,16 +73,35 @@ public final class GraphQlDocumentAuthorizationHandler implements GraphQlExecuti
return context;
}
private static String rootTypeName(OperationDefinition operation) {
/**
* The root type name the schema actually declares for this operation.
*
* <p>Read from the schema, never assumed. {@code schema { query: RootQuery }} is legal, and a
* rule written against {@code RootQuery.adminReport} must be the rule this stage consults — a
* literal {@code "Query"} would look up a coordinate nobody wrote, and an allow-by-default policy
* would then allow the field its rule restricts.
*
* @throws IllegalStateException when there is no schema or it declares no such root; both fail
* the request closed rather than authorize against a guessed name
*/
private static String rootTypeName(GraphQLSchema schema, OperationDefinition operation) {
OperationDefinition.Operation kind =
operation.getOperation() == null
? OperationDefinition.Operation.QUERY
: operation.getOperation();
return switch (kind) {
case QUERY -> "Query";
case MUTATION -> "Mutation";
case SUBSCRIPTION -> "Subscription";
};
if (schema == null) {
throw new IllegalStateException("no schema is available to name the root type of " + kind);
}
GraphQLObjectType root =
switch (kind) {
case QUERY -> schema.getQueryType();
case MUTATION -> schema.getMutationType();
case SUBSCRIPTION -> schema.getSubscriptionType();
};
if (root == null) {
throw new IllegalStateException("the schema declares no root type for " + kind);
}
return root.getName();
}
/**
@@ -11,7 +11,6 @@ backend:
# 켠 상태에서 필수이고 runtime 환경과 맞아야 한다
# (local->LOCAL, dev->DEV, prod->PRODUCTION_INTERNAL|PRODUCTION_PUBLIC).
deployment-mode: ${APP_GRAPHQL_DEPLOYMENT_MODE:}
execution-profile: ${APP_GRAPHQL_EXECUTION_PROFILE:BLOCKING_MVC}
validation-policy-version: ${APP_GRAPHQL_VALIDATION_POLICY_VERSION:v1}
observed-operation-names: ${APP_GRAPHQL_OBSERVED_OPERATION_NAMES:}
console:
@@ -203,7 +203,6 @@ class GraphQlPlatformAutoConfigurationTest {
.contains("backend.graphql.deployment-mode")
.doesNotContain("backend.graphql.production")
.doesNotContain("backend.graphql.environment")
.contains("backend.graphql.execution-profile")
.contains("backend.graphql.console.graphiql-enabled")
.contains("backend.graphql.console.introspection-enabled")
.contains("backend.graphql.limits.maximum-page-size")
@@ -211,7 +210,9 @@ class GraphQlPlatformAutoConfigurationTest {
// Keys that only failed the boot or were echoed back unused were removed (2026-09-25).
.doesNotContain("backend.graphql.cursor.key-ids")
.doesNotContain("backend.graphql.unsupported.multipart-upload")
.contains("backend.graphql.unbridged-blocking-resolvers");
// Servlet-only template (D4): no reactive profile to choose, no event loop to bridge off.
.doesNotContain("backend.graphql.execution-profile")
.doesNotContain("backend.graphql.unbridged-blocking-resolvers");
}
private static GraphQlProperties frameworkDefaults() {
@@ -4,8 +4,6 @@ import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile;
import java.util.Set;
import org.junit.jupiter.api.Test;
/** Starter configuration and startup validation (Stable plan Task 46). */
@@ -40,17 +38,6 @@ class GraphQlPlatformStartupValidatorTest {
assertThat(new GraphQlPlatformStartupValidator().problems(properties)).hasSize(3);
}
@Test
void aBlockingResolverWithoutABridgeCannotRunOnTheReactiveProfile() {
var properties =
GraphQlPlatformSettings.productionDefaults()
.withExecutionProfile(GraphQlExecutionProfile.REACTIVE_WEBFLUX)
.withUnbridgedBlockingResolvers(Set.of("Order.total"));
assertThat(new GraphQlPlatformStartupValidator().problems(properties))
.anySatisfy(problem -> assertThat(problem).contains("Order.total"));
}
@Test
void introspectionAndGraphiqlFollowTheDeploymentMode() {
assertThat(GraphQlDeploymentMode.LOCAL.graphiqlAllowed()).isTrue();
@@ -2,7 +2,6 @@ package dev.caskeleton.adapter.inbound.graphql.autoconfigure;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
@@ -10,24 +9,15 @@ import java.nio.file.Path;
import java.util.List;
import java.util.Locale;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.boot.test.context.runner.ReactiveWebApplicationContextRunner;
import org.springframework.boot.test.context.runner.WebApplicationContextRunner;
/**
* The leaf must not decide which server an adopter runs.
*
* <p>This artifact used to depend on {@code spring-boot-starter-web}, which put an embedded Tomcat
* on every adopter's runtime classpath — while the same artifact advertised a {@code
* REACTIVE_WEBFLUX} execution profile that could never have been honoured. Not one production file
* imports a servlet or {@code org.springframework.web} type, so the dependency bought nothing and
* cost adopters a server they may not have wanted.
*
* <p>Two checks, because each catches what the other cannot. The lockfile assertion catches a
* transitive server sneaking back onto the runtime classpath, which no test that boots a context
* can see. The context assertions catch a deployment whose declared profile does not match the
* server it is actually running on, which the lockfile has no opinion about.
* on every adopter's runtime classpath. Not one production file imports a servlet or {@code
* org.springframework.web} type, so the dependency bought nothing and cost adopters a server they
* may not have wanted. The lockfile assertion catches a transitive server sneaking back onto the
* runtime classpath, which no test that boots a context can see.
*/
class GraphQlTransportNeutralityTest {
@@ -61,113 +51,6 @@ class GraphQlTransportNeutralityTest {
line -> assertThat(line).startsWith("org.springframework.graphql:spring-graphql"));
}
@Test
void aNonWebContextAcceptsAnyProfile() {
new ApplicationContextRunner()
.withPropertyValues("backend.graphql.enabled=true", "backend.graphql.deployment-mode=LOCAL")
.withConfiguration(AutoConfigurations.of(GraphQlRootAutoConfiguration.class))
.withPropertyValues(
"backend.graphql.enabled=true", "backend.graphql.execution-profile=REACTIVE_WEBFLUX")
.run(context -> assertThat(context).hasNotFailed());
}
@Test
void aServletContextRunningTheReactiveProfileRefusesToStart() {
new WebApplicationContextRunner()
.withPropertyValues("backend.graphql.enabled=true", "backend.graphql.deployment-mode=LOCAL")
.withConfiguration(AutoConfigurations.of(GraphQlRootAutoConfiguration.class))
.withPropertyValues(
"backend.graphql.enabled=true", "backend.graphql.execution-profile=REACTIVE_WEBFLUX")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.rootCause()
.hasMessageContaining("this context runs on SERVLET"));
}
@Test
void aReactiveContextRunningTheBlockingProfileRefusesToStart() {
new ReactiveWebApplicationContextRunner()
.withPropertyValues("backend.graphql.enabled=true", "backend.graphql.deployment-mode=LOCAL")
.withConfiguration(AutoConfigurations.of(GraphQlRootAutoConfiguration.class))
.withPropertyValues(
"backend.graphql.enabled=true", "backend.graphql.execution-profile=BLOCKING_MVC")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.rootCause()
.hasMessageContaining("this context runs on REACTIVE"));
}
@Test
void aServletContextRunningTheBlockingProfileStarts() {
new WebApplicationContextRunner()
.withPropertyValues("backend.graphql.enabled=true", "backend.graphql.deployment-mode=LOCAL")
.withConfiguration(AutoConfigurations.of(GraphQlRootAutoConfiguration.class))
.withPropertyValues(
"backend.graphql.enabled=true", "backend.graphql.execution-profile=BLOCKING_MVC")
.run(
context -> {
assertThat(context).hasNotFailed();
assertThat(context.getBean(GraphQlRuntimeTransport.class))
.isEqualTo(GraphQlRuntimeTransport.SERVLET);
});
}
@Test
void aReactiveContextRunningTheReactiveProfileStarts() {
new ReactiveWebApplicationContextRunner()
.withPropertyValues("backend.graphql.enabled=true", "backend.graphql.deployment-mode=LOCAL")
.withConfiguration(AutoConfigurations.of(GraphQlRootAutoConfiguration.class))
.withPropertyValues(
"backend.graphql.enabled=true", "backend.graphql.execution-profile=REACTIVE_WEBFLUX")
.run(
context -> {
assertThat(context).hasNotFailed();
assertThat(context.getBean(GraphQlRuntimeTransport.class))
.isEqualTo(GraphQlRuntimeTransport.REACTIVE);
});
}
@Test
void everyProfileNamesTheTransportItCanRunOn() {
assertThat(GraphQlRuntimeTransport.SERVLET.supports(GraphQlExecutionProfile.BLOCKING_MVC))
.isTrue();
assertThat(GraphQlRuntimeTransport.SERVLET.supports(GraphQlExecutionProfile.REACTIVE_WEBFLUX))
.isFalse();
assertThat(GraphQlRuntimeTransport.REACTIVE.supports(GraphQlExecutionProfile.REACTIVE_WEBFLUX))
.isTrue();
assertThat(GraphQlRuntimeTransport.REACTIVE.supports(GraphQlExecutionProfile.BLOCKING_MVC))
.isFalse();
for (GraphQlRuntimeTransport transport : GraphQlRuntimeTransport.values()) {
assertThat(transport.supports(GraphQlExecutionProfile.MIXED_CONTROLLED))
.as("MIXED_CONTROLLED is the profile for a deployment that runs on both")
.isTrue();
}
}
@Test
void aReactiveContextWithUnbridgedBlockingResolversRefusesToStart() {
new ReactiveWebApplicationContextRunner()
.withPropertyValues("backend.graphql.enabled=true", "backend.graphql.deployment-mode=LOCAL")
.withConfiguration(AutoConfigurations.of(GraphQlRootAutoConfiguration.class))
.withPropertyValues(
"backend.graphql.execution-profile=MIXED_CONTROLLED",
"backend.graphql.unbridged-blocking-resolvers=Order.total")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.rootCause()
.hasMessageContaining("block without an executor bridge on a reactive"));
}
private static boolean onProductionClasspath(String line) {
int separator = line.indexOf('=');
if (separator < 0) {
@@ -1,7 +1,6 @@
package dev.caskeleton.adapter.inbound.graphql.runtime;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.adapter.inbound.graphql.context.GraphQlDeadline;
import dev.caskeleton.adapter.inbound.graphql.context.GraphQlRequestContext;
@@ -12,9 +11,6 @@ import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchPolicyRegis
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderFactory;
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderName;
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyPolicy;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile;
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfileException;
import dev.caskeleton.adapter.inbound.graphql.security.GraphQlContextPropagator;
import dev.caskeleton.adapter.inbound.graphql.testkit.GraphQlRequestContexts;
import graphql.ExecutionInput;
import graphql.ExecutionResult;
@@ -202,45 +198,6 @@ class GraphQlBatchLoaderRegistrationTest {
.isNotEmpty();
}
@Test
void aReactiveRuntimeWithoutABridgeRefusesTheLoader() {
GraphQlBatchLoaderRegistrar registrar =
new GraphQlBatchLoaderRegistrar(
factory(chunkSize(20), Clock.systemUTC()), GraphQlExecutionProfile.REACTIVE_WEBFLUX);
assertThatThrownBy(
() ->
registrar.<String, Map<String, Object>>register(
new DefaultBatchLoaderRegistry(), LOADER, (keys, batchContext) -> Map.of()))
.as("an inline blocking chunk on an event loop stalls every request that loop is serving")
.isInstanceOf(GraphQlExecutionProfileException.class);
}
@Test
void aBridgedLoaderRunsOffTheCallingThreadAndStillSeesTheRequest() {
RecordingLoader downstream = new RecordingLoader();
try (GraphQlBlockingBridge bridge = GraphQlBlockingBridge.bounded(1, 4)) {
Fixture fixture =
new Fixture(
new GraphQlBatchLoaderRegistrar(
factory(chunkSize(20), Clock.systemUTC()),
bridge,
GraphQlExecutionProfile.REACTIVE_WEBFLUX),
"tenant-a",
Clock.systemUTC());
ExecutionResult result = fixture.execute(orders(5, 5), downstream);
assertThat(result.getErrors()).isEmpty();
assertThat(downstream.observedThreads)
.as("the bridge exists to move the blocking call off the thread that subscribed")
.doesNotContain(Thread.currentThread().getName());
assertThat(downstream.observedBoundContexts)
.as("a batch that arrives on the bridge thread with no context has no tenant")
.containsExactly(Boolean.TRUE);
}
}
@Test
void aServletRuntimeLoadsOnTheThreadItWasGiven() {
RecordingLoader downstream = new RecordingLoader();
@@ -267,11 +224,7 @@ class GraphQlBatchLoaderRegistrationTest {
}
private static Fixture fixture(GraphQlBatchPolicy policy, Clock clock, String tenant) {
return new Fixture(
new GraphQlBatchLoaderRegistrar(
factory(policy, clock), GraphQlExecutionProfile.BLOCKING_MVC),
tenant,
clock);
return new Fixture(new GraphQlBatchLoaderRegistrar(factory(policy, clock)), tenant, clock);
}
private static GraphQlDataLoaderFactory factory(GraphQlBatchPolicy policy, Clock clock) {
@@ -305,7 +258,6 @@ class GraphQlBatchLoaderRegistrationTest {
private final Set<String> observedScopes = new LinkedHashSet<>();
private Runnable onCall = () -> {};
private final Set<String> observedThreads = new LinkedHashSet<>();
private final Set<Boolean> observedBoundContexts = new LinkedHashSet<>();
private String extraKey;
private String nullValueKey;
private String omittedKey;
@@ -315,7 +267,6 @@ class GraphQlBatchLoaderRegistrationTest {
requestedKeys.addAll(keys);
observedScopes.add(context.cacheScope());
observedThreads.add(Thread.currentThread().getName());
observedBoundContexts.add(GraphQlContextPropagator.current().isPresent());
onCall.run();
Map<String, Map<String, Object>> rows = new LinkedHashMap<>();
for (String key : keys) {
@@ -1,118 +0,0 @@
package dev.caskeleton.adapter.inbound.graphql.runtime;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.adapter.inbound.graphql.context.GraphQlRequestContext;
import dev.caskeleton.adapter.inbound.graphql.security.GraphQlContextPropagator;
import dev.caskeleton.adapter.inbound.graphql.testkit.GraphQlRequestContexts;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicReference;
import org.junit.jupiter.api.Test;
/**
* A hand-off that refuses is bounded; one that queues is not.
*
* <p>The platform previously offered two "bounded" executors that were not: a
* virtual-thread-per-task executor, which admits every task, and a fixed pool, whose default {@code
* LinkedBlockingQueue} is unbounded — so an overload became latency and memory instead of a
* refusal, and the request deadline was the only thing that ever noticed.
*/
class GraphQlBlockingBridgeTest {
private final GraphQlRequestContext context = GraphQlRequestContexts.testContext("tenant-a");
@Test
void aFullBridgeRefusesInsteadOfQueueing() throws Exception {
CountDownLatch occupied = new CountDownLatch(1);
CountDownLatch release = new CountDownLatch(1);
try (GraphQlBlockingBridge bridge = GraphQlBlockingBridge.bounded(1, 1)) {
bridge
.executorFor(context)
.execute(
() -> {
occupied.countDown();
try {
release.await(5, TimeUnit.SECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
}
});
assertThat(occupied.await(5, TimeUnit.SECONDS)).isTrue();
// One running, one queued: the bridge is now full.
bridge.executorFor(context).execute(() -> {});
assertThatThrownBy(() -> bridge.executorFor(context).execute(() -> {}))
.isInstanceOf(GraphQlBlockingBridgeFullException.class)
.hasMessageContaining(GraphQlBlockingBridgeFullException.CODE);
release.countDown();
}
}
@Test
void theRequestContextTravelsWithTheWork() throws Exception {
AtomicReference<GraphQlRequestContext> seen = new AtomicReference<>();
CountDownLatch done = new CountDownLatch(1);
try (GraphQlBlockingBridge bridge = GraphQlBlockingBridge.bounded(1, 1)) {
bridge
.executorFor(context)
.execute(
() -> {
seen.set(GraphQlContextPropagator.current().orElse(null));
done.countDown();
});
assertThat(done.await(5, TimeUnit.SECONDS)).isTrue();
}
assertThat(seen.get())
.as("a batch load that hopped threads without its context has no tenant")
.isNotNull();
assertThat(seen.get().tenant().value()).isEqualTo("tenant-a");
}
@Test
void theContextDoesNotLeakIntoAPooledThreadAfterwards() throws Exception {
AtomicReference<Boolean> boundAfterwards = new AtomicReference<>();
CountDownLatch first = new CountDownLatch(1);
CountDownLatch second = new CountDownLatch(1);
try (GraphQlBlockingBridge bridge = GraphQlBlockingBridge.bounded(1, 2)) {
bridge.executorFor(context).execute(first::countDown);
assertThat(first.await(5, TimeUnit.SECONDS)).isTrue();
// A raw task on the same pool: nothing should still be bound to that thread.
bridge
.executorFor(context)
.execute(
() -> {
boundAfterwards.set(GraphQlContextPropagator.current().isPresent());
second.countDown();
});
assertThat(second.await(5, TimeUnit.SECONDS)).isTrue();
}
assertThat(boundAfterwards.get())
.as("the propagator binds for the task and restores afterwards")
.isTrue();
}
@Test
void aBridgeMustBeGivenPositiveBounds() {
assertThatThrownBy(() -> GraphQlBlockingBridge.bounded(0, 1))
.isInstanceOf(IllegalArgumentException.class);
assertThatThrownBy(() -> GraphQlBlockingBridge.bounded(1, 0))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void theBoundsAreReadableForOperations() {
try (GraphQlBlockingBridge bridge = GraphQlBlockingBridge.bounded(4, 16)) {
assertThat(bridge.threads()).isEqualTo(4);
assertThat(bridge.queueDepth()).isEqualTo(16);
}
}
}
@@ -14,8 +14,12 @@ import dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationInter
import dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationPolicy;
import dev.caskeleton.adapter.inbound.graphql.testkit.GraphQlRequestContexts;
import graphql.parser.Parser;
import graphql.schema.GraphQLSchema;
import graphql.schema.idl.SchemaParser;
import graphql.schema.idl.UnExecutableSchemaGenerator;
import java.time.Duration;
import java.util.Map;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
@@ -37,6 +41,27 @@ class GraphQlDocumentAuthorizationHandlerTest {
GraphQlSchemaCoordinate.parse("Query.adminReport"), new GraphQlClientProfile("admin"))
.build();
private static final GraphQLSchema DEFAULT_ROOTS_SCHEMA =
schema(
"type Query { health: String adminReport: String a: String b: String c: String d: String }");
/** An adopter is free to name its roots; the rule is written against the names it chose. */
private static final GraphQLSchema RENAMED_ROOTS_SCHEMA =
schema(
"schema { query: RootQuery mutation: RootMutation } "
+ "type RootQuery { adminReport: String } type RootMutation { purge: String }");
private static final GraphQlAuthorizationPolicy RENAMED_ROOTS_FOR_ADMINS_ONLY =
GraphQlAuthorizationPolicy.builder()
.denyByDefault(false)
.allow(
GraphQlSchemaCoordinate.parse("RootQuery.adminReport"),
new GraphQlClientProfile("admin"))
.allow(
GraphQlSchemaCoordinate.parse("RootMutation.purge"),
new GraphQlClientProfile("admin"))
.build();
@Test
void exponentialFragmentFanOutIsAuthorizedWithinTheTimeBound() {
// given
@@ -76,6 +101,43 @@ class GraphQlDocumentAuthorizationHandlerTest {
.hasMessage("GraphQL authorization denied: COORDINATE_NOT_AUTHORIZED");
}
@ParameterizedTest
@ValueSource(strings = {"query Q { adminReport }", "mutation Q { purge }"})
@DisplayName("root 타입 이름을 바꾼 schema 에서도 보호된 root field 는 그 이름의 규칙으로 거부된다")
void aProtectedFieldOnARenamedRootTypeIsStillDenied(String document) {
// given
GraphQlDocumentAuthorizationHandler handler =
new GraphQlDocumentAuthorizationHandler(
new GraphQlAuthorizationInterceptor(RENAMED_ROOTS_FOR_ADMINS_ONLY),
new GraphQlDocumentShapeAnalyzer(),
GraphQlClientPolicy.defaults(100, 10_000, false));
GraphQlExecutionContext selected = selected(document, RENAMED_ROOTS_SCHEMA);
// when
Throwable thrown = catchThrowable(() -> handler.handle(selected));
// then
assertThat(thrown)
.isInstanceOf(GraphQlAuthorizationDeniedException.class)
.hasMessage("GraphQL authorization denied: COORDINATE_NOT_AUTHORIZED");
}
@Test
void aContextWithoutASchemaIsRefusedInsteadOfGuessingRootNames() {
// given
GraphQlDocumentAuthorizationHandler handler =
handler(new GraphQlDocumentShapeAnalyzer(), false);
GraphQlExecutionContext selected = selected("query Q { health }", null);
// when
Throwable thrown = catchThrowable(() -> handler.handle(selected));
// then
assertThat(thrown)
.isInstanceOf(IllegalStateException.class)
.hasMessage("no schema is available to name the root type of QUERY");
}
@ParameterizedTest
@ValueSource(booleans = {true, false})
void aDocumentBeyondTheTraversalBudgetIsRejectedAsTooComplex(boolean introspectionAllowed) {
@@ -105,16 +167,24 @@ class GraphQlDocumentAuthorizationHandlerTest {
}
private static GraphQlExecutionContext selected(String document) {
return selected(document, DEFAULT_ROOTS_SCHEMA);
}
private static GraphQlExecutionContext selected(String document, GraphQLSchema schema) {
GraphQlExecutionContext starting =
GraphQlExecutionContext.starting(
new GraphQlExecutionRequest(document, "Q", Map.of(), document.length(), 0),
GraphQlRequestContexts.testContext("tenant-a"),
null,
schema,
Parser.parse(document));
return new GraphQlOperationSelectionHandler(GraphQlClientPolicy.defaults(100, 10_000, false))
.handle(starting);
}
private static GraphQLSchema schema(String sdl) {
return UnExecutableSchemaGenerator.makeUnExecutableSchema(new SchemaParser().parse(sdl));
}
/** {@code F0} spreads {@code F1} twice, and so on: {@code levels} levels, 2^levels leaf paths. */
private static String doublingFragments(int levels) {
StringBuilder document = new StringBuilder("query Q { ...F0 }");
@@ -57,17 +57,18 @@ public final class TusRequestParser {
/**
* Reads the declared final length.
*
* <p>{@code Upload-Defer-Length: 1} means the client will declare it later, which is legal and
* distinct from a length of zero.
* <p>{@code Upload-Defer-Length} is refused. It belongs to the {@code creation-defer-length}
* extension, which this server does not advertise because no PATCH here can declare the length
* later — an upload created that way could never be finalized.
*/
public OptionalLong declaredLength(HttpServletRequest request) {
if ("1".equals(request.getHeader(TusHeaders.UPLOAD_DEFER_LENGTH))) {
return OptionalLong.empty();
if (request.getHeader(TusHeaders.UPLOAD_DEFER_LENGTH) != null) {
throw MalformedRequestException.of(
"Upload-Defer-Length is not supported; declare Upload-Length on creation");
}
String header = request.getHeader(TusHeaders.UPLOAD_LENGTH);
if (header == null || header.isBlank()) {
throw MalformedRequestException.of(
"tus creation requires Upload-Length or Upload-Defer-Length");
throw MalformedRequestException.of("tus creation requires Upload-Length");
}
long length = parseNonNegative(header);
if (length > properties.maxSize()) {
@@ -80,6 +80,7 @@ public final class RecordingAdminService implements FileserverAdminService {
0,
"",
null,
Optional.empty(),
1));
}
@@ -12,6 +12,7 @@ import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadService;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.UUID;
/** Records which uploads a protocol adapter decided to finalize. */
@@ -43,6 +44,7 @@ public final class RecordingFinalizeService implements FinalizeUploadService {
0,
"",
FileserverWebFixtures.NOW,
Optional.empty(),
1));
}
}
@@ -18,6 +18,7 @@ import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.UUID;
import java.util.function.Function;
@@ -106,6 +107,7 @@ public final class RecordingUploadService implements SingleShotUploadService {
body.length(),
"c".repeat(64),
Instant.parse("2026-08-07T10:00:00Z"),
Optional.empty(),
1);
return FileView.of(descriptor);
}
@@ -30,6 +30,7 @@ import java.time.Instant;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Optional;
import java.util.UUID;
/** Download service backed by an in-memory immutable representation. */
@@ -121,6 +122,7 @@ public final class StubDownloadService implements DownloadApplicationService {
content.length,
DIGEST,
PUBLISHED_AT,
Optional.empty(),
1);
}
@@ -127,23 +127,22 @@ class TusProtocolContractTest {
assertThat(finalizeService.finalized()).containsExactly(uploadIdOf(location));
}
/**
* No PATCH can declare the length later, so a deferred-length upload could never finish. The
* {@code creation-defer-length} extension is not advertised, and a request that assumes it is
* refused before a resource exists.
*/
@Test
void aDeferredLengthUploadIsNeverAutoFinalized() throws Exception {
String location =
void aCreateThatDefersItsLengthIsRefusedBecauseTheExtensionIsNotOffered() throws Exception {
// when
ResultActions created =
mvc.perform(
post("/v1/uploads")
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_DEFER_LENGTH, "1"))
.andExpect(status().isCreated())
.andReturn()
.getResponse()
.getHeader("Location");
post("/v1/uploads")
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_DEFER_LENGTH, "1"));
appendAt(location, 0, "abc");
assertThat(finalizeService.finalized()).isEmpty();
mvc.perform(head(location).header(TusHeaders.RESUMABLE, "1.0.0"))
.andExpect(header().string(TusHeaders.UPLOAD_DEFER_LENGTH, "1"));
// then
created.andExpect(status().isBadRequest());
}
@Test
@@ -3,6 +3,7 @@ package dev.caskeleton.adapter.inbound.web.notification.platform.callback;
import dev.caskeleton.adapter.inbound.web.core.OwnsAbsoluteWebRoute;
import dev.caskeleton.application.notification.platform.api.error.CallbackValidationException;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.Objects;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
@@ -12,7 +13,6 @@ import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@@ -73,13 +73,22 @@ public final class NotificationCallbackMvcController {
*/
public static final int MAX_STORABLE_BODY_BYTES = 65_536 - 28;
/** Receive one provider callback. */
/**
* Receive one provider callback.
*
* <p>The body is read here, not bound: this path is unauthenticated until the signature is
* checked, so a converter that buffers the whole body first would let anyone make the server hold
* whatever they send. A declared oversize is refused before a byte is read; a chunked or
* understated one after one byte past the ceiling.
*/
@PostMapping(path = "/{provider}/{profile}")
public ResponseEntity<Void> callback(
@PathVariable String provider,
@PathVariable String profile,
HttpServletRequest request,
@RequestBody byte[] body) {
@PathVariable String provider, @PathVariable String profile, HttpServletRequest request)
throws IOException {
if (request.getContentLengthLong() > maxBodyBytes) {
return ResponseEntity.status(HttpStatus.CONTENT_TOO_LARGE).build();
}
byte[] body = request.getInputStream().readNBytes(maxBodyBytes + 1);
if (body.length > maxBodyBytes) {
return ResponseEntity.status(HttpStatus.CONTENT_TOO_LARGE).build();
}
@@ -56,7 +56,7 @@ class NotificationCallbackMvcControllerTest {
assertThatThrownBy(
() ->
controller.callback(
"twilio", "twilio-primary", request("application/x-www-form-urlencoded"), body))
"twilio", "twilio-primary", request("application/x-www-form-urlencoded", body)))
.isInstanceOf(CallbackValidationException.class);
assertThat(received).hasSize(1);
@@ -67,15 +67,12 @@ class NotificationCallbackMvcControllerTest {
@Test
void aForwardedHostFromAnUntrustedPeerIsIgnored() {
var request = request("application/json");
var request = request("application/json", "{}".getBytes(StandardCharsets.UTF_8));
request.setRemoteAddr("203.0.113.9");
request.addHeader("X-Forwarded-Proto", "https");
request.addHeader("X-Forwarded-Host", "attacker.example.com");
assertThatThrownBy(
() ->
controller.callback(
"twilio", "twilio-primary", request, "{}".getBytes(StandardCharsets.UTF_8)))
assertThatThrownBy(() -> controller.callback("twilio", "twilio-primary", request))
.isInstanceOf(CallbackValidationException.class);
assertThat(received.getFirst().externalUrl()).doesNotContain("attacker.example.com");
@@ -83,15 +80,12 @@ class NotificationCallbackMvcControllerTest {
@Test
void aForwardedHostFromATrustedProxyBecomesTheCanonicalUrl() {
var request = request("application/json");
var request = request("application/json", "{}".getBytes(StandardCharsets.UTF_8));
request.setRemoteAddr(TRUSTED_PROXY);
request.addHeader("X-Forwarded-Proto", "https");
request.addHeader("X-Forwarded-Host", "callback.example.com");
assertThatThrownBy(
() ->
controller.callback(
"twilio", "twilio-primary", request, "{}".getBytes(StandardCharsets.UTF_8)))
assertThatThrownBy(() -> controller.callback("twilio", "twilio-primary", request))
.isInstanceOf(CallbackValidationException.class);
assertThat(received.getFirst().externalUrl())
@@ -101,13 +95,10 @@ class NotificationCallbackMvcControllerTest {
@Test
void headersSurviveContainerCasingAndStayCaseInsensitive() {
var request = request("application/json");
var request = request("application/json", "{}".getBytes(StandardCharsets.UTF_8));
request.addHeader("X-Twilio-Signature", "abc123");
assertThatThrownBy(
() ->
controller.callback(
"twilio", "twilio-primary", request, "{}".getBytes(StandardCharsets.UTF_8)))
assertThatThrownBy(() -> controller.callback("twilio", "twilio-primary", request))
.isInstanceOf(CallbackValidationException.class);
assertThat(received.getFirst().header("x-twilio-signature")).contains("abc123");
@@ -115,13 +106,39 @@ class NotificationCallbackMvcControllerTest {
}
@Test
void aBodyOverTheTransportCeilingIsRefusedBeforeIngress() {
byte[] oversized = new byte[NotificationCallbackMvcController.MAX_STORABLE_BODY_BYTES + 1];
void aDeclaredOversizeBodyIsRefusedWithoutReadingIt() throws Exception {
// given
int oversize = NotificationCallbackMvcController.MAX_STORABLE_BODY_BYTES + 1;
var request = request("application/json", new byte[oversize]);
var response =
controller.callback("twilio", "twilio-primary", request("application/json"), oversized);
// when
var response = controller.callback("twilio", "twilio-primary", request);
// then
assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CONTENT_TOO_LARGE);
assertThat(request.getInputStream().available()).isEqualTo(oversize);
}
@Test
void anUndeclaredOversizeBodyIsRefusedAfterReadingOneByteOverTheCeiling() throws Exception {
// given: a chunked body carries no Content-Length
int ceiling = NotificationCallbackMvcController.MAX_STORABLE_BODY_BYTES;
var request =
new MockHttpServletRequest(
"POST", "/internal/notification/callbacks/twilio/twilio-primary") {
@Override
public long getContentLengthLong() {
return -1;
}
};
request.setContent(new byte[ceiling + 1_000]);
// when
var response = controller.callback("twilio", "twilio-primary", request);
// then
assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CONTENT_TOO_LARGE);
assertThat(request.getInputStream().available()).isEqualTo(999);
assertThat(received).isEmpty();
}
@@ -138,11 +155,12 @@ class NotificationCallbackMvcControllerTest {
assertThat(response.getBody()).isNull();
}
private static MockHttpServletRequest request(String contentType) {
private static MockHttpServletRequest request(String contentType, byte[] body) {
var request =
new MockHttpServletRequest(
"POST", "/internal/notification/callbacks/twilio/twilio-primary");
request.setContentType(contentType);
request.setContent(body);
return request;
}
}
+6 -4
View File
@@ -297,10 +297,12 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
- `HandlerInterceptor` 입력으로 resolve 하는 이유: route template(`/v1/worklogs/{id}`)을 쓰기 위함. servlet
filter 는 handler mapping 이전에 실행돼 구체 경로만 보므로 모든 id 가 서로 다른 키가 되어버린다.
### RateLimitClientIpMode
- 비인증 rate-limit 키의 클라이언트 IP 소스 선택 enum.
- `REMOTE_ADDR_ONLY` — 직접 노출 배포의 안전한 기본값(spoofing 가능한 forwarded 헤더 무시).
- `FORWARDED_HEADERS_TRUSTED` — 신뢰할 수 있는 ingress/LB 가 forwarded 헤더를 덮어쓰는 경우에만 사용.
### 클라이언트 IP
- 비인증 키의 IP 는 `getRemoteAddr()` 하나다. 헤더를 직접 읽는 모드(`FORWARDED_HEADERS_TRUSTED`)는
XFF 맨 왼쪽 값(호출자가 쓰는 값)을 키로 써서 삭제했다.
- 프록시 뒤에서는 `server.forward-headers-strategy=native` + `server.tomcat.remoteip.internal-proxies`
로 Tomcat 이 신뢰 프록시에게서 온 XFF 만 반영한다. `framework` 는 모든 peer 를 믿으므로
`RateLimitWebConfig` 가 기동을 거부한다.
### RateLimitWebConfig
- servlet filter 가 아니라 interceptor 를 쓰는 이유: 비인증 키에 필요한 route template 이 interceptor 단계에서
@@ -275,6 +275,13 @@ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
HttpHeaders headers,
HttpStatusCode status,
WebRequest request) {
// The JSON body ceiling fails the read that crosses it; inside a bean property the parser
// wraps that failure, and it is still an oversized body rather than a malformed one.
for (Throwable cause = ex.getCause(); cause != null; cause = cause.getCause()) {
if (cause instanceof MaxUploadSizeExceededException tooLarge) {
return handleMaxUploadSizeExceededException(tooLarge, headers, status, request);
}
}
Map<String, Object> details =
ex.getCause() != null ? Map.of("cause", ex.getCause().getClass().getSimpleName()) : null;
return new ResponseEntity<>(
@@ -336,7 +343,7 @@ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
HttpHeaders headers,
HttpStatusCode status,
WebRequest request) {
// An oversized request body classifies as 413 inside the envelope.
// An oversized request body — multipart or JSON — classifies as 413 inside the envelope.
return new ResponseEntity<>(
ErrorResponseFactory.body(
OperationalError.PAYLOAD_TOO_LARGE,
@@ -2,6 +2,7 @@ package dev.caskeleton.adapter.inbound.web.mvc.autoconfigure;
import dev.caskeleton.adapter.inbound.web.error.GlobalExceptionHandler;
import dev.caskeleton.adapter.inbound.web.mvc.context.WebMvcRequestContextArgumentResolver;
import dev.caskeleton.adapter.inbound.web.mvc.filter.JsonBodyLimitFilter;
import dev.caskeleton.adapter.inbound.web.mvc.filter.WebMvcRequestIdFilter;
import dev.caskeleton.shared.tracing.SpanErrorRecorder;
import java.util.List;
@@ -11,9 +12,11 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.jackson.autoconfigure.JsonMapperBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import tools.jackson.core.StreamReadFeature;
/**
* Wires the web platform into a servlet application.
@@ -22,9 +25,10 @@ import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
* corrected onto: the condition lives here and everything else is imported, so "off" means no beans
* rather than beans that happen not to be called.
*
* <p>Three beans: the {@code Envelope} error handler, the request-id filter, and the argument
* resolver that lets a controller declare {@code WebRequestContext}. HTTP errors are the {@code
* Envelope} this handler writes; {@code spring.mvc.problemdetails.enabled} stays false.
* <p>The {@code Envelope} error handler, the request-id filter, the request-body boundary (JSON
* size ceiling and duplicate-key refusal), and the argument resolver that lets a controller declare
* {@code WebRequestContext}. HTTP errors are the {@code Envelope} this handler writes; {@code
* spring.mvc.problemdetails.enabled} stays false.
*
* <p>Every bean is {@link ConditionalOnMissingBean}: the platform supplies the one that would
* otherwise be missing rather than the one that must be used.
@@ -61,6 +65,25 @@ public class WebMvcPlatformAutoConfiguration {
org.springframework.core.Ordered.HIGHEST_PRECEDENCE + 10);
}
/** Refuses a JSON body over the configured ceiling before the converter reads it. */
@Bean
@ConditionalOnMissingBean
public JsonBodyLimitFilter jsonBodyLimitFilter(WebMvcPlatformSettings properties) {
return new JsonBodyLimitFilter(properties.maxJsonBodySize().toBytes());
}
/**
* Rejects a JSON object that names the same key twice.
*
* <p>Jackson keeps the last value by default, so {@code {"role":"user","role":"admin"}} binds as
* admin while a proxy, a validator or a log line that read the first value saw user. Refusing the
* document is the only reading every party agrees on.
*/
@Bean
public JsonMapperBuilderCustomizer strictDuplicateJsonKeys() {
return builder -> builder.enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION);
}
/** Lets a controller declare the request context instead of the servlet request. */
@Bean
@ConditionalOnMissingBean(name = "webMvcRequestContextConfigurer")
@@ -1,6 +1,7 @@
package dev.caskeleton.adapter.inbound.web.mvc.autoconfigure;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.util.unit.DataSize;
/**
* The bound settings of the MVC web platform.
@@ -16,19 +17,25 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
*
* @param enabled whether the platform's MVC wiring is installed at all
* @param trustInboundRequestId whether a caller may choose its own request id
* @param maxJsonBodySize the largest JSON request body accepted; 1MB when omitted
*/
@ConfigurationProperties(prefix = "backend.web.mvc")
public record WebMvcPlatformSettings(Boolean enabled, Boolean trustInboundRequestId) {
public record WebMvcPlatformSettings(
Boolean enabled, Boolean trustInboundRequestId, DataSize maxJsonBodySize) {
public WebMvcPlatformSettings {
enabled = enabled == null || enabled;
// Defaults to false: a caller that can choose its own request id can make two exchanges share
// one identity, which is how a support investigation reads somebody else's request.
trustInboundRequestId = trustInboundRequestId != null && trustInboundRequestId;
maxJsonBodySize = maxJsonBodySize == null ? DataSize.ofMegabytes(1) : maxJsonBodySize;
if (maxJsonBodySize.toBytes() < 1) {
throw new IllegalArgumentException("backend.web.mvc.max-json-body-size must be positive");
}
}
/** The defaults a deployment that configures nothing runs with. */
public static WebMvcPlatformSettings defaults() {
return new WebMvcPlatformSettings(null, null);
return new WebMvcPlatformSettings(null, null, null);
}
}
@@ -0,0 +1,157 @@
package dev.caskeleton.adapter.inbound.web.mvc.filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ReadListener;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletInputStream;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequestWrapper;
import jakarta.servlet.http.HttpServletResponse;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import org.springframework.core.Ordered;
import org.springframework.http.MediaType;
import org.springframework.web.filter.OncePerRequestFilter;
import org.springframework.web.multipart.MaxUploadSizeExceededException;
/**
* Caps a JSON request body before the message converter reads it.
*
* <p>Nothing else in the servlet stack does: Tomcat bounds form posts and Spring bounds multipart,
* but a JSON body is read to the end, and Jackson's own limits (nesting depth 500, number length
* 1000) say nothing about length. Two checks, because either alone is bypassable: the declared
* {@code Content-Length} is refused without reading a byte, and the stream is counted so a chunked
* or understated body fails the read that crosses the ceiling.
*
* <p>The refusal is {@link MaxUploadSizeExceededException}, which the error handler already answers
* as {@code 413 PAYLOAD_TOO_LARGE} in the envelope. Other media types keep their own ceilings
* (multipart, form posts, upload protocols) and pass through untouched.
*/
public final class JsonBodyLimitFilter extends OncePerRequestFilter implements Ordered {
private final long maxBytes;
/**
* A filter with the given ceiling.
*
* @param maxBytes the largest JSON body accepted, in bytes
*/
public JsonBodyLimitFilter(long maxBytes) {
if (maxBytes < 1) {
throw new IllegalArgumentException("maxBytes must be positive");
}
this.maxBytes = maxBytes;
}
@Override
protected boolean shouldNotFilter(HttpServletRequest request) {
String contentType = request.getContentType();
if (contentType == null) {
return true;
}
try {
MediaType type = MediaType.parseMediaType(contentType);
return !MediaType.APPLICATION_JSON.isCompatibleWith(type)
&& !type.getSubtype().endsWith("+json");
} catch (IllegalArgumentException unparseable) {
return true;
}
}
@Override
protected void doFilterInternal(
HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws ServletException, IOException {
chain.doFilter(new BoundedBodyRequest(request, maxBytes), response);
}
@Override
public int getOrder() {
return Ordered.HIGHEST_PRECEDENCE + 15;
}
private static final class BoundedBodyRequest extends HttpServletRequestWrapper {
private final long limit;
BoundedBodyRequest(HttpServletRequest request, long limit) {
super(request);
this.limit = limit;
}
@Override
public ServletInputStream getInputStream() throws IOException {
if (getContentLengthLong() > limit) {
throw new MaxUploadSizeExceededException(limit);
}
return new BoundedInputStream(super.getInputStream(), limit);
}
@Override
public BufferedReader getReader() throws IOException {
String encoding = getCharacterEncoding();
Charset charset = encoding == null ? StandardCharsets.UTF_8 : Charset.forName(encoding);
return new BufferedReader(new InputStreamReader(getInputStream(), charset));
}
}
private static final class BoundedInputStream extends ServletInputStream {
private final ServletInputStream delegate;
private final long limit;
private long consumed;
BoundedInputStream(ServletInputStream delegate, long limit) {
this.delegate = delegate;
this.limit = limit;
}
@Override
public int read() throws IOException {
int value = delegate.read();
if (value >= 0) {
count(1);
}
return value;
}
@Override
public int read(byte[] buffer, int offset, int length) throws IOException {
int read = delegate.read(buffer, offset, length);
if (read > 0) {
count(read);
}
return read;
}
private void count(int read) {
consumed += read;
if (consumed > limit) {
throw new MaxUploadSizeExceededException(limit);
}
}
@Override
public boolean isFinished() {
return delegate.isFinished();
}
@Override
public boolean isReady() {
return delegate.isReady();
}
@Override
public void setReadListener(ReadListener listener) {
delegate.setReadListener(listener);
}
@Override
public void close() throws IOException {
delegate.close();
}
}
}
@@ -1,8 +0,0 @@
package dev.caskeleton.adapter.inbound.web.ratelimit;
import jakarta.servlet.http.HttpServletRequest;
interface ClientIpResolver {
String resolve(HttpServletRequest request);
}
@@ -1,13 +0,0 @@
package dev.caskeleton.adapter.inbound.web.ratelimit;
final class ClientIpResolverFactory {
private ClientIpResolverFactory() {}
static ClientIpResolver create(RateLimitClientIpMode mode) {
return switch (mode) {
case REMOTE_ADDR_ONLY -> new RemoteAddrClientIpResolver();
case FORWARDED_HEADERS_TRUSTED -> new ForwardedHeaderClientIpResolver();
};
}
}
@@ -13,11 +13,7 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
*/
@ConfigurationProperties(prefix = "app.rate-limit")
public record EdgeRateLimitTransportSettings(
boolean enabled,
String defaultPolicyId,
Duration callerDeadlineBudget,
int hashKeyVersion,
RateLimitClientIpMode clientIpMode) {
boolean enabled, String defaultPolicyId, Duration callerDeadlineBudget, int hashKeyVersion) {
private static final Pattern POLICY_ID = Pattern.compile("[a-z][a-z0-9-]{0,62}");
@@ -27,7 +23,6 @@ public record EdgeRateLimitTransportSettings(
callerDeadlineBudget =
callerDeadlineBudget == null ? Duration.ofSeconds(2) : callerDeadlineBudget;
hashKeyVersion = hashKeyVersion == 0 ? 1 : hashKeyVersion;
clientIpMode = clientIpMode == null ? RateLimitClientIpMode.REMOTE_ADDR_ONLY : clientIpMode;
if (!POLICY_ID.matcher(defaultPolicyId).matches()) {
throw new IllegalArgumentException("defaultPolicyId must be a bounded policy identifier");
}
@@ -1,18 +0,0 @@
package dev.caskeleton.adapter.inbound.web.ratelimit;
import jakarta.servlet.http.HttpServletRequest;
final class ForwardedHeaderClientIpResolver implements ClientIpResolver {
private static final String X_FORWARDED_FOR = "X-Forwarded-For";
@Override
public String resolve(HttpServletRequest request) {
String forwarded = request.getHeader(X_FORWARDED_FOR);
if (forwarded == null || forwarded.isBlank()) {
return request.getRemoteAddr();
}
String firstHop = forwarded.split(",", 2)[0].trim();
return firstHop.isEmpty() ? request.getRemoteAddr() : firstHop;
}
}
@@ -1,13 +0,0 @@
package dev.caskeleton.adapter.inbound.web.ratelimit;
/**
* Selects the client-IP source for unauthenticated rate-limit keys. See README for the design
* rationale.
*/
public enum RateLimitClientIpMode {
/** Uses {@code remoteAddr} only; ignores forwarded headers. */
REMOTE_ADDR_ONLY,
/** Trusts forwarded headers. */
FORWARDED_HEADERS_TRUSTED
}
@@ -19,17 +19,16 @@ import org.springframework.web.servlet.HandlerMapping;
*
* <p>The returned raw identity exists only until {@link EdgeSubjectPseudonymizer} runs. It must not
* cross the provider port boundary.
*
* <p>The client IP is {@code getRemoteAddr()} and nothing else. Behind a proxy the container
* rewrites it from {@code X-Forwarded-For} only for peers it trusts ({@code
* server.forward-headers-strategy=native} with {@code server.tomcat.remoteip.internal-proxies}); a
* header read here would be whatever the caller typed.
*/
public final class RateLimitKeyResolver {
private static final String SERVICE_ROLE = "service";
private final ClientIpResolver clientIpResolver;
public RateLimitKeyResolver(ClientIpResolver clientIpResolver) {
this.clientIpResolver = clientIpResolver;
}
public EdgeRateLimitSubject resolve(HttpServletRequest request) {
String operationId = operationId(request);
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
@@ -43,7 +42,7 @@ public final class RateLimitKeyResolver {
return new EdgeRateLimitSubject(kind, user.idpUserId(), operationId);
}
return new EdgeRateLimitSubject(
EdgeRateLimitSubject.Kind.CLIENT_IP, clientIpResolver.resolve(request), operationId);
EdgeRateLimitSubject.Kind.CLIENT_IP, request.getRemoteAddr(), operationId);
}
private static String operationId(HttpServletRequest request) {
@@ -4,6 +4,7 @@ import dev.caskeleton.application.observability.UserPrincipalPseudonymizerPort;
import dev.caskeleton.shared.ratelimit.EdgeRateLimitPort;
import java.time.Clock;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;
@@ -14,9 +15,9 @@ import tools.jackson.databind.ObjectMapper;
/**
* Wires provider-neutral edge enforcement into MVC.
*
* <p>Transport activation, trusted client-IP selection, policy selection, and deadlines come from
* {@code app.rate-limit}. Provider activation is a separate composition-root decision; an enabled
* bridge requires exactly one semantic port and never installs a local fallback.
* <p>Transport activation, policy selection, and deadlines come from {@code app.rate-limit}.
* Provider activation is a separate composition-root decision; an enabled bridge requires exactly
* one semantic port and never installs a local fallback.
*/
@Configuration
@ConditionalOnProperty(prefix = "app.rate-limit", name = "enabled", havingValue = "true")
@@ -30,7 +31,16 @@ public class RateLimitWebConfig implements WebMvcConfigurer {
ObjectMapper objectMapper,
ObjectProvider<Clock> clockProvider,
ObjectProvider<EdgeRateLimitPort> portProvider,
ObjectProvider<UserPrincipalPseudonymizerPort> pseudonymizerProvider) {
ObjectProvider<UserPrincipalPseudonymizerPort> pseudonymizerProvider,
@Value("${server.forward-headers-strategy:none}") String forwardHeadersStrategy) {
// The unauthenticated key is getRemoteAddr(). `framework` installs ForwardedHeaderFilter, which
// rewrites it from X-Forwarded-For for every peer, so any caller picks its own bucket.
if ("framework".equalsIgnoreCase(forwardHeadersStrategy.trim())) {
throw new IllegalStateException(
"server.forward-headers-strategy=framework (APP_SERVER_FORWARD_HEADERS_STRATEGY) lets"
+ " any caller choose its rate-limit key through X-Forwarded-For; use native with"
+ " server.tomcat.remoteip.internal-proxies naming the proxies to trust");
}
EdgeRateLimitPort port = requiredUnique(portProvider, "EdgeRateLimitPort");
UserPrincipalPseudonymizerPort secretBackedPseudonymizer =
requiredUnique(pseudonymizerProvider, "UserPrincipalPseudonymizerPort");
@@ -39,8 +49,7 @@ public class RateLimitWebConfig implements WebMvcConfigurer {
port,
new VersionedEdgeSubjectPseudonymizer(
secretBackedPseudonymizer, transportSettings.hashKeyVersion()),
new RateLimitKeyResolver(
ClientIpResolverFactory.create(transportSettings.clientIpMode())),
new RateLimitKeyResolver(),
clockProvider.getIfAvailable(Clock::systemUTC),
transportSettings.defaultPolicyId(),
transportSettings.callerDeadlineBudget(),
@@ -1,11 +0,0 @@
package dev.caskeleton.adapter.inbound.web.ratelimit;
import jakarta.servlet.http.HttpServletRequest;
final class RemoteAddrClientIpResolver implements ClientIpResolver {
@Override
public String resolve(HttpServletRequest request) {
return request.getRemoteAddr();
}
}
@@ -1,6 +1,8 @@
package dev.caskeleton.adapter.inbound.web.settings;
import jakarta.validation.constraints.PositiveOrZero;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
@@ -39,6 +41,7 @@ public record CorsSettings(
allowedOrigins = List.of();
} else {
allowedOrigins = List.copyOf(allowedOrigins);
allowedOrigins.forEach(CorsSettings::requireExactOrigin);
}
if (allowedMethods == null || allowedMethods.isEmpty()) {
allowedMethods = List.of("GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS");
@@ -51,4 +54,40 @@ public record CorsSettings(
allowedHeaders = List.copyOf(allowedHeaders);
}
}
/**
* An origin is {@code scheme://host[:port]} and nothing else. A browser sends exactly that, so a
* trailing slash, a path, a wildcard host or the literal {@code null} origin (sandboxed frames,
* {@code file:} pages) either never matches or matches far more than intended — and neither shows
* up in a test of the API itself. {@code *} alone stays allowed; credentials already exclude it.
*/
private static void requireExactOrigin(String origin) {
if ("*".equals(origin)) {
return;
}
URI uri;
try {
uri = new URI(origin);
} catch (URISyntaxException malformed) {
throw notAnOrigin(origin);
}
boolean exact =
("http".equals(uri.getScheme()) || "https".equals(uri.getScheme()))
&& uri.getHost() != null
&& uri.getRawUserInfo() == null
&& uri.getRawPath().isEmpty()
&& uri.getRawQuery() == null
&& uri.getRawFragment() == null;
if (!exact) {
throw notAnOrigin(origin);
}
}
private static IllegalArgumentException notAnOrigin(String origin) {
return new IllegalArgumentException(
"APP_SECURITY_CORS_ORIGINS (ca-skeleton.cors.allowed-origins) entry \""
+ origin
+ "\" must be exactly scheme://host[:port] with http or https: no path, trailing"
+ " slash, query, fragment, user info, wildcard host or \"null\"");
}
}
@@ -34,6 +34,8 @@ import org.springframework.core.MethodParameter;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.mock.http.MockHttpInputMessage;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.authentication.BadCredentialsException;
@@ -43,6 +45,7 @@ import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.context.request.ServletWebRequest;
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
import org.springframework.web.multipart.MaxUploadSizeExceededException;
import org.springframework.web.servlet.NoHandlerFoundException;
class GlobalExceptionHandlerTest {
@@ -195,6 +198,27 @@ class GlobalExceptionHandlerTest {
.doesNotContain(secret, "rejectedValue", "rejected interpolated value", "[7]");
}
@Test
void unreadableBodyCausedByTheSizeCeilingIsPayloadTooLarge() {
// given: the parser wraps the ceiling's exception when it fires inside a bean property
HttpMessageNotReadableException unreadable =
new HttpMessageNotReadableException(
"JSON parse error",
new IllegalStateException(new MaxUploadSizeExceededException(64)),
new MockHttpInputMessage(new byte[0]));
// when
ResponseEntity<Object> response =
handler.handleHttpMessageNotReadable(
unreadable,
new HttpHeaders(),
HttpStatus.BAD_REQUEST,
new ServletWebRequest(new MockHttpServletRequest()));
// then
assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CONTENT_TOO_LARGE);
}
@Test
@SuppressWarnings("unchecked")
void constraintValidationUsesFixedReasonAndStripsRequestControlledMapKey() {
@@ -0,0 +1,84 @@
package dev.caskeleton.adapter.inbound.web.mvc.autoconfigure;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import java.util.Map;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
import org.springframework.boot.security.autoconfigure.SecurityAutoConfiguration;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.context.annotation.Import;
import org.springframework.http.MediaType;
import org.springframework.test.context.TestPropertySource;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.ResultActions;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
/**
* The request boundary the platform auto-configuration puts in front of every JSON body: a size
* ceiling and a parser that refuses duplicate keys, both answered as the error envelope.
*/
@WebMvcTest(
controllers = RequestBodyBoundaryTest.Probe.class,
excludeAutoConfiguration = SecurityAutoConfiguration.class)
@ImportAutoConfiguration(WebMvcPlatformAutoConfiguration.class)
@Import(RequestBodyBoundaryTest.Probe.class)
@TestPropertySource(properties = "backend.web.mvc.max-json-body-size=64B")
class RequestBodyBoundaryTest {
@Autowired MockMvc mvc;
@Test
void duplicateJsonKeyIsRejectedAsValidationFailure() throws Exception {
// when
ResultActions result = send("{\"role\":\"user\",\"role\":\"admin\"}");
// then
result
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error.code").value("VALIDATION_FAILED"));
}
@Test
void jsonBodyOverTheCeilingIsRejectedAsPayloadTooLarge() throws Exception {
// when
ResultActions result = send("{\"note\":\"" + "x".repeat(100) + "\"}");
// then
result
.andExpect(status().is(413))
.andExpect(jsonPath("$.error.code").value("PAYLOAD_TOO_LARGE"));
}
@Test
void jsonBodyWithinTheCeilingReachesTheController() throws Exception {
// when
ResultActions result = send("{\"note\":\"ok\"}");
// then
result.andExpect(status().isOk()).andExpect(jsonPath("$.note").value("ok"));
}
private ResultActions send(String json) throws Exception {
return mvc.perform(post("/probe").contentType(MediaType.APPLICATION_JSON).content(json));
}
@RestController
static class Probe {
@PostMapping("/probe")
Map<String, Object> echo(@RequestBody Map<String, Object> body) {
return body;
}
}
@SpringBootConfiguration
@EnableAutoConfiguration(exclude = SecurityAutoConfiguration.class)
static class TestBootstrap {}
}
@@ -0,0 +1,56 @@
package dev.caskeleton.adapter.inbound.web.mvc.filter;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import jakarta.servlet.FilterChain;
import java.util.concurrent.atomic.AtomicReference;
import org.junit.jupiter.api.Test;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.web.multipart.MaxUploadSizeExceededException;
class JsonBodyLimitFilterTest {
private final JsonBodyLimitFilter filter = new JsonBodyLimitFilter(16);
@Test
void undeclaredJsonBodyFailsTheReadThatCrossesTheCeiling() {
// given: a chunked body carries no Content-Length
MockHttpServletRequest request =
new MockHttpServletRequest("POST", "/probe") {
@Override
public long getContentLengthLong() {
return -1;
}
};
request.setContentType("application/json");
request.setContent(new byte[64]);
FilterChain readsEverything = (req, res) -> req.getInputStream().readAllBytes();
// when
Throwable thrown =
catchThrowable(
() -> filter.doFilter(request, new MockHttpServletResponse(), readsEverything));
// then
assertThat(thrown)
.isInstanceOf(MaxUploadSizeExceededException.class)
.hasMessageContaining("16");
}
@Test
void nonJsonBodyReachesTheChainUnwrapped() throws Exception {
// given
MockHttpServletRequest request = new MockHttpServletRequest("PATCH", "/upload");
request.setContentType("application/offset+octet-stream");
request.setContent(new byte[64]);
AtomicReference<Object> seen = new AtomicReference<>();
// when
filter.doFilter(request, new MockHttpServletResponse(), (req, res) -> seen.set(req));
// then
assertThat(seen.get()).isSameAs(request);
}
}
@@ -57,7 +57,7 @@ class EdgeRateLimitTransportBridgeTest {
capture.rawSubject = subject;
return new RateLimitSubjectDigest(DIGEST);
},
new RateLimitKeyResolver(new RemoteAddrClientIpResolver()),
new RateLimitKeyResolver(),
CLOCK,
"api-default",
Duration.ofMillis(750),
@@ -11,13 +11,12 @@ class EdgeRateLimitTransportSettingsTest {
@Test
void defaultsPolicyAndCallerBudgetWithoutSelectingALocalProvider() {
EdgeRateLimitTransportSettings settings =
new EdgeRateLimitTransportSettings(true, null, null, 0, null);
new EdgeRateLimitTransportSettings(true, null, null, 0);
assertThat(settings.enabled()).isTrue();
assertThat(settings.defaultPolicyId()).isEqualTo("api-default");
assertThat(settings.callerDeadlineBudget()).isEqualTo(Duration.ofSeconds(2));
assertThat(settings.hashKeyVersion()).isEqualTo(1);
assertThat(settings.clientIpMode()).isEqualTo(RateLimitClientIpMode.REMOTE_ADDR_ONLY);
}
@Test
@@ -25,19 +24,18 @@ class EdgeRateLimitTransportSettingsTest {
assertThatThrownBy(
() ->
new EdgeRateLimitTransportSettings(
true, "INVALID POLICY", Duration.ofSeconds(1), 1, null))
true, "INVALID POLICY", Duration.ofSeconds(1), 1))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("defaultPolicyId");
assertThatThrownBy(
() ->
new EdgeRateLimitTransportSettings(
true, "api-default", Duration.ofSeconds(31), 1, null))
new EdgeRateLimitTransportSettings(true, "api-default", Duration.ofSeconds(31), 1))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("callerDeadlineBudget");
assertThatThrownBy(
() ->
new EdgeRateLimitTransportSettings(
true, "api-default", Duration.ofSeconds(1), 10_000, null))
true, "api-default", Duration.ofSeconds(1), 10_000))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("hashKeyVersion");
}
@@ -106,7 +106,7 @@ class RateLimitInterceptorTest {
}
@Test
void disabledModeHasNoProviderPseudonymizerOrResolverSideEffects() throws Exception {
void disabledModeHasNoProviderOrPseudonymizerSideEffects() throws Exception {
AtomicInteger calls = new AtomicInteger();
EdgeRateLimitPort port =
request -> {
@@ -122,11 +122,7 @@ class RateLimitInterceptorTest {
new EdgeRateLimitTransportBridge(
port,
pseudonymizer,
new RateLimitKeyResolver(
request -> {
calls.incrementAndGet();
return request.getRemoteAddr();
}),
new RateLimitKeyResolver(),
CLOCK,
"api-default",
Duration.ofSeconds(1),
@@ -146,7 +142,7 @@ class RateLimitInterceptorTest {
new EdgeRateLimitTransportBridge(
request -> outcome,
subject -> new RateLimitSubjectDigest(SUBJECT_DIGEST),
new RateLimitKeyResolver(new RemoteAddrClientIpResolver()),
new RateLimitKeyResolver(),
CLOCK,
"api-default",
Duration.ofSeconds(1),
@@ -14,8 +14,7 @@ import org.springframework.web.servlet.HandlerMapping;
class RateLimitKeyResolverTest {
private final RateLimitKeyResolver resolver =
new RateLimitKeyResolver(new RemoteAddrClientIpResolver());
private final RateLimitKeyResolver resolver = new RateLimitKeyResolver();
@AfterEach
void clearContext() {
@@ -67,33 +66,16 @@ class RateLimitKeyResolverTest {
}
@Test
void remoteAddrModeIgnoresForwardedClientIpWhenPresent() {
void clientIpIgnoresForwardedForAndUsesTheRemoteAddress() {
// given
MockHttpServletRequest req = new MockHttpServletRequest("GET", "/v1/ping");
req.setRemoteAddr("10.0.0.1");
req.addHeader("X-Forwarded-For", "203.0.113.9, 10.0.0.1");
assertThat(resolver.resolve(req).canonicalIdentity()).isEqualTo("10.0.0.1");
}
// when
String identity = resolver.resolve(req).canonicalIdentity();
@Test
void forwardedHeadersTrustedModeUsesFirstForwardedClientIp() {
RateLimitKeyResolver forwardedResolver =
new RateLimitKeyResolver(new ForwardedHeaderClientIpResolver());
MockHttpServletRequest req = new MockHttpServletRequest("GET", "/v1/ping");
req.setRemoteAddr("10.0.0.1");
req.addHeader("X-Forwarded-For", "203.0.113.9, 10.0.0.1");
assertThat(forwardedResolver.resolve(req).canonicalIdentity()).isEqualTo("203.0.113.9");
}
@Test
void forwardedHeadersTrustedModeFallsBackToRemoteAddrWhenHeaderIsBlank() {
RateLimitKeyResolver forwardedResolver =
new RateLimitKeyResolver(new ForwardedHeaderClientIpResolver());
MockHttpServletRequest req = new MockHttpServletRequest("GET", "/v1/ping");
req.setRemoteAddr("198.51.100.4");
req.addHeader("X-Forwarded-For", " ");
assertThat(forwardedResolver.resolve(req).canonicalIdentity()).isEqualTo("198.51.100.4");
// then
assertThat(identity).isEqualTo("10.0.0.1");
}
}
@@ -2,14 +2,45 @@ package dev.caskeleton.adapter.inbound.web.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.application.observability.UserPrincipalPseudonymizerPort;
import dev.caskeleton.shared.ratelimit.EdgeRateLimitPort;
import dev.caskeleton.shared.ratelimit.RateLimitDecision;
import dev.caskeleton.shared.ratelimit.RateLimitOutcome;
import java.time.Duration;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.runner.WebApplicationContextRunner;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.HandlerMapping;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import tools.jackson.databind.ObjectMapper;
class RateLimitWebConfigTest {
private static final String PEER = "203.0.113.7";
private final List<String> pseudonymized = new ArrayList<>();
private final WebApplicationContextRunner runner =
new WebApplicationContextRunner().withUserConfiguration(RateLimitWebConfig.class);
private final WebApplicationContextRunner enabled =
runner
.withPropertyValues("app.rate-limit.enabled=true")
.withBean(ObjectMapper.class, ObjectMapper::new)
.withBean(EdgeRateLimitPort.class, () -> request -> allowed())
.withBean(
UserPrincipalPseudonymizerPort.class,
() ->
raw -> {
pseudonymized.add(raw);
return "a".repeat(64);
});
@Test
void disabledCapabilityRegistersNoInterceptorConfiguration() {
runner.run(
@@ -19,4 +50,71 @@ class RateLimitWebConfigTest {
.doesNotHaveBean(RateLimitWebConfig.class)
.doesNotHaveBean(RateLimitInterceptor.class));
}
@Test
void spoofedForwardedForDoesNotChangeTheUnauthenticatedKey() {
// given: the forwarded-header opt-in an older deployment may still carry
enabled
.withPropertyValues("app.rate-limit.client-ip-mode=forwarded-headers-trusted")
.run(
context -> {
HandlerInterceptor interceptor =
interceptorOf(context.getBean(RateLimitWebConfig.class));
// when
for (String spoofed : List.of("198.51.100.1", "198.51.100.2")) {
interceptor.preHandle(
unauthenticated(spoofed), new MockHttpServletResponse(), new Object());
}
// then
String peerKey = "9:CLIENT_IP|11:" + PEER + "|12:GET /v1/ping";
assertThat(pseudonymized).containsExactly(peerKey, peerKey);
});
}
@Test
void frameworkForwardHeadersStrategyIsRefusedWhileRateLimiting() {
enabled
.withPropertyValues("server.forward-headers-strategy=framework")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.hasStackTraceContaining("server.forward-headers-strategy=framework"));
}
private static HandlerInterceptor interceptorOf(RateLimitWebConfig config) {
var registry =
new InterceptorRegistry() {
List<Object> registered() {
return getInterceptors();
}
};
config.addInterceptors(registry);
return (HandlerInterceptor) registry.registered().getFirst();
}
private static MockHttpServletRequest unauthenticated(String forwardedFor) {
MockHttpServletRequest request = new MockHttpServletRequest("GET", "/v1/ping");
request.setRemoteAddr(PEER);
request.addHeader("X-Forwarded-For", forwardedFor);
request.setAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE, "/v1/ping");
return request;
}
private static RateLimitOutcome allowed() {
return new RateLimitOutcome.Evaluated(
new RateLimitDecision(
true,
10,
9,
Duration.ZERO,
Instant.parse("2026-09-25T00:00:01Z"),
"api-default",
"v1",
RateLimitDecision.DecisionSource.GLOBAL_SHARED_STORE,
RateLimitDecision.DecisionCertainty.CERTAIN));
}
}
@@ -1,10 +1,13 @@
package dev.caskeleton.adapter.inbound.web.settings;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import java.util.ArrayList;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
@@ -117,6 +120,41 @@ class CorsSettingsTest {
});
}
@ParameterizedTest
@ValueSource(
strings = {
"https://app.example.com/",
"https://app.example.com/path",
"https://app.example.com?x=1",
"https://app.example.com#top",
"https://user@app.example.com",
"https://*.example.com",
"ftp://app.example.com",
"app.example.com",
"null",
" "
})
void originThatIsNotExactlySchemeHostPortFailsWithTheEnvKeyName(String origin) {
// when
Throwable thrown =
catchThrowable(() -> new CorsSettings(true, List.of(origin), null, null, false, 0));
// then
assertThat(thrown)
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("APP_SECURITY_CORS_ORIGINS");
}
@Test
void exactOriginWithPortIsAccepted() {
// when
CorsSettings settings =
new CorsSettings(true, List.of("https://app.example.com:8443"), null, null, true, 0);
// then
assertThat(settings.allowedOrigins()).containsExactly("https://app.example.com:8443");
}
@Test
void collectionSettingsAreSnapshotsAndImmutable() {
List<String> origins = new ArrayList<>(List.of("https://example.test"));
+1
View File
@@ -62,6 +62,7 @@ values matter only in a composition that adopts it.
| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` |
| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`; explicit origins only |
| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` |
| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`; messages each STOMP client channel (inbound, outbound) queues before rejecting |
`WebSocketSettings` is `@Validated`. Invalid enabled settings fail context startup.
+1
View File
@@ -44,6 +44,7 @@ runtimeOnly project(':adapter:inbound:websocket') // WebSocket (STOMP push)
| `APP_WEBSOCKET_ENDPOINT` | `/ws` | handshake 경로 |
| `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000` | 쉼표 구분 origin 목록. wildcard 금지 |
| `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` | 서버 push 대상. `/topic/` 아래 경로 하나 |
| `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000` | STOMP 인바운드·아웃바운드 채널 executor 큐 상한. 가득 차면 메시지를 거부한다(스레드 수는 CPU×2 고정) |
켠 상태에서 값이 잘못되면(wildcard origin, 정규화되지 않은 경로) 기동이 실패한다.

Some files were not shown because too many files have changed in this diff Show More