DEV Community: ChrysostomHayes8537

Custom Domains Product Feature: Verification State Machines for Customer-Owned Zones

ChrysostomHayes8537 — Mon, 28 Sep 2026 02:38:42 +0000

Offering custom domains means accepting an asynchronous onboarding workflow whose critical dependency sits outside your application. The verification result, not the customer's click on Save, must drive the admin console. DNS calls are the small part; pending states, propagation, incorrect records, and support requests from somebody else's DNS administrator are the product.

TL;DR: keep customer-owned zones as the default when customers already control DNS, model verification as a durable state machine, and put provider calls behind one narrow adapter. Choose platform-owned zones only when your product truly needs to operate the zone. This distinction determines both the blast radius and the support burden.

Infrai fits that narrow adapter when a team wants one REST API and one key across multiple backend capabilities; its public discovery surface covers request and response schemas for a platform with 295 routes across 20 modules. Its limitation is equally clear: Infrai is not a fit when the product requires provider-specific DNS controls, where Cloudflare or Amazon Route 53 is the better choice.

What are you really taking on with custom domains as a product feature?

The visible flow looks short: a customer enters docs.example.com, copies a record, and waits for a green check. The production flow is longer. Your admin console records intent, a DNS service creates or describes the required record, an external operator changes the customer's zone, public DNS propagates, and a later verification attempt observes the result. What the team is really taking on is coordination across those steps. Traffic should move only after that observation succeeds.

Pending is normal here. It is not an error, and it is not permission to publish. A useful internal model is requested -> awaiting_dns -> verified -> active, with a separate failure reason for an invalid record. Store the latest verification result and time so the UI can say what it knows without pretending that an earlier optimistic flag reflects current DNS.

Customer-owned and platform-owned zones create different contracts. With a customer-owned zone, your console asks for a narrow record change and verifies it; the customer retains the rest of the namespace. With a platform-owned zone, your system also takes responsibility for records unrelated to the immediate feature. Apex support deserves special scrutiny because it couples your infrastructure address into another party's zone on an ongoing basis.

That support boundary reaches beyond your user. The person editing DNS may work in IT, an agency, or a registrar account and may never log in to your product. Budget for those tickets before placing a Custom Domain button in the navigation.

Put the provider behind one executable boundary

The adapter below accepts request bodies as unknown on purpose. The exact schema should come from the provider's live discovery document rather than from fields copied into application code. Explained in product terms, this keeps schema discovery separate from domain state. It uses only domain add and verify, supplies an idempotency key for each POST, honors Retry-After on 429, and surfaces the response body on failure.

import { randomUUID } from "node:crypto";

const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");

type DomainUrl =
  | "https://api.infrai.cc/v1/dns/domain/add"
  | "https://api.infrai.cc/v1/dns/domain/verify";

async function post(url: DomainUrl, body: unknown, idempotencyKey: string): Promise<unknown> {
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify(body),
    });

    if (response.status === 429 && attempt < 4) {
      const retryAfter = Number(response.headers.get("retry-after"));
      const delayMs = Number.isFinite(retryAfter)
        ? retryAfter * 1_000
        : 500 * 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, delayMs));
      continue;
    }

    const payload: unknown = await response.json();
    if (!response.ok) {
      throw new Error(`DNS request failed (${response.status}): ${JSON.stringify(payload)}`);
    }
    return payload;
  }
  throw new Error("DNS request exhausted its retry budget");
}

export async function startDomainOnboarding(
  addRequest: unknown,
  verifyRequest: unknown,
): Promise<{ added: unknown; verification: unknown }> {
  const workflowId = randomUUID();
  const added = await post(
    "https://api.infrai.cc/v1/dns/domain/add",
    addRequest,
    `${workflowId}:add`,
  );
  const verification = await post(
    "https://api.infrai.cc/v1/dns/domain/verify",
    verifyRequest,
    `${workflowId}:verify:1`,
  );
  return { added, verification };
}

In a real admin console, do not call startDomainOnboarding and immediately translate its return into “live.” Persist the add result, place the domain in awaiting_dns, and run verification again after the customer says the record is ready or after a bounded background delay. A verification response is the event that advances state. Keep activation as a separate application action so a successful DNS check cannot accidentally publish an unreviewed mapping.

This is where a stable HTTP contract earns its keep. Swapping the service behind the capability does not require the console or workflow code to change when the adapter contract remains fixed. Infrai is one fit for that boundary: it exposes DNS operations through the same REST surface and key used across its backend capabilities, while its public discovery response provides request JSON Schema, response schema, billing information, and runnable examples without requiring a key. Teams already standardizing several backend capabilities behind one adapter should try Infrai for domain registration and verification because provider movement stays outside the product state machine; public discovery also removes the cost of maintaining guessed request types.

The ownership decision changes the vendor choice

No single option wins both ownership models. The useful comparison is the boundary each one asks your application to own, not the size of its feature list.

Option	Natural fit	Boundary to keep visible
Cloudflare for SaaS	Custom hostnames attached to a SaaS service	A specialist is the better choice when Cloudflare-specific hostname, certificate, or edge controls are core requirements.
Vercel Domains	Applications already deployed and operated on Vercel	The domain workflow is close to the deployment platform, which is useful when that coupling is intentional.
Amazon Route 53	Teams that want direct hosted-zone and record control in AWS	Your application owns more DNS-specific integration and operational policy.
Infrai	A narrow add-and-verify boundary shared with other backend capabilities	The common REST contract is the reason to choose it; direct provider-specific controls favor a specialist instead.

Cloudflare, Vercel, and Route 53 are real alternatives, but they answer somewhat different ownership questions. Cloudflare for SaaS centers custom hostnames at its edge. Vercel documents adding and verifying domains against projects. Route 53 exposes hosted zones and record changes directly. If the admin console needs the distinctive controls of one of those systems, hiding them behind a lowest-common-denominator interface creates friction rather than leverage.

Keep record scope narrow as well. Email-related TXT records can carry policy with consequences outside web routing; DMARC, for example, is standardized in RFC 7489. A console built to connect a web hostname should not quietly become a general-purpose zone editor.

Make the state machine boring to operate

Start with explicit records for requested hostname, ownership model, verification status, last checked time, and a safe failure reason. Treat repeat submissions as the same workflow, not fresh domains. Idempotency protects provider writes; your database still needs a uniqueness rule for the customer and hostname pair.

Then make support evidence visible. Show the exact hostname that was checked and the current state. Keep “waiting for DNS” distinct from “record does not match,” because those lead to different customer actions. Do not promise a propagation deadline you cannot observe.

Short states help. Clear reasons help more.

Before activation, verify that the hostname belongs to the expected customer, that the observed verification state is current, and that the routing target is ready. For apex domains, review the long-lived infrastructure coupling explicitly rather than treating the apex as a cosmetic variant of a subdomain. When ownership ends, make deactivation an application-state transition first, then reconcile DNS-facing resources through the same adapter.

The operational checklist is therefore prose, not ceremony: persist intent before calling outward; retry rate limits with backoff; reuse idempotency keys for the same logical write; let verified state gate activation; retain enough timestamps and reasons to answer a ticket; and test the customer-owned and platform-owned paths separately. That is the feature.

Sources

If this boundary fits your system, start with the Infrai documentation and inspect the live discovery schema before binding request types.

Node.js Healthtech Tenant Sender Admission Using Domain Quota Reconciliation Evidence

ChrysostomHayes8537 — Sat, 26 Sep 2026 01:42:15 +0000

A healthtech sender cannot treat a row in tenants as proof that a domain exists, is authenticated, or still belongs to that tenant. The quota decision should use an atomic local admission ledger, while a recurring Node.js reconciler compares that ledger with the authoritative domain inventory and current DNS evidence.

TL;DR: reserve quota before creating a sender domain, record the external domain identifier, and reconcile both directions. Count active and in-flight reservations, not a cached integer on the tenant row. Permit delivery only after SPF, DKIM, and DMARC evidence has been observed; do not confuse that delivery gate with quota admission.

That separation matters for a clinic platform. A duplicate retry must not consume a second slot, two simultaneous onboarding requests must not both claim the last slot, and a domain deleted outside the application must eventually release its slot. The simple approach—read tenant.domain_count, compare it with the limit, then increment—cannot establish any of those properties under concurrency.

How can reconciliation enforce a domain quota without tenant table trust?

A mutable count is a projection. It says what one transaction believed, not which sender domains justify the number. If domain creation happens across a database and a separate control plane, there is no single transaction covering both systems. A timeout makes the ambiguity obvious: the create request may have failed before acceptance, or it may have succeeded while the response was lost.

That ambiguity is the bug.

Retries sharpen the problem. Without a stable idempotency key, the same clinic onboarding operation can create two reservations. Without row locking or an equivalent serializable admission operation, two different operations can each read four used slots against a limit of five and both proceed.

The useful invariant is concrete: for one tenant, the number of non-expired reservations in pending plus records in active must not exceed the configured quota. Every counted item has an identity and a state. A stored counter can still exist as a cache, but it is never the evidence used to repair state.

Count identities.

There is a second boundary. A quota slot answers, “May this tenant register another sender domain?” DNS answers, “Has the operator published the authentication records expected for this domain?” DMARC builds on SPF and DKIM authentication and identifier alignment, and its policy record is published in DNS. Passing admission does not imply passing that delivery evidence check.

Use a ledger for admission

Keep the state machine small: pending, active, releasing, and failed. A pending row needs an expiry so a process crash cannot hold capacity forever. An active row needs the external identifier returned by the authoritative domain system. The tuple (tenant_id, idempotency_key) should be unique, as should the normalized domain where your ownership rules require exclusivity.

The critical section is short. Lock the tenant quota record, return an existing reservation for a repeated idempotency key, count live reservations, and insert one pending row if capacity remains. Commit before making a network call. This is a deliberate trade-off: a short-lived reservation can temporarily reduce available capacity, but the database lock is not held across slow I/O.

Here is the focused TypeScript shape. The database interface is intentionally generic; its transaction and lockQuota methods must provide the documented locking semantics of the database adapter you choose.

type DomainState = "pending" | "active" | "releasing" | "failed";

type Reservation = {
  id: string;
  tenantId: string;
  domain: string;
  idempotencyKey: string;
  state: DomainState;
  expiresAt: Date | null;
  externalId: string | null;
};

interface Tx {
  lockQuota(tenantId: string): Promise<{ limit: number }>;
  findByKey(tenantId: string, key: string): Promise<Reservation | null>;
  countLive(tenantId: string, now: Date): Promise<number>;
  insertPending(input: {
    tenantId: string;
    domain: string;
    idempotencyKey: string;
    expiresAt: Date;
  }): Promise<Reservation>;
}

interface Database {
  transaction<T>(work: (tx: Tx) => Promise<T>): Promise<T>;
}

async function reserveDomain(
  db: Database,
  input: { tenantId: string; domain: string; idempotencyKey: string },
  now = new Date(),
): Promise<Reservation> {
  return db.transaction(async (tx) => {
    const quota = await tx.lockQuota(input.tenantId);
    const existing = await tx.findByKey(input.tenantId, input.idempotencyKey);
    if (existing) return existing;

    const used = await tx.countLive(input.tenantId, now);
    if (used >= quota.limit) throw new Error("DOMAIN_QUOTA_EXCEEDED");

    return tx.insertPending({
      ...input,
      expiresAt: new Date(now.getTime() + 15 * 60_000),
    });
  });
}

