@@ -328,7 +328,32 @@ func userAgentOverride(logger *slog.Logger, userAgent string) chromedp.ActionFun
328328// }
329329// }
330330
331- func navigateActionFunc (logger * slog.Logger , url string , skipNetworkIdleEvent , skipNetworkAlmostIdleEvent bool ) chromedp.ActionFunc {
331+ // navigateOptions carries the lifecycle-gating knobs for
332+ // [navigateActionFunc].
333+ type navigateOptions struct {
334+ // SkipNetworkIdleEvent, when true, skips the wait for the
335+ // "networkIdle" lifecycle event.
336+ SkipNetworkIdleEvent bool
337+
338+ // SkipNetworkAlmostIdleEvent, when true, skips the wait for the
339+ // "networkAlmostIdle" lifecycle event.
340+ SkipNetworkAlmostIdleEvent bool
341+
342+ // SkipLifecycleEvents, when true, returns as soon as the
343+ // [page.Navigate] RPC ack returns. All lifecycle waits
344+ // (DomContentEventFired, LoadEventFired, LoadingFinished, and
345+ // both network-idle events) are bypassed. Callers set this when
346+ // the operator provided an explicit readiness signal
347+ // (waitForExpression or waitForSelector) that will gate the
348+ // downstream print or screenshot action, so Gotenberg does not
349+ // need to also impose its own lifecycle gate. Pages whose load
350+ // lifecycle never fires cleanly (blocking scripts, streaming
351+ // responses, misbehaving iframes) otherwise stall navigate and
352+ // starve the explicit signal.
353+ SkipLifecycleEvents bool
354+ }
355+
356+ func navigateActionFunc (logger * slog.Logger , url string , opts navigateOptions ) chromedp.ActionFunc {
332357 return func (ctx context.Context ) error {
333358 logger .DebugContext (ctx , fmt .Sprintf ("navigate to '%s'" , url ))
334359
@@ -337,19 +362,24 @@ func navigateActionFunc(logger *slog.Logger, url string, skipNetworkIdleEvent, s
337362 return fmt .Errorf ("navigate to '%s': %w" , url , err )
338363 }
339364
365+ if opts .SkipLifecycleEvents {
366+ logger .DebugContext (ctx , "skipping lifecycle events; waitForExpression or waitForSelector gates readiness" )
367+ return nil
368+ }
369+
340370 waitFunc := []func () error {
341371 waitForEventDomContentEventFired (ctx , logger ),
342372 waitForEventLoadEventFired (ctx , logger ),
343373 waitForEventLoadingFinished (ctx , logger ),
344374 }
345375
346- if ! skipNetworkIdleEvent {
376+ if ! opts . SkipNetworkIdleEvent {
347377 waitFunc = append (waitFunc , waitForEventNetworkIdle (ctx , logger ))
348378 } else {
349379 logger .DebugContext (ctx , "skipping network idle event" )
350380 }
351381
352- if ! skipNetworkAlmostIdleEvent {
382+ if ! opts . SkipNetworkAlmostIdleEvent {
353383 waitFunc = append (waitFunc , waitForEventNetworkAlmostIdle (ctx , logger ))
354384 } else {
355385 logger .DebugContext (ctx , "skipping network almost idle event" )
0 commit comments