Datapages Server

Server entry point

Read datapages first for the build loop, hard rules and naming conventions.

On its first run, datapages gen writes the server command's main.go. It does not regenerate that file on later runs.

NewServer

datapages gen reads the type arguments to find the app package and output directory.

s, err := datapages.NewServer[
	app.App,                     // App
	app.SessionData,             // or datapages.DisableSessions
	datapages.DisablePrometheus, // or datapages.EnablePrometheus
	datapagesgen.Server,         // the datapagesgen of that app package
](&a, broker, opts...) // the app is passed by pointer

Keep the call inside the module. Import datapages with a package name because the scanner rejects dot imports. Generated code is always in datapagesgen directly below its app package. One module can contain several apps. Run one with datapages watch --app frontend.

datapages.EnablePrometheus requires WithPrometheus, DisablePrometheus rejects it.

Broker

A broker is always required. It sends events between server instances and to SSE subscribers. Use modules/messaging/natscore for multiple instances. Use modules/messaging/inmem only for one instance. The generated server uses NATS. Start it with make up before starting the server.

Options

var opts []datapages.ServerOption
opts = append(opts,
	datapages.WithLogger(slog.Default()),
	datapages.WithMiddleware(mw),
	datapages.WithSessions(datapages.SessionsConfig{}),
	datapages.WithSessionManager[app.SessionData](mgr),
	datapages.WithAssets(app.StaticFS, false),
	datapages.WithHTTPServer(&http.Server{ReadHeaderTimeout: 10 * time.Second}),
	datapages.WithDatastarJS("https://cdn.example.com/datastar.js"),
	datapages.WithShutdownTimeout(30*time.Second),
	datapages.WithAssetsCache(datapages.AssetsCacheConfig{}),
	datapages.WithBodySizeLimit(1<<20),
	datapages.WithLogSampling(datapages.LogSamplingConfig{Interval: time.Minute}),
	datapages.WithPrometheus(datapages.PrometheusConfig{Host: ":9091"}),
)

WithBodySizeLimit limits the request body of an action that declares Signals. The default is 1 MiB. An over-limit request returns 400 while reading signals. A handler that reads r.Body itself gets no limit: wrap the body in http.MaxBytesReader. WithLogSampling limits repeated framework warnings, not application logs. WithHTTPServer uses every supplied field except Addr and Handler. Keep WriteTimeout at zero because a nonzero value ends long-lived SSE streams.

WithPrometheus starts a second HTTP server that serves /metrics on the configured host. WithShutdownTimeout limits how long ListenAndServe waits after context cancellation for requests, SSE streams and StreamClose hooks. When the timeout expires, Datapages logs the shutdown error and returns. Cancel the context on SIGTERM as well as SIGINT with signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM). Docker, Kubernetes and systemd stop a process with SIGTERM, which otherwise ends it without a graceful shutdown.

Deployments need no application code. Each page sends its build ID with Datastar requests. A server with a different ID returns 205 Reset Content without running the handler. The page then reloads. Shutdown resets open SSE streams. Datastar then reconnects to the next process. The ID defaults to a hash of the executable. Set WithBuildID when replicas use different binaries for one release. During a rolling deployment, route each client to one build.

The session cookie uses the Secure attribute. Set DisableSecureCookie only when the complete deployment uses plain HTTP, where the browser would reject the secure cookie. datapages.IsDevMode() reports whether the dev server is active. DATAPAGES_DEV_MODE and TEMPL_DEV_MODE enable development behavior. Log at slog.LevelDebug when you need to inspect that behavior.

Declaring PageOffline generates datapagesgen.WithOffline(offline.Config{...}). The option serves the service worker. See datapages-offline.

If WithMiddleware adds a Content-Security-Policy, it must allow script-src 'unsafe-inline' 'unsafe-eval'. Datapages writes the build script, the CSRF script and the instance ID script inline. Datastar compiles every data-* expression at run time.

WithCSPNonce(func(r *http.Request) string) replaces both allowances with a nonce. The application mints the nonce and puts it in its own policy header. Datapages reads it back, writes it on the html element as data-nonce and on every script it writes. Mint the nonce in middleware and store it in the request context: Datapages calls the function several times per response and every call with the same request must return the same value. data-nonce turns on Datastar's CSP mode, which compiles expressions through a nonced script element instead of Function. It needs Datastar 1.0.3 or later. The nonce must differ per response.

WithOffline passes the nonce to the offline module regardless of option order. The nonce cannot reach a page served from the service worker's cache; see datapages-offline.

s.ListenAndServe(ctx, "localhost:8080")
s.ListenAndServeTLS(ctx, "localhost:8443", certPath, keyPath)