Build Formspree

The build, in order

1. 1

   Accept a post

   hideshow

   A plain HTML form on another site submits and lands on a thank-you.

   1. 1.1Create the project and tables

      forms (id, slug, name, redirect_url, notify_email, webhook_url), submissions (id, form_id, received_at, fields JSON, ip_hash, user_agent_class, spam). Fields as JSON because you do not control the markup that posts to you.

      terminalcopy

      mkdir formback && cd formback && git init && npm init -y && npm pkg set type=module
      mkdir -p data/uploads && cp .env.example .env

   2. 1.2Implement POST /f/:slug for urlencoded and multipart text fields, 64 kB cap, 303 to redirect_url or a plain thank-you; JSON when the Accept header asks

   done when · tick each as it passes

   • A blank HTML page's form submits with JavaScript disabled and lands on the thank-you
   • One row with the fields intact
   • A 100 kB body is refused

   next phase
2. 2

   Spam controls

   hideshow

   Honeypot, rate limit, origin allowlist, bot filter, all flagging rather than deleting.

   1. 2.1Honeypot field _gotcha: filled means store with spam true and redirect normally
   2. 2.2Per-IP limit of 10 per hour in SQLite; refuse origins not in ALLOWED_ORIGINS; coarse bot user-agent filter

   done when · tick each as it passes

   • A filled honeypot redirects and stores a spam row
   • The eleventh post in an hour is refused
   • A disallowed origin gets 403

   next phase
3. 3

   Notifications

   hideshow

   Email and webhook that never make the visitor wait.

   1. 3.1Send an email over SMTP_URL with the fields as a table, fire-and-forget with a timeout
      terminalcopy

      npm install nodemailer@6

   2. 3.2POST the JSON to webhook_url when set, same rules

   done when · tick each as it passes

   • A submission stores and redirects with SMTP unreachable
   • A real send arrives readable on a phone

   next phase
4. 4

   File uploads

   hideshow

   Safe uploads with a generated name and a streaming cap.

   1. 4.1Stream multipart files to UPLOAD_DIR/<slug>/ with a 10 MB cap while streaming and a MIME sniff
      terminalcopy

      npm install busboy@1 sharp@0.35.3

   2. 4.2Strip EXIF from images and never web-serve UPLOAD_DIR directly

   done when · tick each as it passes

   • An 11 MB file is refused before it is fully read
   • A renamed executable is refused
   • Two same-named uploads coexist

   next phase
5. 5

   Admin

   hideshow

   Forms, the snippet, submissions with spam separate, CSV.

   1. 5.1Basic-auth /admin: create forms and copy the paste-in HTML snippet with the honeypot field
   2. 5.2Submissions per form with a spam tab, restore-from-spam, and streamed CSV

   done when · tick each as it passes

   • A form goes from created to a real submission using only the snippet
   • A 10,000-row export does not grow memory

   next phase
6. 6

   Deploy

   hideshow

   HTTPS, backups covering uploads, README.

   1. 6.1/healthz, systemd, Caddy, nightly backup of data/

      Files deploy/formback.serviceCaddyfile

   2. 6.2README: the snippet verbatim, the allowlist step, where data lives

      Files README.md

   done when · tick each as it passes

   • A restore brings back rows and files
   • The README reaches a working form

   next phase