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

329 lines
13 KiB
Go

// Package form is forms: a form is defined once (its fields, screens, hidden
// values, theme and sinks), answered at a public address by anyone or by a
// signed-in person, and every completed response is routed where the form says:
// the event stream, the CRM, a forwarding address, a welcome mail and the form's
// webhooks.
//
// It is a zip App ([New]) a host composes, the way hanzo-inc/cloud composes
// hanzoai/iam: every route is a typed op, so one registration is the REST
// route, the OpenAPI operation, the MCP tool, the CLI command and the SDK method.
//
// /v1/form/forms[/{id}] the org's forms (org admin)
// /v1/form/forms/{id}/responses[/{response}] its responses
// /v1/form/forms/{id}/{summary,export,import} what they add up to, out and in
// /v1/form/forms/{id}/webhooks[/{webhook}] where they are posted, and how it went
// /v1/form/themes[/{id}] the org's themes
// /v1/form/public/{id}[/responses] the form as drawn, and answering it (no credential)
//
// THE HOST DECIDES WHO, AND WHERE THINGS ARE KEPT. Every record lives in the
// org's own store ([Store]: Hanzo Base, one per org); who is calling, which org
// they act in and whether they administer it are the host's identity boundary
// ([Deps.Caller]), never a field of a request. A public submission names its org
// in the form's public id and nothing else.
package form
import (
"context"
"encoding/json"
"errors"
"log/slog"
"net/http"
"time"
"github.com/zap-proto/zip"
)
//go:generate go run github.com/zap-proto/zip/cmd/zipdoc
// Caller is who an org-scoped request is, as the host's identity boundary
// attested it.
type Caller struct {
// Org is the org the caller acts in; empty for nobody.
Org string
// Admin is whether they administer Org (or hold platform authority).
Admin bool
// Subject is the signed-in person's IAM subject, set only for a person
// holding their own token.
Subject string
// Email is that person's address, from their token.
Email string
}
// Client is what the host knows of the machine a request came from.
type Client struct {
// IP is the caller's address, as the host reads one; empty inside the cluster.
IP string
// OptedOut is a browser that sent Sec-GPC or DNT: nothing about it is stated
// on the event stream.
OptedOut bool
}
// Event is one occurrence the service states on the host's event stream.
type Event struct {
// Name is form_viewed, form_started or form_submitted.
Name string
// Form is the form's id, Public its public id.
Form, Public string
// Response is the response's id; empty on form_viewed.
Response string
// PersonID is the CRM person the response is from, when the service knows
// it. Never an address.
PersonID string
// Visitor is the page's visitor id, when it sent one.
Visitor string
// Fields are the refs of the fields answered, never what was said.
Fields []string
}
// The occurrences the events sink states.
const (
Viewed = "form_viewed"
Started = "form_started"
Submitted = "form_submitted"
)
// Filing is one completed response as the CRM files it: on the timeline of the
// person it is from, or on the org's own timeline when it names nobody.
type Filing struct {
// Ref is the timeline entry's key, "form:<response id>": filing it twice is
// one entry.
Ref string
// Form is the form's id, Public its public id, Title its title.
Form, Public, Title string
// Kind is the form's kind.
Kind string
// PersonID is the CRM person; empty files on the org's own timeline.
PersonID string
// Email, Name and Company fill the person: created when missing, given only
// the fields still empty when held.
Email, Name, Company string
// List is the CRM list the person joins; empty joins none.
List string
// Answers are the answers as question and text, in field order, without the
// one that named the person's address.
Answers []QA
// Hidden are the values the page passed in.
Hidden map[string]string
// Visitor is the page's visitor id; Subject the signed-in person's subject.
Visitor, Subject string
// Path is the page the form was answered on.
Path string
// At is when the response was completed.
At time.Time
// Verified is whether the person is the signed-in respondent. An unverified
// filing is a claim: marked so on the timeline, on the person only when the
// CRM already holds them and without changing them, and never on a list.
Verified bool
}
// Confirmation asks the double opt-in for an address a response only claimed:
// the address is mailed a link, and only a press on it joins the list.
type Confirmation struct {
// Email is the address, List the list it would join.
Email, List string
// Form is the form's id, Public its public id: where the ask came from.
Form, Public string
// IP is the submitter's address, so the host counts the ask against it as
// it counts the public subscribe's.
IP string
}
// QA is one question and what was said to it, as text.
type QA struct {
Question string `json:"question"`
Answer string `json:"answer"`
}
// Mail is one mail the service asks the host to send.
type Mail struct {
// To is the address, Name who it is.
To, Name string
// Subject is the subject line, Text the body as plain text.
Subject, Text string
// Kind is forward (a response to the form's own address) or welcome (to the
// respondent).
Kind string
// Form is the form's id: the host bounds and counts mail per form.
Form string
}
// Secrets keeps a webhook's signing secret: in KMS, under the org, never in the
// store. A missing secret is ErrNoSecret.
type Secrets interface {
Put(ctx context.Context, org, name string, value []byte) error
Get(ctx context.Context, org, name string) ([]byte, error)
Delete(ctx context.Context, org, name string) error
}
// ErrNoSecret is a secret the keeper does not hold.
var ErrNoSecret = errors.New("form: no such secret")
// Deps is what a host hands the service. Store, Caller, Client and Settings are
// required; a nil sink is a sink the host does not have, and the service says
// so by not filing there.
type Deps struct {
// Store is where every record lives: one Base per org.
Store Store
// Platform is the org whose Base holds the public index: the platform's own.
Platform string
// Caller is who an org-scoped request is.
Caller func(ctx context.Context) Caller
// Client is the machine a request came from.
Client func(ctx context.Context) Client
// Intended is the anti-forgery verdict on a change; nil admits.
Intended func(ctx context.Context) error
// Allow spends one of limit per window from what the address ip has for name,
// across the deployment, and reports whether there was one to spend. The host
// counts an address by its networks (an IPv6 /64 and /48), and an empty ip is
// one shared budget, never none.
Allow func(ctx context.Context, name, ip string, limit int, window time.Duration) bool
// Settings is the platform's configuration, its defaults when none is saved.
Settings func(ctx context.Context) Settings
// Person is the CRM person an address is: the join key every event and
// filing carries.
Person func(email string) string
// Emit states an occurrence on the event stream, detached.
Emit func(ctx context.Context, org string, e Event)
// File files a completed response in the org's CRM.
File func(ctx context.Context, org string, f Filing) error
// Mail sends one mail in the org's name.
Mail func(ctx context.Context, org string, m Mail) error
// Confirm asks the double opt-in for a claimed address and a list; nil, or a
// list the host has no double opt-in for, asks nothing.
Confirm func(ctx context.Context, org string, c Confirmation) error
// Secrets keeps webhook signing secrets.
Secrets Secrets
// HTTP posts webhook deliveries. Nil is a client that refuses any address
// inside a private network.
HTTP *http.Client
// Log is where the service says what it could not do.
Log *slog.Logger
// Now is the clock. Nil is time.Now.
Now func() time.Time
}
// service carries the dependencies onto every typed op.
type service struct {
d Deps
org installs
out *deliverer
}
// New is the forms App, every route registered. A host composes it with Use.
func New(d Deps) *zip.App {
if d.Log == nil {
d.Log = slog.Default()
}
if d.Now == nil {
d.Now = time.Now
}
if d.HTTP == nil {
d.HTTP = guarded()
}
if d.Person == nil {
d.Person = func(string) string { return "" }
}
s := &service{d: d}
s.out = newDeliverer(s)
app := zip.New(zip.Config{AppName: "form", DisableStartupMessage: true})
routes(app, s)
if err := app.Build(); err != nil {
panic("form: app does not compose: " + err.Error())
}
return app
}
// Prefix is the address every op is under.
const Prefix = "/v1/form"
// routes registers every op. Static segments come before the parameters beside
// them, so a first-match router resolves each address one way.
func routes(app *zip.App, s *service) {
g := app.Group(Prefix)
// The public half is guarded before a byte of a submission is decoded: its
// content type, its address's rate and its size (guard, public.go).
p := g.Group("/public", s.guard)
p.Get("/:id", s.publicForm, zip.WithOperationID("get_public_form"))
p.Post("/:id/responses", s.submit, zip.WithOperationID("submit_form_response"), zip.WithStatus(http.StatusCreated))
g.Get("/themes", s.listThemes, zip.WithOperationID("list_form_themes"))
g.Post("/themes", s.createTheme, zip.WithOperationID("create_form_theme"), zip.WithStatus(http.StatusCreated))
g.Get("/themes/:id", s.getTheme, zip.WithOperationID("get_form_theme"))
g.Put("/themes/:id", s.replaceTheme, zip.WithOperationID("replace_form_theme"))
g.Delete("/themes/:id", s.deleteTheme, zip.WithOperationID("delete_form_theme"), zip.WithStatus(http.StatusNoContent))
g.Get("/forms", s.listForms, zip.WithOperationID("list_forms"))
g.Post("/forms", s.createForm, zip.WithOperationID("create_form"), zip.WithStatus(http.StatusCreated))
g.Get("/forms/:id", s.getForm, zip.WithOperationID("get_form"))
g.Put("/forms/:id", s.replaceForm, zip.WithOperationID("replace_form"))
g.Patch("/forms/:id", s.updateForm, zip.WithOperationID("update_form"))
g.Delete("/forms/:id", s.deleteForm, zip.WithOperationID("delete_form"), zip.WithStatus(http.StatusNoContent))
g.Get("/forms/:id/summary", s.summary, zip.WithOperationID("summarize_form"))
g.Get("/forms/:id/export", s.export, zip.WithOperationID("export_form_responses"))
g.Post("/forms/:id/import", s.importResponses, zip.WithOperationID("import_form_responses"))
g.Get("/forms/:id/responses", s.listResponses, zip.WithOperationID("list_form_responses"))
g.Get("/forms/:id/responses/:response", s.getResponse, zip.WithOperationID("get_form_response"))
g.Delete("/forms/:id/responses/:response", s.deleteResponse, zip.WithOperationID("delete_form_response"), zip.WithStatus(http.StatusNoContent))
g.Post("/forms/:id/responses/:response/file", s.refile, zip.WithOperationID("file_form_response"))
g.Get("/forms/:id/webhooks", s.listWebhooks, zip.WithOperationID("list_form_webhooks"))
g.Post("/forms/:id/webhooks", s.createWebhook, zip.WithOperationID("create_form_webhook"), zip.WithStatus(http.StatusCreated))
g.Get("/forms/:id/webhooks/:webhook", s.getWebhook, zip.WithOperationID("get_form_webhook"))
g.Put("/forms/:id/webhooks/:webhook", s.replaceWebhook, zip.WithOperationID("replace_form_webhook"))
g.Delete("/forms/:id/webhooks/:webhook", s.deleteWebhook, zip.WithOperationID("delete_form_webhook"), zip.WithStatus(http.StatusNoContent))
g.Get("/forms/:id/webhooks/:webhook/deliveries", s.listDeliveries, zip.WithOperationID("list_form_deliveries"))
g.Post("/forms/:id/webhooks/:webhook/deliveries/:delivery/retry", s.redeliver, zip.WithOperationID("redeliver_form_webhook"))
}
// admin admits an administrator of the org the caller acts in, and answers it.
func (s *service) admin(ctx context.Context) (string, error) {
c := s.d.Caller(ctx)
if c.Org == "" {
return "", zip.ErrUnauthorized("form: sign in to an org")
}
if !c.Admin {
return "", zip.ErrForbidden("form: an org admin manages its forms and reads their responses")
}
return c.Org, nil
}
// change admits an administrator's change: admin, then the anti-forgery verdict.
func (s *service) change(ctx context.Context) (string, error) {
org, err := s.admin(ctx)
if err != nil {
return "", err
}
if s.d.Intended != nil {
if err := s.d.Intended(ctx); err != nil {
return "", err
}
}
return org, s.ready(ctx, org)
}
// stamp is a time as the wire carries it.
func stamp(t time.Time) string {
if t.IsZero() {
return ""
}
return t.UTC().Format(time.RFC3339)
}
// failed is the answer to a store that did not answer: logged here, a 503 there.
func (s *service) failed(what string, org string, err error) error {
var he *zip.HTTPError
if errors.As(err, &he) && he.Status < 500 {
return err
}
s.d.Log.Warn("form: "+what, "org", org, "err", err)
return zip.Errorf(http.StatusServiceUnavailable, "form: %s", what)
}
// raw is v as a JSON value, for a record's json field.
func raw(v any) json.RawMessage {
b, _ := json.Marshal(v)
return b
}