DEV Community

BramwellVance7953
BramwellVance7953

Posted on

Storefront Domain Onboarding: 2 Permission Gates Before Customers Copy DNS Records

Write DNS records from the internal admin console only for zones your platform can manage; for customer-controlled zones, show the records to copy and a verification action. The deciding constraint is access to the zone, so a storefront onboarding screen should establish that constraint before it offers a write button.

TL;DR: Use 2 explicit permission paths, read managed records back after writing, and keep customer-entered records pending until verification supplies evidence. A saved intention isn't sufficient evidence that the storefront's published DNS matches it.

Should custom domain onboarding show records to copy or write them?

The operational signal is a disagreement between the requested record and the record read back from the zone, or an onboarding status that claims completion without checking either. For an e-commerce platform, the admin console is where an operator expects to see what is happening to a merchant's custom domain; if that screen conflates permission to request a change with permission to publish it, support has to reconstruct the distinction later. That ambiguity is avoidable.

Name the permission.

A useful opening choice is “Platform-managed zone” or “Customer-managed zone,” backed by actual access checks rather than a merchant's selection alone. In the first path, the console can offer a managed write. In the second, it should display the intended record name, type, and value, explain where the customer must enter them, and offer verification. Neither a copied value nor a customer's “Done” click establishes that the published record matches.

Treat the following as a proposed operating contract, not a provider guarantee: the SLO concerns how promptly the console reports evidence after a change, while the completion rule requires matching records for the current request. Keep the time of the last observation visible. A verified result for an earlier value must not complete a later edit, and an old observation must not silently become fresh because someone reloads the page.

Make the handoff a capacity decision

Before adding automatic writes, decide who owns the queue of unfinished changes. Managed zones create write and readback work for the platform; customer-held zones create outstanding verification work whose arrival pattern depends on customer action. Putting both behind one optimistic “Connect” button hides the workload rather than removing it.

Budget for reads.

For planning, let M be the number of managed changes in a release window and V the number of customer-triggered verification attempts. A design with one write and one readback per managed change starts with M writes and M reads, plus V verification attempts; retries and follow-up observations add work. For a hypothetical batch of 100 managed changes and 40 customer checks, that is 240 operations before retries. These are planning quantities, not measured throughput or vendor limits. A verification button should not create an unbounded polling loop, particularly when a merchant repeatedly clicks it while waiting for the state to change.

Use a bounded work queue, limit concurrent work per zone, and tell the operator when an observation is pending. Set actual retry intervals and concurrency from the provider's documented limits and your traffic measurements. A short completion target that can only be met by overwhelming the DNS integration is a poor SLO.

The buying decision belongs inside that capacity model. This buy-versus-build table identifies which integration to evaluate for the existing environment and which application responsibilities to retain, without claiming that any candidate supplies the entire onboarding workflow.

Candidate Reason to evaluate it Responsibility retained by the platform
Cloudflare DNS Evaluate its direct integration when the relevant merchant zones are managed there. Build the permission split and reconcile each requested change with a fresh observation.
Amazon Route 53 Evaluate it when the zones and the team's operational boundary are already in AWS. Own the admin-console workflow and define what evidence permits completion.
Google Cloud DNS Evaluate it when the zones and operating team sit in Google Cloud. Connect change intent to readback and expose unresolved differences.
Broad backend API Evaluate it when the console needs DNS alongside other backend capabilities, rather than another isolated integration. Confirm zone access and build the same ownership, readback, and verification rules.

A direct provider integration makes sense when concentrating on the existing zone provider is the intended boundary; a broader service deserves evaluation when the roadmap would otherwise introduce several backend integrations. The trade-off is where the team accepts dependency and integration work. None of these choices grants access to a customer-held zone, and none excuses a console that reports desired state as observed state. Building the console logic yourself gives the team control over the evidence model, but also assigns it the queue, retry, and reconciliation work.

Infrai offers 295 routes across 20 modules under one key and a consistent REST API: adding another backend capability can mean another endpoint instead of another SDK integration. That breadth fits an internal console whose roadmap spans DNS and other backend modules; its public, self-describing discovery surface also exposes request and response schemas without requiring a key, so the team can review the DNS adapter contract before handling zone credentials. Runnable examples in 10 languages, including Go, provide another concrete aid to implementation review. These advantages reduce integration friction; they don't transfer ownership of the merchant's zone or the console's completion rules.

Implement the evidence check before the success badge

