refactor: 백엔드 리펙토링 진행 중
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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다.
|
||||
|
||||
@@ -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`:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`,
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 갱신 필요).
|
||||
|
||||
Reference in New Issue
Block a user