ADR-0008: Bizzy account connections
Capture initial Bizzy credentials with one worker and let BullMQ own execution retries.
Status: Accepted.
Date: 2026-09-23
Decision
Replace bizzy/account-provisioning with bizzy/account-connect. Use
@gigflow/worker processors and @gigflow/engine-jobs contracts. This applies
ADR-0007's domain worker structure
and gives this worker a name for its domain operation.
The connection processor loads a request, signs in through its assigned proxy, and captures credentials from an authenticated Bizzy response. It saves the account and completes the request in one database transaction. It does not save a browser session or enqueue health and session jobs.
BullMQ owns retries and execution locks. Jobs use three attempts with exponential backoff and jitter. Simple deduplication uses the request ID. Redis limits the queue to three active jobs across all worker replicas. The processor does not claim database leases, send lease heartbeats, or schedule its own retry jobs.
Persistence and failure handling
Keep the existing request table for this step. Job data contains only the request ID. Credentials stay out of job data and logs.
Before saving results, compare the request timestamp and proxy configuration version with the values read before login. Discard results if an operator changed the request or proxy. Account creation uses a short transaction and the existing proxy assignment lock. Repeated completion returns the saved account.
An authentication challenge marks the request as action_required. Transient
login errors use BullMQ retries. The final failed login attempt marks the request
as failed. Browser resources close on success and failure.
The authenticated response also supplies the initial health evidence required by the current account selectors. No extra health probe is needed for this step.
Delivery and deployment
Keep the existing queue name, bizzy-account-provisioning, and job name,
bizzy-account-provision, while producers migrate. The new client method is
enqueueAccountConnect. Helm watches the existing queue and deploys the renamed
worker image.
Keep the delivery sweep. It recovers pending requests that have no queued job and delivers the next due batch item. The connection processor advances the batch cursor after a terminal result, but does not enqueue the next item. A batch can therefore wait up to five minutes for the next sweep, in addition to its configured spacing.
Follow-up cleanup
The health and session workers, their delivery schedules, and their Admin/API actions are removed. Company import records rejected account credentials and proxy failures with version guards. It selects enabled accounts and proxies that are not invalid, quarantined, or cooling down. It does not require a recent health probe. Rate limits and usage counters remain in Redis.
The authenticated-response observer now belongs to the account-connect worker. The shared browser package and its session capture helpers are removed.
Legal-entity import is explicitly deferred. Keep its account pool, governor, health-age eligibility rule, and recovery job contracts until that worker is migrated. Its recovery jobs have no consumers after the worker removal. Keep the session table and scheduling query required by this path. No database tables are dropped in this cleanup.