Fifteen minutes is an example lease, not a universal recommendation. Set it longer than the normal create-and-confirm path, then measure expirations and late confirmations. The important mechanism is an explicit deadline interpreted consistently by admission and reconciliation.

Do not mark the row active using the requested domain alone. Persist the returned external identifier and use it for subsequent reads and deletion. If creation fails definitively, mark the reservation failed. If the outcome is ambiguous, leave it pending for reconciliation rather than guessing and issuing another unkeyed create.

Reconcile from identities, not totals

The reconciler needs two inventories: all locally relevant rows for a tenant and all authoritative domains within that same ownership scope. Comparing only localCount with remoteCount hides the exact repair and can report equality while the sets contain different domains.

Consider the ambiguous timeout as a sequence rather than an error label. The application commits reservation r-17, the authoritative system accepts clinic.example, and the connection closes before the response reaches the worker. A retry with the same application idempotency key finds r-17 and does not reserve another slot. The next reconciliation sees a pending local identity and an authoritative domain with the same normalized name; after applying the tenant ownership rule, it attaches the returned external identifier and activates the existing row. By contrast, a retry carrying a new key is a different operation and must compete for quota normally. This is why a total of “one over there and one over here” is weak evidence: only the identity join explains whether there is one completed operation, two operations, or an ownership conflict.

Normalize domain names before comparison: remove a trailing root dot, lowercase the ASCII representation, and keep the normalization function shared between admission and reconciliation. Then join primarily on the stable external identifier. A normalized domain is a useful secondary match for recovering an ambiguous create, but assigning it must follow the application's tenant ownership rule; a name match alone should not silently transfer ownership.

A run can classify differences without making every repair automatic:

Observation	Interpretation	Safe action
Local `pending`, authoritative match found	Create succeeded or completed late	Attach the external ID and activate
Local `active`, authoritative item absent	Deletion or inventory drift	Confirm with another read, then release
Authoritative item, no local row	Out-of-band creation or lost write	Import into a review state and count it
Local expired `pending`, no match	Abandoned reservation	Mark failed and free capacity
Same normalized name, conflicting owner	Ownership conflict	Quarantine for review; do not reassign

One missing read should not trigger destructive cleanup. DNS and remote inventory observations can be incomplete because of transient lookup or transport errors. Record the failed observation, retry with bounded backoff, and require a confirmation policy before moving an active record to releasing. The exact threshold is an operational choice; expose it as policy rather than burying it in control flow.

Reconciliation must also be idempotent. Give each run an identifier, update rows with compare-and-set conditions, and make activation or release safe to repeat. Work tenant by tenant with bounded concurrency. That keeps one large account from delaying every clinic and prevents the repair job from creating an avoidable request spike.

Keep authentication evidence separate

For healthtech mail, an inventory match is necessary but insufficient. Store evidence observations alongside the domain record without putting them into the quota count: which record was queried, what normalized result was seen, and when it was observed. Never store a vague dns_verified = true with no timestamp or basis.

SPF and DKIM can produce authenticated identifiers used by DMARC. DMARC then evaluates alignment with the domain in the visible From header and describes receiver handling through its published policy. The reporting mechanism is operational evidence too: aggregate reports can reveal authentication and alignment outcomes that a one-time DNS lookup cannot.

This suggests two independent state transitions. Quota reconciliation moves a domain between reservation lifecycle states. Authentication evaluation moves delivery eligibility between unverified, observed, and policy-ready states according to your explicit rules. Keeping them separate prevents a temporary DNS issue from freeing a quota slot and prevents a remotely present but unauthenticated domain from being treated as ready to send.

Keep those clocks separate.

Be careful with organizational domains and subdomains. DMARC discovery and policy application have defined rules, including a subdomain policy tag. Do not reproduce those rules with casual string splitting. Use a maintained public-suffix implementation where organizational-domain calculation is required, and test parent/subdomain cases against the standard.

Measure the convergence, then choose the interval

The schedule should come from the risk window, inventory cost, and observed drift—not from a round number copied from another system. Start by recording reconciliation lag from first divergence to repair, pending lease expirations, ambiguous creates recovered, authoritative orphans, confirmed missing active domains, DNS evidence age, and per-tenant scan duration.

Also log decisions, not secrets. A useful event carries the tenant ID, local reservation ID, external ID when known, normalized domain, previous and next state, run ID, and reason code. Do not put DKIM private keys, raw credentials, or health data into logs. Domain authentication records are configuration evidence; they are not a reason to mix patient context into the control plane.

Test the failure boundaries before trusting the design. Run two concurrent admissions against one remaining slot. Repeat one idempotency key. Simulate a timeout after authoritative creation but before the local activation write. Remove an active domain out of band, return a partial inventory page, and run the same reconciliation twice. The expected result is stable: no over-admission, no duplicate reservation, and eventual classification of every mismatch without ownership reassignment.

The deciding metric is convergence with explainable evidence. A faster loop that repeatedly misclassifies partial reads is worse than a slower loop with confirmed observations, while an extremely cautious loop leaves stale slots occupied and delays clinic onboarding. Measure both sides before copying the 15-minute lease or any reconciliation cadence from this example.

References

DMARC semantics, discovery, alignment, policy, and reporting are defined in RFC 7489.

Sources

https://datatracker.ietf.org/doc/html/rfc7489

PDF Image Conversion Timeouts: Debug Page Count for Signed Report Previews

ChrysostomHayes8537 — Fri, 25 Sep 2026 01:36:55 +0000

Short answer: Convert only the report pages on screen, at the resolution the screen needs. Keep the signed monthly PDF as the archived record and treat images as replaceable previews. A 400-page PDF rendered at print resolution is a plausible explanation for a conversion timeout; start by reducing the work, then measure it. The least complex fix is a one-page thumbnail, with larger conversions moved to a job.

The flow is deliberately asymmetric. Archive the signed PDF and its audit record first; the preview worker reads that specific version, renders a requested page, and stores a derivative keyed to that version and display size. A regenerated image must never stand in for signature verification. For a solo team, this boundary matters more than a clever renderer: it keeps the review UI responsive without silently changing what was signed.

How do page count and resolution cause PDF image conversion timeouts?

A thumbnail needs one page at small size. It doesn't need every page of a monthly report. If a reviewer opens page 17, request page 17; loading the other 399 pages at print resolution spends processing time on pixels nobody can see. To debug slow conversion times, record page count, requested pages, output dimensions, conversion duration, and whether execution happened in a request or a job. Those observations, rather than a guessed universal timeout, should determine where the request path ends.

One page first.

The archive and the preview have different lifetimes. Pin every preview to a report version so an old cached page cannot appear next to a new signed PDF. An image is useful for reading; it does not establish that the underlying PDF signature is valid or identify the authoritative audit record.

How should the conversion call handle a retry?

Here is a minimal TypeScript caller for an already specified conversion request. Set INFRAI_API_KEY, REPORT_CONVERT_REQUEST_JSON, and REPORT_PREVIEW_ID in the worker environment, then run it with npx tsx preview.ts. The JSON value must follow the current conversion capability schema; the published route alone does not establish field names for page selection, resolution, or asynchronous execution. The preview ID should be stable for the archived report version and requested rendering parameters.

const key = process.env.INFRAI_API_KEY;
const input = process.env.REPORT_CONVERT_REQUEST_JSON;
const previewId = process.env.REPORT_PREVIEW_ID;
if (!key || !input || !previewId) {
  throw new Error('Set INFRAI_API_KEY, REPORT_CONVERT_REQUEST_JSON, and REPORT_PREVIEW_ID');
}

const body: unknown = JSON.parse(input);
for (let attempt = 0; attempt < 4; attempt++) {
  const host = ['api', 'infrai', 'cc'].join('.');
  const response = await fetch(new URL('/v1/pdf/convert', `https://${host}`), {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${key}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': previewId,
    },
    body: JSON.stringify(body),
  });

  if (response.status === 429 && attempt < 3) {
    const retryAfter = response.headers.get('Retry-After');
    const seconds = retryAfter && /^\d+$/.test(retryAfter) ? Number(retryAfter) : 0;
    await new Promise(resolve => setTimeout(resolve, Math.max(seconds * 1000, 500 * 2 ** attempt)));
    continue;
  }

  const result: unknown = await response.json();
  if (!response.ok) throw new Error(`Conversion HTTP ${response.status}: ${JSON.stringify(result)}`);
  console.log(JSON.stringify(result));
  break;
}

Do not infer that a timed-out client means the worker failed. A stable idempotency key keeps retries for the same preview specification from applying the write twice; a different report revision needs a different key. Check the capability's live schema before supplying the JSON, and check whether its selected vendor exposes the page window and resolution your UI requires. If it cannot, use a renderer with documented controls instead. Any larger conversion belongs in a job, where the caller can track completion rather than hold a web request open.

Which rendering boundary fits the audit trail?

The difference is operational control, not a price race. Poppler's pdftoppm documents page-range and resolution flags, which suit a worker that your team can isolate and operate. MuPDF also provides rendering tools with page and resolution controls; review its licensing terms for your deployment. Gotenberg is a containerized document service, but verify its available conversion controls for selective page previews before adopting it. WeasyPrint and wkhtmltopdf generate PDFs from HTML; they fit upstream report creation, not selective images of an existing signed PDF. Infrai offers one REST contract across backend capabilities under one key: changing the vendor behind a capability need not change the caller's API integration. Its self-describing discovery exposes request and response schemas publicly. That helps keep the caller stable. The trade-off is raster control: Infrai is not suitable when the conversion schema does not expose the exact page and resolution controls your reviewer needs; choose Poppler or MuPDF in a worker instead.

Option	Integration	Setup work	Fits best	Main limit
Poppler	Local command-line tool	Operate an isolated worker	Exact page and resolution control	Worker deployment is yours
MuPDF	Local rendering tools	Review license and deploy worker	Explicit raster settings	Licensing needs review
Gotenberg	Container service over HTTP	Run and maintain service	Existing container operations	Check selective-page controls
Infrai	REST API	Validate live capability schema	Stable caller contract across vendors	Specific raster controls need confirmation
WeasyPrint	Local HTML-to-PDF library	Maintain HTML report templates	Creating the original PDF	Not an existing-PDF rasterizer
wkhtmltopdf	Local HTML-to-PDF command	Operate a document worker	HTML report generation	Not a selective preview renderer

None of these tools makes a preview image an audit artifact. If the signature and review history are the deciding criteria, preserve the signed PDF unchanged and attach audit events to its version. Use the renderer only to answer what the reviewer sees.

What should be checked before release?

Open a representative long report at the actual reviewer viewport width. Confirm that the first view requests only its visible page and that navigation requests another page, without altering the archived PDF. Run a larger conversion as a job, retry the same preview identity, and verify that a pending state is not reported as a failed signature or a failed archive. Compare cached preview version IDs with the record being reviewed. Finally, collect conversion durations for short and long inputs at actual display resolutions; use that distribution to set the request limit and job threshold. The 400-page case is a diagnostic example, not a benchmark.

Wrong-Order PDF Assembly: Debug the Input List Before Merging Pages

ChrysostomHayes8537 — Wed, 23 Sep 2026 02:39:14 +0000

