docs(architecture): document active warm broker pool
- commit
- 1cfa5210d18a70e9875ec2e64cd09565348ee56c
- author
- brice · · 2026-09-22 21:27 UTC
- parent
- e4992c6
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +11 -7
M docs/architecture.md +11 -7
| @@ -175,7 +175,7 @@ mutation, so a racing close can never admit work after shutdown. The codec | |||
| 175 | 175 | itself stays stateless over `wire.ScanEnvelope`. No socket, framing pump, | |
| 176 | 176 | or P3.2 transport is introduced here. | |
| 177 | 177 | ||
| 178 | - | ## Broker pool core (Plan 001 P2.2, not activated) | |
| 178 | + | ## Broker connection pool | |
| 179 | 179 | ||
| 180 | 180 | `internal/usecase/broker.Pool` owns bounded physical keys and logical stream | |
| 181 | 181 | reservations, but no session data or traffic queues. Local and registered remote | |
| @@ -200,16 +200,20 @@ and are canceled when their final reservation leaves. Acquisition coalescing | |||
| 200 | 200 | keys on the exact policy plus the explicit `BrokerDaemonStartMode`, so an | |
| 201 | 201 | existing-only request is never shared with a dial that may start the target; | |
| 202 | 202 | after authentication the canonical key is identity plus exact policy alone. | |
| 203 | - | Physical retirement keeps its key occupied until Close finishes. Fake-clock idle | |
| 204 | - | eviction and shutdown close transports outside the bookkeeping lock. | |
| 203 | + | Physical retirement keeps its key occupied until Close finishes. The pool keeps | |
| 204 | + | at most eight idle physical transports warm by default, including connections | |
| 205 | + | established by a first successful probe. `warmTransports: 0` disables warm | |
| 206 | + | reuse; `warmIdleTimeout` defaults to `off` and may set an idle deadline. | |
| 207 | + | Broker shutdown always closes warm transports. Fake-clock idle eviction and | |
| 208 | + | shutdown close transports outside the bookkeeping lock. | |
| 205 | 209 | ||
| 206 | 210 | Logical and physical ports expose terminal signals independent of message reads. | |
| 207 | 211 | A stream terminal failure releases only its reservation; physical failure fans | |
| 208 | 212 | out separately scoped typed loss errors. The pool owns neither framing nor | |
| 209 | - | fairness: future transport adapters must implement independently bounded queues | |
| 210 | - | and prompt cancellation/Close. Shutdown joins owned operations and relies on | |
| 211 | - | that explicit port contract. No production composition or real multiplexing is | |
| 212 | - | introduced here, and existing production connectivity ownership is unchanged. | |
| 213 | + | fairness: transport adapters implement independently bounded queues and | |
| 214 | + | prompt cancellation/Close. Shutdown joins owned operations and relies on | |
| 215 | + | that explicit port contract. Production clients use this pool for local and | |
| 216 | + | remote logical streams. | |
| 213 | 217 | ||
| 214 | 218 | Physical `Done` is authoritative: adapters publish stable `Err` and | |
| 215 | 219 | `FailureKind`, then close physical `Done` before terminating affected logical | |
| @@ -175,7 +175,7 @@ mutation, so a racing close can never admit work after shutdown. The codec | |||||
| 175 | itself stays stateless over `wire.ScanEnvelope`. No socket, framing pump, | 175 | itself stays stateless over `wire.ScanEnvelope`. No socket, framing pump, | ||
| 176 | or P3.2 transport is introduced here. | 176 | or P3.2 transport is introduced here. | ||
| 177 | 177 | ||||
| 178 | - | ## Broker pool core (Plan 001 P2.2, not activated) | 178 | + | ## Broker connection pool |
| 179 | 179 | ||||
| 180 | `internal/usecase/broker.Pool` owns bounded physical keys and logical stream | 180 | `internal/usecase/broker.Pool` owns bounded physical keys and logical stream | ||
| 181 | reservations, but no session data or traffic queues. Local and registered remote | 181 | reservations, but no session data or traffic queues. Local and registered remote | ||
| @@ -200,16 +200,20 @@ and are canceled when their final reservation leaves. Acquisition coalescing | |||||
| 200 | keys on the exact policy plus the explicit `BrokerDaemonStartMode`, so an | 200 | keys on the exact policy plus the explicit `BrokerDaemonStartMode`, so an | ||
| 201 | existing-only request is never shared with a dial that may start the target; | 201 | existing-only request is never shared with a dial that may start the target; | ||
| 202 | after authentication the canonical key is identity plus exact policy alone. | 202 | after authentication the canonical key is identity plus exact policy alone. | ||
| 203 | - | Physical retirement keeps its key occupied until Close finishes. Fake-clock idle | 203 | + | Physical retirement keeps its key occupied until Close finishes. The pool keeps |
| 204 | - | eviction and shutdown close transports outside the bookkeeping lock. | 204 | + | at most eight idle physical transports warm by default, including connections |
| 205 | + | established by a first successful probe. `warmTransports: 0` disables warm | |||
| 206 | + | reuse; `warmIdleTimeout` defaults to `off` and may set an idle deadline. | |||
| 207 | + | Broker shutdown always closes warm transports. Fake-clock idle eviction and | |||
| 208 | + | shutdown close transports outside the bookkeeping lock. | |||
| 205 | 209 | ||||
| 206 | Logical and physical ports expose terminal signals independent of message reads. | 210 | Logical and physical ports expose terminal signals independent of message reads. | ||
| 207 | A stream terminal failure releases only its reservation; physical failure fans | 211 | A stream terminal failure releases only its reservation; physical failure fans | ||
| 208 | out separately scoped typed loss errors. The pool owns neither framing nor | 212 | out separately scoped typed loss errors. The pool owns neither framing nor | ||
| 209 | - | fairness: future transport adapters must implement independently bounded queues | 213 | + | fairness: transport adapters implement independently bounded queues and |
| 210 | - | and prompt cancellation/Close. Shutdown joins owned operations and relies on | 214 | + | prompt cancellation/Close. Shutdown joins owned operations and relies on |
| 211 | - | that explicit port contract. No production composition or real multiplexing is | 215 | + | that explicit port contract. Production clients use this pool for local and |
| 212 | - | introduced here, and existing production connectivity ownership is unchanged. | 216 | + | remote logical streams. |
| 213 | 217 | ||||
| 214 | Physical `Done` is authoritative: adapters publish stable `Err` and | 218 | Physical `Done` is authoritative: adapters publish stable `Err` and | ||
| 215 | `FailureKind`, then close physical `Done` before terminating affected logical | 219 | `FailureKind`, then close physical `Done` before terminating affected logical | ||