Skip to content

fix: recover imports, contacts, and app startup - #1297

Merged
nicobao merged 4 commits into
zkorum:mainfrom
nicobao:fix/import-recovery
Nov 4, 2026
Merged

nicobao merged 4 commits into
zkorum:mainfrom
nicobao:fix/import-recovery

Conversation

@nicobao

@nicobao nicobao commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Summary

This combines three reviewed fixes:

  • Import recovery (92a516a1): stop active imports from blocking ordinary conversation creation; break the circular dependency between import publication and opinion-group analysis; repair notification code generation/serialization; add bounded, owner-scoped recovery and API-enforced deadlines.
  • Organization-only project contacts (3243f341): support a person identified by first or last name, or a selected organization without a person name; enforce identity/contact-channel invariants; inherit organization logos; consolidate form/persistence handling and regenerate the API clients.
  • Reliable frontend startup (e75b7eae): coordinate required boot modules before mounting the application, keep telemetry failures nonfatal, and provide a localized, accessible recovery screen instead of partially starting without required plugins.

Import completion now means validated conversation data and counters are fully saved and published. Analysis is queued after that transaction commits. Fully saved legacy imports can recover without waiting for analysis; partial/abandoned imports fail rather than blocking the user indefinitely. Deployment and recovery guidance is included below.

Verification on the combined branch

  • API: 78 tests across admission, contact contracts/constraints, project pages, type-safety boundaries, and shared code generation, plus the 5 CLI tests run by pnpm test.
  • Frontend: 23 targeted tests across startup, cached import admission, contact forms, and contact presentation.
  • Import worker: 65 tests, Ruff, and strict BasedPyright checks. Integration tests apply the actual Flyway migration history, including V0113, to disposable PostgreSQL containers.
  • API TypeScript and frontend Vue/TypeScript checks pass.
  • Focused import linting and git diff --check pass.
  • The startup commit also includes production-build/browser-failure verification and its full frontend-suite verification.
  • Known baseline issue: the repository-wide soft-delete policy check reports the existing DROP TABLE in V0112__parallel_puppet_master.sql. V0113 in this PR changes contact nullability/check constraints, not application-row deletion.

What must be deployed

Component Required action Reason
PostgreSQL Apply V0113__curly_secret_warriors.sql with the production Flyway configuration Allows nullable project_contact.first_name and enforces identity/nonblank contact-channel checks
services/import-worker / Compose import-worker Rebuild and replace all old worker instances Import publication/recovery, notification models, heartbeats, deadlines, and terminal-state guards
services/api / Compose api Rebuild and redeploy Contact writes/reads/DTOs and API-side expiry/admission recovery
services/agora / Compose app Rebuild and redeploy the production frontend image Import UI, organization-only contacts, startup coordinator, and recovery screen
Reverse-proxy nginx Test configuration and reload after API/frontend container replacement Refresh replacement-container upstream addresses; no nginx-image change is required by this PR

The Svelte landing page (services/app) and the other worker images do not need deployment for this PR. Keep the existing math updater running and verify it is healthy: it performs background analysis after publication. The email worker already coalesces absent person names and falls back to the project title, so nullable contact first names do not require an email-worker redeploy.

There are no new runtime environment variables. The import deadline is the shared one-hour policy constant. Existing production secrets, database connections, Valkey configuration, and worker settings remain applicable.

Ordered rollout

This sequence assumes production is already on the current main baseline. Check Flyway history first: if earlier migrations are still pending, their independent rollout requirements also apply. Do not treat an unrestricted migration from an older production baseline as only a V0113 upgrade.

  1. Build and publish the three release images from the same release revision, using the existing production build configuration and secrets. Use explicit release tags. The Compose example exposes API_IMAGE_TAG and AGORA_IMAGE_TAG, but hardcodes the import worker to latest; update the real worker image reference explicitly. Use the actual production Compose/environment rather than the checked-in placeholder settings.
  2. Preflight and apply V0113 before enabling the new contact UI/API writes. The new CHECK constraints validate existing rows, including soft-deleted contacts. Check existing identities/channels against the new rules and existing stored channel formats against the new read DTOs; correct any pre-existing violations before migration. Run the normal production-writer Flyway migration (pnpm db:migrate from the production-configured API release checkout). Migration is a separate operation: the API runtime image neither ships the migration directory nor automatically runs Flyway. PostgreSQL/Flyway's normal transactional execution keeps this four-statement change atomic; plan for its table lock/constraint validation.
  3. Replace the import workers first, preserving the database and Valkey queue. Allow old workers to drain/stop and ensure all instances use the fixed version before introducing API-side expiry. Bring up only import-worker initially. Let recovery drain fully saved legacy imports still marked processing before moving on: recovery is batched at 100 records, so one pass is not necessarily enough. Background analysis can then run on the published conversations.
  4. Deploy every API replica and verify readiness before serving the new frontend. Completing this rollout before organization-only/last-name-only contacts are created avoids old API replicas receiving records their response schemas cannot represent. Test/reload the existing reverse proxy after API container replacement as needed to refresh its upstream address.
  5. Deploy the Vue frontend (Compose service app), then test/reload the proxy after its container replacement. Preserve the agora-assets persistent volume: the existing entrypoint merges release assets and retains old hashed chunks for open tabs. Avoid a volume-removing teardown. Fresh page loads receive the new startup gate; already-open tabs need a refresh to get the startup fix and the new contact rendering contract.

