serve

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 7, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package serve holds the two pieces of HTTP plumbing `puzzle dev` and `puzzle preview` must agree on: the loopback port scan (D90) and the mode-aware mapping from a request path onto a built dist/ tree.

The resolver exists because "what URL serves what file" is a property of the OUTPUT MODE, not of the command: an SPA falls back to index.html for anything that is not a file, a hybrid build serves the prerendered page for a route when one exists, and a true static build resolves clean URLs against directory index.html files and 404s on a miss — because that is what a static host does, and preview's job is to behave like one. Resolve answers only "which file, what status"; writing the response (live-reload injection in dev, none in preview) stays with each caller.

Index

Constants

View Source
const (
	ModeSPA    = ""
	ModeHybrid = "hybrid"
	ModeStatic = "static"
)

The resolved output modes. They are the values `puzzle.config.js` `output` takes ("" meaning the default SPA build), so a config value passes straight in.

View Source
const PortScanLimit = 10

PortScanLimit is how many consecutive ports Listen tries before giving up. A busy default port is a papercut, not a failure (the same posture as Vite, Next, and Astro), but the scan is bounded so a wedged machine reports a real error instead of walking the port space.

Variables

This section is empty.

Functions

func BoundPort

func BoundPort(ln net.Listener, fallback int) int

BoundPort reports the port a listener actually bound, falling back to fallback for a non-TCP address that could never occur through Listen but should not panic a type assertion if it ever did.

func Listen

func Listen(port int, strict bool) (net.Listener, error)

Listen binds the first free loopback port at or above `port`, returning the listener. With strict set, only `port` itself is tried (D90).

Loopback only: the dev and preview servers are a local convenience, not a LAN service. The banner prints localhost, so the bind must match. No host config option in v1.

Any bind failure advances the scan, and the FIRST error is what surfaces once the range is exhausted — it belongs to the port the user actually asked for. Testing for EADDRINUSE specifically would need per-OS errno handling (Windows reports WSAEADDRINUSE), and it buys nothing: a failure that is not "in use" (permission, unavailable interface) fails identically on every candidate, so the scan costs a few syscalls and still reports the right error.

Port 0 is passed through untouched — the kernel picks a free port and the one attempt always succeeds, so there is nothing to scan.

Types

type Result

type Result struct {
	// File is the absolute path of the file to serve. Empty only when Status is
	// 404 and the tree carries no 404.html.
	File string
	// Shell reports that File is the ROOT dist/index.html being served as the SPA
	// document (either the root URL or the history-API fallback). Never true in
	// static mode, which has no shell. `puzzle dev` treats this response
	// specially: it is the one that carries the injected live-reload client in SPA
	// mode, and the one that degrades to the D92 build-error page when the file is
	// missing.
	Shell bool
	// HTML reports that File is an HTML document, so a caller may rewrite it
	// (dev's serve-time reload injection) rather than stream it verbatim.
	HTML bool
	// Status is the status code to write: 200, or 404 for a static-mode miss.
	Status int
}

Result is how a request path maps onto the dist tree.

func Resolve

func Resolve(dist, mode, urlPath string) Result

Resolve maps urlPath onto dist for the given output mode.

  • SPA: an existing regular file, else the root index.html (history fallback).
  • hybrid: an existing regular file, else the route's prerendered <path>/index.html when one was written, else the root index.html — the router owns whatever was not prerendered.
  • static: an existing regular file, else the clean-URL <path>/index.html, else a real 404 (dist/404.html when the catch-all route wrote one, which is the file GitHub Pages / Netlify / Cloudflare serve). No index.html fallback: a static host has no router to fall back to.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL