@@ -25,6 +25,24 @@
 # upstream as opensearch-project/opensearch-k8s-operator#1585, fixed by #1586;
 # drop it on the first release carrying that.
 #
+# patches/timeout-cluster-api-calls.diff bounds the calls the operator makes to
+# a cluster's HTTP API. Upstream builds its own http.Transport, which carries no
+# dial, handshake or response-header timeout; it passes context.Background() to
+# every call it makes on its own behalf; the calls that take a context from the
+# caller are handed one with no deadline on it; and no http.Client is
+# configured, so there is no timeout there either. A cluster that accepts a
+# connection and then says nothing therefore holds the call for as long as the
+# process lives, and with one worker per controller that one call stops every
+# OpenSearchCluster from being reconciled. The deletion that then waits out its
+# whole termination timeout is the visible end of it. The patch bounds a request
+# on the RoundTripper, the one level that also reaches the product check
+# opensearch-go runs for itself before a client's first request, and bounds the
+# call again where the call site can be reached, because the library retries a
+# request up to three more times on 502, 503 and 504 and the transport's
+# deadline starts over on each. Tracked as cozystack/cozystack#4337;
+# it belongs upstream, there is no upstream issue for it yet, and the patch goes
+# away with the first release that carries a fix.
+#
 # patches/trace-stalled-component-reconcilers.diff names the component a
 # reconcile is stuck in. The cluster controller runs nine component reconcilers
 # in sequence and none of them logs unconditionally when it is entered, so a
@@ -37,9 +55,12 @@
 # It reports rather than repairs: drop it once the stall itself is understood
 # and fixed.
 #
-# The patches are applied in the order the glob expands, which is alphabetical,
-# and skip-unusable-drain-exclusion builds on restart-on-permanently-yellow. A
-# rename that reorders them fails the build rather than producing a wrong binary.
+# The patches are applied in the order the glob expands, which is alphabetical.
+# skip-unusable-drain-exclusion builds on restart-on-permanently-yellow, and
+# timeout-cluster-api-calls rewrites os_client.go call sites that
+# skip-unusable-drain-exclusion both adds and quotes as context, so it has to
+# come after it. A rename that reorders them fails the build rather than
+# producing a wrong binary.
 FROM golang:1.26@sha256:079e59808d2d252516e27e3f3a9c003740dee7f75e55aa71528766d52bcfc16a AS builder
 
 # Keep in step with the chart version pulled by `make update`: the chart's
@@ -63,7 +84,10 @@ WORKDIR /workspace/opensearch-operator
 # them: the build below compiles main.go, so a test file that had stopped
 # compiling, or stopped asserting, would still produce an image. These two
 # package trees are the ones the patches touch, and both run without a cluster.
-RUN go test ./opensearch-gateway/... ./pkg/reconcilers/...
+# -race is on because the timeout tests run a listener in one goroutine and
+# inspect what it accepted from another: an unsynchronised access there passes
+# the plain run, so nothing else would catch it. The builder has cgo and gcc.
+RUN go test -race ./opensearch-gateway/... ./pkg/reconcilers/...
 
 RUN GOOS=$TARGETOS GOARCH=$TARGETARCH CGO_ENABLED=0 go build -a -o manager main.go