Referência

Ctx

Tudo que uma função de rota pode fazer com o contexto da requisição.

*trilha.Ctx embrulha a requisição e a resposta. É criado por requisição e não deve ser usado por outra goroutine depois que o handler devolve.

Requisição#

Resposta#

Cache HTTP#

true quer dizer que o 304 já foi escrito: devolva nil, nil e não escreva mais nada. Só GET e HEAD respondem 304; nos outros métodos os cabeçalhos são escritos e a resposta é sempre false. Etiqueta vazia ou data zerada não escrevem nada. Quando os dois são declarados, quem decide é o If-None-Match e a data fica como metadado, como pede a RFC 9110. Os arquivos em static/ já vêm com ETag: a impressão digital do conteúdo que vai no ?v=.

Entre página e layout#

Ilhas#

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

Renderiza <div data-trilha-island="…" data-trilha-props="…"> com os filhos como conteúdo de origem, vindo do servidor. src é um módulo em public/ (endereçado pelo Asset, então leva o hash do conteúdo) cuja exportação padrão é a função de montagem, chamada uma vez com (el, props). props é qualquer coisa que o encoding/json serialize, ou nil; viaja como atributo escapado e volta pelo JSON.parse, então é dado, nunca marcação. Props que não serializam avisam uma vez e deixam o conteúdo de origem em paz. O carregador é um único script inline com o nonce da requisição, emitido junto da primeira ilha da resposta (Interatividade).

Conexão longa e corpo grande#

O limite padrão é do app; a exceção é da rota. Levante no middleware.go da rota, não no handler — o CSRF de formulário lê o corpo antes do handler rodar, então a decisão tem de vir antes:

// app/anexos/middleware.go
func Middleware(c *trilha.Ctx, next trilha.Next) error {
	if c.Request().Method == "POST" {
		c.AllowBody(8 << 20) // só esta requisição; o resto do app segue no limite do app
		c.NoReadDeadline()
	}
	return next()
}

Estourar o limite continua sendo 413 com a mensagem de sempre, pelo FormErr, pelos Bind* ou na leitura direta do Request().Body.

WebSocket#

O Trilha não tem WebSocket próprio, e isso é decisão. O protocolo é transporte: não encosta em rota, em layout nem em render. O que ele exige — frames de fragmentação e continuação, frame de controle no meio de uma mensagem, aperto de mão de fechamento com prazo, validação de UTF-8, máscara, limite de tamanho, escrita concorrente, contrapressão, permessage-deflate — são algumas centenas de linhas que a suíte Autobahn cobra em mais de 500 casos. A assimetria decide: o seu app pode pôr coder/websocket no go.mod dele (o princípio II obriga o framework, não o app), mas não consegue tirar essas linhas do framework.

O que faltava era a porta, e ela é o Hijack:

func WS(c *trilha.Ctx) error {
	conn, _, err := c.Hijack() // prazos de leitura e escrita já removidos
	if err != nil {
		return err
	}
	defer conn.Close()
	return meuWebsocket.Serve(conn) // coder/websocket, gorilla, o que você escolher
}

Depois do Hijack a conexão é sua: o framework não escreve cabeçalho, página de erro nem corpo nela, e o log de acesso registra 101.

Segurança#

O token é verificado automaticamente em POST, PUT, PATCH e DELETE de page.go (e de route.go se Config.CSRFForAPI estiver ligado), pelo campo _csrf ou pelo cabeçalho X-CSRF-Token.

Bind#

Bind(v any) error preenche uma struct a partir do formulário (ou do JSON, quando o Content-Type é application/json). Campos casam pela tag form:"nome" (ou pelo nome do campo); tipos: string, []string, bool (on/true/1), int, int64, float64 (vírgula ou ponto), time.Time (2006-01-02 ou 2006-01-02T15:04) e ponteiros (nil quando ausente). Struct aninhada é achatada, com a tag como prefixo (Cobranca Endereco +"form:\"cob_\""+ lê cob_cep…). Valores que não convertem viram FieldErrors (mensagem trilha.BindInvalid, ajustável) depois de todos os campos serem tentados. A tag validate:"..."` de cada campo é aplicada logo em seguida, na mesma passada: veja Validação.

File#

File(campo string, regras FileRules) (*Upload, error) lê um arquivo do formulário multipart e só o devolve se ele passar pelas regras.

Regra que falha vira FieldErrors no nome do campo, como no Bind; qualquer outra coisa (corpo quebrado, disco cheio) volta como está. As mensagens saem do ValidationMessages (required, filemax, filetype) — veja Validação.