Node.js Bounded Domain Verification Polling With Customer Visible Pending Reasons
For a marketplace that gives each tenant a subdomain, make domain proof a bounded state machine and show customers the last observation, not a guessed DNS diagnosis. The deciding constraint is zone ownership: a platform-owned zone and a customer-owned zone have different authorization boundaries, even when both end in the same route. TL;DR: create an immutable verification attempt with an expiry,…
When a marketplace offers subdomains to tenants, each tenant's zone is treated as a bounded state machine. The key factor determining the level of authorization is whether the zone is owned by the platform or the customer. Platform-owned zones are controlled by the platform, while customer-owned zones are managed by the tenant. This distinction is crucial because domain ownership impacts the operational boundaries and the verification process.
In a customer-owned zone, a DNS challenge serves as evidence that the tenant can publish a specific record at a specified owner name. However, this evidence is temporary and does not guarantee permanent proof for all future route changes. The trade-off here is that customer-owned zones preserve the tenant's naming control but require additional verification steps, such as a proof flow, an expiry policy, and a rollback mechanism.
On the other hand, platform-owned zones simplify the process for the tenant but limit branding options and domain portability.
The verification process should stop checking DNS once a certain expiry time is reached, as indicated by a customer-visible reason like "record_not_observed_yet." This reason is intentionally narrow, providing the customer with information about the current status without making assumptions about the propagation, typos, or delegation issues.
The state model for bounded domain verification polling includes four states: pending, verified, expired, and cancelled. While an attempt is pending, the system should display the record name, record type, expiry, and the most recent observation to the customer.
The polling system should maintain a small state model to keep track of the attempt's status and provide a clear reason for each state. When an attempt is pending, the system should show the record name, record type, expiry, and the last observation. A specific example might include the following JSON response: { "status": "pending", "reason": "record_not_observed_yet", "record": { "name": "_marketplace-verify.store.customer.example", "type": "TXT" }, "expiresAt": "2026-09-16T10:30:00Z", "nextCheckAfterSeconds": 300 }.
The "nextCheckAfterSeconds" field serves as a scheduling hint, indicating the time interval before the next check, but it is not a prediction of when DNS will converge. The retry schedule should be stored with the attempt when it is created.
It's important to note that bounded domain verification polling cannot diagnose the customer's DNS provider, repair delegations, or make cached answers disappear. In cases where detailed delegation investigation or proof from several independent resolvers is required, a manual review or support path should be provided instead of trying to create an overly confident pending reason.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