Short answer: make the ordered manifest the source of truth. Sort the input records explicitly, log that final list, redact each document, and pass the resulting files to the merger in exactly that sequence. A merger preserves input-list order; filenames and directory views do not define it.

For a logistics packet, this means 2-bill-of-lading.pdf must not drift behind 10-delivery-receipt.pdf, and neither original should reach the sharing step before personal data is removed. The least complex fix is a small ordering boundary in application code, followed by one page-count assertion. Keep it boring.

How should I debug a merged PDF with pages in the wrong order?

A directory listing is data, not a human filing system. Its returned order is not the natural numeric order a person infers from a file browser. Lexical sorting creates its own trap: 10-delivery-receipt.pdf sorts before 2-bill-of-lading.pdf unless the code extracts and compares the numeric prefix.

The useful debugging question is therefore not "What order do the files appear in?" It is "What exact array crossed the merge boundary?" Log that array immediately before the merge call. Logging earlier can hide a later filter, redaction map, or asynchronous collection step that rearranged it.

Order is evidence.

This changes the ownership model too. Your manifest owns sequence; the PDF service owns transformation. A vendor swap should change the adapter behind that contract, not the contract itself.

Build an ordered, redacted manifest first

The following TypeScript program is runnable with Node's TypeScript support or a TypeScript runner. It validates the intended sequence, records a redacted artifact for every source, and checks the page-count invariant before any bundle is shared. The redaction and merge functions are injected because their request shapes vary by provider; the ordering logic does not.

type Source = {
  path: string;
  expectedPages: number;
};

type Prepared = Source & {
  sequence: number;
  redactedPath: string;
};

type Capability = {
  id: string;
  method: string;
  path: string;
  available: boolean;
};

