Documentation
¶
Overview ¶
Package devsite serves a built site directory the way the hosted static service serves a deployment, so the local dev loop is the deployed behavior.
THE DIRECTORY IS READ ON EVERY REQUEST. There is no deploy step and no snapshot: rebuild with your generator and the next reload has it, delete a file and it is gone. That is the one deliberate difference from hosted, where a deployment is immutable and activation is a pointer move — locally, freezing the bytes at startup would mean restarting the emulator after every build, which is the whole thing this avoids.
Everything a visitor can observe is the hosted behavior: the same path resolution (index files, the trailing-slash redirect, clean URLs, SPA fallback, the custom 404 page), the same content types, and content-hash ETags. Two things are deliberately NOT reproduced, both because reproducing them wastes a developer's afternoon on a local machine:
- Caching. Hosted, a fingerprinted asset gets a year and `immutable`. Here every response is `no-cache` with an ETag, so a rebuild is always picked up and revalidation is still a 304. An immutable asset stuck in a browser for a year is not something a developer can clear from this side.
- The trailing-slash redirect is 302 rather than 301, for the same reason: a permanent redirect a browser has memorized outlives the mistake that caused it.
Index ¶
- func ContentTypeFor(p string) string
- func DetectSPA(st Stats) (bool, string)
- func HumanBytes(n int64) string
- func IsImmutablePath(p string) bool
- func IsNavigationRequest(r *http.Request, p string) bool
- func NormalizePath(raw string) (string, bool)
- func NotModified(ifNoneMatch, etag string) bool
- type Options
- type Server
- type Stats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContentTypeFor ¶
ContentTypeFor returns the type the hosted service will send for this path.
func DetectSPA ¶
DetectSPA decides whether unmatched paths should get the shell.
A client-routed build emits one page; a generator emits one per route, and a 404.html means it has a considered answer for a miss. Guessing wrong in either direction is confusing — an SPA whose deep links 404, or a site whose typos silently render the homepage — so the caller logs what was decided rather than letting it be silent.
func HumanBytes ¶
HumanBytes formats a size the way the deploy command does, so the two agree.
func IsImmutablePath ¶
IsImmutablePath reports whether the hosted service would let a browser cache this path for a year: a delimited run of at least 8 alphanumerics containing a digit, before the extension. Nothing is served immutably HERE — this is what the startup summary counts, so a build whose fingerprinting is not working is visible before it is deployed.
func IsNavigationRequest ¶
IsNavigationRequest reports whether this is a top-level navigation rather than a subresource fetch. That is the question the SPA fallback turns on, and nothing else uses it.
/edit/something.js typed into the address bar and /assets/app-4f2a91bc.js referenced by a script tag are the same string, so the extension cannot tell them apart: the first is one of the app's own routes and must get the shell, the second is a file that is genuinely missing and must 404. The browser already says which it is, in a header the page cannot forge.
Three rungs, because not every client sends it: Sec-Fetch-Dest from any modern browser, then Accept for older ones that still mark navigations with text/html, then the extension for curl and CI checks. Anything unrecognized is a navigation, which is the permissive answer.
func NormalizePath ¶
NormalizePath decodes and resolves a request path to the form a site is keyed in, or returns ok=false for something that is not a path at all. Ported from the hosted service so the two agree on what /a/../b and /hello%20world.html mean.
func NotModified ¶
NotModified reports whether the caller already holds this exact content. `W/` is stripped because every ETag here is a content hash, so weak and strong comparison give the same answer.
Types ¶
type Options ¶
type Options struct {
// Dir is the build output directory, e.g. ./dist. It need not exist yet — a generator that
// has not run is a normal state at startup, not an error.
Dir string
// SPA overrides the detection when non-nil.
SPA *bool
// CleanURLs resolves /about to /about.html. Defaults on, as hosted.
CleanURLs bool
// NotFound is the page served for a miss when SPA is off. Defaults to /404.html, as hosted.
NotFound string
// Overlay are files served from memory, by site path ("/altengine.json"), ahead of the
// directory: a file the emulator generates for a site without writing into the build output.
// With an overlay, Dir may be empty — the site is then the overlay alone.
Overlay map[string][]byte
}
Options configures a site server. The zero value of SPA means "decide from the directory".
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server serves one directory as a site.
type Stats ¶
type Stats struct {
Files int
Bytes int64
Immutable int // files the hosted service would cache for a year
Pages int // .html files
HasIndex bool
Has404 bool
Missing bool // the directory does not exist yet
}
Stats is what one walk of the directory can tell a developer before they deploy.