devsite

package
v0.2.37 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 14 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContentTypeFor

func ContentTypeFor(p string) string

ContentTypeFor returns the type the hosted service will send for this path.

func DetectSPA

func DetectSPA(st Stats) (bool, string)

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

func HumanBytes(n int64) string

HumanBytes formats a size the way the deploy command does, so the two agree.

func IsImmutablePath

func IsImmutablePath(p string) bool

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

func IsNavigationRequest(r *http.Request, p string) bool

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

func NormalizePath(raw string) (string, bool)

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

func NotModified(ifNoneMatch, etag string) bool

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.

func New

func New(o Options) (*Server, error)

New builds a site server for dir.

func (*Server) Dir

func (s *Server) Dir() string

Dir returns the absolute directory being served.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Server) Summary

func (s *Server) Summary() []string

Summary is the startup block: what will be served, and what the hosted service will make of it.

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.

func Scan

func Scan(dir string) Stats

Scan walks the directory once. Cheap enough to run at startup and on the first request after the directory appears.

Jump to

Keyboard shortcuts

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