convert

Documentation

Overview

Package convert is the ONE AND ONLY package in the eden-press module that imports github.com/chromedp/chromedp (and its cdproto companion). Every chromedp-touching type, launch flag, and CDP call lives under convert/ or one of its subpackages (convert/chrome, and the sibling exporters convert/pdf and convert/png added by later TRDs).

press/, chase/, and profiles/ MUST NEVER import convert/ (directly or transitively) -- doing so would pull chromedp into the public render path, breaking the zero-chromedp boundary that scripts/check-no-chromedp.sh mechanically enforces in CI (`go list -deps ./press/... ./chase/... ./profiles/...` must contain zero chromedp packages). The dependency edge is strictly one-directional: convert/ imports press/ (to consume press.Output as its rendering input), and press/ never imports convert/.

This boundary is why chromedp is provisioned here, in this TRD, and nowhere else: the moment chromedp entered go.mod, check-no-chromedp.sh became the load-bearing proof that the one-directional edge holds.

Index

• type ImageFormat
  • func (f ImageFormat) String() string
• type Options

Types

type ImageFormat

type ImageFormat int

ImageFormat selects the raster image format a screenshot-based exporter (convert/png, added by a later TRD) produces. The zero value is PNG.

const (
	// PNG is the lossless raster format and the zero value of ImageFormat.
	PNG ImageFormat = iota
	// JPEG is the lossy raster format, selectable when smaller output size
	// matters more than pixel-perfect fidelity.
	JPEG
)

func (ImageFormat) String

func (f ImageFormat) String() string

String returns the lower-case name of the format ("png" or "jpeg"). An unrecognized value (outside the two declared constants) returns "unknown" rather than panicking.

type Options

type Options struct {
	// BrowserPath, when non-empty, is an explicit Chrome/Chromium executable
	// override -- the highest-precedence tier of convert/chrome.Discover's
	// fallback chain. Leave empty to let Discover fall through to
	// CHROME_PATH, then auto-detection, then the documented pinned-download
	// tier.
	BrowserPath string

	// StartTimeout bounds how long browser ALLOCATION may take -- the launch
	// plus the DevTools handshake -- before New gives up and returns an error.
	// Zero means DefaultStartTimeout.
	//
	// This exists because there was previously no bound at all: allocation ran
	// against context.Background(), so a browser that never became usable left
	// the caller blocked forever with nothing logged. A hang is unobservable by
	// construction -- no error, no exit code -- and this one took down an
	// export sidecar in production, where the readiness endpoint that called it
	// simply stopped answering.
	//
	// It covers two different failures. A browser can fail to complete its
	// DevTools handshake at all, or it can complete the handshake and then
	// stall before its first tab is usable. The production incident was the
	// second kind: the websocket connection was established, and Chrome's
	// crash-looping GPU process then starved the renderer so it never answered
	// Runtime.enable. Set BrowserLog to tell the two apart.
	//
	// It bounds ONLY startup. The browser's own lifetime stays tied to an
	// unbounded context, because a deadline there would kill a healthy
	// long-lived Session mid-render.
	StartTimeout time.Duration

	// BrowserLog, when non-nil, receives Chrome's combined stdout+stderr for
	// the browser's entire lifetime. When nil, that output is discarded -- but
	// the pipe is still created and still drained.
	//
	// That distinction is not cosmetic, and it is the difference between
	// diagnosing a failed launch and guessing at one. chromedp reads Chrome's
	// output only until it finds the "DevTools listening on" line; from there
	// it branches on whether a writer was configured, and with NO writer it
	// CLOSES the output pipe outright. Every line Chrome emits after startup is
	// then destroyed at the source.
	//
	// Two failed production deploys produced zero browser diagnostics for
	// exactly this reason: Chrome's GPU process was crash-looping and saying so
	// continuously, but the crash-loop begins after the websocket URL is parsed
	// -- that is, after chromedp had already closed the pipe. Setting this
	// writer surfaced the root cause on the first run afterwards.
	//
	// Leaving it nil is safe and is the default; convert/chrome substitutes
	// io.Discard rather than passing nil through, so the pipe is never closed
	// out from under a browser that still has something to say.
	BrowserLog io.Writer
}

Options is the shared cross-exporter option surface both convert/pdf and convert/png (added by later TRDs) consume. It is deliberately minimal -- mirroring the frozen-surface discipline of press.Options -- and grows a field only when a named consumer needs it, never speculatively.