petitweb

README

Popcorn Web

Popcorn Web is a small, TinyGo-oriented web application framework for Go, built directly on net/http. Templates, SQL, request binding, and OpenAPI compile to typed Go ahead of time, so a renamed template argument or a SELECT that no longer matches its result type is a build error rather than a production incident. Nothing is rediscovered by reflection at request time, which is also what lets the same source compile under TinyGo.

Routing is net/http's own ServeMux, handlers stay http.HandlerFunc, and queries return through database/sql — so the middleware, httptest tests, and http.Handlers already in your codebase keep working, and a handler can leave this framework as easily as it entered.

Documentation: https://shibukawa.github.io/popcornweb/

Quick start

brew install shibukawa/tap/pw
pw init myapp
cd myapp
pw dev

pw init asks about ten choices and then writes a project that already compiles: a handler, a typed page, a document shell, error pages, configuration, and a devbox.json. It runs go mod tidy and pw generate before reporting success, so there is no separate setup step afterwards. pw dev then starts the declared services, regenerates code, applies pending migrations, builds, runs, and restarts on every change — Ctrl-C stops all of it together.

Generated projects pin their own Go toolchain, so you do not need a matching Go installed before creating one. Devbox is optional; if Go is on PATH, run pw dev directly.

Installing

The pw command

pw handles scaffolding, code generation, formatting, migrations, and the development server. Install it first.

Channel	Command	Covers
Homebrew	brew install shibukawa/tap/pw	macOS (Apple Silicon and Intel), Linux
Nix	nix run github:shibukawa/popcornweb#pw -- version	x86_64-linux, aarch64-linux, aarch64-darwin
Release archive	releases page	every target, and the only channel covering Windows
Go toolchain	go install github.com/shibukawa/popcornweb/cmd/pw@latest	anywhere a matching Go toolchain is installed

Homebrew and the release archives ship a prebuilt binary; the Nix derivation and go install build from source. go install is listed last because it needs a Go toolchain matching the module's requirement, which is exactly the prerequisite the other three channels remove. The flake also exposes a devShells.default with Go, gopls, and TinyGo if you want the host toolchain without Devbox.

Confirm the installation with pw version.

The library

Popcorn Web requires Go 1.26 or later. pw init writes a go.mod that already requires the framework; an existing module needs one step:

go get github.com/shibukawa/popcornweb

Application code imports pw, which is the stable application-facing API:

import "github.com/shibukawa/popcornweb/pw"

Using pw

One command covers the project lifecycle. Every command except pw init finds the project by walking upward from the working directory until it reaches popcornweb.toml, so all of them work from any nested directory.

Command	Purpose
pw init	create a runnable project in a new directory
pw add	enable a capability the project declined at init
pw new	scaffold one more handler or page
pw generate	write everything a compiler needs, stopping before the compiler
pw check	report generated files that are stale or missing
pw fmt	format template sources into their canonical form
pw i18n	reconcile message catalogs against the templates that use them
pw migrate	inspect, apply, and roll back migrations
pw seed	load seed datasets
pw build	generate and compile a release binary
pw dev	watch, regenerate, migrate, rebuild, and restart
pw doctor	report what a named environment will actually run
pw lsp	serve editor analysis over the Language Server Protocol

pw build --backend selects the HTTP implementation (nethttp or fasthttp) and --target selects deployment packaging (lambda, azure-functions, google-cloud-run-functions, vercel-go). Run pw help for the full flag list of every command.

What the code looks like

A .pw.html file is a typed template language that compiles to Go. Its parameters become a Go struct, so misspelling one is a generation error with a position rather than a blank region at runtime.

package handlers

export component Home(count: int): html {
  <main>
    <h1>Hello, World!</h1>
    <p>Page views: <strong>{count}</strong></p>
  </main>
}

A .pw.sql file is the same idea for queries. The result contract is declared, and a projection that stops matching it fails generation.

package queries

type AccessCounter { count: int }

export statement IncrementAccess(): sql.one<AccessCounter> {
  INSERT INTO access_counter (id, count)
  VALUES (1, 1)
  ON CONFLICT(id) DO UPDATE SET count = access_counter.count + 1
  RETURNING count
}

The handler that joins them is a plain http.HandlerFunc:

package handlers

import (
	"net/http"

	"github.com/shibukawa/popcornweb/pw"
	"myapp/queries"
)

func init() { mux.HandleFunc("GET /{$}", home) }