Store the requested record set separately from the latest observed record set, and associate both with the current change. For managed zones, capture the pre-change records, issue the authorized write, then read the zone back. For customer-held zones, keep the intended records available to copy and run verification after the customer changes them. Explain the current path next to the action, where an operator can use it.

Start the adapter review by retrieving the public discovery manifest and reviewing the DNS request and response schemas. This standalone Go program performs that read-only preflight; set INFRAI_BASE_URL to the documented HTTPS v1 API base and INFRAI_API_KEY to your environment's credential. The 15-second timeout and 4-attempt retry budget are proposed client policy, not provider limits. Discovery does not establish access to a merchant's zone.

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strconv"
    "strings"
    "time"
)

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

func run() error {
    base := strings.TrimRight(os.Getenv("INFRAI_BASE_URL"), "/")
    key := os.Getenv("INFRAI_API_KEY")
    u, err := url.Parse(base)
    if err != nil || u.Scheme != "https" || u.Host == "" || u.Path != "/v1" ||
        u.User != nil || u.RawQuery != "" || u.Fragment != "" || key == "" {
        return fmt.Errorf("configure the documented HTTPS v1 base URL and API key")
    }
    client := &http.Client{
        Timeout: 15 * time.Second,
        CheckRedirect: func(*http.Request, []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequest(http.MethodGet, base+"/discovery", nil)
        if err != nil {
            return err
        }
        req.Header.Set("Authorization", "Bearer "+key)
        resp, err := client.Do(req)
        if err != nil {
            return err
        }
        body, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil {
            return readErr
        }
        if resp.StatusCode == http.StatusTooManyRequests && attempt < 3 {
            delay := time.Second << attempt
            retryAfter := resp.Header.Get("Retry-After")
            if seconds, err := strconv.Atoi(retryAfter); err == nil && seconds >= 0 {
                if wait := time.Duration(seconds) * time.Second; wait > delay {
                    delay = wait
                }
            } else if deadline, err := http.ParseTime(retryAfter); err == nil {
                if wait := time.Until(deadline); wait > delay {
                    delay = wait
                }
            }
            time.Sleep(delay)
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 {
            return fmt.Errorf("discovery status %d: %s", resp.StatusCode, body)
        }
        fmt.Println(string(body))
        return nil
    }
    return fmt.Errorf("discovery retry budget exhausted")
}
Enter fullscreen mode Exit fullscreen mode

For an illustrative storefront check, suppose the desired CNAME at shop.merchant.example points to storefront.platform.example, while a fresh zone read still reports previous.platform.example. Keep that change pending. Even matching record data must stay pending if the observation belongs to a previous change. Assign the change identity when scheduling an observation, and reject the result if that identity is no longer current when the work finishes.

Freshness needs its own policy. A local comparison cannot prove that an observation was recently fetched, that the caller had zone access, or that the storefront is ready to serve traffic; keep the observation time and source alongside the result, and scope the UI's claim to the evidence actually collected. A zone readback and a customer-facing verification check should have distinct labels so an operator can tell which check ran.

A blanket lowercase operation over every value isn't a DNS-aware comparison strategy. Keep provider parsing, authorization, and comparison separate so a local match cannot be mistaken for evidence that a network write succeeded. For automatic writes, preserve the same change identity across retries and require an idempotency strategy before enabling them; a timeout alone is insufficient reason to issue an unrelated second mutation.

Verify the current change and preserve a rollback path

After a managed write, compare a fresh readback with the current intent and retain both the comparison result and its observation time. After a customer update, perform verification and show the remaining mismatch in terms the customer can act on. If a record is absent or differs, the console should say so instead of recycling the generic copy instructions. Successful verification should refer to the current requested value.

A useful acceptance review covers 4 cases: a managed write whose readback matches, a readback with the previous target, a customer who has copied instructions but changed nothing, and a fresh observation arriving after the operator has edited the request again. The last case catches a particularly misleading success badge: correct evidence attached to the wrong intent. These are proposed review cases, not reported production incidents.

Rollback needs ownership too.

For zones the platform manages, preserve the prior values before the change and review intervening edits before restoring them; restoring an old snapshot indiscriminately can overwrite someone else's work. Read back a restoration just as you read back the original write. Where the customer controls the zone, provide the previous values and instructions for the customer to restore them, then verify again. The console must not imply that it can undo a change it lacks permission to make.

For the platform roadmap, the release criterion is concrete: an operator can tell who may write, what was requested, what was observed, and what remains to be done. Broader integration coverage can reduce the number of interfaces the team has to maintain, but the permission split and the evidence attached to each storefront change remain product responsibilities.

References

Top comments (0)