Reference

Ctx

Everything a route function can do with the request context.

*trilha.Ctx wraps the request and the response. It is created per request and must not be used by another goroutine after the handler returns.

Request#

Response#

HTTP cache#

true means the 304 is already written: return nil, nil and write nothing else. Only GET and HEAD answer 304; on other methods the headers are written and the answer is always false. An empty tag or a zero date writes nothing. When both are declared, If-None-Match decides and the date stays as metadata, as RFC 9110 asks. Files under static/ already carry an ETag: the content fingerprint that goes in ?v=.

Between page and layout#

Islands#

func (c *Ctx) Island(src string, props any, children ...h.Node) h.Node

Renders <div data-trilha-island="…" data-trilha-props="…"> with the children as the server-rendered fallback. src is a module in public/ (addressed through Asset, so it carries the content hash) whose default export is the mount function, called once with (el, props). props is anything encoding/json serializes, or nil; it travels as an escaped attribute and is read back with JSON.parse, so it is data and never markup. Props that do not serialize warn once and leave the fallback alone. The loader is a single inline script with the request nonce, emitted with the first island of the response (Interactivity).

Long connections and large bodies#

The default limit belongs to the app; the exception belongs to the route. Raise it in the route's middleware.go, not in the handler — form CSRF reads the body before the handler runs, so the decision has to come first:

// app/anexos/middleware.go
func Middleware(c *trilha.Ctx, next trilha.Next) error {
	if c.Request().Method == "POST" {
		c.AllowBody(8 << 20) // this request only; every other route keeps the app's limit
		c.NoReadDeadline()
	}
	return next()
}

Going over the limit is still a 413 with the usual message, through FormErr, Bind* or a direct read of Request().Body.

WebSocket#

Trilha has no WebSocket of its own, and that is a decision. The protocol is transport: it touches no route, no layout and no render. What it does need — fragmentation and continuation frames, control frames interleaved with a message, the close handshake with a deadline, UTF-8 validation, masking, size limits, concurrent writes, backpressure, permessage-deflate — is a few hundred lines that the Autobahn suite tests in 500+ cases. The asymmetry decides it: your app can add coder/websocket to its go.mod (principle II binds the framework, not the app), but it cannot take those lines out of the framework.

What was missing was the door, and Hijack is it:

func WS(c *trilha.Ctx) error {
	conn, _, err := c.Hijack() // read and write deadlines already cleared
	if err != nil {
		return err
	}
	defer conn.Close()
	return meuWebsocket.Serve(conn) // coder/websocket, gorilla, whatever you picked
}

After Hijack the connection is yours: the framework writes no header, no error page and no body on it, and the access log records 101.

Security#

The token is verified automatically on POST, PUT, PATCH and DELETE of page.go (and of route.go if Config.CSRFForAPI is on), through the _csrf field or the X-CSRF-Token header.

Bind#

Bind(v any) error fills a struct from the form (or from JSON, when the Content-Type is application/json). Fields match by the form:"name" tag (or by the field name); types: string, []string, bool (on/true/1), int, int64, float64 (comma or dot), time.Time (2006-01-02 or 2006-01-02T15:04) and pointers (nil when absent). A nested struct is flattened, with the tag as prefix (Billing Address +"form:\"bill_\""+ reads bill_zip…). Values that do not convert become FieldErrors (message trilha.BindInvalid, adjustable) after every field has been tried. The validate:"..."` tag of each field is applied right after, in the same pass: see Validation.

File#

File(field string, rules FileRules) (*Upload, error) reads one file from a multipart form and only answers with it if it passes the rules.

A rule that fails is FieldErrors under the field's name, like Bind; anything else (a broken body, a full disk) comes back as itself. Messages come from ValidationMessages (required, filemax, filetype) — see Validation.