For a Compose deployment, use service-scoped pull/up -d --no-deps steps in the order above, with recovery/readiness checks between them. Do not rely on scripts/infra/update-agora.sh to implement this ordered rollout: it pulls only nginx and runs a bulk up -d. Explicitly pull the new API/frontend/import-worker images, stage their replacement, and use the existing nginx -t / nginx -s reload procedure after container changes.

Post-rollout checks

  • An affected fully saved import becomes completed and its conversation is accessible, even if analysis has not finished.
  • A fresh CSV/URL import publishes after ingestion; analysis results appear afterward. Manual conversation creation remains available while another import is active.
  • Abandoned imports release their slot after expiry; queued jobs are not incorrectly classified as stale ingestion merely because the queue is busy.
  • Create, edit, and reload organization-only and last-name-only contacts; check desktop/mobile display and inherited/overridden logos.
  • Verify a fresh application load initializes Vue Query and the other required plugins. In staging, a failed required boot module should show the recovery screen rather than a partially running application.

Rollback considerations

  • V0113 is not a freely reversible expand/contract change after new contacts are saved. Organization-only and last-name-only contacts can have first_name = NULL. A pre-PR API/frontend expects a first name, and restoring NOT NULL can fail. Keep the expanded schema and a contact-compatible API/frontend, or reconcile the affected data before a pre-PR rollback; do not blindly undo the migration.
  • Prefer a contact-compatible frontend build if rolling back only the startup change. Preserve the asset volume during rollback too.
  • Rolling the import worker back restores the publication/analysis deadlock for new imports. Previously recovered/completed imports remain completed; avoid reverting this fix as a general rollback strategy.
  • Actual production migration history, contact-data validity, and the specific reported import have not been inspected from this workspace. Those are production verification steps, not assumptions proved by the local tests.

Deploy: import-worker, api, agora

Complete imports when validated conversation data and counters are fully saved, then run opinion-group analysis in the background. This breaks the circular dependency where imports waited for analysis while the math worker rejected importing conversations.

Scope active-import admission to CSV and URL imports so cached query data cannot disable ordinary conversation creation. Recover fully saved legacy imports before timeout cleanup, and publish new imports atomically with their completion notification before queueing analysis.

Fix generated Pydantic datetime and UUID constraints at the schema-export boundary. Preserve required nullable event fields while omitting absent optional fields so the API accepts worker notifications.

Apply a shared one-hour queueing and ingestion deadline, with owner-scoped heartbeats and API-side recovery when the worker is unavailable. Run bounded, non-blocking maintenance while ingestion slots are occupied; distinguish queued work from abandoned ingestion and protect saved imports across recovery batches.

Guard terminal states, duplicate deliveries, cross-user updates, and cleanup after a lost commit acknowledgement. Keep normal polling read-only, use typed Drizzle and generated SQLAlchemy queries, derive request types from Zod, and remove obsolete analysis-gating and result plumbing.

Add database-backed lifecycle, stale-replica, ownership, queue-privacy, query-count, saturation, and frontend cache regression coverage. Document diagnosis, recovery guarantees, and the worker-first rollout order for existing overdue imports.

Deploy: import-worker, api, agora
Allow a contact to identify a person by first or last name, or use a selected organization without a personal name. Enforce identity and nonblank email-or-website requirements in the API and database, and generate the V0113 migration with synchronized schema fixtures.

Display the organization as the primary contact name when no person is named, without repeating it below. Reuse organization logos, preserve image proportions and explicit contact image overrides, and retain the initials fallback across desktop and mobile.

Consolidate contact form parsing and backend persistence. Normalize contact values on create/update using the existing email normalization helper, preserve stored values during reads, and always reset the save loading state.

Refresh OpenAPI and both clients through normal generation. Cover the contact contract, form behavior, display logic, schema serialization, logo inheritance, and database insert/update constraints with focused tests.

Deploy: agora, api
Quasar skips failed boot-module imports and can mount App.vue without Vue Query, causing useRealtimeSSE to throw before the application initializes. Coordinate required boot modules explicitly and render the application only after every required initializer succeeds.

Load boot modules concurrently, preserve initialization order, and keep telemetry failures nonfatal. Statically import the coordinator from the root component so it cannot become another independently skipped boot chunk. Track completion per Vue app with weak references and route initialization failures through the existing chunk-recovery and privacy-aware error handler while allowing the recovery screen to mount.

Add a standalone recovery screen with all eleven display languages, RTL support, theme styling, keyboard accessibility, and a native reload action. Keep recovery usable when browser storage is unavailable, and update the Vue Query boot file to the current Quasar wrapper.

Cover shared QueryClient injection, per-app isolation, required module and initializer failures, optional telemetry failures, environment selection, localized recovery, focus management, and unavailable storage. Verify all 1,669 frontend tests, TypeScript, focused lint and formatting, a production-mode build, and browser-injected startup and navigation failures.

Deploy: agora
@netlify

netlify Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for agoracitizen canceled.

Name Link
🔨 Latest commit 7c3bcec
🔍 Latest deploy log https://app.netlify.com/projects/agoracitizen/deploys/6aea4c51c390f82aa91bb94b

Keep the detailed deployment and recovery runbook in the pull request description rather than a checked-in incident document. Remove the README link while retaining the essential worker-first rollout guidance.

Deploy: none
@nicobao
nicobao merged commit 7cdb2cb into zkorum:main Nov 4, 2026
5 of 6 checks passed
@nicobao
nicobao deleted the fix/import-recovery branch November 4, 2026 08:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant