Skip to content

Hymical Forms v0.2.0

Choose a tag to compare

View all tags
@quangshuynh quangshuynh released this 25 Aug 14:30
· 2 commits to main since this release
v0.2.0
8e99004
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Hymical Forms v0.2.0

The first release intended to be evaluated and used beyond local development.

Hymical Forms is a self-hostable form ingestion service focused on reliable webhook delivery. It accepts public HTML form submissions, persists them durably, and delivers them asynchronously through a PostgreSQL-backed worker.

Highlights

  • Form ingestion with validation and request limits
  • PostgreSQL persistence with Alembic migrations
  • Idempotent submission handling
  • Transactional outbox for durable webhook delivery
  • HMAC-SHA256 signed webhooks
  • Worker leases, retries, backoff, and crash recovery
  • At-least-once delivery semantics
  • Management API key authentication
  • Endpoint management
  • Delivery inspection and manual replay
  • Distributed per-source and per-endpoint rate limiting
  • Submission retrieval and filtering
  • JSON and CSV export
  • Operator-run retention cleanup
  • Real PostgreSQL integration and concurrency tests
  • MkDocs documentation site

Reliability model

A successful form submission and its delivery obligation are committed in the same database transaction before the API returns 202 Accepted.

Webhook delivery happens in a separate worker process. Failed deliveries are retried with bounded exponential backoff, and abandoned worker claims become eligible again after their lease expires.

Delivery is intentionally at least once, not exactly once. Receivers should deduplicate using the submission ID included in the signed webhook payload.

Security and operations

This release includes:

  • digest-only storage for management API keys
  • one-time webhook signing-secret disclosure
  • HMAC webhook verification
  • public-ingestion rate limiting
  • request-size and field limits
  • CSV formula-injection protection
  • partial SSRF protections for webhook destinations
  • schema revision checks at application startup

Release-quality pass

The 0.2.0 release also includes:

  • consistent version reporting
  • architecture documentation
  • an end-to-end demo walkthrough
  • package and clean-install verification
  • wheel and source-distribution validation
  • documentation and security review
  • coding-agent guidance for Claude Code and Codex

Known limitations

Hymical Forms is still under active development.

Notable limitations include:

  • PostgreSQL is the supported production database
  • SQLite cannot currently migrate through the full Alembic history
  • webhook delivery is at least once and may produce duplicates after ambiguous worker failures
  • SSRF protection is not complete against DNS rebinding or hostnames resolving to private addresses
  • rate limiting is traffic protection, not spam classification
  • there are no users, roles, organizations, or tenant boundaries
  • retention cleanup is operator-run rather than scheduled
  • endpoint deletion is not implemented

See the documentation for full setup, architecture, API behavior, and limitations.

Assets 2
Loading
0 Join discussion