func home(w http.ResponseWriter, r *http.Request) {
	counter, err := queries.IncrementAccess(r.Context())
	if err != nil {
		pw.WriteProblem(w, r, pw.InternalServerError(err))
		return
	}
	pw.WriteHTML(w, r, Home(HomeParams{Count: counter.Count}))
}

pw generate writes the _pw_gen.go files that back Home, HomeParams, and queries.IncrementAccess. They are build output, excluded by the .gitignore pw init wrote, and never edited by hand.

Features

Core

Feature
Standard-library routing	pw.ServeMux is a type alias for net/http.ServeMux — same patterns, wildcards, and precedence
Registered and discovered routing	register routes explicitly, or let a directory tree declare them
Middleware	ordinary func(http.Handler) http.Handler, plus request IDs, recovery, body limits, and request-scoped loggers
Typed configuration	TOML and environment variables, per-environment, with scaffolds generated from the declarations
Custom commands	typed CLI subcommands on the deployed binary
Operational endpoints	health, readiness, OpenAPI, graceful shutdown, reverse-order cleanup

Frontend and rendering

Feature
Typed templates	.pw.html components with typed parameters, compiled to Go
Scoped styles and Tailwind	a component's <style> block is namespaced at compile time; Tailwind is one pw add tailwind away
Responses	HTML, JSON, XML, CSV, redirects, downloads, and RFC 9457 problem documents
Async rendering	stream the page around a boundary that is still loading
Live rendering	keep updating a region while the reader stays on the page
Partial updates	answer a same-origin link with only the regions whose markup differs
Rendering cache	cache rendered output by scope
Static assets	embedded, fingerprinted asset serving
i18n	message catalogs reconciled against the templates that use them, plus locale routing

Interactivity

Feature
Server actions	name a Go function from a template instead of writing its URL
Forms	client-side feedback that agrees with the server-side checks, and suggestion lists that need no script
Fragments	server-rendered fragments combined with dialogs, popovers, and custom elements
Navigation	view transitions and speculation rules, so ordinary page-to-page navigation feels continuous
Signals	a named instruction from a live source to code the page registered
Component scripts and browser controls	the small amount of browser code a server-rendered page still needs
htmx and React	supported when you want them, not required
Typed streams	one response as a sequence of typed events — SSE, NDJSON, or a JSON array, chosen by the client
WebSocket	declare an inbound and an outbound struct; generation writes the encoding on both sides

Storage

Feature
Typed SQL	.pw.sql compiled to typed Go over database/sql
Relational databases	SQLite, PostgreSQL, and MySQL/MariaDB, each on TinyGo as well
DynamoDB and Firestore	typed .pw.dynamo and Firestore templates
Object storage	uploads in S3-compatible storage, through a TinyGo-capable S3 client
Batching	cutting the cost of many statements — a transaction on SQLite, Batch and COPY on PostgreSQL
Data cache	reuse what an upstream call returned for the same typed question, with concurrent misses collapsed onto one call
Migrations and seed data	applied by pw migrate and pw dev

Authentication and security

Feature
What is defended by default	what the framework handles, what it hands you, and where a request is checked before your handler runs
Authentication	OpenID Connect (Authorization Code with PKCE), WebAuthn passkeys, or both; jwt_only verifies a bearer token without mounting a login
Sessions	opaque server-side sessions or sealed cookies, over several stores
Security headers	validated browser policy by default, plus CSRF
CORS and rate limiting	configuration switches rather than assembled stacks

Operations

Feature
OpenTelemetry	structured logs and traces, with framework spans reaching each SQL statement
OpenAPI 3.1	generated from the handlers, bindings, and comments already in the code
Compression	negotiated zstd and gzip, off by default because a proxy usually owns it
pw doctor	resolves a named environment and reports missing, conflicting, or unsafe settings before deployment
Dev console	routes, queries, storybook, telemetry, and diagnostics during pw dev
Testing	run an application from an isolated copy of every registered configuration, with E2E support

Build and deployment targets

Target
Go and TinyGo	the same source, with no reflection in the generated path
net/http and fasthttp	selected by pw build --backend
Containers	image builds from the project
Serverless	AWS Lambda, Azure Functions, Google Cloud Run functions, Vercel
Reverse proxy and service proxy	in front of, or from within, the application

Examples

examples/ holds complete applications, each with its own README.

Example
helloworld	the pw init scaffold, with a SQLite counter
todo	one todo list written twice against one PostgreSQL table — once with net/http and pgx, once with the framework — so binary size and throughput are measured on identical behaviour
async_render	a page whose slow sections stream in afterwards
live_render	two regions that keep changing on the server's clock
partial_update	two routes under one layout, with a table whose rows update in place
htmx_fragment	a task board where every interaction re-renders one region
websocket_chat	a chat room over a typed WebSocket, in both builds
oidclogin	browser login through OpenID Connect
passkeylogin	OpenID Connect creates the account, a passkey handles repeat login

