server

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jun 27, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MIMEType 

func MIMEType(ext string) string

MIMEType returns the Content-Type for a file extension. Checks overrides first, then falls back to mime.TypeByExtension, then application/octet-stream.

func RecopyPassthroughFile 

func RecopyPassthroughFile(path string, cfg *config.Config) (string, error)

RecopyPassthroughFile computes the output path for a changed passthrough file.

func ReloadMessage 

func ReloadMessage() []byte

ReloadMessage returns the JSON message sent to the browser via WebSocket to trigger a full page reload.

func RenderOverlay 

func RenderOverlay(errs []BuildError) string

RenderOverlay produces an HTML string for the browser error overlay, displaying all active build errors with file path, line number, error message, pipeline stage, and source code snippet. Used only in dev mode (alloy serve). Never included in alloy build output.

func RenderWarningBanner 

func RenderWarningBanner(warnings []string) string

RenderWarningBanner produces an HTML string for the persistent warning banner displayed when data sources are unreachable. Shows alongside the error overlay in the browser during dev mode.

func WatchDirs 

func WatchDirs(cfg *config.Config) []string

WatchDirs returns the list of directories to watch for file changes, derived from the project config. Always includes content/, layouts/, data/, assets/, static/. Adds component source dirs when SSR is configured.

Types

type BuildError 

type BuildError struct {
	FilePath string // Source file that caused the error (e.g., "content/blog/my-post.md")
	Line     int    // Line number in the source file (0 if unavailable)
	Message  string // Human-readable error description
	Stage    string // Pipeline stage where the failure occurred (e.g., "template rendering")
	Snippet  string // Relevant source code lines around the error
}

BuildError represents a structured error from the build pipeline, displayed in the browser error overlay during dev mode (alloy serve only).

type ChangeEvent 

type ChangeEvent struct {
	Path       string
	ChangeType ChangeType
	IsRemove   bool
}

ChangeEvent represents a single file change detected by the watcher.

type ChangeType 

type ChangeType int

ChangeType classifies a file change to determine rebuild scope. 

const (
	// ContentChange means a file in content/ was modified.
	ContentChange ChangeType = iota + 1
	// LayoutChange means a file in layouts/ was modified.
	LayoutChange
	// DataChange means a file in data/ or a _data.yaml was modified.
	DataChange
	// AssetChange means a file in assets/ was modified.
	AssetChange
	// StaticChange means a file in static/ was modified.
	StaticChange
	// ComponentChange means a component source file was modified.
	ComponentChange
	// PassthroughChange means a file in a passthrough from: directory was modified.
	PassthroughChange
)

func ClassifyChange 

func ClassifyChange(path string, cfg *config.Config) ChangeType

ClassifyChange determines the ChangeType for a modified file path based on which watched directory it falls under.

type Debouncer 

type Debouncer struct {
	// contains filtered or unexported fields
}

Debouncer collects rapid file change events and fires a single callback after a quiet period (default 50ms). If the number of events within a single debounce window exceeds the bulk threshold, it signals a full rebuild instead of incremental.

func NewDebouncer 

func NewDebouncer(interval time.Duration, bulkThreshold int) *Debouncer

NewDebouncer creates a debouncer with the given quiet interval and bulk change threshold.

func (*Debouncer) Debounce 

func (d *Debouncer) Debounce(events []ChangeEvent) ([]ChangeEvent, RebuildScope)

Debounce accepts a stream of change events and calls onRebuild once after the quiet interval elapses. Returns the accumulated events and the recommended rebuild scope (incremental vs full).

type OverlayState 

type OverlayState struct {
	// contains filtered or unexported fields
}

OverlayState tracks active build errors for the dev server error overlay. Errors are accumulated during a failed rebuild and cleared on success.

func NewOverlayState 

func NewOverlayState() *OverlayState

NewOverlayState creates an empty overlay state with no active errors.

func (*OverlayState) ClearErrors 

func (s *OverlayState) ClearErrors()

ClearErrors removes all active errors after a successful rebuild.

func (*OverlayState) Errors 

func (s *OverlayState) Errors() []BuildError

Errors returns the active build errors.

func (*OverlayState) HasErrors 

func (s *OverlayState) HasErrors() bool

HasErrors returns true if there are active build errors.

func (*OverlayState) SetErrors 

func (s *OverlayState) SetErrors(errs []BuildError)

SetErrors records build errors from a failed rebuild.

func (*OverlayState) SetWarnings 

func (s *OverlayState) SetWarnings(warnings []string)

SetWarnings records persistent warnings (e.g., unreachable data sources).

func (*OverlayState) Warnings 

func (s *OverlayState) Warnings() []string

Warnings returns the active warnings.

type RebuildScope 

type RebuildScope int

RebuildScope indicates whether to do an incremental or full rebuild. 

const (
	// RebuildIncremental means only affected pages are rebuilt.
	RebuildIncremental RebuildScope = iota + 1
	// RebuildFull means all pages are rebuilt (triggered by bulk changes, config, etc.).
	RebuildFull
	// RebuildPipeline means the change requires running the pipeline (content, layouts, data).
	RebuildPipeline
	// RebuildRecopy means the change only requires recopying files (static, assets, passthrough).
	RebuildRecopy
)

func RebuildScopeForChangeType 

func RebuildScopeForChangeType(ct ChangeType) RebuildScope

RebuildScopeForChangeType returns the rebuild scope for a given change type.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server is the Alloy dev/preview server.

func New 

