Skip to content

Commit 430f95f

Browse files
committed
feat(chromium): skip lifecycle waits when waitForExpression or waitForSelector is set
1 parent 259d80b commit 430f95f

4 files changed

Lines changed: 78 additions & 6 deletions

File tree

‎pkg/modules/chromium/browser.go‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -317,7 +317,11 @@ func (b *chromiumBrowser) pdf(ctx context.Context, logger *slog.Logger, url, out
317317
disableJavaScriptActionFunc(logger, b.arguments.disableJavaScript),
318318
setCookiesActionFunc(logger, options.Cookies),
319319
userAgentOverride(logger, options.UserAgent),
320-
navigateActionFunc(logger, url, options.SkipNetworkIdleEvent, options.SkipNetworkAlmostIdleEvent),
320+
navigateActionFunc(logger, url, navigateOptions{
321+
SkipNetworkIdleEvent: options.SkipNetworkIdleEvent,
322+
SkipNetworkAlmostIdleEvent: options.SkipNetworkAlmostIdleEvent,
323+
SkipLifecycleEvents: options.WaitForExpression != "" || options.WaitForSelector != "",
324+
}),
321325
hideDefaultWhiteBackgroundActionFunc(logger, options.OmitBackground, options.PrintBackground),
322326
forceExactColorsActionFunc(logger, options.PrintBackground),
323327
emulateMediaTypeActionFunc(logger, options.EmulatedMediaType, options.EmulatedMediaFeatures),
@@ -343,7 +347,11 @@ func (b *chromiumBrowser) screenshot(ctx context.Context, logger *slog.Logger, u
343347
disableJavaScriptActionFunc(logger, b.arguments.disableJavaScript),
344348
setCookiesActionFunc(logger, options.Cookies),
345349
userAgentOverride(logger, options.UserAgent),
346-
navigateActionFunc(logger, url, options.SkipNetworkIdleEvent, options.SkipNetworkAlmostIdleEvent),
350+
navigateActionFunc(logger, url, navigateOptions{
351+
SkipNetworkIdleEvent: options.SkipNetworkIdleEvent,
352+
SkipNetworkAlmostIdleEvent: options.SkipNetworkAlmostIdleEvent,
353+
SkipLifecycleEvents: options.WaitForExpression != "" || options.WaitForSelector != "",
354+
}),
347355
hideDefaultWhiteBackgroundActionFunc(logger, options.OmitBackground, true),
348356
forceExactColorsActionFunc(logger, true),
349357
emulateMediaTypeActionFunc(logger, options.EmulatedMediaType, options.EmulatedMediaFeatures),

‎pkg/modules/chromium/chromium.go‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,11 +160,22 @@ type Options struct {
160160
WaitWindowStatus string
161161

162162
// WaitForExpression is the custom JavaScript expression to wait before
163-
// converting an HTML document until it returns true
163+
// converting an HTML document until it returns true.
164+
//
165+
// When set, Gotenberg skips the browser lifecycle events
166+
// (DomContentEventFired, LoadEventFired, LoadingFinished,
167+
// networkIdle, networkAlmostIdle) during navigation and treats the
168+
// expression as the sole readiness signal. Encode any load-event
169+
// dependency into the expression itself (for example
170+
// "document.readyState === 'complete' && window.myAppReady").
164171
WaitForExpression string
165172

166173
// WaitForSelector is the element query to wait until visible before
167174
// converting an HTML document.
175+
//
176+
// When set, Gotenberg skips the browser lifecycle events during
177+
// navigation and treats the selector visibility as the sole
178+
// readiness signal.
168179
WaitForSelector string
169180

170181
// Cookies are the cookies to put in the Chromium cookies' jar.

‎pkg/modules/chromium/tasks.go‎

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -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")

‎test/integration/features/chromium_convert_html.feature‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,29 @@ Feature: /forms/chromium/convert/html
195195
Wait delay > 2 seconds or expression window globalVar === 'ready' returns true.
196196
"""
197197

198+
Scenario: POST /forms/chromium/convert/html (waitForExpression skips lifecycle events)
199+
Given I have a Gotenberg container with the following environment variable(s):
200+
| LOG_LEVEL | debug |
201+
When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
202+
| files | testdata/feature-rich-html/index.html | file |
203+
| waitForExpression | window.globalVar === 'ready' | field |
204+
Then the response status code should be 200
205+
Then the response header "Content-Type" should be "application/pdf"
206+
Then there should be 1 PDF(s) in the response
207+
Then the Gotenberg container should log the following entries:
208+
| skipping lifecycle events; waitForExpression or waitForSelector gates readiness |
209+
210+
Scenario: POST /forms/chromium/convert/html (no readiness signal keeps lifecycle waits)
211+
Given I have a Gotenberg container with the following environment variable(s):
212+
| LOG_LEVEL | debug |
213+
When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
214+
| files | testdata/page-1-html/index.html | file |
215+
Then the response status code should be 200
216+
Then the response header "Content-Type" should be "application/pdf"
217+
Then there should be 1 PDF(s) in the response
218+
Then the Gotenberg container should NOT log the following entries:
219+
| skipping lifecycle events; waitForExpression or waitForSelector gates readiness |
220+
198221
Scenario: POST /forms/chromium/convert/html (Wait For Selector)
199222
Given I have a default Gotenberg container
200223
When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):

0 commit comments

Comments
 (0)