Editor support

tools/vscode is a Visual Studio Code extension that highlights the three source dialects — .pw.html, .pw.sql, and .pw.dynamo — including the template expressions embedded in their HTML, SQL, and clause bodies. It is a grammar only: nothing is executed, no binary is needed, and it works on a file opened with no workspace. Diagnostics and completion are planned for a later version through a pw lsp language server.

Documentation

• Why Popcorn Web — what the project is trying to do, and the measurements behind it
• Installation
• Tutorial — five chapters from an empty directory to a login
• Guides — one page per feature, in English and Japanese
• Performance — binary size and throughput per build target, and what changes when you switch
• Reference — the runtime API, the template and query languages, and every configuration key

License

Apache License 2.0. See LICENSE.

The MySQL driver carried by tinygodriver includes an MPL-2.0 TinyGo fork; that notice travels with any artifact that links it.

Documentation

Overview

Package petitweb provides the reflection-free runtime for Petitweb classic applications. It deliberately builds on net/http: handlers, middleware, and response writers remain ordinary standard-library values.

Index

• Constants
• func CSV(w http.ResponseWriter, status int, records [][]string) error
• func Download(w http.ResponseWriter, status int, filename, contentType string, ...) error
• func HTML(w http.ResponseWriter, status int, renderer Renderer) error
• func JSON(w http.ResponseWriter, status int, value any) error
• func ReadRequestID(ctx context.Context) (string, bool)
• func Redirect(w http.ResponseWriter, r *http.Request, location string, status int)
• func WriteError(w http.ResponseWriter, r *http.Request, err error)
• func XML(w http.ResponseWriter, status int, value any) error
• type App
  • func New(options ...Option) *App
  • func (a *App) Handle(pattern string, handler http.Handler)
  • func (a *App) HandleFunc(pattern string, handler http.HandlerFunc)
  • func (a *App) Handler() http.Handler
  • func (a *App) ListenAndServe(addr string) error
  • func (a *App) Middlewares() []Middleware
  • func (a *App) Mux() *httpmux.ServeMux
  • func (a *App) Run(ctx context.Context, addr string) error
  • func (a *App) Serve(server *http.Server) error
  • func (a *App) SetErrorRenderer(renderer ErrorRenderer)
  • func (a *App) Shutdown(ctx context.Context) error
  • func (a *App) String() string
  • func (a *App) Use(middleware ...Middleware)
  • func (a *App) Validate() error
  • func (a *App) WriteError(w http.ResponseWriter, r *http.Request, err error)
• type Attribute
  • func Bool(key string, value bool) Attribute
  • func Err(err error) Attribute
  • func Float64(key string, value float64) Attribute
  • func Int(key string, value int) Attribute
  • func Int64(key string, value int64) Attribute
  • func String(key, value string) Attribute
• type ErrorHandler
  • func (h ErrorHandler) WriteError(w http.ResponseWriter, r *http.Request, err error)
• type ErrorPage
  • func (p ErrorPage) String() string
• type ErrorRenderer
• type HSTSConfig
• type Lifecycle
• type Logger
  • func ReadLogger(ctx context.Context) Logger
• type Middleware
  • func LifecycleHeaders(lifecycle Lifecycle) (Middleware, error)
  • func MaxRequestBody(bytes int64) Middleware
  • func Recover(handler ErrorHandler) Middleware
  • func RequestID(header string, logger Logger) Middleware
  • func SecurityHeaders(config SecurityHeadersConfig) (Middleware, error)
• type Option
  • func WithCloser(closer func(context.Context) error) Option
  • func WithErrorRenderer(renderer ErrorRenderer) Option
  • func WithMiddleware(middleware ...Middleware) Option
  • func WithOpenAPI(document []byte) Option
  • func WithReadinessCheck(check ReadyCheck) Option
  • func WithServerConfig(config ServerConfig) Option
• type ReadyCheck
• type RenderFunc
  • func (f RenderFunc) Render(w io.Writer) error
• type Renderer
• type SecurityHeadersConfig
  • func DefaultSecurityHeaders() SecurityHeadersConfig
• type ServerConfig
  • func DefaultServerConfig() ServerConfig
  • func (c ServerConfig) Validate() error

Constants