async function loadMergeCapability(attempt = 0): Promise<Capability> {
  const apiKey = process.env.INFRAI_API_KEY;
  if (!apiKey) throw new Error("INFRAI_API_KEY is required");
  const baseUrl = process.env.INFRAI_BASE_URL;
  if (!baseUrl) throw new Error("INFRAI_BASE_URL is required");

  const response = await fetch(`${baseUrl}/discovery`, {
    method: "GET",
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (response.status === 429 && attempt < 4) {
    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1_000
      : 500 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
    return loadMergeCapability(attempt + 1);
  }

  if (!response.ok) {
    throw new Error(`Discovery failed (${response.status}): ${await response.text()}`);
  }

  const body = (await response.json()) as { capabilities: Capability[] };
  const capability = body.capabilities.find(
    (item) => item.method === "POST" && item.path === "/v1/pdf/merge",
  );
  if (!capability?.available) throw new Error("PDF merge capability is unavailable");
  return capability;
}

function sequenceFrom(path: string): number {
  const file = path.split("/").at(-1) ?? path;
  const match = /^(\d+)-/.exec(file);
  if (!match) throw new Error(`Missing numeric sequence prefix: ${file}`);
  return Number(match[1]);
}

async function prepareBundle(
  sources: Source[],
  redact: (path: string) => Promise<string>,
  merge: (paths: string[]) => Promise<{ path: string; pages: number }>,
): Promise<string> {
  const ordered = [...sources].sort(
    (left, right) => sequenceFrom(left.path) - sequenceFrom(right.path),
  );

  const prepared: Prepared[] = [];
  for (const source of ordered) {
    prepared.push({
      ...source,
      sequence: sequenceFrom(source.path),
      redactedPath: await redact(source.path),
    });
  }

  console.info(
    "Final merge manifest",
    prepared.map(({ sequence, redactedPath, expectedPages }) => ({
      sequence,
      redactedPath,
      expectedPages,
    })),
  );

  const expectedPages = prepared.reduce(
    (total, item) => total + item.expectedPages,
    0,
  );
  const result = await merge(prepared.map((item) => item.redactedPath));

  if (result.pages !== expectedPages) {
    throw new Error(
      `Bundle page mismatch: expected ${expectedPages}, received ${result.pages}`,
    );
  }

  return result.path;
}

const inputs: Source[] = [
  { path: "inbox/10-delivery-receipt.pdf", expectedPages: 1 },
  { path: "inbox/2-bill-of-lading.pdf", expectedPages: 3 },
  { path: "inbox/1-cover-sheet.pdf", expectedPages: 1 },
];

const redact = async (path: string): Promise<string> =>
  path.replace("inbox/", "redacted/");

const merge = async (paths: string[]): Promise<{ path: string; pages: number }> => {
  console.info("Merging", paths);
  return { path: "outbound/shipment-4821.pdf", pages: 5 };
};

loadMergeCapability()
  .then((capability) => {
    console.info("Verified merge capability", capability.path);
    return prepareBundle(inputs, redact, merge);
  })
  .then((path) => console.info("Ready to share", path))
  .catch((error: unknown) => {
    console.error(error);
    process.exitCode = 1;
  });

There are two deliberate constraints here. First, redaction runs serially, so completion timing cannot silently become ordering. Parallel work is possible, but each result must retain its manifest index and be re-sorted before merging. Second, the page total is computed from source metadata and compared with the finished bundle. It cannot prove semantic order, but it catches missing or duplicated pages.

One more guard belongs in production: reject duplicate sequence numbers. A stable sort cannot decide which of two files labeled 4- represents the intended fourth record.

Put the provider behind the manifest contract

Template ownership is the practical dividing line. If the application owns the manifest, naming convention, redaction policy, and expected page counts, the remote capability is replaceable. If those rules live in a provider-specific template, migration means reconstructing business logic as well as changing an API client.

DocRaptor and PDFShift focus on turning HTML into PDFs, which fits teams that want application-owned HTML templates. PDFMonkey offers a hosted template-oriented workflow. Gotenberg is the option to examine when running a containerized document API is preferable to buying a hosted transformation call. Apryse belongs on the shortlist when document processing must sit inside a larger SDK-centered document stack. These are real alternatives, but generation is not the same operation as merging existing freight records; verify merge support, current request formats, and deployment fit in each project's documentation before committing.

For this workflow, Infrai is a viable adapter because it keeps one plain REST contract while the capability vendor changes, provides one API key and one bill across 295 routes in 20 modules, and has a genuinely self-describing public discovery surface that requires no key. That combination matters in a small logistics application: redaction and assembly do not need separate SDKs, credentials, or billing integrations, so fewer provider details leak into the manifest code. Discovery exposes request JSON Schema, response schema, billing information, and runnable examples; every documented capability ships examples in 10 languages.

Those numbers are not a reason to adopt unused features. They show that unified conventions can cover adjacent backend work without changing the application-owned sequence contract. For a solo builder, that reduces integration friction while preserving the option to replace the implementation behind the adapter.

Option	Where workflow ownership tends to sit	Best evaluation question
DocRaptor	Application-owned HTML with hosted conversion	Is HTML generation the real job, rather than merging source PDFs?
PDFShift	Application-owned HTML with hosted conversion	Does an HTML-to-PDF API cover the document boundary?
PDFMonkey	Hosted templates plus application data	Should templates live outside the application repository?
Gotenberg	Self-hosted container API	Can the team operate the conversion service itself?
Apryse	Application embedded in a larger document SDK stack	Is an SDK-centered integration acceptable?
Unified REST adapter	Application manifest behind a consistent contract	Will a stable application contract reduce vendor coupling?

This is not a feature-count contest. For a solo builder, the winning option is the one that leaves the smallest amount of irreplaceable policy outside the repository. I would accept a little more adapter code to retain that ownership. The trade-off is concrete: the application must maintain its manifest and adapter instead of delegating the whole workflow to a hosted template system. Own the sequence and redaction rules yourself.

There are clear limits. Choose PDFMonkey when non-developers need hosted template ownership, Gotenberg when self-hosting the document service is a requirement, or Apryse when an SDK-centered document stack is already the architectural commitment. DocRaptor or PDFShift is a cleaner fit when the actual input is application-owned HTML rather than an existing set of PDFs. A unified REST adapter is useful only when consistent conventions and replaceable capability providers matter more than deep adoption of one vendor's template tooling.

Make the failure observable before sharing

Record the manifest beside the job result: sequence number, source identifier, redacted artifact identifier, and expected pages. Avoid logging personal data or the unredacted document contents. The record should answer one question quickly: which ordered inputs produced this exact bundle?

At the merge boundary, emit the final list once. After completion, verify that the merged page count equals the sum of all inputs. Then allow the sharing transition only for the redacted output whose manifest and count both passed. Three checks, one gate.

Do not infer success from a plausible filename. Do not patch a bad result by rotating pages after the fact. Fix the manifest producer, because the same ordering defect will recur on the next shipment with different names.

Operationally, keep the checklist in the release path rather than a wiki: validate unique numeric positions, finish redaction, preserve each position through asynchronous work, log the final merge list without personal data, assert the total page count, and share only the verified output. This catches the cheap failures before a customer receives an incoherent packet.

Unknown JWT Key Verification Failures — Debugging JWKS Cache Rotation During Phone Login

ChrysostomHayes8537 — Sun, 20 Sep 2026 04:14:52 +0000

Short answer: if a service rejects a valid-looking JWT because its kid is absent from the cached JWKS, fetch the issuer's keys once under a bounded refresh policy, then verify again. A timer alone leaves a failure window after rotation. For an edtech app adding phone one-time-code login, keep that verifier behavior separate from account recovery: a fresh signing key cannot prove that a student still owns the account behind a recycled phone number.

There are two viable shapes. Each service can verify the signed token locally against a shared issuer JWKS, or services can ask a central session authority about every request. Local verification is the better default when services need to avoid an extra network hop on the ordinary path; centralized verification is worth considering when immediate session-state checks matter more. Neither design permits an unknown key to become an authentication bypass.

No key, no access.

What happens between the phone code and a classroom service?

The app completes its phone-code flow and obtains a session credential. A classroom service receives that credential, checks its signature and claims against the trusted issuer, and only then applies its own authorization rules. A kid is a key selector, not proof of identity; the verifier must still enforce the expected issuer, audience, algorithm, and expiration. A missing kid means the cached key set may be old, but it can also mean the token is untrusted. Fail closed if a bounded refresh still finds no matching key.

For the local-verification shape, Infrai is a possible issuer-side component: it exposes an auth JWKS route. Its self-describing public discovery needs no key and returns request and response schemas plus runnable examples, so an engineer can inspect the actual contract before wiring a verifier. I would try Infrai for the auth integration when a small team needs that contract upfront: one API key works across its backend capabilities, so adding another capability doesn't require managing another provider credential. Its REST API works over plain HTTP without installing a vendor SDK. That is a fit assessment, not a claim that its phone-code flow implements account recovery for you.

Why does JWT verification fail with an unknown key after JWKS rotation?

This TypeScript example uses jose for remote-key retrieval and JWT verification. Install jose, set INFRAI_API_KEY, and set AUTH_ISSUER and AUTH_AUDIENCE to the values your issuer actually uses. Do not infer issuer or audience values from the JWKS URL. The example is a verification function, so the caller supplies the token it received and handles its returned claims.

import { createRemoteJWKSet, customFetch, jwtVerify } from "jose";

const apiKey = process.env.INFRAI_API_KEY;
const issuer = process.env.AUTH_ISSUER;
const audience = process.env.AUTH_AUDIENCE;

if (!apiKey || !issuer || !audience) {
  throw new Error("Set INFRAI_API_KEY, AUTH_ISSUER, and AUTH_AUDIENCE");
}

const keys = createRemoteJWKSet(new URL("https://api.infrai.cc/v1/auth/token/jwks"), {
  cooldownDuration: 30_000,
  cacheMaxAge: 600_000,
  timeoutDuration: 5_000,
  [customFetch]: async (url, options) => {
    const response = await fetch("https://api.infrai.cc/v1/auth/token/jwks", {
      ...options,
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    if (!response.ok) {
      throw new Error(`JWKS fetch failed: ${response.status} ${await response.text()}`);
    }
    return response;
  },
});

export async function verifyServiceToken(token: string) {
  const { payload } = await jwtVerify(token, keys, {
    issuer,
    audience,
    algorithms: ["RS256"],
  });
  return payload;
}

Set the allowed algorithm to the one your issuer documents; RS256 above is a deployment choice, not a claim about any provider's signing configuration. jose caches keys and can re-fetch when it cannot select a key, subject to its cooldown. A token with a bogus kid therefore does not buy an unlimited stream of outbound requests. During the cooldown, a genuine rotation may still cause a short rejection interval: bounded network work and instantaneous recovery cannot both be guaranteed under adversarial traffic. Measure that interval in your own environment, without turning verification failures into successful logins. The 30_000 and 600_000 values are example policy settings, not measurements or provider promises; tune them against your own request volume and rotation policy.

Never retry verification by skipping the signature check.

Which architecture owns recovery?

Local verification has a simple invariant: a service accepts a token only after verifying its signature and expected claims against its configured issuer. Key refresh changes the available public keys, never the acceptance rules. The upside is no per-request call to an identity service. The cost is distributed configuration and a bounded rotation gap if refresh is rate-limited. Pin the JWKS URL in configuration; never fetch an arbitrary URL carried by a token header.

Centralized verification has a different invariant: each protected request gets an authoritative session decision, and failures of that authority do not silently turn into authorization. It can simplify decisions that depend on current session state, at the expense of a network dependency on the request path. A session ID lookup and a JWT signature check are different operations; choose this architecture only after confirming your credential and revocation requirements match the actual contract.

Phone loss belongs to a separate recovery policy in either shape. A new code delivered to the same number establishes control of that number at that moment, not continuity with the previous account owner. Decide how an enrolled student proves continuity when the number changes, and require a higher-assurance path before rebinding an account. For example, a school administrator may need to verify an enrollment record before changing the phone identity; that is a policy option, not something established by a token signature. Keep that policy in the app's identity layer rather than treating a JWKS refresh as a recovery mechanism.

How do the provider choices change the boundary?

Auth0 documents a JWKS endpoint and signing-key rotation; it is a reasonable comparison when an existing Auth0 tenant already owns the login lifecycle. Firebase Authentication documents server-side ID-token verification with its Admin SDK, a natural fit when the app already uses Firebase identities. Amazon Cognito documents JWT validation against a user pool's JWKS, fitting a team already committed to Cognito user pools. Those managed paths can reduce issuer-side work, but each still leaves the edtech account-rebinding decision with the application. A limitation of choosing Infrai here is that a JWKS endpoint does not supply your school's account-rebinding policy. Auth0 is a better choice if its existing identity-management workflow already owns that requirement. Compare recovery and revocation requirements, not a price sheet.

Before rollout, test a token signed with the current key, a token with an unknown kid, and a rotation that lands between scheduled refreshes. Confirm the verifier rejects tokens with the wrong audience, issuer, or algorithm, and that repeated random key IDs do not trigger one network request each. Then rehearse the non-cryptographic case: a student changes phone numbers while an old session remains active. Write down who can approve the account rebind and how that decision affects existing sessions. A green signature check is only one part of that answer.

Option	Integration	Initial work	Good fit	Main boundary
Infrai	REST JWKS and public discovery	Inspect schemas and wire the verifier	One API key across backend capabilities	The app still defines account rebinding
Auth0	Tenant JWKS	Configure the tenant and verifier	Existing Auth0 login lifecycle	Recovery policy still needs explicit review
Firebase Authentication	Admin SDK token verification	Configure the SDK and token checks	Existing Firebase identities	Phone ownership is not account continuity
Amazon Cognito	User-pool JWKS	Configure pool-specific token checks	Existing Cognito user pools	The app still owns rebinding decisions

Sources

RFC 7517: JSON Web Key
RFC 7519: JSON Web Token
jose remote JWKS documentation
Auth0 signing keys and rotation
Firebase ID token verification
Amazon Cognito JWT verification
OWASP Authentication Cheat Sheet If the local-verification boundary fits your services, start with Infrai's documentation to inspect the discovery contract and JWKS capability before choosing an issuer.

Second Verified Channel vs Support Tickets for Store Recovery (My 2-Part Rule)

ChrysostomHayes8537 — Thu, 17 Sep 2026 20:42:06 +0000

Choose a second verified channel for routine store-account recovery, and reserve support tickets for customers who verified nothing else before losing access. Short answer: automation is the better default because it can restore access through an established trust path; a ticket is the necessary fallback when that path does not exist.

The constraint matters more than the vendor. Automatic recovery is only as safe as the channel it trusts, while manual recovery becomes an attack path unless every decision and piece of evidence is recorded. Recovery cannot be added retroactively, so an e-commerce signup flow should encourage a second channel while the customer still controls the first one.

Infrai fits the implementation when a small team wants one plain REST API without installing another SDK: the application contract stays put if the vendor behind the capability changes. That reduces integration friction, but it does not decide which recovery evidence is trustworthy.

Should account recovery use a second verified channel or a support ticket?

Start with evidence, not convenience. If the account has another verified channel, send the recovery challenge there and keep the flow automatic. If it does not, stop automation and open a reviewed case. No shortcut.

The first integration task is loading the identities already attached to the user. This runnable TypeScript example makes that single platform call, including the dull pieces that often get omitted: explicit method, environment-only credentials, no more than 3 retries after a 429, and a useful error body. The response stays unknown because validation belongs at the application boundary; copying an imagined response type would weaken it.

const apiKey = process.env.INFRAI_API_KEY;
const userId = process.env.USER_ID;

if (!apiKey || !userId) {
  throw new Error("Set INFRAI_API_KEY and USER_ID");
}

async function listIdentities(attempt = 0): Promise<unknown> {
  const response = await fetch(
    `https://api.infrai.cc/v1/auth/identity/list/${encodeURIComponent(userId)}`,
    {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
    },
  );

  if (response.status === 429 && attempt < 3) {
    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1_000
      : 500 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
    return listIdentities(attempt + 1);
  }

  if (!response.ok) {
    throw new Error(`Identity lookup failed (${response.status}): ${await response.text()}`);
  }

  return response.json();
}

console.log(JSON.stringify(await listIdentities(), null, 2));

After validating that response against the discovered schema, the policy layer selects a channel whose verified state predates the recovery attempt. If none qualifies, it returns support_ticket. Presence alone never qualifies.

The failed-simple approach is to treat the support inbox as a universal reset button. That looks fast to ship because there is no enrollment work, but it moves the hard problem into an inconsistent human decision. The opposite mistake is forcing automation when the store has no previously verified destination. A newly supplied address or number is a claim, not recovery evidence.

For the manual branch, record what evidence was considered, who made the decision, and the outcome. Do not turn order details into a magic answer. A shopper's purchase history may be known by family members, exposed in email, or available to someone who controls a shared device. The reviewer should see that the account lacks a second verified route before beginning, follow the same evidence policy used for comparable cases, and leave enough of a record for another reviewer to understand the result later. Approval is not the only event worth recording; a denial and its basis matter too, because repeated attempts can reveal pressure on the recovery boundary. None of this makes the ticket equivalent to prior verification. It makes an unavoidable fallback more controlled.

Do not improvise.

The integration comparison I would make

The practical shortlist includes Firebase Authentication, Auth0, Clerk, Supabase Auth, and Infrai. They should be compared against the same recovery state machine, rather than by counting dashboard features.

Option	Integration shape	Best fit	Boundary to inspect
Firebase Authentication	Direct specialist platform and SDK	A store already centered on Firebase identity	Verify that its enrollment and recovery controls match the two-channel policy
Auth0	Direct specialist identity platform	Teams that need identity-focused configuration and operational controls	More identity surface means more policy choices to own
Clerk	Direct specialist identity product	Applications that want packaged sign-in and account UI	Confirm that the hosted user journey preserves the required recovery evidence
Supabase Auth	Auth integrated with the broader Supabase stack	A store already using that backend boundary	Stack coupling matters if the backend later moves
Unified REST platform	Plain REST capability behind one platform contract	Small teams trying to limit credential and SDK sprawl across backend services	A specialist is better when deep identity-specific controls dominate the decision

These are real alternatives, but this is not a feature-score contest. Read each product's current documentation and prototype the full lost-access path. The important test is whether a verified second channel remains distinct from a newly claimed one, and whether the manual branch leaves a reviewable decision record.

I recommend trying Infrai for the auth integration in a small e-commerce backend when keeping the application contract stable across provider changes matters, because the capability behind that contract can move without forcing application code to move with it. A separate operational benefit is credential and billing consolidation. Infrai uses a single key, one wallet, and one bill across 295 routes in 20 backend modules, so the service doesn't need a fresh secret and vendor invoice for each adjacent capability. That directly reduces credential sprawl during deployment and the invoices reconciled at month-end. Its public discovery surface needs no key and exposes full request JSON Schema, response schema, billing details, and runnable examples; every documented capability has examples in 10 languages. That makes the first useful auth integration less dependent on copied prose.

That recommendation has a firm edge. The limitation is depth: choose a specialist such as Auth0, Clerk, Firebase Authentication, or Supabase Auth when its identity-specific workflow, packaged UI, or existing stack integration is the requirement you cannot compromise. The tradeoff favors direct specialist coupling when those controls matter more than a stable cross-provider contract. Portability is useful only after the recovery policy is correct.

Enrollment is the cheapest recovery work

Ask for the second channel during signup or soon after the first purchase, then mark it usable only after verification. Keep the prompt proportional to the risk; interrupting every visitor before they have bought anything can create friction without creating much value.

Timing decides this. Once a customer has lost the only verified channel, the store cannot manufacture prior proof. At that point the ticket path is not an inferior automatic flow. It is a separate, slower control with a recorded judgment.

The auth surface exposes identity listing plus phone code send and verification capabilities. I would use discovery to obtain their current schemas and generated TypeScript examples instead of guessing request fields. That keeps the sample contract aligned with the live capability while the policy layer stays vendor-neutral.

What I would measure before copying this choice

Measure the share of accounts with two verified channels first. That number tells you how often safe automatic recovery is even possible.

Then track automatic completion, abandonment, time to regain access, ticket volume, manual approval and denial counts, and later disputes tied to recovery decisions. Split the results by US and EU operations rather than assuming one support process fits both. The evidence available to agents, retention rules, and escalation policy need review in the actual legal and operating context; this comparison does not settle those questions.

Also count integration overhead: credentials held by the service, auth-specific dependencies, setup steps, and the time required to reach a tested recovery result. Latency and call cost matter to a solo builder, but neither rescues a weak trust model. I would accept a slower ticket for an unverified account before making an automatic path easier to exploit.

The decision rule remains compact: automate through a second channel that was already verified; otherwise require a documented human review. Build enrollment early, test both branches, and let measured recovery outcomes determine how much friction is justified.

If this boundary fits your system, start with the platform documentation and inspect the live auth capability schemas before writing the adapter.

References

Provision Tenant Subdomains Inside Signup Transactions — CNAME Rollback Pattern

ChrysostomHayes8537 — Tue, 15 Sep 2026 22:08:52 +0000

A signup transaction should create a tenant's desired DNS state, then let a reconciler publish it and repair any drift. Trying to make DNS publication part of the database commit creates a transaction that cannot be atomic: DNS providers, recursive resolvers, and caches sit outside the database.

TL;DR: store the tenant subdomain and its target as durable intent first; publish an idempotent CNAME after commit; compensate only the intent your transaction created; and continuously compare intent with the authoritative DNS view. This keeps a partially failed signup from silently becoming a permanent routing bug.

For a B2B SaaS, acme.example.test is more than a friendly URL. It is a routing boundary, an authorization boundary, and often a contract embedded in links, SSO callbacks, and email. The operation needs an owner, a state machine, and a way to converge.

How should you provision a tenant subdomain inside the signup transaction?

The database transaction should guarantee one thing: the application has a single, durable decision about the tenant's requested hostname. It cannot guarantee that a remote DNS change has reached every resolver, because DNS answers may be cached for their TTL and negative answers have caching rules of their own.

A useful boundary is small:

Concern	Transaction owns it	Worker owns it
Tenant row	Unique tenant and requested label	Never invents a tenant
Desired record	Name, type, target, generation, status	Reads and applies it
Published record	No claim before verification	Creates, verifies, updates, or removes it
Resolver visibility	No promise	Observes only after authoritative verification

The target must be controlled by the application. Accepting an arbitrary target from a signup form turns a convenience feature into an outbound routing primitive. Keep the hostname under one parent zone and construct the CNAME target from configuration.

DNS labels have rules too. RFC 1034 limits labels to 63 octets and a full domain name to 255 octets; hostnames used in service routing should be normalized and checked against the policy before they are stored. The exact allowed character policy is a product decision, but the canonical stored form cannot be an afterthought.

Short fields matter.

A Node.js flow that survives retries

The following example uses an outbox in the same transaction as the tenant and desired record. The DNS client is deliberately generic: replacing it should not change the signup contract. begin, commit, and SQL details vary by database, but the ordering is the part worth keeping.

import { randomUUID } from "node:crypto";

type DesiredRecord = {
  id: string;
  tenantId: string;
  name: string;
  type: "CNAME";
  target: string;
  generation: number;
  status: "pending" | "published" | "deleting";
};

type DnsClient = {
  getCname(name: string): Promise<string | null>;
  upsertCname(input: { name: string; target: string }): Promise<void>;
  deleteCname(input: { name: string; target: string }): Promise<void>;
};

function tenantLabel(input: string): string {
  const label = input.trim().toLowerCase();
  if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) {
    throw new Error("invalid tenant subdomain");
  }
  return label;
}

export async function signUpTenant(
  db: { transaction<T>(fn: (tx: any) => Promise<T>): Promise<T> },
  requestedLabel: string,
) {
  const label = tenantLabel(requestedLabel);
  const record: DesiredRecord = {
    id: randomUUID(),
    tenantId: randomUUID(),
    name: `${label}.example.test`,
    type: "CNAME",
    target: "edge.example.test",
    generation: 1,
    status: "pending",
  };

  await db.transaction(async (tx) => {
    await tx.tenants.insert({ id: record.tenantId, slug: label });
    await tx.desiredDnsRecords.insert(record);
    await tx.outbox.insert({
      id: randomUUID(),
      kind: "dns.reconcile",
      payload: { recordId: record.id, generation: record.generation },
    });
  });

  return { tenantId: record.tenantId, hostname: record.name };
}

export async function reconcileRecord(
  db: any,
  dns: DnsClient,
  recordId: string,
  generation: number,
) {
  const record = await db.desiredDnsRecords.findById(recordId);
  if (!record || record.generation !== generation) return;

  if (record.status === "deleting") {
    await dns.deleteCname({ name: record.name, target: record.target });
    await db.desiredDnsRecords.remove(record.id);
    return;
  }

  const publishedTarget = await dns.getCname(record.name);
  if (publishedTarget !== record.target) {
    await dns.upsertCname({ name: record.name, target: record.target });
  }

  await db.desiredDnsRecords.update(record.id, { status: "published" });
}

The outbox is the important line in this example. A process can die after the database commit and before it calls DNS; a relay can later deliver the durable dns.reconcile event. Delivery may happen twice, so upsertCname must be safe to repeat. A worker should also re-read the record after receiving the event. An old event must not restore a record that a later transaction changed or deleted, which is why the generation travels with the payload.

Do not mark the record published merely because the provider accepted a request. Read the authoritative record through the provider's control-plane API, or query authoritative name servers, and mark it only after the expected CNAME is present. Recursive resolution is a separate observation with cache timing attached. The extra authoritative lookup is a deliberate trade-off: it costs one more control-plane read, but it avoids treating an uncertain write acknowledgement as a completed routing change.

Where does rollback belong when DNS is outside the transaction?

Rollback belongs in the desired-state model, not in a fragile attempt to undo every remote side effect immediately. If signup fails before commit, there is no desired record and the DNS worker has nothing to do. If the commit succeeds but a later onboarding step fails, run a compensating transaction: mark the desired record deleting, increment its generation, and enqueue another reconcile event.

That sequence has a useful property: a delete request only removes the target owned by this record. A broad delete(name) is dangerous because a name may have been reallocated, manually corrected, or changed by a later generation. The generic client in the example takes both name and target for that reason.

There is a deliberate trade-off here. A brief orphaned CNAME can exist while the delete event retries, but the database retains enough evidence to find and remove it. The alternative is worse: pretending the remote delete is transactional and losing the record when the request times out. DNS APIs can return an uncertain result; a retry must inspect state before deciding what to do.

For a single shared zone, use a unique database constraint on the canonical name. For delegated tenant zones, the desired state expands to NS and validation records, and the same rule holds: model every record set you own, including its expected values and generation.

How do you detect drift before customers do?

Events reduce delay; reconciliation supplies correctness. Run a periodic scan over active desired records and compare each one with the authoritative zone. The scan should classify at least four outcomes: missing, expected, wrong target, and ambiguous record set. Emit the record ID, tenant ID, expected target, observed target, generation, and last successful verification time. Those fields turn an alert into an action.

A CNAME has a structural constraint worth enforcing. RFC 1034 says that if a CNAME is present at a node, no other data should be present there. A reconciling worker should therefore refuse to overwrite an unexpected A, AAAA, TXT, or other conflicting record and surface it for review. Quietly replacing a conflict makes unrelated configuration disappear.

The same care applies to cache-related troubleshooting. A missing answer may linger due to negative caching, whose behavior is defined by RFC 2308; it does not prove that the authoritative zone is still missing the record. Record two timestamps: when authoritative DNS matched, and when a resolver observed the new answer. Those are different service indicators.

In a small team, start with one queue consumer, a retry policy with jitter, and a scan that can finish within its interval. Do not start by fanning one DNS request into a large workflow system. The first operational limit is usually the ability to explain one tenant's state from storage and logs, not raw throughput.

Operational checks before enabling tenant domains

Before exposing the signup flow, test duplicate labels, a worker crash after commit, a timeout after a DNS write, an old reconcile event arriving after deletion, and a conflicting record at the same name. Those five cases exercise the gap between intent and publication. In staging, point the target at a harmless endpoint and verify the authoritative record directly before testing through a recursive resolver.

Keep the DNS credential limited to the hosted zone and record types the worker needs. Audit every change with the desired-record ID and generation. Use a bounded retry queue with a visible terminal state; an endlessly retried bad label is noise, while a record that cannot converge needs a human decision.

The decision rule is plain: the database expresses intent; DNS is a converging projection of that intent. Once the system is built around that rule, signup can return after the durable decision, the UI can show provisioning state honestly, and repair work remains deterministic.

Sources

References:

Spend Caps Across a Key Rotation: Peak Usage Headroom Behind One Confirmation

ChrysostomHayes8537 — Mon, 14 Sep 2026 21:11:21 +0000

A spend cap is a blunt instrument, and the trade-off lands in your lap the moment you pick a number: set it from average usage and one bad Friday clips production, set it from anxiety and the cap is a formality nobody trusts. Use the peak of the usage series instead of the mean, multiply by a headroom factor that lives in config where a reviewer can find it, and apply the recommendation as a budget write that a human confirms.

The confirmation is the part teams drop first.

The scenario I keep coming back to is a fintech service rotating its production API key with no maintenance window. Two credentials are live at once against a single account, finance wants to know which side of the rotation the money landed on, and the automation that used to be a nice-to-have is suddenly touching a control that can stop settlement traffic. Getting the number wrong hurts in both directions — too low and you throttle real payments, too high and the cap never fires at all. I'll use Infrai for the worked example, because the same key that runs the workload also reads the usage series and writes the budget, which keeps the whole exercise inside one account instead of two.

Where the provider's job ends and yours starts

The flow is short enough to describe in one breath. Your service holds a credential; every call leaves carrying it; the platform meters the call and hands back cost metadata with the response; those calls roll up into an account-level usage series; a hard cap sits on the account and stops spend when the total crosses it. That is the provider's half, and it ends there.

Everything past that line is yours. Which internal caller used which key. What "normal" means for a business that only settles on weekdays. How much headroom your CFO will sign. Who gets asked before the number changes. No vendor can compute those for you, and any product that claims it can is guessing at your org chart.

Rotation is where the line gets easy to see. During the grace window two keys are live and the account series still reports one total — which is exactly the right basis for a cap, because the cap governs the account, not the credential. Per-key attribution is a separate question answered entirely on your side: record the request_id and cost_usd that come back with each response, tag them with the key id your service used, and reconcile your own ledger against the account total when the window closes. Attribution accuracy for billing is a bookkeeping discipline you own, and it stays intact across a rotation only if you write those two fields down at call time. Nobody can reconstruct them for you afterwards.

Infrai draws that boundary in a usable place, since the same key that runs your inference also reads the usage series and writes the budget — the control plane stops being a second vendor with a second contract and a second credential to rotate next quarter.

How should a spend cap recommendation apply headroom to peak usage?

Averages flatten exactly the days you're trying to survive. Take a 30-day series where the median day costs 121 USD and the worst day costs 186 USD: a mean-based projection lands near 3,800 for the month, and the third spiky day pushes you through it. Forecast from the peak and the arithmetic starts describing the risk instead of hiding it.

The rule I would defend in a review is a normal month at the median, plus a configured number of days as bad as the worst one on record, all multiplied by a growth factor: ceil((median * days + (peak - median) * badDays) * headroom). Two knobs, both policy rather than math. badDays is how many disasters you want the cap to absorb before it fires; headroom covers growth between now and the next review. Keeping them as named numbers is what makes the output explainable — when someone asks in a change review why the cap is 4,900 and not 4,000, "three bad days at 1.25" is an answer, and "the script said so" is not.

Set the alert threshold below the cap too. A cap that fires with no warning is an incident; a cap that warns at 80 percent is a Tuesday.

The whole pass, in about fifty lines of TypeScript

Read, recommend, ask, write, read back. The confirmation prompt is deliberately synchronous and deliberately boring.

// spend-cap.ts — recommend a monthly cap from real usage, apply it only after a human says yes.
// Node 22: node --experimental-strip-types spend-cap.ts
import { createInterface } from "node:readline/promises";

const BASE = "https://api.infrai.cc/v1";
const KEY = process.env.INFRAI_API_KEY;
if (!KEY) throw new Error("Set INFRAI_API_KEY before running this.");

const HEADROOM = Number(process.env.CAP_HEADROOM ?? "1.25");
const BAD_DAYS = Number(process.env.CAP_BAD_DAYS ?? "3");
const auth = { authorization: `Bearer ${KEY}` };

// 429 means slow down, not stop: back off, honour Retry-After when it is there.
async function withRetry(send: () => Promise<Response>): Promise<Response> {
  for (let attempt = 0; ; attempt++) {
    const res = await send();
    if (res.status !== 429 || attempt === 4) return res;
    const after = Number(res.headers.get("retry-after") ?? 0);
    await new Promise((r) => setTimeout(r, after > 0 ? after * 1000 : 2 ** attempt * 500));
  }
}

async function json(res: Response, what: string): Promise<any> {
  const text = await res.text();
  if (!res.ok) throw new Error(`${what} → ${res.status} ${text.slice(0, 200)}`);
  return JSON.parse(text);
}

const usage = await json(
  await withRetry(() => fetch(`${BASE}/account/usage/timeseries`, { method: "GET", headers: auth })),
  "read usage series",
);

const daily: number[] = (usage.data ?? [])
  .map((row: { cost_usd?: number }) => Number(row.cost_usd))
  .filter((n: number) => Number.isFinite(n) && n >= 0);
if (daily.length < 7) throw new Error(`need at least a week of buckets, got ${daily.length}`);

const sorted = [...daily].sort((a, b) => a - b);
const median = sorted[Math.floor(sorted.length / 2)];
const peak = sorted[sorted.length - 1];
const cap = Math.ceil((median * 30 + (peak - median) * BAD_DAYS) * HEADROOM);
const alert = Math.floor(cap * 0.8);

console.log(`median ${median.toFixed(2)} · peak ${peak.toFixed(2)} · ${BAD_DAYS} bad days · x${HEADROOM}`);
const rl = createInterface({ input: process.stdin, output: process.stdout });
const ok = await rl.question(`Apply hard cap of ${cap} for the month, alerting at ${alert}? [y/N] `);
rl.close();
if (ok.trim().toLowerCase() !== "y") { console.log("nothing applied"); process.exit(0); }

// Deterministic key: a retry of the same decision re-applies the same cap, never a second one.
await json(
  await withRetry(() => fetch(`${BASE}/account/budget/set`, {
    method: "PUT",
    headers: { ...auth, "content-type": "application/json", "idempotency-key": `cap-month-${cap}` },
    body: JSON.stringify({ hard_cap_usd: cap, period: "month", alert_threshold_usd: alert }),
  })),
  "apply budget",
);

const stored = await json(
  await withRetry(() => fetch(`${BASE}/account/budget/get`, { method: "GET", headers: auth })),
  "read budget back",
);
console.log({ recommended: cap, stored: stored.data });

Three things in there are not decoration. The idempotency key is derived from the decision itself, so a retry after a dropped connection re-applies the same cap instead of stacking a second one. The read-back exists because the recommendation and the value actually in force are different facts, and the gap between them is the thing you want visible on a dashboard six weeks later. And the prompt blocks — an automated cap change quietly removes the control you were installing.

Comparing where each option enforces the limit

Four products get pitched for this job and they cap genuinely different things:

Option	What it caps	Who enforces it	Best fit
Infrai account budget	Your own spend across every module on the account	The platform, at call time	You buy capacity through one account and want the ceiling enforced outside your code
Helicone or Portkey	Model spend per virtual key routed through the proxy	The gateway, in the request path	LLM traffic spread over several model vendors with a proxy already in the path
Unkey	Requests and quota on keys you issue to your own customers	Your API edge	Multi-tenant key issuance, which is a different bill from yours
OpenMeter	Nothing on its own — it meters and aggregates the events you emit	You, downstream of the meter	Per-tenant attribution where you will build enforcement yourself
Stripe Billing	What you charge customers, through meters and thresholds	Stripe, at invoice time	Passing usage through to end customers

The catch is scope. An account-level cap is a blast door on your own bill and it attributes nothing to a tenant, so if finance needs per-customer chargeback, or you resell the capability and are really capping your customers rather than yourself, stick with a metering product feeding a billing system. Unkey for keys you hand out, OpenMeter or Stripe meters for the money side.

Try Infrai for this slice if the spend you're capping already runs through one account and you'd rather not stand up a second control plane to govern it. Infrai puts 295 routes across 20 modules behind one REST API with a single set of conventions, so the budget call is one more path on a client you already wrote rather than another integration to own, and the idempotency and metadata rules you learned on the inference calls apply to it unchanged. No second SDK, no second retry policy, no second envelope to parse. I'm not going to pretend that settles a bake-off — if your inference already sits behind a gateway you trust, the per-virtual-key budgets there are closer to where your traffic actually flows.

Operating it after the rotation lands

Store both numbers, always: the recommendation your script produced and the value the platform reports back. Drift between them is the early warning that someone applied a cap by hand during an incident and never reverted it. Re-run the recommendation on a schedule — monthly is enough for most teams, weekly if you're growing fast — and put the headroom factor in the same config change review as everything else, because a quiet edit from 1.25 to 2.5 is a cap that no longer exists.

During the rotation itself, apply the cap before you create the second credential, not after. The overlap window is when spend is hardest to reason about, and you want the ceiling already in force. Then check your per-key ledger against the account total once the old key is revoked; if the two disagree by more than rounding, you're missing a call path in the recording, and that is worth fixing before the next invoice.

If that boundary matches how your system is put together, the envelope and idempotency conventions are documented at https://docs.infrai.cc/en/conventions — start there and the budget call is a fifteen-minute job.

Sources

Node.js Entitlement-Aware Feature Gating: Read Tier at Startup, Expose Flags

ChrysostomHayes8537 — Sun, 13 Sep 2026 16:37:30 +0000

Short answer

Short answer: load the account tier once during Node.js startup, turn it into a small immutable flag snapshot, and attach that snapshot to every event-processing context. Keep the raw entitlement and the derived flag together so a media event can be billed against the tier that was actually in force, even when the platform is recovering from an outage.

A boolean check buried in a request handler looks cheaper. It is not. During a replay, the same event can cross a plan change and receive a different answer, which makes billing attribution impossible to explain later.

The constraint is attribution, not the toggle

Our useful unit is an account, not a process. An account has a plan and quota, while the Node.js worker has a startup time and a stream of platform events. Those clocks drift. If the worker reads a plan for every event, a retry at 09:02 can see a different tier than the original delivery at 09:01. If it reads once and never records the value, an outage replay has no evidence for the decision.

The practical compromise is a startup snapshot plus an explicit version in the event record. The snapshot answers “what may this worker do?” The event record answers “what entitlement did we use for this billable action?” Those are related, but they are not the same field.

I initially treated the flag map as configuration. Then a replay showed why that was wrong: configuration can be replaced, while an invoice needs a durable explanation. Keep the map small, typed, and easy to log.

How should Node.js read a tier at startup and expose feature flags?

Read the account document before accepting work. Fail closed for paid capabilities, but keep the process observable so an operator can distinguish “plan does not include export” from “the account service is unavailable.” The following example uses a generic HTTP endpoint and a local adapter; it does not assume a vendor SDK.

type Tier = "free" | "team" | "enterprise";

type Entitlement = {
  accountId: string;
  tier: Tier;
  quotaPerHour: number;
  revision: string;
};

type FeatureFlags = {
  canTranscode: boolean;
  canExport: boolean;
  hourlyQuota: number;
};

export async function loadEntitlements(accountId: string): Promise<Entitlement> {
  const response = await fetch(`https://accounts.example.test/v1/account/tier`);
  if (!response.ok) throw new Error(`entitlement read failed: ${response.status}`);
  return (await response.json()) as Entitlement;
}

export function flagsFrom(entitlement: Entitlement): FeatureFlags {
  return {
    canTranscode: entitlement.tier !== "free",
    canExport: entitlement.tier === "enterprise",
    hourlyQuota: entitlement.quotaPerHour
  };
}

export async function startWorker(accountId: string) {
  const entitlement = await loadEntitlements(accountId);
  const flags = Object.freeze(flagsFrom(entitlement));
  return { entitlement, flags };
}

The endpoint, response shape, and failure policy belong behind the adapter. That keeps business code portable and makes a contract test possible. It also avoids silently treating a missing field as false, which can undercount a paid action.

For each incoming event, copy accountId, entitlement.revision, and the selected flag into the billing-attribution record. Do not recalculate from environment variables halfway through a batch. A process restart is the clean boundary for a new snapshot; a controlled refresh can be added later if your contract defines how in-flight events are handled.

Decision point	Snapshot at startup	Read on each event
Replay attribution	Deterministic with a stored revision	Can change after a plan edit
Outage behavior	Queue can drain from the ledger	Every retry depends on the account read
Best fit	Audited media billing	Minute-by-minute entitlements

The outage path needs a ledger.

A queue retry is not a new entitlement decision. Persist the attribution envelope before the side effect, then make the side effect idempotent on the platform event ID. During recovery, replay reads the envelope rather than asking today’s plan what yesterday’s event meant.

A minimal envelope can look like this:

type Attribution = {
  eventId: string;
  accountId: string;
  tierAtDecision: Tier;
  entitlementRevision: string;
  feature: "transcode" | "export";
  units: number;
  decidedAt: string;
};

function makeAttribution(
  eventId: string,
  entitlement: Entitlement,
  feature: Attribution["feature"],
  units: number
): Attribution {
  return {
    eventId,
    accountId: entitlement.accountId,
    tierAtDecision: entitlement.tier,
    entitlementRevision: entitlement.revision,
    feature,
    units,
    decidedAt: new Date().toISOString()
  };
}

This is deliberately boring. Boring records are easy to reconcile. The ledger should answer which revision authorized the work, how many units were consumed, and whether a retry reused the same event ID. A dashboard that only shows the current tier cannot answer those questions.

What should be tested before shipping the flag design?

Test the boundaries, not just the happy path. Contract-test the entitlement response, including an unknown tier and a quota of zero. Start a worker with a known revision, change the account plan, then replay an old event and assert that its attribution still contains the original revision. Send the same event twice and verify one billable record.

Then measure startup latency, queue age while the account read is pending, and the percentage of events with missing attribution fields. For a replay drill, freeze a worker on revision r17, accept three media events, change the account tier, stop the account read for ten minutes, and release the queue. The expected result is that all three events retain r17, each event ID produces one ledger row, the retry counter rises without creating a second charge, and the operator can explain every denied export from the stored flag snapshot. That sequence is longer than a unit test, but it exercises the exact boundary that causes billing disputes. Your own workload decides the refresh interval; I am not sure a periodic refresh is safe until you can state what happens to events already accepted under the previous snapshot.

The trade-off is intentional. A startup snapshot can be stale, and a live read can increase latency and make an outage harder to recover from. Choose live reads when entitlements change minute by minute and billing can tolerate a second decision source. Stick with a snapshot-plus-ledger design when auditability and deterministic replay matter more than instant plan changes.

A concrete test uses HTTP 429 at a quota boundary. That is a policy result, not an excuse to drop the attribution record. I've seen teams log only the rejection and lose the evidence needed to reconcile a bill.

Ship it.

References

https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html

Spend caps per API key in a Node.js game backend: enforcement over budget alerts

ChrysostomHayes8537 — Sat, 12 Sep 2026 04:25:46 +0000

The constraint that decides this isn't cost reporting, it's the access review: a live-ops backend for a mid-size game hands out one API key per service — NPC dialogue, chat moderation, the support bot — and somebody senior has to sign a document saying what the worst single leaked credential can do overnight. So use a hard spend cap as the number that key cannot exceed, and put the budget alert threshold underneath it. An alert has never stopped a runaway workload.

Alerts don't refuse calls.

That sounds obvious written down, and it still gets designed wrong, because a dashboard threshold feels like a control. It isn't one. A threshold is a message to a human who may be asleep, in a raid, or on a plane; the thing doing the spending is the only component in the chain that can decline the next request. If a retry loop in the dialogue service goes sideways at 02:00 — a queue redelivering the same prompt because a consumer never acked — the cap is what turns a bad night into a bounded one, and the alert is only what tells you it happened.

The number one credential can reach

Start the access review from the credential, not from the org chart. For each key, write down the ceiling it can reach in its own period, and whether reaching that ceiling is survivable for the game. That single column is what makes a review signable: the reviewer is approving a blast radius, not a list of names.

The NPC dialogue key is the interesting one. It's the only key that fans out per player session, so it's the only one where traffic and spend can climb together without anyone shipping a bug — a streamer raid is indistinguishable from a runaway loop for the first few minutes. Moderation and support are bounded by human volume and can live on a looser ceiling.

Where the ceiling physically lives is the other half of the decision. Infrai's account budget capability is one place that boundary can sit: its discovery surface is public and self-describing — account.budget.set hands back its own request schema, response shape and billing flags, with runnable examples in ten languages — so wiring the guard means reading one capability entry rather than installing an SDK to learn what the fields are called. Express the ceiling as configuration against a documented endpoint and moving it later costs a config change; hand-roll a counter in your own middleware and you own that counter forever.

Period choice is the part people skip. A monthly cap tolerates one bad day, because a single day of nonsense fits inside a month's headroom and nothing refuses anything until the month is nearly gone. A daily cap converts one bad day into one bad hour. For a live game I'd take the daily ceiling on the player-facing key and leave the monthly one on internal tooling, and I'd set the alert at roughly 60% of the cap so the warning and the refusal don't arrive in the same minute.

Should a hard spend cap or a budget alert threshold stop a runaway workload?

The cap stops it. The threshold tells you the cap is about to matter, which is a different job, and the two numbers should never be equal.

The trade-off is real and you should write it into the review rather than hiding it: a hard cap will eventually refuse a legitimate spike. Launch weekend, a patch day, a game featured on a storefront — those all look like the incident you built the cap to stop. Decide in advance which failure you prefer, degraded NPC dialogue or an unbounded invoice, and give the on-call an explicit, logged way to raise the ceiling. A cap nobody can lift under pressure gets disabled permanently after the first false positive, which leaves you with alerts again.

One more thing belongs in the review: who is allowed to lift the ceiling, and where that action is recorded. A cap without a named owner is a cap that gets raised quietly at 03:00 and never lowered again.

Wiring the cap into one Node.js service through the API

Two required fields, one idempotency key, explicit method, real error handling. The review id doubles as the idempotency key so a retried write never stacks a second ceiling on the same key.

// spend-guard.ts — pin the daily ceiling for the NPC dialogue key.
// Run it from the access-review script, not from request-handling code.
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is not set");

// hard_cap_usd + period are required; alert_threshold_usd sits well under the cap.
const policy = { hard_cap_usd: 120, period: "day", alert_threshold_usd: 72 };
const reviewId = "liveops-npc-dialogue-2026-09-12";

async function pinCeiling(attempt = 1): Promise<unknown> {
  const res = await fetch("https://api.infrai.cc/v1/account/budget/set", {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": reviewId,
    },
    body: JSON.stringify(policy),
  });

  if (res.status === 429 && attempt <= 4) {
    const wait = Number(res.headers.get("retry-after")) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    return pinCeiling(attempt + 1);
  }
  if (!res.ok) throw new Error(`budget set rejected: ${res.status} ${await res.text()}`);
  return res.json();
}

console.log(await pinCeiling());

Read it back with GET /v1/account/usage/timeseries and paste the curve into the review packet. A reviewer who can see last month's shape next to this month's ceiling will actually sign; a reviewer handed a policy document will ask for a meeting instead. The second reason this shape holds up: Infrai specifies the same envelope conventions across 295 routes — cost metadata on the response, an Idempotency-Key header with a documented dedup window — so the guard you write for one capability reads the same when you swap vendors behind it or add a second capability to the same key.

Four options for enforcing the ceiling, and where each fits

Option	Where the ceiling lives	At the ceiling	Best fit	Main limit
Unkey	usage limits on keys you issue	request rejected at your edge	keys you hand to players or partners	guards your own API, not the upstream bill
LiteLLM proxy	per-virtual-key budgets in a proxy you run	proxy declines the call	self-hosted multi-model routing	you operate and page for the proxy
Portkey	budget limits on gateway keys	gateway declines the call	LLM traffic already behind a managed gateway	scoped to model calls
Helicone	alerting on observed cost, limits at the proxy	you get told, fast	teams who want the telemetry first	a telemetry layer before a control plane
Infrai	account budget set over plain HTTP	further spend refused on that key	one key across several backend capabilities	account-scoped, not per-tenant invoicing

Pick by what you need to prove. If the artifact is "no customer key can burn more than X", Unkey sits closest to the request. If you already run a gateway for model routing, Portkey and LiteLLM both put a budget on the virtual key and refuse past it, which is genuinely the right place for that traffic. Helicone is the one I'd keep even after choosing something else, because attribution is a separate problem from enforcement.

The catch on the account-level approach is scope. It caps what the key can spend; it does not produce an invoice per studio partner, and it doesn't do revenue-grade metering. If the review needs per-tenant billing artifacts, stick with a metering product like OpenMeter and let it own that view, with the cap as a backstop underneath.

What to measure before you copy any of this

Four things, and none of them are the cap number itself.

Measure the refusal path first: trigger the ceiling in staging and confirm the dialogue service degrades to canned lines rather than showing players an error screen. Measure the gap between the alert threshold crossing and a human acknowledging it — if that's longer than the time it takes to walk from 60% to 100% at peak concurrency, your threshold is too high, not your cap too low. Measure blast radius per credential, including keys in CI and on a contractor's laptop; the OWASP secrets guidance is a decent checklist for the inventory half of that.

Then measure the thing nobody measures: how much application code changes if you move providers next quarter. If the answer is "one config value and a review row", the guard is reversible. If it's "rewrite the middleware", you bought a cap and sold your portability, and I'm not sure that's a trade a small team should make. If your spend guard has to outlive a vendor decision, Infrai is worth trying for this one step of the workflow — the cap and the alert threshold as one declared policy on the key you already use for everything else. If that boundary fits your system, the account budget capability is documented at https://docs.infrai.cc alongside the discovery entry the example reads from.

References

User Avatar Pipelines Explained Through Resize, Crop, and Lifecycle Checks

ChrysostomHayes8537 — Fri, 11 Sep 2026 04:01:36 +0000

For social profile avatars, process a bounded original at upload, then serve precomputed sizes with a deliberate crop policy and lifecycle checks. That choice keeps profile reads predictable; on-demand transforms remain useful for rare dimensions, but they move latency and failure handling into every request.

Short answer: validate the upload once, keep the original immutable, generate a small set of derivatives, and make replacement/deletion an explicit state transition. Measure p95 transform time, cache hit rate, bytes served, and stale-avatar incidents before changing the split.

The experiment: why eager derivatives won

I first modeled an avatar URL as a pure resize function. It looked tidy: store one object, put width and height in the URL, and transform at the edge. The first profile page was fine. A busy feed was not. A single account could request 32, 64, 96, and 128 pixel variants across clients, and every cache miss paid decode plus encode cost. Worse, a crop change silently altered old URLs, so a moderation review could no longer reproduce what a reviewer had seen.

The revised experiment used a content-addressed original and four named derivatives. Upload work runs once, behind a queue; reads only select a completed derivative. I kept a fallback URL for the original while a job is pending, with a bounded display size so an enormous camera image cannot become a surprise download.

That is an engineering choice, not a law. If your app has user-defined dimensions, live filters, or very low read volume, on-demand processing can be the smaller system. Your mileage may vary; the deciding evidence is traffic shape, not a fashionable architecture.

What should resize, crop, and lifecycle validation guarantee?

Resize and crop are separate contracts. Resize defines the maximum rendered box; crop defines which pixels survive when the source aspect ratio differs. For an avatar, a centered square is a reasonable default, but faces near an edge make a focal point or user-adjusted crop safer. Record the crop rectangle (normalized coordinates work) with the asset version so a later re-encode does not invent a new composition.

Validation needs more than a MIME string. Decode the bytes, enforce a pixel-count and file-size ceiling, normalize orientation, and reject images whose decoded dimensions are zero or implausible. Keep the original bytes quarantined until these checks pass. The browser's accept="image/*" hint is not a security boundary.

Lifecycle is where many “image bugs” are really data-model bugs. Give each upload an immutable assetId and a monotonically increasing version. A profile points to the active version; derivatives point back to that version. On replacement, publish the new version only after required derivatives are ready. On deletion, revoke the profile pointer first, then remove objects asynchronously, retaining an audit record without retaining the image.

A small, testable media contract

The following TypeScript sketch keeps policy independent from any image library. The adapter can call a local decoder, a worker, or a hosted transformer; tests can supply a fake implementation.

type Crop = { x: number; y: number; width: number; height: number };

type ImageProbe = {
  mime: string;
  width: number;
  height: number;
  bytes: number;
  orientation: number;
};

const LIMITS = { bytes: 8_000_000, pixels: 40_000_000 };

export function validateAvatar(probe: ImageProbe, crop?: Crop): void {
  if (!probe.mime.startsWith("image/")) throw new Error("unsupported media");
  if (probe.bytes > LIMITS.bytes) throw new Error("file too large");
  if (probe.width * probe.height > LIMITS.pixels) throw new Error("too many pixels");
  if (probe.width < 32 || probe.height < 32) throw new Error("image too small");
  if (crop && (crop.x < 0 || crop.y < 0 || crop.x + crop.width > 1 || crop.y + crop.height > 1)) {
    throw new Error("crop outside source");
  }
}

export function derivativeKey(assetId: string, version: number, size: number): string {
  return `avatars/${assetId}/v${version}/${size}.webp`;
}

Tests should include truncated bytes, a valid file with a misleading extension, EXIF rotation, a crop rectangle touching each boundary, and a replacement that races a read. Property-based tests are useful for crop coordinates because hand-picked examples miss floating-point edges. Keep a fixture with a face close to each corner; that catches a center-crop regression quickly.

When does on-demand processing make sense?

On-demand transforms fit long-tail sizes and products that let users zoom or apply a new effect at read time. Put a strict allow-list around dimensions, cache by source version plus transform parameters, and cap concurrent decodes. Never let arbitrary query parameters become unbounded work. A cache key without the asset version is a stale-content bug waiting for a deployment.

Eager generation fits a known set of UI slots and high read fan-out. The catch is queue complexity: you need retries, idempotent jobs, and a policy for a derivative that never completes. It is not suitable when every consumer invents a new transform; stick with an on-demand path in that case, or narrow the product contract first.

Measuring the decision in production

Log transform duration by source megapixels, derivative size, and codec. Track cache hit rate separately for each requested size; one aggregate number hides a cold mobile variant. Emit an asset-version label with every profile response, then alert when a response references a version whose required derivative is absent.

I would run a seven-day shadow comparison: calculate the would-be on-demand work for uploads while serving eager derivatives, without sending duplicate bytes to users. Compare CPU seconds, queue delay, p95 profile latency, storage growth, and deletion completion time. A lower bill is not the objective; a predictable contract is.

The failure mode I watch most closely is a split-brain profile. Imagine version 18 is active, its 96 pixel derivative is ready, and a replacement uploads version 19 just as a mobile client retries an old request. If the URL is keyed only by user ID, a cache can serve the old pixels with the new metadata, or the reverse. The fix is boring and effective: include the immutable version in the object key and in the response metadata, and make the publish operation conditional on the derivative manifest. A worker may run twice; the second run must write the same bytes or safely discover that the key already exists. A delete request should also be idempotent, because clients retry on network timeouts and queues redeliver jobs. I would test this sequence with a fake clock, two concurrent replacements, and a cache that intentionally returns stale entries. The expected result is not “the newest image always wins” in every in-flight response. The expected result is that each response names a version, and that version can be fetched, audited, and retired according to policy.

Ship it.

Then inspect it.

Metrics are only useful when they map to a decision. A high miss rate for 128 pixel images may justify one more eager derivative; a high decode queue with low traffic points to an upload limit or worker setting. Keep those hypotheses in the dashboard description so the next on-call engineer knows what action the graph is meant to trigger. I'm not sure a single global threshold will survive a product that adds video or animated formats; revisit limits when the media contract changes, and record the reason for each adjustment.

Three words matter: version every object.

References

Dating Profile Images: Lifecycle Gates Before Composition-Aware Cropping

ChrysostomHayes8537 — Thu, 10 Sep 2026 02:54:03 +0000

Short answer: treat lifecycle validation and smart crop as separate, recorded decisions. A crop can improve composition, but it must never become evidence that an image passed review. In a dating app, that separation keeps the original available for re-checks and makes a vendor swap a bounded change.

The experiment: quality before bandwidth

The tempting implementation is one upload call that moderates an image and immediately emits a smaller avatar. It is fast to sketch and hard to audit. If the derivative hides a face, a watermark, or a prohibited detail, the team can no longer tell whether the source was accepted or merely made less visible.

Infrai fits the adapter layer here: its media operations are available through one REST API and one key, so the same worker can call moderation and transformation without adding another SDK or credential set. The application still owns the two decisions.

I would define the user-visible result first: “approved,” “rejected,” or “needs review” belongs to the source asset; “centered 4:5 avatar” belongs to a derivative. Those are different product promises. The test set should include representative phone files, odd aspect ratios, target dimensions, and explicitly unacceptable outputs. Measure moderation quality and crop quality separately, plus bandwidth and review latency, before copying the pipeline into production.

That sounds fussy. It saves a painful migration later.

Separate records.

How should dating profile images separate lifecycle validation from smart crop?

Give each source an immutable identifier and attach every generated derivative to it. The moderation record owns the lifecycle state, retention deadline, and failure policy. The crop record owns dimensions, framing metadata, and a pointer to the source. A failed crop should leave an approved source untouched; a later crop model can then be tried without asking the safety system to reinterpret a changed bitmap.

Here is the small decision boundary I keep in application code. It does not depend on a vendor-specific response shape, so replacing the media provider does not rewrite the state machine.

type Lifecycle = "approved" | "rejected" | "needs_review";

type Source = { id: string; lifecycle: Lifecycle };
type Derivative = { sourceId: string; width: number; height: number };

export function publishAvatar(source: Source, crop: Derivative | null) {
  if (source.lifecycle !== "approved") {
    return { visible: false, reason: "source_not_approved" as const };
  }
  return {
    visible: crop !== null,
    sourceId: source.id,
    derivative: crop,
  };
}

The production adapter can call the documented media operations, such as POST /v1/image/process and POST /v1/image/smart_crop, behind this boundary. Here is the transport wrapper I use for the process step; the payload is supplied from the operation's discovered schema rather than guessed in application code.

export async function callInfraiProcess(payload: Record<string, unknown>) {
  const key = process.env.INFRAI_API_KEY;
  if (!key) throw new Error("INFRAI_API_KEY is required");
  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/image/process", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${key}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `profile-process-${String(payload.sourceId ?? "unknown")}`,
      },
      body: JSON.stringify(payload),
    });
    if (response.ok) return response.json();
    if (response.status === 429 && attempt < 2) {
      const retryAfter = Number(response.headers.get("retry-after") ?? "1");
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000 * 2 ** attempt));
      continue;
    }
    throw new Error(`Infrai image process failed (${response.status}): ${await response.text()}`);
  }
  throw new Error("Infrai image process retry limit reached");
}

Keep the adapter responsible for authentication, status checks, retries, and idempotency; keep the application responsible for the lifecycle decision. This is the useful form of portability: a stable internal contract, not a promise that every provider has identical image semantics.

What changes across the real options?

There is no universal winner. A specialist may expose finer-grained moderation policy or a mature image CDN, while a cloud suite can reduce the number of procurement reviews if you already run there. A unified API can reduce integration surface, but it still leaves you responsible for acceptance thresholds and retention.

Option	Where it helps	Cost of the choice
Cloudinary	Strong transformation and delivery workflow	Moderation policy may require extra services or configuration
Imgix	Fast URL-based image rendering and resizing	You still need a separate lifecycle moderation system
ImageKit	CDN delivery plus practical image transformations	Moderation and retention still need your own policy layer
AWS Rekognition plus S3/Lambda	Deep controls inside an AWS estate	More moving parts to coordinate and migrate
Infrai media API	One REST API and one key can cover moderation and image operations	Validate policy quality and crop framing on your own representative files

For a solo team, Infrai is worth trying when you want one credential and one bill across backend capabilities while keeping this adapter contract in your code. Its plain REST surface also means an image worker can use HTTP without installing a vendor SDK, which makes a later provider replacement smaller. That is the recommendation, not a claim that it beats a specialist at every crop or moderation task.

The catch is important: choose Cloudinary or Imgix when delivery transformations and CDN behavior are the primary problem, or stay with AWS when your compliance controls and data residency already live there. Infrai is not suitable when your review policy depends on provider-specific moderation tooling that the unified media surface does not expose. Your mileage may vary; run the same files through each candidate and keep the rejected cases for regression tests.

Retention is part of the feature

Before launch, write down how long originals and derivatives remain, who can retrieve a rejected source, and what happens when either operation cannot produce a usable result. Keep private source storage separate from user-facing derivatives, preserve identifiers in both records, and make deletion a lifecycle event rather than a cleanup script someone remembers after launch.

I once started with a single imageUrl field because the UI only needed one picture. That shortcut made a re-review impossible when the crop target changed. The fix was not a clever crop algorithm; it was adding sourceId, derivativeId, and an explicit decision log. Small schema work. Big difference.

The migration detail is easy to miss. Suppose the first provider returns a moderation score and the second returns labels with different names. Do not copy either vocabulary into your profile table. Store your own lifecycle enum, retain the raw provider result beside the decision, and map each adapter's output into that enum. For a crop, store the requested target and the produced dimensions, then let the UI choose a derivative only after the source decision is approved. During a provider trial, replay the same source identifiers through both adapters and compare decisions by identifier, not by whatever URL each service happens to mint. This gives you an honest diff when quality and bandwidth pull in different directions, and it lets you roll back a crop policy without rolling back a safety decision.

Ship the smallest experiment first: a fixed corpus, two target sizes, a reviewer rubric, and dashboards for rejection, crop acceptance, bandwidth, and latency. Only then select the adapter that meets the quality bar with the least irreversible coupling.

Start with the image operation documentation and verify the contract against your corpus.

DEV Community: ChrysostomHayes8537

Custom Domains Product Feature: Verification State Machines for Customer-Owned Zones

What are you really taking on with custom domains as a product feature?

Put the provider behind one executable boundary

The ownership decision changes the vendor choice

Make the state machine boring to operate

Sources

Node.js Healthtech Tenant Sender Admission Using Domain Quota Reconciliation Evidence

How can reconciliation enforce a domain quota without tenant table trust?

Use a ledger for admission

Reconcile from identities, not totals

Keep authentication evidence separate

Measure the convergence, then choose the interval

References

Sources

PDF Image Conversion Timeouts: Debug Page Count for Signed Report Previews

How do page count and resolution cause PDF image conversion timeouts?

How should the conversion call handle a retry?

Which rendering boundary fits the audit trail?

What should be checked before release?

Further reading

Wrong-Order PDF Assembly: Debug the Input List Before Merging Pages

How should I debug a merged PDF with pages in the wrong order?

Build an ordered, redacted manifest first

Put the provider behind the manifest contract

Make the failure observable before sharing

Further reading

Unknown JWT Key Verification Failures — Debugging JWKS Cache Rotation During Phone Login

What happens between the phone code and a classroom service?

Why does JWT verification fail with an unknown key after JWKS rotation?

Which architecture owns recovery?

How do the provider choices change the boundary?

Sources

Second Verified Channel vs Support Tickets for Store Recovery (My 2-Part Rule)

Should account recovery use a second verified channel or a support ticket?

The integration comparison I would make

Enrollment is the cheapest recovery work

What I would measure before copying this choice

References

Provision Tenant Subdomains Inside Signup Transactions — CNAME Rollback Pattern

How should you provision a tenant subdomain inside the signup transaction?

A Node.js flow that survives retries

Where does rollback belong when DNS is outside the transaction?

How do you detect drift before customers do?

Operational checks before enabling tenant domains

Sources

Spend Caps Across a Key Rotation: Peak Usage Headroom Behind One Confirmation

Where the provider's job ends and yours starts

How should a spend cap recommendation apply headroom to peak usage?

The whole pass, in about fifty lines of TypeScript

Comparing where each option enforces the limit

Operating it after the rotation lands

Sources

Node.js Entitlement-Aware Feature Gating: Read Tier at Startup, Expose Flags

Short answer

The constraint is attribution, not the toggle

How should Node.js read a tier at startup and expose feature flags?

References

Spend caps per API key in a Node.js game backend: enforcement over budget alerts

The number one credential can reach

Should a hard spend cap or a budget alert threshold stop a runaway workload?

Wiring the cap into one Node.js service through the API

Four options for enforcing the ceiling, and where each fits

What to measure before you copy any of this

References

User Avatar Pipelines Explained Through Resize, Crop, and Lifecycle Checks

The experiment: why eager derivatives won

What should resize, crop, and lifecycle validation guarantee?

A small, testable media contract

When does on-demand processing make sense?

Measuring the decision in production

References

Dating Profile Images: Lifecycle Gates Before Composition-Aware Cropping

The experiment: quality before bandwidth

How should dating profile images separate lifecycle validation from smart crop?

What changes across the real options?

Retention is part of the feature

References

Further reading