Hymical Forms v0.2.1

Hymical Forms v0.2.1 is a correctness release that strengthens webhook delivery ownership under lease expiry and worker recovery.

What changed

• Added explicit claim tokens for webhook delivery ownership
• Prevented stale workers from overwriting deliveries that have been reclaimed by another worker
• Preserved accurate attempt history even when a stale worker's HTTP request completes late
• Prevented lifetime attempt numbers from being reused during concurrent completion
• Added focused PostgreSQL integration tests covering stale-owner races and competing completion results
• Added migration 0006 for delivery claim tokens
• Expanded documentation around lease ownership, late attempts, and deployment safety

Delivery semantics

Webhook delivery remains at least once.

A webhook may still be delivered more than once if a request succeeds but Forms cannot durably record that success before the lease is reclaimed. Receivers should continue to deduplicate using the submission identity when necessary.

The change in v0.2.1 is narrower: once a worker's claim has been superseded, that worker can no longer overwrite the authoritative delivery state owned by the newer claim.

Upgrade note

Stop all existing Forms workers before upgrading.

Apply the database migrations, then start the v0.2.1 workers.

Do not run pre-v0.2.1 workers and v0.2.1 workers concurrently during this migration. Older workers do not understand delivery claim tokens and can bypass the ownership fencing introduced in this release.

Verification

The release is covered by the full test suite plus real PostgreSQL integration tests for delivery claiming, lease expiry, stale-worker completion, attempt numbering, and recovery behavior.

What's Changed

• delivery claim fencing by @quangshuynh in #9

Full Changelog: v0.2.0...v0.2.1

Hymical Forms v0.2.0

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.