Files
zeekayandGitHub 4e80324a1f form: every door is judged before decoding, and a deleted response stays deleted (#7)
MCP and the call plane reached the submit op with no route in front of it, and
the op decoded up to a megabyte before asking the rate: eight calls past the
rate allocated over a gigabyte. The op now keeps the raw body and decodes it
only after the rate and the size, whichever door it came through, and a refusal
names at most twenty problems.

A filing retry re-reads its response and stops when it was deleted, so nothing
erased is filed or written back. Retries are bounded per org. Every org keeps a
reserve of five delivery places beside the shared pool, so no set of orgs fills
the queue for the rest. A mail budget a saved document leaves out is the
default, never none. A webhook says whether the respondent is verified and names
a person only then. A blocked address reads like one that does not resolve.

Claude-Session: https://claude.ai/code/session_016DKtyuzxU43Gsc6Pm9vKTF
2026-11-02 09:56:43 -08:00

489 lines
17 KiB
Go

package form
// public.go — the form as a respondent sees it, and answering it. No credential
// is needed for either: the form's public id names its org, the index says
// whether it is published, and a stranger's submission is held to the platform's
// body bound, its rate per address, a field a person never fills, and the form's
// own fields.
import (
"context"
"encoding/json"
"errors"
"mime"
"net/http"
"regexp"
"strings"
"time"
"github.com/zap-proto/zip"
)
// PublicRef names a form by its public id.
type PublicRef struct {
// ID is the form's public id, "<org>.<slug or id>", from the path.
ID string `json:"id"`
}
// PublicForm is a form as a respondent's page draws it: nothing about where its
// responses go.
type PublicForm struct {
// ID is the form's public id.
ID string `json:"id"`
// Kind is form or subscribe.
Kind string `json:"kind"`
// Title is the form's title.
Title string `json:"title"`
// Fields are the questions, in order.
Fields []Field `json:"fields"`
// Welcome is the screen before the first question.
Welcome *Screen `json:"welcome,omitempty"`
// Thanks is the screen after a submission, or where the respondent is sent.
Thanks *Screen `json:"thanks,omitempty"`
// Hidden names the values the page passes in.
Hidden []string `json:"hidden,omitempty"`
// Settings are how the form is answered.
Settings Drawn `json:"settings"`
// Theme is the theme the form is drawn in, when it names one.
Theme *Theme `json:"theme,omitempty"`
}
// Drawn are the settings a renderer reads.
type Drawn struct {
// Language is the form's language tag.
Language string `json:"language"`
// Progress is whether a progress bar is shown.
Progress bool `json:"progress"`
// Mode is one (a question at a time) or all.
Mode string `json:"mode"`
}
// Submission is one respondent's answers to a public form.
type Submission struct {
// raw is the body as it came, decoded by the op only once its rate and size
// are judged; size is its length.
raw []byte
size int
// ID is the form's public id, from the path.
ID string `json:"id"`
// Token is the client's idempotency token for this response: 8 to 64
// letters, digits, dashes and underscores. A submission sent twice under one
// token is one response, so a double click or a retry files nothing twice.
// Absent, the response is new each time.
Token string `json:"token"`
// Answers are the answers, one per field at most.
Answers []Answer `json:"answers"`
// Hidden are the values the page passes in, by the names the form declares;
// each one line of at most 500 characters.
Hidden map[string]string `json:"hidden"`
// LandedAt is when the respondent opened the form, RFC 3339.
LandedAt string `json:"landed_at"`
// Completed is false to save the answers so far and keep the response open
// (a later submission under the same token completes it); true or absent
// submits it whole, every required field answered. A completed response is
// final.
Completed *bool `json:"completed"`
// Visitor is the page's visitor id: letters, digits, dot, dash and
// underscore, at most 64. It is who the response is from when nobody is
// signed in and no email field is answered.
Visitor string `json:"visitor"`
// Path is the page the form was answered on, at most 500 characters.
Path string `json:"path"`
// Website is a field no person sees and no person fills: a submission that
// fills it is refused.
Website string `json:"website"`
}
// UnmarshalJSON records the body's size and whether it decoded, and refuses
// nothing: the op judges, in its order.
//
// A body past BodyCeiling is not decoded at all: its size is recorded, the op
// refuses it, and not one of its answers is ever allocated.
//
// Nothing is decoded here: the bytes are kept (none past BodyCeiling) and the op
// decodes them after it has judged the caller's rate and the body's size, so a
// submission that arrives by any door, a route, MCP or the call plane, is
// judged in one order before a byte of it is allocated as answers.
func (in *Submission) UnmarshalJSON(b []byte) error {
in.size = len(b)
in.raw = nil
if len(b) <= BodyCeiling {
in.raw = append([]byte(nil), b...)
}
return nil
}
// decode reads the kept body into the submission, keeping a public id the path
// already named. It reports whether the body was one.
func (in *Submission) decode() bool {
if in.raw == nil {
return in.size == 0
}
type body Submission
var v body
if err := json.Unmarshal(in.raw, &v); err != nil {
return false
}
id := in.ID
*in = Submission(v)
if id != "" {
in.ID = id
}
return true
}
// guardedKey marks a request the public guard has already judged.
type guardedKey struct{}
// guard judges a submission before its body is decoded: it is application/json
// (a cross-site form or a no-cors fetch cannot send one without asking first),
// its address has a submission left in the window, and it is inside the
// platform's body bound. A read passes through.
func (s *service) guard(c *zip.Ctx) error {
if c.Method() != http.MethodPost {
return c.Next()
}
ctx := c.Context()
if t, _, err := mime.ParseMediaType(c.Header("Content-Type")); err != nil || t != "application/json" {
return zip.Errorf(http.StatusUnsupportedMediaType, "form: a submission is application/json")
}
st := s.settings(ctx)
if !s.allowed(ctx, "form:response", s.d.Client(ctx).IP, st) {
return zip.Errorf(http.StatusTooManyRequests, "form: too many submissions; try again later")
}
if n := len(c.Body()); n > st.Limits.Body {
return zip.Errorf(http.StatusRequestEntityTooLarge, "form: the submission is larger than %d bytes", st.Limits.Body)
}
c.SetContext(context.WithValue(ctx, guardedKey{}, true))
return c.Next()
}
// Receipt is what a submission is answered.
type Receipt struct {
// ID is the response's id.
ID string `json:"id"`
// Completed is whether the response is now submitted whole.
Completed bool `json:"completed"`
// SubmittedAt is when it was completed, RFC 3339.
SubmittedAt string `json:"submitted_at,omitempty"`
// Thanks is the form's thank-you screen, for a completed response.
Thanks *Screen `json:"thanks,omitempty"`
}
var (
tokenShape = regexp.MustCompile(`^[A-Za-z0-9_-]{8,64}$`)
visitorShape = regexp.MustCompile(`^[A-Za-z0-9_.-]{1,64}$`)
)
// resolve reads the form a public id names, as published. A public id the index
// does not hold, or a form that is private, is a 404.
func (s *service) resolve(ctx context.Context, pid string) (string, *Form, error) {
pid = strings.TrimSpace(pid)
if pid == "" || len(pid) > 200 {
return "", nil, zip.ErrNotFound("form: no such form")
}
if err := s.indexReady(ctx); err != nil {
return "", nil, err
}
idx, err := s.d.Store.Get(ctx, s.d.Platform, Index, derived("public", pid))
if errors.Is(err, ErrNotFound) {
return "", nil, zip.ErrNotFound("form: no such form")
}
if err != nil {
return "", nil, s.failed("the form could not be found", s.d.Platform, err)
}
org, id := field(idx, "org"), field(idx, "form")
r, err := s.d.Store.Get(ctx, org, Forms, id)
if errors.Is(err, ErrNotFound) {
return "", nil, zip.ErrNotFound("form: no such form")
}
if err != nil {
return "", nil, s.failed("the form could not be read", org, err)
}
f := formOf(org, r)
if f.Settings.Visibility != "public" || f.PublicID != pid {
return "", nil, zip.ErrNotFound("form: no such form")
}
return org, &f, nil
}
// Reads a published form as its page draws it: the questions, the screens, the
// hidden values it takes, how it is answered and its theme. Nothing about where
// its responses go. No credential is needed; a form that is private, deleted or
// never was is a 404.
func (s *service) publicForm(ctx context.Context, in *PublicRef) (*PublicForm, error) {
org, f, err := s.resolve(ctx, in.ID)
if err != nil {
return nil, err
}
out := &PublicForm{
ID: f.PublicID, Kind: f.Kind, Title: f.Title, Fields: f.Fields, Welcome: f.Welcome, Thanks: f.Thanks, Hidden: f.Hidden,
Settings: Drawn{Language: f.Settings.Language, Progress: f.Settings.Progress, Mode: f.Settings.Mode},
}
if f.Theme != "" {
if r, err := s.d.Store.Get(ctx, org, Themes, f.Theme); err == nil {
t := themeOf(r)
t.Created, t.Updated = "", ""
out.Theme = &t
}
}
c := s.d.Client(ctx)
st := s.settings(ctx)
if f.Sinks != nil && f.Sinks.Events && !c.OptedOut && s.allowed(ctx, "form:view", c.IP, st) {
s.emit(ctx, org, Event{Name: Viewed, Form: f.ID, Public: f.PublicID})
}
return out, nil
}
// allowed spends one of the address's submissions; a caller with no address is
// inside the cluster.
func (s *service) allowed(ctx context.Context, name, ip string, st Settings) bool {
if s.d.Allow == nil {
return true
}
return s.d.Allow(ctx, name, ip, st.Limits.Rate, st.window())
}
// Answers a published form. No credential is needed.
//
// The answers are read against the form's own fields: each names a field (by
// ref) once and carries the one value its type takes, inside its bounds; a
// completed submission answers every required field. Hidden values are the
// names the form declares. The response is from the signed-in person when there
// is one (their account, from their token, never from the body), else from the
// email field's answer, else from the page's visitor id.
//
// Idempotent by token: the same token is the same response, so a submission
// sent twice files one. With completed false the answers so far are saved and
// the response stays open; a completed response is final and a later submission
// under its token is answered with it unchanged. A subscribe form's response is
// keyed by its address instead: one address is one subscriber.
//
// A completed response goes to the form's sinks: the event stream, the CRM, the
// forwarding address, the welcome mail and the webhooks.
//
// 429 past the platform's rate for one address, 413 past its body bound, 400
// for a body that does not decode, a field no person fills, or any problem with
// the answers (every one named), 404 for a form that is not published.
//
// Example: {"token":"r_9f1c2a7b","answers":[{"field":"rating","number":5},{"field":"comment","text":"Loved it"}],"hidden":{"video":"7mVTEAHHjPc"},"landed_at":"2026-11-02T08:34:10Z","visitor":"v_k3j2h1","path":"/beta"}
func (s *service) submit(ctx context.Context, in *Submission) (*Receipt, error) {
st := s.settings(ctx)
c := s.d.Client(ctx)
// The route's guard has judged the rate and the size already; a submission
// reaching the op another way is judged here.
if guarded, _ := ctx.Value(guardedKey{}).(bool); !guarded && !s.allowed(ctx, "form:response", c.IP, st) {
return nil, zip.Errorf(http.StatusTooManyRequests, "form: too many submissions; try again later")
}
if in.size > st.Limits.Body {
return nil, zip.Errorf(http.StatusRequestEntityTooLarge, "form: the submission is larger than %d bytes", st.Limits.Body)
}
if !in.decode() {
return nil, zip.ErrBadRequest("form: the submission does not decode")
}
if len(in.Answers) > st.Limits.Fields || len(in.Hidden) > st.Limits.Hidden {
return nil, zip.ErrBadRequest("form: more answers or hidden values than a form has")
}
if strings.TrimSpace(in.Website) != "" {
return nil, zip.ErrBadRequest("form: the submission was refused")
}
org, f, err := s.resolve(ctx, in.ID)
if err != nil {
return nil, err
}
answers, problems := checkAnswers(*f, in.Answers, st)
completed := in.Completed == nil || *in.Completed
if completed {
if gaps := missing(*f, answers); len(gaps) > 0 {
problems = append(problems, "unanswered: "+strings.Join(gaps, ", "))
}
}
hidden := map[string]string{}
for name, v := range in.Hidden {
if !containsString(f.Hidden, name) {
problems = append(problems, "hidden: the form takes no value "+quote(name))
continue
}
v, ok := line(v, 500)
if !ok {
problems = append(problems, "hidden: "+name+" is one line of at most 500 characters")
continue
}
hidden[name] = v
}
token := strings.TrimSpace(in.Token)
if token != "" && !tokenShape.MatchString(token) {
problems = append(problems, "token is 8 to 64 letters, digits, dashes and underscores")
}
visitor := strings.TrimSpace(in.Visitor)
if visitor != "" && !visitorShape.MatchString(visitor) {
problems = append(problems, "visitor is letters, digits, dot, dash and underscore, at most 64")
}
path, ok := line(in.Path, 500)
if !ok {
problems = append(problems, "path is one line of at most 500 characters")
}
if len(problems) > 0 {
return nil, zip.ErrBadRequest("form: " + strings.Join(problems, "; "))
}
if token == "" {
token = "t_" + fresh()
}
who := s.respondent(ctx, *f, answers, visitor)
// Every submission is its own response under its token, a subscribe form's
// too: an address typed first is not the address's for good, and a later
// submission from it is recorded in full. Its list is joined once: the CRM
// keys a membership by the person.
id := derived("response", f.ID+"\x00"+token)
now := s.d.Now().UTC()
held, err := s.d.Store.Get(ctx, org, Responses, id)
switch {
case errors.Is(err, ErrNotFound):
held = nil
case err != nil:
return nil, s.failed("the response could not be read", org, err)
}
if held != nil {
if r := responseOf(held); r.Completed {
return &Receipt{ID: r.ID, Completed: true, SubmittedAt: r.SubmittedAt, Thanks: f.Thanks}, nil
}
}
rec := Record{
"id": id, "form": f.ID, "token": token, "completed": completed, "answers": answers, "hidden": hidden,
// The email column is a verified address only: it is what a welcome is
// counted by, and a claim is nobody's.
"respondent": who, "email": verifiedEmail(who), "person": who.PersonID, "last": last(answers), "path": path, "source": "web",
}
if held == nil {
rec["at"] = baseTime(now)
}
// A landing time is the page's word: one in the future, or more than 30 days
// back, is no landing this response had, and it is kept as none.
landed := when(in.LandedAt)
if landed.After(now) || now.Sub(landed) >= 30*24*time.Hour {
landed = time.Time{}
}
if !landed.IsZero() {
rec["landed"] = baseTime(landed)
}
if completed {
rec["submitted"] = baseTime(now)
if !landed.IsZero() {
rec["duration"] = int(now.Sub(landed).Seconds())
}
}
if err := s.d.Store.Put(ctx, org, Responses, rec); err != nil {
return nil, s.failed("the response could not be saved", org, err)
}
out := &Receipt{ID: id, Completed: completed}
if f.Sinks != nil && f.Sinks.Events && !c.OptedOut {
// A claimed address is nobody's on the event stream: only a signed-in
// respondent is a person there.
ev := Event{Form: f.ID, Public: f.PublicID, Response: id, Visitor: who.Visitor, Fields: refs(answers)}
if who.Verified {
ev.PersonID = who.PersonID
}
if held == nil {
ev.Name = Started
s.emit(ctx, org, ev)
}
if completed {
ev.Name = Submitted
s.emit(ctx, org, ev)
}
}
if completed {
out.SubmittedAt, out.Thanks = stamp(now), f.Thanks
r := Response{
ID: id, Form: f.ID, Token: token, Completed: true, LandedAt: stamp(landed), SubmittedAt: stamp(now),
Answers: answers, Hidden: hidden, Respondent: who, Path: path, Source: "web",
}
s.route(org, *f, r, c.IP)
}
s.expire(org, f.ID, st)
return out, nil
}
// respondent is who a response is from: the signed-in person, from their token;
// else the address the CRM mapping's email field (or the first email field)
// answers; else the visitor.
func (s *service) respondent(ctx context.Context, f Form, answers []Answer, visitor string) Respondent {
c := s.d.Caller(ctx)
if c.Subject != "" && address(c.Email) {
email := strings.ToLower(c.Email)
return Respondent{Kind: "account", Subject: c.Subject, Email: email, PersonID: s.d.Person(email), Visitor: visitor, Verified: true}
}
// A typed address is a claim, and only a form that takes claims records one.
if email := strings.ToLower(textOf(f, answers, emailRef(f))); f.Settings.Identity != Verified && address(email) {
return Respondent{Kind: "email", Email: email, PersonID: s.d.Person(email), Visitor: visitor}
}
if visitor != "" {
return Respondent{Kind: "visitor", Visitor: visitor}
}
return Respondent{Kind: "none"}
}
// emailRef is the field whose answer is the respondent's address: the CRM
// mapping's, else the form's first email field.
func emailRef(f Form) string {
if f.Sinks != nil && f.Sinks.CRM != nil && f.Sinks.CRM.Email != "" {
return f.Sinks.CRM.Email
}
for _, fd := range f.Fields {
if fd.Type == Email {
return fd.Ref
}
}
return ""
}
// subscriber is a subscribe form's required email field: the address that is
// the subscriber.
func subscriber(f Form) string {
for _, fd := range f.Fields {
if fd.Type == Email && fd.Required {
return fd.Ref
}
}
return ""
}
// last is the ref of the last field answered, in form order.
func last(answers []Answer) string {
if len(answers) == 0 {
return ""
}
return answers[len(answers)-1].Field
}
// refs are the refs of the fields answered.
func refs(answers []Answer) []string {
out := make([]string, 0, len(answers))
for _, a := range answers {
out = append(out, a.Field)
}
return out
}
func containsString(list []string, s string) bool {
for _, x := range list {
if x == s {
return true
}
}
return false
}
func quote(s string) string { return `"` + clip(s, 64) + `"` }
// verifiedEmail is the respondent's address when it is verified, else none.
func verifiedEmail(r Respondent) string {
if r.Verified {
return r.Email
}
return ""
}