Documentation
¶
Overview ¶
Package preview is the preview backend: it starts or detects the project's dev server from the starter manifest's dev command and port (loaded through pkg/starterstore), and tracks the server's lifecycle — starting, running, stopped, failed — for the preview pane's presentational component.
The Manager is the single owner of a dev-server start for one project root, and it follows the starter manifest strictly:
- it never guesses a command. A missing manifest, or a manifest without a usable dev declaration (a dev command AND a dev port), settles the state to stopped with a reason;
- it detects an already-running server on the manifest's dev port and adopts it (running, detected) instead of starting a second one;
- a dev server it starts runs in its own process group (verify's DevProcess, the shared platform process type), so Stop releases the port for real, and a liveness monitor settles the state to failed when the dev command dies or the port stops answering.
The package is standard-library plus repo-internal only, so it compiles for the CLI, the webui server, and WASM builds alike. Under WASM the process support is a no-op stub (verify's js build), so Start settles to failed with the stub's reason; hosted previews are out of scope here and are not a local dev server.
Index ¶
Constants ¶
const DefaultReadyTimeout = 30 * time.Second
DefaultReadyTimeout bounds how long Start waits for the dev port to answer after spawning the dev command: it mirrors verify's dev-server timeout (a cold dev-server start without stalling a turn).
Variables ¶
This section is empty.
Functions ¶
func PortServing ¶
PortServing reports whether anything answers a plain HTTP GET on port (any status counts — the dev-port probe). Callers outside the package use it for the detection fast path (the webui start handler) so a dev server already up on the manifest's port is reported synchronously instead of after a start that would find it mid-flight.
Types ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager drives one project's dev server. One manager per project root; every method is safe for concurrent use.
func New ¶
New returns the preview manager for a project root: the manager that starts or detects that project's dev server.
func (*Manager) Restart ¶
Restart stops the dev server this manager started and starts it again. A detected (external) server is not owned, so a restart re-detects it: the port already serves the app, and the outcome is running (detected).
func (*Manager) Start ¶
Start ensures the project's dev server is running and returns the state it settled into:
- running (detected) when something already answers on the manifest's dev port — the manager adopts it instead of starting a second one;
- running when it spawned the manifest's dev command and the port answered within the ready timeout;
- failed with a reason when the dev command could not be started, exited before readiness, or the ready timeout elapsed;
- stopped with a reason when the project has no usable dev declaration (missing or invalid manifest, no dev command, no dev port) — the manager never guesses a command.
Start is synchronous: it blocks until the outcome is known. Callers that want a non-blocking start (the webui handler, so the pane can poll State) run it in a goroutine. A Start that arrives while a first start is still settling waits for that cycle and reports its settled state — it never spawns a second server.
func (*Manager) State ¶
State returns the dev server's current lifecycle state.
A detected (external) running server is re-probed on every read: an external server that dies later settles to stopped (the manager did not start it, so "failed" would be a lie). A started (owned) server's liveness is maintained by the liveness monitor instead, so State never blocks on a probe in that case.
type Option ¶
type Option func(*Manager)
Option customizes a Manager.
func WithReadyTimeout ¶
WithReadyTimeout overrides how long Start waits for the dev port to answer after spawning the dev command (DefaultReadyTimeout otherwise).
type State ¶
type State struct {
Status Status `json:"status"`
URL string `json:"url,omitempty"`
Error string `json:"error,omitempty"`
Detected bool `json:"detected,omitempty"`
// Hosted marks that the URL is a platform-registered preview (the agent
// called register_preview_port in a hosted workspace) rather than a
// local dev server managed by this package. The pane embeds the hosted
// URL directly; local start/restart/stop actions never apply to it.
Hosted bool `json:"hosted,omitempty"`
}
State is the lifecycle snapshot the preview pane renders: the state, the embed URL while running, the reason while stopped/failed, and whether a running server was detected on the port rather than started by the manager.
Source Files