const (
	LevelTrace = pwruntime.LevelTrace
	LevelDebug = pwruntime.LevelDebug
	LevelInfo  = pwruntime.LevelInfo
	LevelWarn  = pwruntime.LevelWarn
	LevelError = pwruntime.LevelError
)

Severities.

Functions

func CSV

func CSV(w http.ResponseWriter, status int, records [][]string) error

CSV writes records using the standard CSV encoder.

func Download

func Download(w http.ResponseWriter, status int, filename, contentType string, content []byte) error

Download writes bytes as an attachment using a safely encoded filename.

func HTML

func HTML(w http.ResponseWriter, status int, renderer Renderer) error

HTML writes a complete HTML response. The renderer is buffered so its error cannot leave a partially committed success response.

func JSON

func JSON(w http.ResponseWriter, status int, value any) error

JSON writes a JSON response.

func ReadRequestID

func ReadRequestID(ctx context.Context) (string, bool)

ReadRequestID returns the validated request correlation ID.

func Redirect

func Redirect(w http.ResponseWriter, r *http.Request, location string, status int)

Redirect performs a normal browser redirect.

func WriteError

func WriteError(w http.ResponseWriter, r *http.Request, err error)

WriteError writes with safe defaults and RFC 9457 negotiation.

func XML

func XML(w http.ResponseWriter, status int, value any) error

XML writes an XML response.

Types

type App

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

App owns an application's mux, middleware, operational endpoints, and server lifecycle. Configuration is frozen the first time Handler or Serve is called.

func New

func New(options ...Option) *App

New constructs an application with safe server defaults.

func (*App) Handle

func (a *App) Handle(pattern string, handler http.Handler)

Handle registers a standard net/http handler.

func (*App) HandleFunc

func (a *App) HandleFunc(pattern string, handler http.HandlerFunc)

HandleFunc registers a standard net/http handler function.

func (*App) Handler

func (a *App) Handler() http.Handler

Handler freezes configuration and returns the fully composed handler. Invalid startup configuration panics; callers that need error handling should call Validate first or use Serve/ListenAndServe.

func (*App) ListenAndServe

func (a *App) ListenAndServe(addr string) error

ListenAndServe validates and serves until the server is shut down.

func (*App) Middlewares

func (a *App) Middlewares() []Middleware

Middlewares returns an immutable snapshot of configured middleware.

func (*App) Mux

func (a *App) Mux() *httpmux.ServeMux

Mux returns the application's standard library mux. It must be configured before Handler or Serve freezes the application.

func (*App) Run

func (a *App) Run(ctx context.Context, addr string) error

Run serves until ctx is cancelled, then performs graceful shutdown.

func (*App) Serve

func (a *App) Serve(server *http.Server) error

Serve runs the application using server's listener settings and Petitweb's validated timeouts. Supplying a server allows tests and advanced deployments to use an existing listener via server.Serve separately after Handler().

func (*App) SetErrorRenderer

func (a *App) SetErrorRenderer(renderer ErrorRenderer)

SetErrorRenderer installs an HTML error renderer before serving.

func (*App) Shutdown

func (a *App) Shutdown(ctx context.Context) error

Shutdown drains active handlers and closes resources in reverse order.

func (*App) String

func (a *App) String() string

func (*App) Use

func (a *App) Use(middleware ...Middleware)

Use appends middleware before the application is frozen.

func (*App) Validate

func (a *App) Validate() error

Validate checks all startup invariants without freezing the App.

func (*App) WriteError

func (a *App) WriteError(w http.ResponseWriter, r *http.Request, err error)

WriteError negotiates an error using the renderer configured on the App.

type Attribute

type Attribute = pwruntime.Attribute

Attribute is one scalar key-value pair on a record.

func Bool

func Bool(key string, value bool) Attribute

func Err

func Err(err error) Attribute

Err renders an error as a record attribute. A nil error is safe.

func Float64

func Float64(key string, value float64) Attribute

func Int

func Int(key string, value int) Attribute

func Int64

func Int64(key string, value int64) Attribute

func String

func String(key, value string) Attribute

Attribute constructors.

type ErrorHandler

type ErrorHandler struct {
	Renderer ErrorRenderer
	// Logger is optional; the zero value falls back to the request logger.
	Logger Logger
}

ErrorHandler negotiates safe HTML and RFC 9457 error responses.

func (ErrorHandler) WriteError

func (h ErrorHandler) WriteError(w http.ResponseWriter, r *http.Request, err error)

WriteError writes err exactly once. Internal error causes are never exposed.

type ErrorPage

