Cloudflare Workers

Choose the portable entry

Use the portable @irondome-dev/sdk entry in Cloudflare Workers. Install the published JavaScript SDK from npm:

npm install @irondome-dev/sdk@0.2.0

Do not import /node or /deno here. See the SDK availability and setup instructions for more details.

The portable entry uses the platform's Fetch implementation. It does not create or own a Node HTTPS agent.

Configure secrets

Store IRONDOME_API_KEY as a Worker secret and configure IRONDOME_BASE_URL as a trusted server binding. Never accept the key or base URL from an incoming request.

Use https://api.irondome.dev for every plan. Read plans and limits for quota and billing.

Cloudflare documents secret configuration in its Workers secrets guide.

Set the key using the interactive secret prompt:

npx wrangler secret put IRONDOME_API_KEY

Add the base URL to the vars section of your existing wrangler.jsonc:

{
  "vars": {
    "IRONDOME_BASE_URL": "https://api.irondome.dev"
  }
}

For local development, put the key in an ignored .dev.vars file. Keep it out of vars, source control, and browser code. Deploy your existing Worker with npx wrangler deploy after integrating the helper below.

Use a request-scoped client

This helper belongs inside your existing protected signup handler:

import { IronDome } from '@irondome-dev/sdk';

export async function checkSignupEmail(email, env) {
  const client = new IronDome({
    apiKey: env.IRONDOME_API_KEY,
    baseUrl: env.IRONDOME_BASE_URL,
    timeoutMs: 3000,
    maxInFlight: 4,
  });
  return await client.check(email);
}

Creating this SDK object does not create a new socket pool. Workers manages connection reuse. Keep network I/O inside the invocation and do not share in-flight promises, response streams, or abort controllers across requests.

Body framing and concurrency

The SDK sends a fixed-length byte body so Workers can derive Content-Length. Generic streamed request bodies may not satisfy IronDome's known-length requirement. Do not attempt to force socket behavior with a Connection header or a Node agent.

Start with bounded per-invocation concurrency and leave room for other dependencies. maxInFlight is an application admission limit, rather than a promise of owning that many TCP sockets.

Warmup

A warmup is only useful within a supported request lifecycle. A health request during a page-load invocation does not guarantee a later signup invocation reuses the same connection. Do not run network calls at module initialization or share the Node warmup helper's promise across Worker invocations.

Follow the platform's lifecycle rules and let its transport handle networking. See the official Workers Fetch documentation.

Signup decisions and errors

Await this helper before creating the account. Reject disposable addresses according to your policy and handle SDK errors separately; a failed check must not become an allowed result. Keep your existing request validation and signup rate limits. See signup validation for the decision flow.