func New(cfg *config.Config) *Server

New creates a new Server with the given config in dev mode.

func NewWithMode 

func NewWithMode(cfg *config.Config, mode ServerMode) *Server

NewWithMode creates a new Server with the given config and explicit mode.

func (*Server) BroadcastReload 

func (s *Server) BroadcastReload()

BroadcastReload sends a reload message to all connected WebSocket clients. Failed connections are removed from the map but not closed here — handleWebSocket owns the close to avoid double-close.

func (*Server) DebounceInterval 

func (s *Server) DebounceInterval() int

DebounceInterval returns the file watcher debounce interval in milliseconds.

func (*Server) DetermineRebuildAction 

func (s *Server) DetermineRebuildAction(changedFiles []string) RebuildScope

DetermineRebuildAction decides whether a set of file changes should trigger an incremental or full rebuild. Many simultaneous changes trigger a full rebuild.

func (*Server) HandleExternalSourceFailure 

func (s *Server) HandleExternalSourceFailure(sourceName string, err error) error

HandleExternalSourceFailure handles an unreachable external data source. In dev mode: logs warning, continues with stale cache data. In build mode: returns error (build must abort even if stale cache exists).

func (*Server) HandlePluginCrash 

func (s *Server) HandlePluginCrash(pluginName string, err error) error

HandlePluginCrash handles a plugin subprocess crash. In both modes: stops the server / aborts the build.

func (*Server) InjectOverlay 

func (s *Server) InjectOverlay(html []byte, overlay *OverlayState) ([]byte, error)

InjectOverlay wraps the response HTML with the error overlay when there are active build errors. Only applies in dev mode.

func (*Server) Mode 

func (s *Server) Mode() ServerMode

Mode returns the current server operating mode.

func (*Server) Overlay 

func (s *Server) Overlay() *OverlayState

Overlay returns the server's error overlay state.

func (*Server) Port 

func (s *Server) Port() int

Port returns the actual port the server is listening on. Returns 0 before the server has started.

func (*Server) RenderPage 

func (s *Server) RenderPage(path string, content []byte) ([]byte, error)

RenderPage renders a single page and returns its HTML. In dev mode, returns error overlay HTML on failure instead of propagating the error. In build mode, returns the error directly.

func (*Server) Serve404Page 

func (s *Server) Serve404Page(outputDir string) ([]byte, error)

Serve404Page reads 404.html from the output root and returns its contents. In dev mode, injects the live-reload WebSocket script before </body> so the 404 page auto-reloads when the user fixes a broken route. Returns an error if the file does not exist, allowing the caller to fall back to Go's default http.NotFound() response.

func (*Server) ServeContentFile 

func (s *Server) ServeContentFile(urlPath string) ([]byte, error)

ServeContentFile reads a non-content file from the content directory. Used in dev mode to serve colocated files (SVGs, images, etc.) directly from source without writing to _site/.

func (*Server) SetNoDrafts 

func (s *Server) SetNoDrafts(noDrafts bool)

SetNoDrafts configures the server to exclude draft content even in dev mode. This is triggered by the --no-drafts CLI flag.

func (*Server) ShouldIncludeDrafts 

func (s *Server) ShouldIncludeDrafts() bool

ShouldIncludeDrafts returns true if draft content should be visible. Dev mode includes drafts; preview mode excludes them (same as build). The --no-drafts flag overrides dev mode behavior.

func (*Server) ShouldOpenBrowser 

func (s *Server) ShouldOpenBrowser() bool

ShouldOpenBrowser returns true if the server should auto-open a browser on start.

func (*Server) ShouldRunSSR 

func (s *Server) ShouldRunSSR() bool

ShouldRunSSR returns true if the server should execute the Phase 2 SSR pipeline. Only true in preview mode when SSR is configured.

func (*Server) ShouldWriteToDisk 

func (s *Server) ShouldWriteToDisk() bool

ShouldWriteToDisk returns true if the server should write output to _site/ (preview mode) instead of serving from an in-memory map (dev mode).

func (*Server) Start 

func (s *Server) Start(port int) error

Start launches the HTTP server on the given port. The server runs in a background goroutine; call Stop() or Wait() to manage lifecycle.

func (*Server) StartOnPort 

func (s *Server) StartOnPort(port int) error

StartOnPort attempts to start the server on a specific port. Returns a descriptive error if the port is already in use.

func (*Server) StartWithPortFallback 

func (s *Server) StartWithPortFallback(preferredPort, maxAttempts int) (int, error)

StartWithPortFallback tries to start the server on preferredPort, incrementing up to maxAttempts times if the port is occupied. Returns the actual port used.

func (*Server) Stop 

func (s *Server) Stop() error

Stop gracefully shuts down the server with a 5-second timeout.

func (*Server) Wait 

func (s *Server) Wait()

Wait blocks until the server stops (via Stop() or error).

func (*Server) WebSocketReloadMessage 

func (s *Server) WebSocketReloadMessage() string

WebSocketReloadMessage returns the JSON message sent to connected browsers to trigger a page reload. Format: {"type": "reload"}

type ServerMode 

type ServerMode int

ServerMode represents the operating mode of the dev server. 

const (
	// ModeDev is the default `alloy serve` mode: Phase 1 only, in-memory,
	// client-side components, drafts visible.
	ModeDev ServerMode = iota + 1
	// ModePreview is `alloy serve --preview`: same pipeline as build,
	// writes to _site/, SSR if configured, drafts excluded.
	ModePreview
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.