type ErrorPage struct {
	Status    int
	Title     string
	Detail    string
	Code      string
	RequestID string
	// contains filtered or unexported fields
}

ErrorPage is the sanitized model passed to an application's HTML renderer.

func (ErrorPage) String

func (p ErrorPage) String() string

type ErrorRenderer

type ErrorRenderer func(http.ResponseWriter, *http.Request, ErrorPage) error

ErrorRenderer writes a complete HTML error response.

type HSTSConfig

type HSTSConfig = middlewares.HSTSConfig

HSTSConfig controls Strict-Transport-Security on direct HTTPS requests.

type Lifecycle

type Lifecycle = middlewares.Lifecycle

Lifecycle describes an API resource's deprecation and sunset dates.

type Logger

type Logger = pwruntime.Logger

Logger is the context-bound logger returned by ReadLogger.

func ReadLogger

func ReadLogger(ctx context.Context) Logger

ReadLogger always returns a usable request-aware logger. A request that never passed through RequestID still gets the logger installed on the context, and a context with nothing installed still gets one that can be called.

type Middleware

type Middleware func(http.Handler) http.Handler

Middleware is the standard Go HTTP middleware signature.

func LifecycleHeaders

func LifecycleHeaders(lifecycle Lifecycle) (Middleware, error)

LifecycleHeaders announces an API resource's lifecycle without changing its response status or behavior.

func MaxRequestBody

func MaxRequestBody(bytes int64) Middleware

MaxRequestBody limits downstream reads from the request body.

func Recover

func Recover(handler ErrorHandler) Middleware

Recover converts a panic into a safe negotiated error response.

func RequestID

func RequestID(header string, logger Logger) Middleware

RequestID validates or creates a request ID and exposes it through context. The zero Logger is accepted and resolves to the one installed on the request.

func SecurityHeaders

func SecurityHeaders(config SecurityHeadersConfig) (Middleware, error)

SecurityHeaders sets policy headers before downstream response commitment. Strict-Transport-Security is limited to direct HTTPS connections.

type Option

type Option func(*App) error

Option configures an App before it starts serving.

func WithCloser

func WithCloser(closer func(context.Context) error) Option

WithCloser registers a process-lifetime resource closer. Closers run in reverse registration order after active requests have drained.

func WithErrorRenderer

func WithErrorRenderer(renderer ErrorRenderer) Option

WithErrorRenderer installs the HTML error renderer.

func WithMiddleware

func WithMiddleware(middleware ...Middleware) Option

WithMiddleware appends middleware. Middleware executes in the order supplied.

func WithOpenAPI

func WithOpenAPI(document []byte) Option

WithOpenAPI supplies a generated OpenAPI document for the configured endpoint.

func WithReadinessCheck

func WithReadinessCheck(check ReadyCheck) Option

WithReadinessCheck adds a critical dependency readiness check.

func WithServerConfig

func WithServerConfig(config ServerConfig) Option

WithServerConfig replaces the default server configuration.

type ReadyCheck

type ReadyCheck func(context.Context) error

ReadyCheck reports whether a critical application dependency can serve.

type RenderFunc

type RenderFunc func(io.Writer) error

RenderFunc adapts a generated render function to Renderer.

func (RenderFunc) Render

func (f RenderFunc) Render(w io.Writer) error

type Renderer

type Renderer interface {
	Render(io.Writer) error
}

Renderer is implemented by generated, reflection-free HTML templates.

type SecurityHeadersConfig

type SecurityHeadersConfig = middlewares.SecurityHeadersConfig

SecurityHeadersConfig contains browser security response headers.

func DefaultSecurityHeaders

func DefaultSecurityHeaders() SecurityHeadersConfig

DefaultSecurityHeaders returns the classic mode defaults.

type ServerConfig

type ServerConfig struct {
	Address           string
	ReadHeaderTimeout time.Duration
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration
	IdleTimeout       time.Duration
	ShutdownTimeout   time.Duration
	MaxRequestBody    int64
	TrustedProxies    []string
	// Health, Readiness, and OpenAPI are the absolute paths their endpoints
	// serve, and an unset path serves nothing. There is no default path: an
	// application that answers on /healthz should say so where a reader of its
	// setup can see it, rather than inherit it from here.
	Health    string
	Readiness string
	OpenAPI   string
}

ServerConfig controls the classic HTTP server and operational endpoints.

func DefaultServerConfig

func DefaultServerConfig() ServerConfig

DefaultServerConfig returns conservative production-oriented defaults.

func (ServerConfig) Validate

func (c ServerConfig) Validate() error

Validate checks startup invariants before a listener accepts requests.