Forem: Alexis

Auto Estimate PostgreSQL Table and Index Size from EF Core Models

Alexis — Sat, 28 Mar 2026 16:42:36 +0000

TL;DR: EfCore.StorageEstimator combines EF Core model metadata with explicit workload assumptions so you can estimate PostgreSQL heap, index, and graph growth before production data exists.

If you use EF Core with PostgreSQL, you can usually answer schema questions like these:

What tables will exist?
Which columns are nullable?
Which indexes are we creating?
Are we using owned types, many-to-many, complex properties, or inheritance?

What you usually cannot answer quickly is this: how much storage will this model consume once real tenants, projects, assets, or events start piling up?

That is the gap EfCore.StorageEstimator is trying to close. It takes the parts EF Core already knows from the compiled model and combines them with the parts only you know: expected row counts, field fill rates, average payload lengths, and navigation multiplicities.

The tool estimates PostgreSQL table size, index size, and how row counts grow across related entities. Here is the kind of report it produces from a real EF Core model:

Path	Entity	Rows	Heap Bytes	Index Bytes	Total Bytes	Table	Properties	Indexes
SampleProject	SampleProject	120	81920	49152	131072	sample_projects	9	2
SampleProject.Assets	SampleAsset	1440	11796480	204800	12001280	sample_assets	7	1
SampleProject.Tags	SampleTag	480	40960	32768	73728	sample_tags	2	1

Total Estimated Rows: 2040
Total Estimated Bytes: 12206080

Why this exists

PostgreSQL storage is not intuitive to estimate by hand. Tables and indexes are stored in fixed-size pages, commonly 8 KB, with per-page headers, per-row headers, alignment rules, null bitmaps, and index entry overhead. Large values can also be pushed into TOAST storage. The official PostgreSQL docs explain the physical model, but that still leaves you doing a lot of manual math for real schemas.

EF Core already has the schema part. Its metadata model describes how your entity types map to the database. If you already use Npgsql, that model also knows PostgreSQL-specific store types like jsonb, bytea, arrays, and numeric precision.

Most teams still do capacity planning in a spreadsheet, a Notion page, or a rough architecture note. That usually drifts away from the actual model. Indexes get missed. Owned types get forgotten. Many-to-many join tables are hand-waved. Row counts are discussed separately from the schema that creates the storage bill.

EfCore.StorageEstimator puts those two sides together.

A minimal example

Start by annotating the parts of the model that EF Core cannot infer from the schema alone.

using EfCore.StorageEstimator.Planning;

[StorageEntity(12)]
public sealed class Project
{
  [StorageField(AverageLength = 64)]
  public string Name { get; set; } = string.Empty;

  [StorageNavigation(8)]
  public IReadOnlyList<TaskItem> Tasks { get; } = [];
}

[StorageEntity(1)]
public sealed class TaskItem
{
  [StorageField(0.5d, AverageLength = 120)]
  public string? Notes { get; set; }
}

Then run the estimate from a dedicated analysis process:

using EfCore.StorageEstimator;
using EfCore.StorageEstimator.Estimation;
using EfCore.StorageEstimator.Rendering;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection()
  .AddStorageEstimator()
  .BuildServiceProvider();

var estimator = services.GetRequiredService<IStorageEstimator>();

var report = estimator.Estimate(new StorageEstimateRequest
{
  Model = dbContext.Model,
  Roots =
  [
    new StorageTraversalRoot(typeof(Project)),
    new StorageTraversalRoot(typeof(Project))
    {
      EntityCountOverride = 5_000,
      Label = "Large Tenant"
    }
  ]
});

var markdown = new MarkdownReportRenderer().Render(report);
Console.WriteLine(markdown);

A few details matter here:

Model = dbContext.Model tells the estimator to read the real EF Core model.
EntityCountOverride lets you compare scenarios without editing attributes.
Label gives the root a friendlier name in the output.

What the report looks like

The sample app in the repository renders a Markdown report like this:

Path	Entity	Rows	Heap Bytes	Index Bytes	Total Bytes	Table	Properties	Indexes
SampleProject	SampleProject	120	81920	49152	131072	sample_projects	9	2
SampleProject.Assets	SampleAsset	1440	11796480	204800	12001280	sample_assets	7	1
SampleProject.Tags	SampleTag	480	40960	32768	73728	sample_tags	2	1

Total Estimated Rows: 2040
Total Estimated Heap Bytes: 11919360
Total Estimated Index Bytes: 286720
Total Estimated Bytes: 12206080

That report shape is useful because it answers several questions at once:

which path in the graph is producing the most rows
which table is consuming most of the heap
how much of the bill comes from indexes
how much of the estimate is grounded in real schema metadata

In this sample, the root entity is small, but the Assets branch dominates total storage once multiplicity is applied. That is the kind of result that is easy to miss in a spreadsheet and obvious in a traversal-based report.

What the packages do

The repository currently exposes three main surfaces:

Package	Purpose
`EfCore.StorageEstimator.Contracts`	Planning attributes and DTOs
`EfCore.StorageEstimator`	Runtime estimator, EF Core schema reader, PostgreSQL sizing math, Markdown and JSON renderers
`EfCore.StorageEstimator.Analyzers`	Roslyn diagnostics for invalid planning metadata

It is a library-first toolchain. You run it from a dedicated console app, internal tool, test harness, or analysis host. The estimator reads dbContext.Model, it does not need a live database connection to calculate an estimate.

Warnings and analyzers

The estimator emits warnings when traversal stops at an unannotated branch or when storage sizing falls back to default assumptions.

The analyzer package catches invalid metadata earlier in the build:

Rule	Meaning
`EFSA001`	`[StorageNavigation]` targets a type without `[StorageEntity]`
`EFSA002`	`[StorageEntity]` row count must be greater than zero
`EFSA003`	`[StorageField]` fill rate must be between `0` and `1`
`EFSA004`	`[StorageField(AverageLength = ...)]` must be zero or greater
`EFSA005`	`[StorageNavigation]` multiplicity must be greater than zero

That combination matters because the estimate stays explicit. Schema facts come from EF Core, workload assumptions live in code, and missing planning data shows up as warnings instead of disappearing into hand-wavy math.

Summary

If you already use EF Core and PostgreSQL, you already own half the information needed for capacity planning. EF Core knows the shape of the schema. Your team knows the expected scale. EfCore.StorageEstimator combines those two inputs into a report you can run early, review often, and tighten over time.

It gives you a concrete estimate before production data exists, using the model you already have.

Learn more:

GitHub repository: https://github.com/Alos-no/EfCore.StorageEstimator
NuGet package: https://www.nuget.org/packages/EfCore.StorageEstimator/

Claude Code VS Code extension freezes with multiple chat tabs? Workaround for Windows

Alexis — Sun, 01 Mar 2026 01:09:40 +0000

If your Claude Code extension hangs/freezes when running multiple agents, then I feel your pain.

The root cause appears to be multiple claude.exe processes fighting over ~/.claude.json with no file locking. Anthropic knows, the 2.0.61 changelog literally says:

2.0.61

Reverted VSCode support for multiple terminal clients due to responsiveness issues.

They added multi-tab support, claim it broke, and they reverted it. Multiple tabs used to work fine for me before 2.0.61, now newer versions freeze constantly.

Workaround: pin to 2.0.60

Install 2.0.60 from the VSIX and disable auto-update. This is the last version before the multi-client changes landed.

Next problem: 2.0.60 has claude-opus-4-5-20251101 hardcoded and doesn't recognize Opus 4.6.

Fix: patch the binary

Close VS Code completely, then run in PowerShell:

# Back up first
$dir = "$env:USERPROFILE\.vscode\extensions\anthropic.claude-code-2.0.60-win32-x64\resources\native-binary"
Copy-Item "$dir\claude.exe" "$dir\claude.exe.bak"

# Patch
$bytes = [System.IO.File]::ReadAllBytes("$dir\claude.exe")
$enc = [System.Text.Encoding]::GetEncoding("iso-8859-1")
$text = $enc.GetString($bytes)

$idx = 0; $count = 0
while (($idx = $text.IndexOf('"claude-opus-4-5-20251101"', $idx)) -ne -1) {
    $r = $enc.GetBytes('"claude-opus-4-6"         ')
    [Array]::Copy($r, 0, $bytes, $idx, $r.Length)
    $count++; $idx += 26
}

[System.IO.File]::WriteAllBytes("$dir\claude.exe", $bytes)
Write-Host "Patched $count occurrence(s)."

Should patch 6 occurrences.

Restart VS Code, ask what model are you? => Opus 4.6.

Adjust path for Cursor (\.cursor\extensions\...). To restore: Copy-Item claude.exe.bak claude.exe -Force (or just copy manually)

5 Email Attack Vectors Every SaaS Should Block

Alexis — Tue, 20 Jan 2026 08:30:00 +0000

TL;DR: A simple email input field is an attack surface. Users exploit aliases, relay services, and disposable domains to abuse free tiers, evade bans, and game referral systems. Here's how to defend against each vector.

Your registration form has one text field: email. It looks innocent. It's not.

That field is an attack surface for multi-accounting, ban evasion, referral fraud, and trial abuse. A determined user can create hundreds of accounts using a single Gmail address. Privacy-focused services give users unlimited anonymous aliases. Disposable email providers exist specifically for throwaway accounts.

This article covers five attack vectors and how to defend against each. See open-source libraries at the end for ready-to-use implementations.

1. Alias Abuse: One Inbox, Infinite Accounts

Most email providers support aliases that all deliver to the same inbox. Users exploit this to create multiple accounts that appear unique but aren't.

Gmail: Dots and Plus-Addressing

Gmail ignores dots in the local part and supports plus-addressing:

john.doe@gmail.com
johndoe@gmail.com
j.o.h.n.d.o.e@gmail.com
johndoe+signup1@gmail.com
johndoe+signup2@gmail.com
johndoe+freetrialforever@gmail.com

All six addresses deliver to the same inbox. A naive uniqueness check treats them as different users.

ProtonMail: Dots, Hyphens, and Underscores

ProtonMail goes further. As a security measure against impersonation, they ignore dots, hyphens, and underscores:

journalist.name@protonmail.com
journalistname@protonmail.com
journalist-name@protonmail.com
journalist_name@protonmail.com

All equivalent. ProtonMail implemented this to prevent attackers from registering lookalike addresses.

Yahoo: Hyphen-Based Aliases

Yahoo uses hyphens instead of plus signs:

john@yahoo.com
john-shopping@yahoo.com
john-newsletters@yahoo.com

Fastmail: Subdomain Addressing

Fastmail supports both plus-addressing and subdomain aliases:

user+tag@fastmail.com
anything@user.fastmail.com
randomalias@user.fastmail.com

The subdomain format is particularly dangerous because the local part can be anything.

Defense: Provider-Specific Normalization

Normalize emails before storing or checking uniqueness:

public static class EmailNormalizer
{
    private static readonly HashSet<string> GmailDomains =
        new(StringComparer.OrdinalIgnoreCase) { "gmail.com", "googlemail.com" };

    private static readonly HashSet<string> ProtonMailDomains =
        new(StringComparer.OrdinalIgnoreCase) { "protonmail.com", "proton.me", "pm.me" };

    public static string Normalize(string email)
    {
        var atIndex = email.LastIndexOf('@');
        var localPart = email[..atIndex];
        var domain = email[(atIndex + 1)..].ToLowerInvariant();

        if (GmailDomains.Contains(domain))
        {
            localPart = StripPlusSuffix(localPart);
            localPart = localPart.Replace(".", "");
        }
        else if (ProtonMailDomains.Contains(domain))
        {
            localPart = StripPlusSuffix(localPart);
            localPart = localPart.Replace(".", "")
                                 .Replace("-", "")
                                 .Replace("_", "");
        }
        // Yahoo: strip hyphen suffix
        // Fastmail: handle subdomain addressing
        // Outlook/iCloud: strip plus suffix only

        return $"{localPart.ToLowerInvariant()}@{domain}";
    }

    private static string StripPlusSuffix(string localPart)
    {
        var plusIndex = localPart.IndexOf('+');
        return plusIndex > 0 ? localPart[..plusIndex] : localPart;
    }
}

Store both the original email (for sending) and the normalized form (for uniqueness checks).

2. Relay Services: Unlimited Anonymous Aliases

Email relay services let users generate unlimited unique addresses that forward to their real inbox. Unlike provider aliases, each relay address is genuinely unique at the DNS level.

Major Relay Services

Service	Domain(s)	Notes
Apple Hide My Email	`privaterelay.appleid.com`	Built into iCloud+
Firefox Relay	`mozmail.com`	Free tier available
DuckDuckGo	`duck.com`	Email Protection feature
SimpleLogin	`simplelogin.com`, `slmails.com`, etc.	Proton-owned
Proton Pass	`passmail.net`	Password manager integration
addy.io (AnonAddy)	`addy.io`, `anonaddy.com`	Subdomain aliases
Fastmail Masked Email	`fastmail.com`	Premium feature
GitHub	`users.noreply.github.com`	Commit email privacy

Subdomain-Based Services

Some services use username-based subdomains:

randomalias@johndoe.anonaddy.com
anotheralias@johndoe.anonaddy.com

This requires wildcard matching, not just exact domain checks.

Defense: Relay Service Blocklist

public static class RelayServiceBlocklist
{
    private static readonly HashSet<string> BlockedDomains =
        new(StringComparer.OrdinalIgnoreCase)
    {
        "privaterelay.appleid.com",
        "mozmail.com",
        "duck.com",
        "simplelogin.com", "slmails.com",
        "passmail.net",
        "addy.io", "anonaddy.com",
        "users.noreply.github.com"
    };

    private static readonly string[] WildcardParents =
    {
        "anonaddy.com",  // *.anonaddy.com
        "aleeas.com"     // *.aleeas.com (SimpleLogin)
    };

    public static bool IsRelayService(string domain)
    {
        if (BlockedDomains.Contains(domain))
            return true;

        foreach (var parent in WildcardParents)
        {
            if (domain.EndsWith($".{parent}", StringComparison.OrdinalIgnoreCase))
                return true;
        }

        return false;
    }
}

Tradeoff: Blocking relay services frustrates privacy-conscious users. Consider your product's threat model. A free tier with expensive compute? Block them. A paid product with identity verification? Maybe allow them.

3. Disposable Emails: Throwaway Accounts

Disposable email providers create temporary inboxes that expire after minutes or hours. Users create an account, verify the email, and abandon the address.

Scale of the Problem

The disposable-email-domains community maintains a blocklist of 38,000+ domains. New services appear constantly.

Common Disposable Providers

Mailinator, Guerrilla Mail, 10 Minute Mail
Temp Mail, ThrowAwayMail, Fake Inbox
Thousands of lesser-known variants

4. Fake Domains: Non-Existent Email Addresses

Users provide email addresses with domains that can't receive mail:

Typos: user@gmial.com, user@hotnail.com
Invented domains: user@notreal.fake
Expired domains: Previously valid, now unregistered

Defense: MX Record Validation

Verify the domain has mail exchanger (MX) records in DNS:

public class MxRecordValidator
{
    private readonly ILookupClient _dnsClient;

    public async Task<bool> HasValidMxRecordsAsync(string domain, CancellationToken ct)
    {
        try
        {
            var result = await _dnsClient.QueryAsync(domain, QueryType.MX, ct);

            // Check for MX records
            if (result.Answers.MxRecords().Any())
                return true;

            // Fallback: Check for A/AAAA records (some domains accept mail without MX)
            var aResult = await _dnsClient.QueryAsync(domain, QueryType.A, ct);
            return aResult.Answers.ARecords().Any();
        }
        catch (DnsResponseException)
        {
            return false;
        }
    }
}

Performance note: DNS lookups add latency. Cache results and consider making MX validation async (verify after initial signup, not blocking).

5. Format Bypass: Invalid Email Strings

Weak regex patterns allow malformed addresses or miss edge cases.

Common Validation Mistakes

// Too permissive - allows invalid characters
var weak = @".+@.+";

// Too strict - rejects valid addresses
var strict = @"^[a-z]+@[a-z]+\.[a-z]{2,3}$";
// Rejects: user+tag@domain.com, UPPERCASE@domain.com, user@domain.co.uk

Defense: HTML5 Living Standard Pattern

The HTML5 specification defines a practical email validation pattern that handles real-world addresses:

public partial class EmailValidator
{
    // HTML5 Living Standard email pattern
    // Source: https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address
    private const string Html5Pattern =
        @"^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$";

    [GeneratedRegex(Html5Pattern, RegexOptions.Compiled)]
    private static partial Regex EmailRegex();

    public bool IsValidFormat(string email)
    {
        if (string.IsNullOrWhiteSpace(email))
            return false;

        return EmailRegex().IsMatch(email);
    }
}

This pattern is a "willful violation" of RFC 5322. It rejects technically valid but practically useless addresses (like "quoted string"@domain.com) while accepting everything real users actually use.

Validation Pipeline

Combine all defenses in order of computational cost:

public async Task<ValidationResult> ValidateAsync(string email)
{
    // 1. Format (fast, no I/O)
    if (!IsValidFormat(email))
        return Failure(Error.InvalidFormat);

    var domain = ExtractDomain(email);

    // 2. Relay service (fast, in-memory lookup)
    if (IsRelayService(domain))
        return Failure(Error.RelayService);

    // 3. Disposable domain (fast, in-memory lookup)
    if (IsDisposable(domain))
        return Failure(Error.Disposable);

    // 4. MX records (slow, DNS lookup)
    if (!await HasValidMxRecordsAsync(domain))
        return Failure(Error.InvalidDomain);

    return Success();
}

Order matters. Check cheap operations first, expensive operations last.

Open Source Libraries

Don't build this from scratch. These libraries handle normalization, relay detection, disposable blocklists, and MX validation:

Language	Library	Features
.NET	Alos.Email.Validation	Provider normalization, relay blocklist, 38K+ disposable domains, MX validation, auto-update
Node.js	mailchecker	55K+ disposable domains, multi-language (JS, PHP, Python, Ruby, Go, Rust)
Node.js	email-verifier	MX validation, disposable detection, caching
Python	email-validator	RFC compliance, MX validation, internationalization
Python	disposable-mail-checker	Disposable domain blocklist based on community lists
Ruby	valid_email2	MX validation, disposable blocklist, Rails integration
Go	email-verifier	Disposable detection, free provider detection, auto-update, SMTP check
PHP	email-checker	1K+ disposable domains, Symfony/Laravel integration
PHP	disposable-email-filter-php	Auto-updated weekly, framework-agnostic, Laravel support

None of these defenses are perfect. Determined attackers can register custom domains, use corporate email, or buy access to real accounts. The goal is to raise the cost of abuse high enough that it's not worth the effort for most attackers.

Why Your .NET Tests Are 10x Slower on Windows (and How to Fix It)

Alexis — Tue, 13 Jan 2026 08:30:00 +0000

TL;DR: On Windows, localhost resolves to IPv6 first. Docker containers only listen on IPv4. Each connection waits 2-4 seconds for the IPv6 timeout before falling back. Fix it by forcing IPv4 at the socket level.

Our .NET Aspire integration tests took 15 minutes. They should have taken 2 minutes. Every test waited 5+ seconds before doing anything useful.

The culprit: Windows trying IPv6 for localhost when Docker only speaks IPv4.

The Problem

When you connect to localhost on Windows:

Windows DNS returns both ::1 (IPv6) and 127.0.0.1 (IPv4)
.NET prefers IPv6 and tries ::1 first
Docker containers bind to 0.0.0.0 (IPv4 only)
The IPv6 connection hangs for ~2 seconds
.NET falls back to IPv4 and succeeds

On Linux, an IPv6 connection to a non-listening port gets an immediate "connection refused." Windows just waits.

The Multiplication Effect

A single Aspire integration test might make:

Component	Connections
Test → API endpoints	2-3 HTTP calls
Service → Service	2-4 HTTP calls
Services → PostgreSQL	1+ connections
Services → Redis	1+ connections
JWT validation → JWKS	1 HTTP call

Each localhost connection adds ~2 seconds of dead time. Ten connections per test means 20+ seconds of pure waiting.

The .NET Issue

This is documented in dotnet/runtime#65375: "HttpClient.GetAsync is really slow to localhost, really fast to 127.0.0.1." Closed as "not actionable" because it's OS behavior, not a .NET bug. Affects .NET 6+ and .NET Core 3.1.

The Fix: Force IPv4 at Socket Level

For HttpClient instances created via IHttpClientFactory, intercept the connection and force IPv4:

using System.Net;
using System.Net.Sockets;

builder.Services.ConfigureHttpClientDefaults(http =>
{
    http.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        ConnectCallback = async (context, cancellationToken) =>
        {
            var host = context.DnsEndPoint.Host;

            // Force IPv4 for localhost, let OS decide for everything else
            var addressFamily = host.Equals("localhost", StringComparison.OrdinalIgnoreCase)
                ? AddressFamily.InterNetwork  // IPv4 only
                : AddressFamily.Unspecified;

            var entry = await Dns.GetHostEntryAsync(host, addressFamily, cancellationToken);
            var socket = new Socket(SocketType.Stream, ProtocolType.Tcp) { NoDelay = true };

            try
            {
                await socket.ConnectAsync(entry.AddressList, context.DnsEndPoint.Port, cancellationToken);
                return new NetworkStream(socket, ownsSocket: true);
            }
            catch
            {
                socket.Dispose();
                throw;
            }
        }
    });
});

This covers all HttpClient instances registered through IHttpClientFactory.

Non-HTTP Connections

Different libraries need different fixes. Create a shared utility:

public static class LocalhostExtensions
{
    public static string NormalizeToIPv4(string value)
    {
        if (string.IsNullOrEmpty(value))
            return value;

        return value.Replace("localhost", "127.0.0.1", StringComparison.OrdinalIgnoreCase);
    }

    public static Uri NormalizeToIPv4(Uri uri)
    {
        if (!uri.Host.Equals("localhost", StringComparison.OrdinalIgnoreCase))
            return uri;

        return new UriBuilder(uri) { Host = "127.0.0.1" }.Uri;
    }
}

Then apply it per-library:

PostgreSQL (Npgsql)

var builder = new NpgsqlConnectionStringBuilder(connectionString);
builder.Host = LocalhostExtensions.NormalizeToIPv4(builder.Host);
return builder.ConnectionString;

Redis (StackExchange.Redis)

var connectionString = LocalhostExtensions.NormalizeToIPv4(originalConnectionString);
var options = ConfigurationOptions.Parse(connectionString);

// TLS cert is issued for 'localhost', not '127.0.0.1'
// WARNING: Only bypass validation in test environments
options.CertificateValidation += (sender, cert, chain, errors) => true;

return ConnectionMultiplexer.Connect(options);

JWT JWKS Discovery

var jwksEndpoint = $"{vaultBaseUrl.TrimEnd('/')}/.well-known/jwks.json";
jwksEndpoint = LocalhostExtensions.NormalizeToIPv4(jwksEndpoint);

var configManager = new ConfigurationManager<OpenIdConnectConfiguration>(
    jwksEndpoint,
    new JwksConfigurationRetriever(),
    new HttpDocumentRetriever());

Raw HttpClient (Test Code)

var endpoint = app.GetEndpoint("my-api");
var baseAddress = LocalhostExtensions.NormalizeToIPv4(endpoint);
var client = new HttpClient { BaseAddress = new Uri(baseAddress) };

Summary of Fixes by Component

Component	Fix Location
IHttpClientFactory clients	Socket-level `ConnectCallback`
Npgsql	Connection string `Host` property
StackExchange.Redis	Connection string + TLS bypass
ConfigurationManager	URL before construction
Raw HttpClient	BaseAddress before construction

Conditional Application

These fixes should only run in test mode:

var isTestingEnabled = configuration.GetValue<bool>("Testing:Enabled");

if (isTestingEnabled)
{
    // Apply IPv4 normalization
}

Production deployments use real hostnames and aren't affected.

Results

Metric	Before	After
Per-test time	~5-6 seconds	~0.6-0.8 seconds
Full suite (100 tests)	~10 minutes	~2 minutes

5-8x faster by eliminating IPv6 timeout waits.

Honeypot Fields: Bot Protection That's Free and Takes 5 Minutes

Alexis — Wed, 07 Jan 2026 08:30:00 +0000

TL;DR: A honeypot is a hidden form field that bots fill out and humans don't. When the field contains data, you reject the submission. It's invisible, requires no user interaction, and blocks most automated spam.

Your contact form is getting hammered. Dozens of spam submissions per day. You could set up a CAPTCHA, but that means integrating a third-party service, managing API keys, and dealing with the UX cost: 15% of users abandon forms when faced with a CAPTCHA challenge.

Honeypots are simpler. A few lines of HTML and CSS, a server-side check, and you're done. No external dependencies, no API costs, no user friction. They won't stop every bot, but they'll stop most of them, and your legitimate users won't notice they exist.

How It Works

A honeypot exploits a fundamental difference between humans and bots:

Humans fill out visible fields and ignore what they can't see
Bots parse HTML and fill out every field they find

You add a form field that's hidden via CSS. Humans never see it. Bots fill it out. If the field has a value when the form is submitted, you reject it.

<form action="/submit" method="POST">
  <label for="email">Email</label>
  <input type="email" name="email" id="email" required />

  <!-- Honeypot: hidden from humans, visible to bots -->
  <div class="form__alt" aria-hidden="true">
    <label for="website">Website</label>
    <input type="text" name="website" id="website" tabindex="-1" autocomplete="off" />
  </div>

  <button type="submit">Subscribe</button>
</form>

<style>
  .form__alt {
    position: absolute;
    left: -9999px;
    width: 1px;
    height: 1px;
    overflow: hidden;
  }
</style>

Server-side validation:

[HttpPost("subscribe")]
public IActionResult Subscribe([FromForm] SubscribeRequest request)
{
    // Honeypot check: if filled, it's a bot
    if (!string.IsNullOrEmpty(request.Website))
    {
        logger.LogWarning("Honeypot triggered from {IP}", HttpContext.Connection.RemoteIpAddress);

        // Return 200 to avoid revealing the trap
        return Ok();
    }

    // Process legitimate submission
    await subscriptionService.AddAsync(request.Email);

    return Ok(new { success = true });
}

Implementation Details That Matter

Field Naming

Don't name your field honeypot or trap. Bots look for obvious names and skip them.

Bad Names	Good Names
`honeypot`	`website`
`trap`	`company`
`spam`	`fax`
`bot-check`	`mobile`

Use names that look like legitimate optional fields. Bots expect forms to have fields like website or company and will fill them.

Hiding Techniques

Don't use:

type="hidden": Bots know to skip these
display: none inline: Bots detect inline styles
visibility: hidden: Easily detected

Do use:

External CSS with positioning off-screen
aria-hidden="true" for accessibility
tabindex="-1" so keyboard users skip it
autocomplete="off" to prevent browser autofill

Response Strategy

When a honeypot catches a bot, return a success response. If you return an error, the bot operator learns their submission was detected and can adjust.

// Good: Silent rejection
if (isHoneypotFilled)
{
    return Ok(); // Bot thinks it succeeded
}

// Bad: Reveals the trap
if (isHoneypotFilled)
{
    return BadRequest("Bot detected"); // Bot operator learns to avoid this
}

Adding Time-Based Detection

Bots submit forms instantly. Humans need time to read and type.

Add a timestamp when the page loads. Check how long the submission took. Reject anything faster than a reasonable threshold.

<input type="hidden" name="form_time" value="1703894400" />

[HttpPost("contact")]
public IActionResult Contact([FromForm] ContactRequest request)
{
    var submissionTime = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
    var loadTime = request.FormTime;
    var elapsed = submissionTime - loadTime;

    // Reject if submitted in less than 3 seconds
    if (elapsed < 3)
    {
        logger.LogWarning("Form submitted too fast: {Seconds}s", elapsed);

        return Ok();
    }

    // Honeypot check
    if (!string.IsNullOrEmpty(request.Website))
    {
        return Ok();
    }

    // Process legitimate submission
    // ...
}

The Laravel Honeypot package uses a 1-second default threshold. For complex forms, 5-10 seconds is reasonable.

When Honeypots Work

Honeypots are effective against:

Bot Type	Effectiveness
Basic scrapers	High: Fill every field blindly
Form-filling scripts	High: Don't execute CSS
Spam services	Medium: Some have learned to skip hidden fields
Headless browsers	Low: Can execute CSS and detect hidden fields

Studies report 80% reduction in basic spam with honeypots alone. Combined with time-based checks, some implementations block over 99% of automated submissions.

When Honeypots Fail

Honeypots won't catch:

Sophisticated bots that execute JavaScript and respect CSS. Headless browsers like Puppeteer can detect which fields are visible.

Human spam from click farms or paid operators. If a human fills out the form, the honeypot won't trigger.

Targeted attacks where the attacker inspects your form structure. Once they identify the honeypot, they skip it.

Password manager autofill that fills hidden fields. This is a documented issue, covered in our companion post on password manager ignore attributes.

Layered Protection

Honeypots work best as one layer in a defense stack:

Layer	Catches
Honeypot	Basic bots that fill all fields
Time check	Bots that submit instantly
Rate limiting	High-volume automated attacks
Cloudflare Turnstile	Sophisticated bots, headless browsers

For most contact forms and newsletter signups, honeypot + time check provides adequate protection without user friction. Add Turnstile or server-side validation (like Akismet) for high-value forms.

Framework Integrations

Most form libraries have built-in honeypot support:

Framework	Package/Feature
Laravel	spatie/laravel-honeypot
WordPress	Contact Form 7 Honeypot plugin
React	Manual implementation or remix-utils for Remix
ASP.NET	Manual implementation (see examples above)

Summary

Honeypots trade sophistication for simplicity. They won't stop every bot, but they'll stop most of them, and your users won't know they're there.

Technique	What It Catches
Hidden field	Bots that fill all fields
Time threshold	Bots that submit instantly
Deceptive naming	Bots that skip obvious traps

For forms where user experience matters more than bulletproof security, honeypots are the right tool. For authentication, payments, or high-value actions, combine them with stronger measures.

Related: Why Your Honeypot Catches Humans (Not Bots), on preventing password managers from filling honeypot fields.

Honeypots are one layer of defense. For comprehensive bot protection, see Cloudflare Turnstile or Cloudflare Bot Management.

Cache Purge on Cloudflare for C# Applications

Alexis — Tue, 06 Jan 2026 08:30:00 +0000

TL;DR: The Cloudflare.NET SDK lets you purge cached content programmatically: invalidate specific URLs when CMS content changes, or purge entire subdomains for multi-tenant platforms.

Cloudflare's CDN caches your content at edge locations worldwide. This is great for performance, but creates a problem: when content changes, visitors might see stale versions until the cache expires.

The manual solution is logging into the Cloudflare dashboard and clicking "Purge Cache." This doesn't scale when your CMS publishes dozens of articles per day, or when tenant content updates need immediate visibility.

The Cloudflare.NET SDK provides typed access to the cache purge API, letting you invalidate content from your .NET application.

Purge Options

The API supports several purge strategies, all available on every plan:

Strategy	Use Case	Limit
Specific URLs	Individual pages changed	30 URLs per request
By prefix	Section of site updated	30 prefixes per request
By host	Entire subdomain changed	30 hostnames per request
Everything	Full cache clear	Use sparingly

Rate limits vary by plan (Free: 5 requests/minute, Pro/Business: 5-10 requests/second, Enterprise: 50 requests/second).

For most applications, purging specific URLs is the right approach.

Scenario 1: CMS Publish Webhook

The Problem

Your content team uses a headless CMS (Contentful, Sanity, Strapi, or similar). When they publish an article, the cached version on Cloudflare doesn't update until the TTL expires. Editors see their changes immediately in the CMS preview, then complain that the live site shows old content.

The Solution

Create a webhook endpoint that receives publish events from your CMS and purges the affected URLs:

[ApiController]
[Route("webhooks")]
public class CmsWebhookController(
    ICloudflareApiClient cloudflare,
    ILogger<CmsWebhookController> logger) : ControllerBase
{
    private const string ZoneId = "your-zone-id";
    private const string BaseUrl = "https://example.com";
    private const string DefaultLocale = "en-US";

    [HttpPost("contentful")]
    public async Task<IActionResult> HandleContentfulPublish(
        [FromBody] ContentfulWebhookPayload payload,
        [FromHeader(Name = "X-Contentful-Topic")] string topic)
    {
        // X-Contentful-Topic format: ContentManagement.Entry.publish
        if (!topic.EndsWith(".publish", StringComparison.OrdinalIgnoreCase))
        {
            return Ok();
        }

        var urlsToPurge = BuildUrlsForEntry(payload);

        if (urlsToPurge.Count == 0)
        {
            logger.LogInformation("No URLs to purge for entry {EntryId}", payload.Sys.Id);
            return Ok();
        }

        logger.LogInformation(
            "Purging {Count} URLs for entry {EntryId}: {Urls}",
            urlsToPurge.Count,
            payload.Sys.Id,
            string.Join(", ", urlsToPurge));

        await cloudflare.Zones.PurgeCacheAsync(ZoneId,
            new PurgeCacheRequest(Files: urlsToPurge));

        return Ok(new { purged = urlsToPurge.Count });
    }

    private List<string> BuildUrlsForEntry(ContentfulWebhookPayload payload)
    {
        var urls = new List<string>();
        var contentType = payload.Sys.ContentType?.Sys.Id;

        switch (contentType)
        {
            case "blogPost":
                var slug = GetLocalizedField(payload.Fields, "slug");
                if (slug != null)
                {
                    urls.Add($"{BaseUrl}/blog/{slug}");
                    urls.Add($"{BaseUrl}/blog"); // Blog index page
                }
                break;

            case "page":
                var pageSlug = GetLocalizedField(payload.Fields, "slug");
                if (pageSlug != null)
                {
                    urls.Add($"{BaseUrl}/{pageSlug}");
                }
                break;

            case "siteSettings":
                // Global settings changed, purge homepage
                urls.Add(BaseUrl);
                urls.Add($"{BaseUrl}/");
                break;
        }

        return urls;
    }

    private static string? GetLocalizedField(JsonElement? fields, string fieldName)
    {
        // Contentful fields are nested by locale: fields.slug["en-US"]
        if (fields is not { } f)
            return null;

        if (!f.TryGetProperty(fieldName, out var fieldElement))
            return null;

        if (!fieldElement.TryGetProperty(DefaultLocale, out var localizedValue))
            return null;

        return localizedValue.GetString();
    }
}

public record ContentfulWebhookPayload(
    [property: JsonPropertyName("sys")] ContentfulSys Sys,
    [property: JsonPropertyName("fields")] JsonElement? Fields
);

public record ContentfulSys(
    [property: JsonPropertyName("id")] string Id,
    [property: JsonPropertyName("contentType")] ContentfulLink? ContentType
);

public record ContentfulLink(
    [property: JsonPropertyName("sys")] ContentfulSys Sys
);

Handling the 30 URL Limit

If a single publish event affects more than 30 URLs, batch the requests. Add this method to the controller:

private async Task PurgeBatchedAsync(List<string> urls)
{
    foreach (var batch in urls.Chunk(30))
    {
        await cloudflare.Zones.PurgeCacheAsync(ZoneId,
            new PurgeCacheRequest(Files: batch.ToList()));

        logger.LogInformation("Purged batch of {Count} URLs", batch.Length);
    }
}

Scenario 2: Multi-Tenant Cache Invalidation

The Problem

You're running a multi-tenant platform where each tenant has a subdomain (acme.yourapp.com, globex.yourapp.com). When a tenant updates their content, you need to purge their subdomain's cache without affecting other tenants.

The Solution

Purge by hostname when tenant content changes:

public class TenantCacheService(
    ICloudflareApiClient cloudflare,
    ILogger<TenantCacheService> logger)
{
    private const string ZoneId = "your-zone-id";
    private const string BaseDomain = "yourapp.com";

    public async Task InvalidateTenantCacheAsync(string tenantSlug)
    {
        var hostname = $"{tenantSlug}.{BaseDomain}";

        logger.LogInformation("Purging cache for tenant hostname: {Hostname}", hostname);

        await cloudflare.Zones.PurgeCacheAsync(ZoneId,
            new PurgeCacheRequest(Hosts: [hostname]));

        logger.LogInformation("Cache purged for {Hostname}", hostname);
    }

    public async Task InvalidateMultipleTenantsCacheAsync(IEnumerable<string> tenantSlugs)
    {
        var hostnames = tenantSlugs
            .Select(slug => $"{slug}.{BaseDomain}")
            .ToList();

        logger.LogInformation("Purging cache for {Count} tenant hostnames", hostnames.Count);

        await cloudflare.Zones.PurgeCacheAsync(ZoneId,
            new PurgeCacheRequest(Hosts: hostnames));
    }

    // For more granular control, purge specific URLs instead of the entire hostname
    public async Task InvalidateTenantCacheByUrlsAsync(
        string tenantSlug,
        IEnumerable<string> paths)
    {
        var hostname = $"{tenantSlug}.{BaseDomain}";

        var urls = paths
            .Select(path => $"https://{hostname}{path}")
            .ToList();

        // Batch to stay under 30 URL limit
        foreach (var batch in urls.Chunk(30))
        {
            await cloudflare.Zones.PurgeCacheAsync(ZoneId,
                new PurgeCacheRequest(Files: batch.ToList()));
        }
    }
}

Installation

dotnet add package Cloudflare.NET.Api

Configuration

See the Getting Started guide for full setup instructions.

appsettings.json

{
  "Cloudflare": {
    "ApiToken": "your-api-token",
    "AccountId": "your-account-id"
  }
}

Required Permissions

Your API token needs the Cache Purge permission at Zone level.

When creating a custom API token in the Cloudflare dashboard:

Permission: Zone → Cache Purge → Purge
Zone Resources: Select the specific zone or "All zones"

Dependency Injection Setup

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCloudflareApiClient(builder.Configuration);
builder.Services.AddScoped<TenantCacheService>();

Error Handling

try
{
    await cloudflare.Zones.PurgeCacheAsync(zoneId, request);
}
catch (CloudflareApiException ex) when (ex.Errors.Any(e => e.Code == 10000))
{
    // Authentication error
    logger.LogError("Authentication failed: {Message}", ex.Errors.First().Message);
}
catch (CloudflareApiException ex) when (ex.Errors.Any(e => e.Code == 7003))
{
    // Zone not found or invalid identifier
    logger.LogError("Invalid zone: {Message}", ex.Errors.First().Message);
}
catch (CloudflareApiException ex) when (ex.Errors.Any(e => e.Code == 1094))
{
    // Exceeded 30 file limit
    logger.LogError("Too many URLs: {Message}", ex.Errors.First().Message);
}
catch (CloudflareApiException ex)
{
    foreach (var error in ex.Errors)
    {
        logger.LogError("[{Code}] {Message}", error.Code, error.Message);
    }
}

Summary

Scenario	What You Get
CMS Webhook	Automatic cache invalidation when content is published
Multi-Tenant	Per-tenant cache purge without affecting other customers

The purge API is simple, but automating it removes the "why is the old content still showing?" conversation from your workflow.

Get started:

dotnet add package Cloudflare.NET.Api

Learn more:

Cloudflare.NET is an open-source, community-maintained SDK. Contributions are welcome!

Why Your Honeypot Catches Humans (Not Bots)

Alexis — Tue, 30 Dec 2025 08:30:00 +0000

TL;DR: Password managers autofill hidden honeypot fields, causing legitimate users to fail bot detection. Five vendor-specific data-* attributes tell password managers to ignore these fields.

You implemented honeypot spam protection correctly: a hidden field that humans never see but bots fill out. Submissions with data in that field get rejected.

Then support tickets arrive: "I can't submit the form." The users aren't bots. They're using 1Password, LastPass, or Bitwarden, and their password manager dutifully filled every field on the page, including your invisible trap.

This is a documented problem. Craft CMS users report it. LocalWiki had to address it. Users on IsThereAnyDeal forums couldn't log in because Proton Pass triggered the honeypot.

The fix is straightforward: tell password managers to ignore the field.

The Attributes

Each password manager uses its own data attribute. There's no standard.

Provider	Attribute	Value	Evidence
1Password	`data-1p-ignore`	Boolean	1Password Developer Docs
LastPass	`data-lpignore`	`"true"`	LastPass Support
Bitwarden	`data-bwignore`	Boolean	Bitwarden Source Code
Dashlane	`data-form-type`	`"other"`	Dashlane SAWF Specification
Proton Pass	`data-protonpass-ignore`	Boolean	Proton Pass Source Code

NordPass has no documented developer attribute as of December 2025.

Boolean attributes like data-1p-ignore require no value. LastPass requires ="true" explicitly, or it may still autofill.

The Fix

Add all five attributes to your honeypot field:

<div class="form__alt" aria-hidden="true">
  <label for="website">Website</label>
  <input
    type="text"
    name="website"
    id="website"
    tabindex="-1"
    autocomplete="off"
    data-1p-ignore
    data-lpignore="true"
    data-bwignore
    data-form-type="other"
    data-protonpass-ignore
  />
</div>

<style>
  .form__alt {
    position: absolute;
    left: -9999px;
    width: 1px;
    height: 1px;
    overflow: hidden;
  }
</style>

The autocomplete="off" attribute is included for completeness, but most password managers ignore it. The vendor-specific attributes are what actually work.

Why So Many Attributes?

Password managers deliberately override autocomplete="off". Chrome's position is that users should control their credentials, not websites. Firefox agrees.

This is reasonable for login forms. It's problematic for honeypots, search bars, and other non-credential fields. The vendor-specific attributes exist because the standard attribute doesn't work.

Other Use Cases

Honeypots are the most common case, but these attributes help elsewhere:

Search inputs in admin panels: If your search field has name="name", password managers recognize the pattern and show autofill icons. Apache Superset added data-1p-ignore to fix this.

API key and token fields: Password managers autofill saved credentials into fields named "key" or "secret". HashiCorp Nomad encountered this in their token settings UI.

CMS content fields: Editors in WordPress or similar systems see password popups on unrelated text fields, requiring constant dismissal.

Accessibility Note

WCAG 2.2 Accessible Authentication requires that password managers work on login forms. Blocking autofill on actual credential fields violates accessibility guidelines.

These attributes should only be used on:

Honeypot fields
Search inputs
Non-credential configuration fields

Never on username or password fields for authentication.

Summary

Password managers fill every field they recognize, including hidden honeypots. The solution is five data attributes that tell each major password manager to skip specific fields.

Attribute	Provider
`data-1p-ignore`	1Password
`data-lpignore="true"`	LastPass
`data-bwignore`	Bitwarden
`data-form-type="other"`	Dashlane
`data-protonpass-ignore`	Proton Pass

Add all five to honeypot fields. Your bot protection will stop catching humans.

DNS Automation for Multi-Tenant SaaS on CloudFlare

Alexis — Mon, 29 Dec 2025 08:30:00 +0000

TL;DR: The Cloudflare.NET SDK lets you automate DNS for multi-tenant apps: provision tenant subdomains, onboard customer vanity domains with automatic SSL, and migrate zones via BIND import/export, all from C# with full IntelliSense.

If you're building a multi-tenant SaaS application, you've probably hit this wall: DNS changes don't scale with manual dashboard clicks.

Every new tenant needs a subdomain. Every enterprise customer wants their vanity domain. Every migration involves exporting zone files and hoping nothing breaks. And somewhere along the way, DNS became the one piece of infrastructure that isn't automated.

The Cloudflare.NET SDK brings DNS management into your .NET codebase. This article covers three common scenarios.

Why a Typed SDK?

A typed SDK gives you:

IntelliSense everywhere - Method signatures, parameter types, and return types are discoverable in your IDE
Compile-time safety - Catch typos and type mismatches before runtime
Comprehensive XML documentation - Every method, parameter, and model is documented inline
Online API reference - Searchable documentation with examples

Compare this to shelling out to CLI tools or writing raw HTTP requests. When you're managing hundreds of DNS records, the compiler catching a typo beats debugging a 400 response at 2am.

Scenario 1: Multi-Tenant Subdomain Provisioning

The Problem

You're building a SaaS platform where each tenant gets a subdomain:

acme.yourapp.com
globex.yourapp.com
initech.yourapp.com

When a customer signs up, you need to create their DNS record automatically. When they cancel, you need to clean it up. Doing this manually doesn't scale past a dozen tenants.

The Solution

Automate DNS provisioning as part of your tenant onboarding flow:

public class TenantProvisioningService(
    ICloudflareApiClient cloudflare,
    ILogger<TenantProvisioningService> logger)
{
    private readonly string _zoneId = "your-zone-id";
    private readonly string _baseDomain = "yourapp.com";
    private readonly string _appServerIp = "203.0.113.50";

    public async Task<TenantProvisioningResult> ProvisionTenantAsync(string tenantSlug)
    {
        var subdomain = $"{tenantSlug}.{_baseDomain}";

        logger.LogInformation("Provisioning DNS for tenant: {Subdomain}", subdomain);

        // Create the A record pointing to your application server
        var record = await cloudflare.Dns.CreateDnsRecordAsync(_zoneId,
            new CreateDnsRecordRequest(
                Type: DnsRecordType.A,
                Name: subdomain,
                Content: _appServerIp,
                Proxied: true,  // Enable Cloudflare's CDN and security
                Ttl: 1          // Automatic TTL when proxied
            ));

        logger.LogInformation("Created DNS record {Id} for {Subdomain}", record.Id, subdomain);

        return new TenantProvisioningResult(
            TenantSlug: tenantSlug,
            Subdomain: subdomain,
            DnsRecordId: record.Id,
            IsProxied: record.Proxied
        );
    }

    public async Task DeprovisionTenantAsync(string tenantSlug, string dnsRecordId)
    {
        logger.LogInformation("Removing DNS for tenant: {TenantSlug}", tenantSlug);

        await cloudflare.Dns.DeleteDnsRecordAsync(_zoneId, dnsRecordId);

        logger.LogInformation("Deleted DNS record {Id}", dnsRecordId);
    }
}

public record TenantProvisioningResult(
    string TenantSlug,
    string Subdomain,
    string DnsRecordId,
    bool IsProxied
);

Batch Provisioning

Onboarding a batch of tenants? Use the batch API for atomic operations:

public async Task ProvisionTenantsAsync(IEnumerable<string> tenantSlugs)
{
    var createRequests = tenantSlugs
        .Select(slug => new CreateDnsRecordRequest(
            Type: DnsRecordType.A,
            Name: $"{slug}.{_baseDomain}",
            Content: _appServerIp,
            Proxied: true))
        .ToList();

    // All records created atomically - if one fails, none are created
    var result = await cloudflare.Dns.BatchDnsRecordsAsync(_zoneId,
        new BatchDnsRecordsRequest(Posts: createRequests));

    logger.LogInformation("Batch created {Count} tenant DNS records", result.Posts?.Count ?? 0);
}

The batch API executes operations in a guaranteed order (Deletes → Patches → Puts → Posts) within a single database transaction. If any operation fails, the entire batch rolls back.

Find and Update Existing Records

Need to update a tenant's DNS (e.g., migrating to a new server)?

public async Task UpdateTenantIpAsync(string tenantSlug, string newIpAddress)
{
    var subdomain = $"{tenantSlug}.{_baseDomain}";

    // Find the existing record by hostname
    var existing = await cloudflare.Dns.FindDnsRecordByNameAsync(
        _zoneId,
        subdomain,
        type: DnsRecordType.A);

    if (existing is null)
    {
        throw new InvalidOperationException($"No DNS record found for {subdomain}");
    }

    // Patch only the content field
    await cloudflare.Dns.PatchDnsRecordAsync(_zoneId, existing.Id,
        new PatchDnsRecordRequest(Content: newIpAddress));

    logger.LogInformation("Updated {Subdomain} to point to {Ip}", subdomain, newIpAddress);
}

Scenario 2: White-Label Custom Domains (Cloudflare for SaaS)

The Problem

Your enterprise customers want their own vanity domains:

Instead of acme.yourapp.com, Acme Corp wants app.acme.com
This requires SSL certificates for domains you don't control
You need to validate domain ownership before issuing certificates
The customer needs clear instructions for their DNS changes

Cloudflare for SaaS handles this. The SDK provides full access to the Custom Hostnames API.

The Solution

Implement a custom domain onboarding workflow:

public class CustomDomainService(
    ICloudflareApiClient cloudflare,
    ILogger<CustomDomainService> logger)
{
    private readonly string _zoneId = "your-zone-id";
    private readonly string _fallbackOrigin = "origin.yourapp.com";

    public async Task<CustomDomainOnboardingResult> StartOnboardingAsync(
        string customerId,
        string customerDomain)
    {
        logger.LogInformation(
            "Starting custom domain onboarding for {Customer}: {Domain}",
            customerId, customerDomain);

        // Configure SSL with TXT-based domain control validation
        var sslConfig = new SslConfiguration(
            Method: DcvMethod.Txt,
            Type: CertificateType.Dv,
            Settings: new SslSettings(
                MinTlsVersion: MinTlsVersion.Tls12,
                Http2: SslToggle.On
            )
        );

        // Create the custom hostname
        var hostname = await cloudflare.Zones.CustomHostnames.CreateAsync(_zoneId,
            new CreateCustomHostnameRequest(
                Hostname: customerDomain,
                Ssl: sslConfig
            ));

        logger.LogInformation(
            "Created custom hostname {Id} with status {Status}",
            hostname.Id, hostname.Status);

        // Build customer instructions
        var instructions = BuildCustomerInstructions(hostname);

        return new CustomDomainOnboardingResult(
            CustomHostnameId: hostname.Id,
            Status: hostname.Status.ToString(),
            SslStatus: hostname.Ssl.Status.ToString(),
            CustomerInstructions: instructions
        );
    }

    private CustomerDnsInstructions BuildCustomerInstructions(CustomHostname hostname)
    {
        var instructions = new CustomerDnsInstructions();

        // TXT record for domain ownership verification
        if (hostname.OwnershipVerification is not null)
        {
            instructions.OwnershipTxtRecord = new DnsInstruction(
                Type: "TXT",
                Name: hostname.OwnershipVerification.Name,
                Value: hostname.OwnershipVerification.Value,
                Purpose: "Proves you own this domain"
            );
        }

        // TXT record for SSL certificate validation
        if (hostname.Ssl.ValidationRecords is { Count: > 0 })
        {
            var sslValidation = hostname.Ssl.ValidationRecords[0];

            if (sslValidation.TxtName is not null)
            {
                instructions.SslTxtRecord = new DnsInstruction(
                    Type: "TXT",
                    Name: sslValidation.TxtName,
                    Value: sslValidation.TxtValue!,
                    Purpose: "Validates SSL certificate issuance"
                );
            }
        }

        // CNAME to route traffic (after validation completes)
        instructions.CnameRecord = new DnsInstruction(
            Type: "CNAME",
            Name: hostname.Hostname,
            Value: _fallbackOrigin,
            Purpose: "Routes traffic through Cloudflare to your app"
        );

        return instructions;
    }
}

public record CustomDomainOnboardingResult(
    string CustomHostnameId,
    string Status,
    string SslStatus,
    CustomerDnsInstructions CustomerInstructions
);

public record CustomerDnsInstructions
{
    public DnsInstruction? OwnershipTxtRecord { get; set; }
    public DnsInstruction? SslTxtRecord { get; set; }
    public DnsInstruction? CnameRecord { get; set; }
}

public record DnsInstruction(string Type, string Name, string Value, string Purpose);

Poll for Validation Status

After the customer adds their DNS records, poll for validation (add to CustomDomainService):

public async Task<CustomDomainStatus> CheckValidationStatusAsync(string customHostnameId)
{
    var hostname = await cloudflare.Zones.CustomHostnames.GetAsync(_zoneId, customHostnameId);

    var result = new CustomDomainStatus(
        Hostname: hostname.Hostname,
        OverallStatus: hostname.Status,
        SslStatus: hostname.Ssl.Status,
        IsFullyActive: hostname.Status == CustomHostnameStatus.Active
                       && hostname.Ssl.Status == SslStatus.Active,
        VerificationErrors: hostname.VerificationErrors
    );

    if (result.IsFullyActive)
    {
        logger.LogInformation("Custom domain {Hostname} is fully active!", hostname.Hostname);
    }
    else if (hostname.VerificationErrors is { Count: > 0 })
    {
        logger.LogWarning(
            "Validation errors for {Hostname}: {Errors}",
            hostname.Hostname,
            string.Join(", ", hostname.VerificationErrors));
    }

    return result;
}

public record CustomDomainStatus(
    string Hostname,
    CustomHostnameStatus OverallStatus,
    SslStatus SslStatus,
    bool IsFullyActive,
    IReadOnlyList<string>? VerificationErrors
);

List All Custom Domains

Enumerate all custom hostnames with automatic pagination (add to CustomDomainService):

public async Task<IReadOnlyList<CustomDomainSummary>> ListAllCustomDomainsAsync()
{
    var domains = new List<CustomDomainSummary>();

    await foreach (var hostname in cloudflare.Zones.CustomHostnames.ListAllAsync(_zoneId))
    {
        domains.Add(new CustomDomainSummary(
            Id: hostname.Id,
            Hostname: hostname.Hostname,
            Status: hostname.Status,
            SslStatus: hostname.Ssl.Status,
            CreatedAt: hostname.CreatedAt
        ));
    }

    return domains;
}

public record CustomDomainSummary(
    string Id,
    string Hostname,
    CustomHostnameStatus Status,
    SslStatus SslStatus,
    DateTimeOffset? CreatedAt
);

Scenario 3: DNS Zone Migration via BIND Import/Export

The Problem

You're migrating a domain to Cloudflare from another DNS provider. You have hundreds of DNS records. Manual recreation is error-prone and tedious.

Or you're moving away from Cloudflare and need to export your zone file.

The Solution

The SDK supports BIND zone file import/export - the industry standard for DNS record interchange.

Export from Cloudflare

// Standalone helper or add to a service class
public async Task ExportZoneToFileAsync(string zoneId, string outputPath)
{
    logger.LogInformation("Exporting DNS zone {ZoneId} to BIND format", zoneId);

    var bindContent = await cloudflare.Dns.ExportDnsRecordsAsync(zoneId);

    await File.WriteAllTextAsync(outputPath, bindContent);

    logger.LogInformation("Exported zone to {Path}", outputPath);
}

The exported file looks like standard BIND format:

;;
;; Domain:     example.com.
;; Exported:   2025-01-15 10:30:00
;;

$ORIGIN example.com.
$TTL 300

@       IN  A       203.0.113.50
www     IN  CNAME   example.com.
api     IN  A       203.0.113.51
mail    IN  MX  10  mail.example.com.

Import to Cloudflare

// Standalone helper or add to a service class
public async Task ImportZoneFromFileAsync(string zoneId, string inputPath, bool proxied = false)
{
    logger.LogInformation("Importing DNS zone from {Path}", inputPath);

    var bindContent = await File.ReadAllTextAsync(inputPath);

    var result = await cloudflare.Dns.ImportDnsRecordsAsync(zoneId, bindContent, proxied);

    logger.LogInformation(
        "Import complete: {Added} records added, {Parsed} total parsed",
        result.RecordsAdded,
        result.TotalRecordsParsed);
}

Migration Workflow

Combine export and import for a complete migration:

public class DnsMigrationService(
    ICloudflareApiClient cloudflare,
    ILogger<DnsMigrationService> logger)
{
    public async Task MigrateZoneAsync(
        string sourceZoneId,
        string targetZoneId,
        bool enableProxy = false)
    {
        logger.LogInformation(
            "Migrating DNS from zone {Source} to {Target}",
            sourceZoneId, targetZoneId);

        // Step 1: Export source zone
        var bindContent = await cloudflare.Dns.ExportDnsRecordsAsync(sourceZoneId);

        logger.LogInformation("Exported {Length} bytes of BIND data", bindContent.Length);

        // Step 2: Import to target zone
        var result = await cloudflare.Dns.ImportDnsRecordsAsync(
            targetZoneId,
            bindContent,
            proxied: enableProxy);

        logger.LogInformation(
            "Migration complete: {Added}/{Parsed} records imported",
            result.RecordsAdded,
            result.TotalRecordsParsed);
    }
}

Discover Existing Records

Moving a domain that already has DNS elsewhere? Use the scan API to discover existing records (add to DnsMigrationService):

public async Task DiscoverExistingRecordsAsync(string zoneId)
{
    logger.LogInformation("Scanning for existing DNS records...");

    // Trigger async scan
    await cloudflare.Dns.TriggerDnsRecordScanAsync(zoneId);

    // Wait for scan to complete (in production, use proper polling)
    await Task.Delay(TimeSpan.FromSeconds(10));

    // Review discovered records
    var discovered = await cloudflare.Dns.GetDnsRecordScanReviewAsync(zoneId);

    logger.LogInformation("Discovered {Count} existing records", discovered.Count);

    foreach (var record in discovered)
    {
        logger.LogInformation("  {Type} {Name} -> {Content}", record.Type, record.Name, record.Content);
    }

    // Accept all discovered records
    if (discovered.Count > 0)
    {
        var review = new DnsScanReviewRequest
        {
            // Convert DnsRecord objects to DnsScanAcceptItem for the API
            Accepts = discovered.Select(DnsScanAcceptItem.FromDnsRecord).ToList()
        };

        var result = await cloudflare.Dns.SubmitDnsRecordScanReviewAsync(zoneId, review);

        logger.LogInformation("Accepted {Count} records", result.Accepts);
    }
}

Installation

dotnet add package Cloudflare.NET.Api

Configuration

See the Getting Started guide for full setup instructions.

appsettings.json

{
  "Cloudflare": {
    "ApiToken": "your-api-token",
    "AccountId": "your-account-id"
  }
}

Required Permissions

Scenario	Permission	Level
DNS Records	DNS: Edit	Zone
Custom Hostnames	SSL and Certificates: Edit	Zone
Custom Hostnames	Cloudflare for SaaS: Edit	Zone
Zone Import/Export	DNS: Edit	Zone

Dependency Injection Setup

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCloudflareApiClient(builder.Configuration);

builder.Services.AddScoped<TenantProvisioningService>();
builder.Services.AddScoped<CustomDomainService>();
builder.Services.AddScoped<DnsMigrationService>();

Error Handling

The SDK provides structured exceptions for DNS and Custom Hostname operations:

try
{
    await cloudflare.Dns.CreateDnsRecordAsync(zoneId, request);
}
catch (CloudflareApiException ex) when (ex.Errors.Any(e => e.Code == 81057))
{
    // Record already exists
    logger.LogWarning("DNS record already exists: {Message}", ex.Errors.First().Message);
}
catch (CloudflareApiException ex) when (ex.Errors.Any(e => e.Code == 81058))
{
    // Invalid record content
    logger.LogError("Invalid DNS record: {Message}", ex.Errors.First().Message);
}
catch (CloudflareApiException ex)
{
    // Other API errors
    foreach (var error in ex.Errors)
    {
        logger.LogError("[{Code}] {Message}", error.Code, error.Message);
    }
}

Summary

Most teams have CI/CD, infrastructure-as-code, automated deployments... and then someone clicks around in the Cloudflare dashboard to add a DNS record. The Cloudflare.NET SDK fixes that:

Scenario	What You Get
Multi-Tenant Subdomains	Automated provisioning tied to your signup flow
Custom Domains (Cloudflare for SaaS)	White-label SSL with programmatic DCV workflow
Zone Migration	BIND import/export for provider transitions
Record Discovery	Scan and review existing DNS before migration

The batch API runs in a single transaction, so you can delete a record and recreate it with the same name without race conditions.

Get started:

dotnet add package Cloudflare.NET.Api

Learn more:

GitHub Repository
API Documentation
DNS API Coverage
Cloudflare R2 in .NET Without the AWS SDK Headaches - Companion article on R2 object storage

Cloudflare.NET is an open-source, community-maintained SDK. Contributions are welcome!

Auto-Approve WebFetch and WebSearch in Claude Code with Hooks

Alexis — Fri, 26 Dec 2025 12:09:10 +0000

TL;DR: Claude Code's standard permission settings for WebFetch and WebSearch have known bugs. Hooks bypass these issues and work in CLI, VSCode, and sub-agents.

If you use Claude Code regularly, you've likely encountered the permission prompt fatigue. Every web search, every URL fetch: "Allow WebSearch?" "Allow WebFetch?" Click. Click. Click. You add these tools to your settings.local.json allow list, and yet the prompts keep appearing.

It's a collection of known bugs and edge cases in Claude Code's permission system that affect WebFetch and WebSearch specifically.

The Problem with Standard Permission Settings

The natural approach is to add WebFetch and WebSearch to your permission configuration:

{
  "permissions": {
    "allow": [
      "WebFetch",
      "WebSearch"
    ]
  }
}

This should work. Sometimes it does. Often it doesn't.

1. Wildcard Patterns Don't Match

Adding WebFetch(domain:*) to allow all domains doesn't actually work. Claude Code still prompts for each new domain, then adds specific entries like WebFetch(domain:github.com) to your settings file. The wildcard sits there, ignored.

2. VSCode Extension Ignores Settings

The VSCode extension requires two settings to work together, and the documentation doesn't make this clear:

{
  "claudeCode.allowDangerouslySkipPermissions": true,
  "claudeCode.initialPermissionMode": "bypassPermissions"
}

Without both, your project-level settings are ignored.

3. Sub-Agents Get Auto-Denied

Planning mode and sub-agents (like Explore) run in "dontAsk" mode, which auto-denies tools even when you've configured bypass permissions. You see errors like:

Error: Permission to use WebSearch has been auto-denied in dontAsk mode.

4. Path Normalization Issues

On macOS and Linux, path expansion inconsistencies cause permission rules to not match. A rule for /home/username/project/** won't match a request for ~/project/file.txt.

The Solution: Use Hooks

Hooks bypass the permission system entirely. They intercept tool calls and return explicit allow/deny decisions before the permission check occurs. This works reliably because:

Hooks run before the permission system evaluates rules
Hooks work in all contexts: CLI, VSCode, sub-agents, planning mode
Hooks use explicit JSON responses, not pattern matching

Two hooks handle different scenarios:

PreToolUse: Intercepts tool calls before execution
PermissionRequest: Intercepts permission dialog requests

Configuration

Step 1: Create the Hook Script

Create .claude/hooks/auto_allow_web_tools.py in your project:

#!/usr/bin/env python3
"""
Claude Code hook to auto-approve WebFetch and WebSearch tools.

Exit codes:
  0 = Hook made a decision (JSON output printed to stdout)
  1 = Hook did not make a decision (fall back to normal permission flow)

This hook is FAIL-SAFE: any unexpected error exits with code 1,
which causes Claude Code to fall back to its normal permission prompt.
"""
import json
import sys
from urllib.parse import urlparse


# Optional: restrict WebFetch to a domain allowlist.
# Leave as None to allow ALL domains.
ALLOWED_FETCH_DOMAINS = None  # e.g. {"learn.microsoft.com", "github.com"}

# Optional: force WebSearch to only return results from certain domains.
# Leave as None to not force domain filtering.
FORCE_SEARCH_ALLOWED_DOMAINS = None  # e.g. ["learn.microsoft.com", "github.com"]


def log_error(msg: str) -> None:
    """Log to stderr for debugging (won't affect hook output)."""
    print(f"[auto_allow_web_tools] {msg}", file=sys.stderr)


def host_of(url: str) -> str:
    """Extract lowercase hostname from URL, or empty string on failure."""
    try:
        return (urlparse(url).hostname or "").lower()
    except Exception:
        return ""


def output_and_exit(result: dict) -> None:
    """
    Print JSON result to stdout and exit with code 0.
    Validates output before printing to prevent malformed JSON issues.
    """
    try:
        output = json.dumps(result)
        print(output)
        sys.exit(0)
    except (TypeError, ValueError) as e:
        log_error(f"Failed to serialize output: {e}")
        sys.exit(1)


def handle_pre_tool_use(tool: str, tool_input: dict) -> None:
    """Handle PreToolUse event - decide whether to allow/deny/modify the tool call."""
    updated_input = None

    # Check domain allowlist for WebFetch
    if tool == "WebFetch" and ALLOWED_FETCH_DOMAINS is not None:
        url = tool_input.get("url", "")
        host = host_of(url)
        if host not in ALLOWED_FETCH_DOMAINS:
            output_and_exit({
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": f"WebFetch blocked by hook: {host} not in allowlist",
                }
            })
            return  # Never reached, but makes flow clear

    # Force domain filtering for WebSearch
    if tool == "WebSearch" and FORCE_SEARCH_ALLOWED_DOMAINS is not None:
        updated_input = dict(tool_input)
        updated_input["allowed_domains"] = list(FORCE_SEARCH_ALLOWED_DOMAINS)

    # Allow the tool call
    result = {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "allow",
            "permissionDecisionReason": "Auto-approved WebSearch/WebFetch via hook",
        }
    }
    if updated_input is not None:
        result["hookSpecificOutput"]["updatedInput"] = updated_input

    output_and_exit(result)


def handle_permission_request() -> None:
    """Handle PermissionRequest event - auto-allow if UI shows permission dialog."""
    output_and_exit({
        "hookSpecificOutput": {
            "hookEventName": "PermissionRequest",
            "decision": {"behavior": "allow"},
        }
    })


def main() -> None:
    """
    Main entry point. Reads hook input from stdin and dispatches to handlers.

    IMPORTANT: This hook ONLY handles WebFetch and WebSearch tools.
    All other tools exit with code 1 (no decision), falling back to normal permissions.
    """
    try:
        # Parse input from Claude Code
        data = json.load(sys.stdin)
    except json.JSONDecodeError as e:
        log_error(f"Invalid JSON input: {e}")
        sys.exit(1)
    except Exception as e:
        log_error(f"Failed to read stdin: {e}")
        sys.exit(1)

    event = data.get("hook_event_name", "")
    tool = data.get("tool_name", "")
    tool_input = data.get("tool_input") or {}

    # SECURITY: Only handle WebFetch and WebSearch - nothing else
    if tool not in ("WebFetch", "WebSearch"):
        sys.exit(1)

    # Dispatch to appropriate handler
    if event == "PreToolUse":
        handle_pre_tool_use(tool, tool_input)
    elif event == "PermissionRequest":
        handle_permission_request()
    else:
        # Unknown event type - don't make a decision
        log_error(f"Unknown event type: {event}")
        sys.exit(1)


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        # Catch-all: ensure we NEVER exit 0 without valid output
        log_error(f"Unexpected error: {e}")
        sys.exit(1)

Step 2: Configure the Hook

Add the hook configuration to .claude/settings.local.json:

{
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": []
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "WebFetch|WebSearch",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/auto_allow_web_tools.py",
            "timeout": 5
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "WebFetch|WebSearch",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/auto_allow_web_tools.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Windows users: Replace python3 with py -3 or the full path to your Python executable.

How It Works

PreToolUse Hook

When Claude decides to call WebFetch or WebSearch:

Claude Code invokes the hook with tool details on stdin
The hook checks if the tool is WebFetch or WebSearch
If yes, it outputs JSON with "permissionDecision": "allow"
The tool executes without prompting

PermissionRequest Hook

If a permission dialog would appear (edge cases, sub-agents):

Claude Code invokes the hook before showing the dialog
The hook outputs JSON with "decision": {"behavior": "allow"}
The dialog is suppressed, permission granted

Fail-Safe Design

The script exits with code 1 for any unexpected condition:

Non-WebFetch/WebSearch tools fall through to normal permissions
JSON parse errors fall through
Any exception falls through

Optional: Domain Restrictions

The script supports optional domain filtering. Uncomment and configure:

# Only allow fetching from these domains
ALLOWED_FETCH_DOMAINS = {"docs.microsoft.com", "github.com", "stackoverflow.com"}

# Force all web searches to only return results from these domains
FORCE_SEARCH_ALLOWED_DOMAINS = ["docs.microsoft.com", "github.com"]

With ALLOWED_FETCH_DOMAINS set, WebFetch requests to unlisted domains are denied with a clear message.

With FORCE_SEARCH_ALLOWED_DOMAINS set, the hook modifies the WebSearch input to include domain filtering, regardless of what Claude requested.

Project vs Global Configuration

You can place this configuration in different locations:

Location	Scope	Git
`.claude/settings.local.json`	This project only	Should be in `.gitignore`
`.claude/settings.json`	This project, shareable	Can be committed
`~/.claude/settings.json`	All projects	N/A

For team projects, commit .claude/hooks/auto_allow_web_tools.py but keep settings.local.json in .gitignore so each developer can configure their own preferences.

Debugging

If the hook isn't working:

Check the script runs: echo '{"hook_event_name":"PreToolUse","tool_name":"WebFetch","tool_input":{"url":"https://example.com"}}' | python3 .claude/hooks/auto_allow_web_tools.py
Check stderr: Errors are logged to stderr, visible in Claude Code's debug output
Verify the matcher: The regex WebFetch|WebSearch must match exactly
Check Python path: Ensure python3 (or py -3 on Windows) is available in PATH

Summary

Approach	Works in CLI	Works in VSCode	Works in Sub-Agents
`permissions.allow`	Sometimes	Requires extra settings	No
Wildcard patterns	No	No	No
Hooks (this solution)	Yes	Yes	Yes

Hooks work where permission settings don't. The exit-code-1 fallback means you're never locked out if something goes wrong.

Learn more:

Have questions or improvements? Open an issue or PR on your project's repository.

CloudFlare D1 DevOps from .NET: Test Seeding, Data Sync, and Backups

Alexis — Thu, 25 Dec 2025 09:28:15 +0000

TL;DR: The Cloudflare.NET SDK lets you manage D1 databases from C# for DevOps workflows: seed test data, sync reference tables, and backup to R2 - all without installing Node.js or Wrangler.

D1 is Cloudflare's serverless SQLite database, designed to run at the edge alongside Workers. The typical workflow involves Wrangler CLI for database management - but Wrangler requires Node.js.

If you're a .NET shop, you probably don't want Node.js in your CI/CD pipelines just to run database migrations.

The Cloudflare.NET SDK provides a D1 client that lets you manage databases directly from C#. This article covers three practical DevOps scenarios where this is genuinely useful.

Why a Typed SDK?

A typed SDK gives you:

IntelliSense everywhere - Method signatures, parameter types, and return types are discoverable in your IDE
Compile-time safety - Catch typos and type mismatches before runtime
Comprehensive XML documentation - Every method, parameter, and model is documented inline
Online API reference - Searchable documentation with examples

Compare this to shelling out to wrangler d1 execute and parsing JSON output.

When to Use the D1 HTTP API

Let's be clear about what the D1 HTTP API is designed for. From Cloudflare's documentation:

The D1 HTTP API is best suited for administrative use, such as running migrations, importing data, or managing database schema.

The HTTP API is not for real-time queries from your backend. Latency would be unacceptable. Your Workers should query D1 directly using the native bindings.

However, there are legitimate scenarios where calling D1 from outside Cloudflare makes sense:

Scenario	Why It Works
Test data seeding	Runs once before tests, latency doesn't matter
Reference data sync	Scheduled job pushing authoritative data to the edge
Database backups	Periodic export, latency irrelevant
CI/CD migrations	Schema changes during deployment
Bulk data import	Initial load or periodic refresh

All of these are infrequent operations where the HTTP round-trip is acceptable.

Scenario 1: Test Data Seeding

The Problem

You have integration tests that verify your Workers interact correctly with D1. Before each test run, you need to:

Reset the database to a known state
Insert specific test fixtures
Run tests against real D1 (not mocks)

With Wrangler, you'd shell out to npx wrangler d1 execute - which requires Node.js in your test environment.

The Solution

Seed D1 directly from your xUnit test setup using the D1 API:

public class OrdersWorkerTests : IAsyncLifetime
{
    private readonly ICloudflareApiClient _cf;
    private readonly string _databaseId;

    public OrdersWorkerTests()
    {
        _cf = CreateCloudflareClient();
        _databaseId = Environment.GetEnvironmentVariable("D1_TEST_DATABASE_ID")!;
    }

    public async Task InitializeAsync()
    {
        // Reset to known state
        await _cf.Accounts.D1.QueryAsync(_databaseId, "DELETE FROM orders");
        await _cf.Accounts.D1.QueryAsync(_databaseId, "DELETE FROM customers");

        // Seed test fixtures
        await _cf.Accounts.D1.QueryAsync(_databaseId, """
            INSERT INTO customers (id, name, email) VALUES
            (1, 'Test Customer', 'test@example.com'),
            (2, 'Another Customer', 'another@example.com')
            """);

        await _cf.Accounts.D1.QueryAsync(_databaseId, """
            INSERT INTO orders (id, customer_id, total, status) VALUES
            (100, 1, 99.99, 'pending'),
            (101, 1, 149.99, 'shipped'),
            (102, 2, 29.99, 'delivered')
            """);
    }

    public Task DisposeAsync() => Task.CompletedTask;

    [Fact]
    public async Task GetPendingOrders_ReturnsCorrectCount()
    {
        // Call your Worker endpoint that queries D1
        var response = await _httpClient.GetAsync("/api/orders?status=pending");

        var orders = await response.Content.ReadFromJsonAsync<Order[]>();
        Assert.Single(orders);
        Assert.Equal(100, orders[0].Id);
    }
}

Parameterized Queries

For dynamic test data, use parameterized queries to prevent SQL injection:

await _cf.Accounts.D1.QueryAsync(_databaseId,
    "INSERT INTO orders (customer_id, total) VALUES (?, ?)",
    @params: [customerId, orderTotal]);

Typed Query Results

Query and deserialize results directly:

var results = await _cf.Accounts.D1.QueryAsync<Order>(_databaseId,
    "SELECT id, customer_id, total, status FROM orders WHERE status = ?",
    @params: ["pending"]);

foreach (var order in results[0].Results)
{
    Console.WriteLine($"Order {order.Id}: ${order.Total}");
}

Scenario 2: Reference Data Synchronization

The Problem

Your D1 database contains lookup tables that are mastered in your .NET backend's SQL Server:

Countries and regions
Product categories
Tax rates by jurisdiction
Feature flags

You need to periodically sync this authoritative data from your backend to D1. The data flows from your backend to the edge - the opposite direction of a typical read query.

The Solution

A scheduled job that pushes reference data to D1 using parameterized queries:

public class D1SyncService(
    ICloudflareApiClient cloudflare,
    IDbConnection sqlServer,
    ILogger<D1SyncService> logger)
{
    private readonly string _d1DatabaseId = "your-d1-database-id";

    public async Task SyncCountriesAsync()
    {
        // Fetch authoritative data from SQL Server
        var countries = await sqlServer.QueryAsync<Country>(
            "SELECT code, name, tax_rate FROM countries WHERE active = 1");

        logger.LogInformation("Syncing {Count} countries to D1", countries.Count());

        // Clear and repopulate D1
        await cloudflare.Accounts.D1.QueryAsync(_d1DatabaseId,
            "DELETE FROM countries");

        foreach (var batch in countries.Chunk(100))
        {
            var values = string.Join(",",
                batch.Select(c => $"('{c.Code}', '{c.Name}', {c.TaxRate})"));

            await cloudflare.Accounts.D1.QueryAsync(_d1DatabaseId,
                $"INSERT INTO countries (code, name, tax_rate) VALUES {values}");
        }

        logger.LogInformation("Country sync complete");
    }
}

Register as a Hosted Service

Run the sync on a schedule:

public class D1SyncBackgroundService(
    D1SyncService syncService,
    ILogger<D1SyncBackgroundService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await syncService.SyncCountriesAsync();
                await syncService.SyncCategoriesAsync();
                await syncService.SyncFeatureFlagsAsync();
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "D1 sync failed");
            }

            // Run every hour
            await Task.Delay(TimeSpan.FromHours(1), stoppingToken);
        }
    }
}

Scenario 3: Backup D1 to R2

The Problem

You want automated backups of your D1 databases stored in R2, using your existing .NET infrastructure. No Node.js required.

For a deep dive on the R2 client, see Cloudflare R2 in .NET Without the AWS SDK Headaches.

The Solution

Export D1 using the export API and upload to R2:

public class D1BackupService(
    ICloudflareApiClient cloudflare,
    IR2Client r2,
    ILogger<D1BackupService> logger)
{
    public async Task BackupDatabaseAsync(string databaseId, string databaseName)
    {
        logger.LogInformation("Starting backup of {Database}", databaseName);

        // Start the export
        var exportResult = await cloudflare.Accounts.D1.StartExportAsync(databaseId);

        // Poll until complete
        D1ExportResponse status;
        do
        {
            await Task.Delay(TimeSpan.FromSeconds(2));
            status = await cloudflare.Accounts.D1.PollExportAsync(
                databaseId,
                exportResult.AtBookmark!);
        }
        while (status.Status == "active");

        if (status.Status != "complete")
        {
            throw new InvalidOperationException($"Export failed: {status.Error}");
        }

        // Download the SQL dump
        using var httpClient = new HttpClient();
        var sqlDump = await httpClient.GetByteArrayAsync(status.Result!.SignedUrl!);

        // Upload to R2 with timestamp
        var backupKey = $"backups/{databaseName}/{DateTime.UtcNow:yyyy-MM-dd-HHmmss}.sql";

        using var stream = new MemoryStream(sqlDump);
        await r2.UploadAsync("db-backups", backupKey, stream);

        logger.LogInformation(
            "Backup complete: {Key} ({Size:N0} bytes)",
            backupKey,
            sqlDump.Length);
    }
}

Backup All Databases

Enumerate and backup all D1 databases in your account:

public async Task BackupAllDatabasesAsync()
{
    await foreach (var database in cloudflare.Accounts.D1.ListAllAsync())
    {
        try
        {
            await BackupDatabaseAsync(database.Uuid, database.Name);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Failed to backup {Database}", database.Name);
        }
    }
}

Retention Policy

Combine with R2 lifecycle rules to automatically expire old backups:

// Set retention policy on the backup bucket
await cloudflare.Accounts.Buckets.SetLifecycleAsync("db-backups", new BucketLifecyclePolicy(
    Rules:
    [
        new LifecycleRule(
            Id: "expire-old-backups",
            Enabled: true,
            DeleteObjectsTransition: new DeleteObjectsTransition(
                Condition: LifecycleCondition.AfterDays(30)
            )
        )
    ]
));

Installation

dotnet add package Cloudflare.NET.Api
dotnet add package Cloudflare.NET.R2  # Only needed for R2 backup scenario

Configuration

See the Getting Started guide for full setup instructions.

appsettings.json

{
  "Cloudflare": {
    "ApiToken": "your-api-token",
    "AccountId": "your-account-id"
  },
  "R2": {
    "AccessKeyId": "your-r2-access-key",
    "SecretAccessKey": "your-r2-secret-key"
  }
}

Required Permissions

Your API token needs the D1 permission at Account level:

Operation	Permission Level
List/Get databases	D1: Read
Create/Delete databases	D1: Write
Execute queries	D1: Write
Export/Import	D1: Write

Dependency Injection Setup

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCloudflareApiClient(builder.Configuration);
builder.Services.AddCloudflareR2Client(builder.Configuration); // For backup scenario

builder.Services.AddScoped<D1SyncService>();
builder.Services.AddHostedService<D1SyncBackgroundService>();

CI/CD Integration

GitHub Actions Example

Run D1 migrations from your .NET CI pipeline:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '9.0.x'

      - name: Run D1 Migrations
        env:
          Cloudflare__ApiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          Cloudflare__AccountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        run: dotnet run --project tools/D1Migrations

      # No Node.js required!

Migration Tool Example

A simple console app for running migrations:

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddCloudflareApiClient(builder.Configuration);

var host = builder.Build();
var cf = host.Services.GetRequiredService<ICloudflareApiClient>();

var databaseId = Environment.GetEnvironmentVariable("D1_DATABASE_ID")!;

// Run migrations in order
var migrations = Directory.GetFiles("migrations", "*.sql").Order();

foreach (var migration in migrations)
{
    Console.WriteLine($"Running {Path.GetFileName(migration)}...");
    var sql = await File.ReadAllTextAsync(migration);
    await cf.Accounts.D1.QueryAsync(databaseId, sql);
}

Console.WriteLine("Migrations complete.");

Error Handling

The SDK provides structured exceptions for D1 operations:

try
{
    await cf.Accounts.D1.QueryAsync(databaseId, "SELECT * FROM nonexistent");
}
catch (CloudflareApiException ex) when (ex.Errors.Any(e => e.Code == 7500))
{
    // D1 query error
    Console.WriteLine($"Query failed: {ex.Errors.First().Message}");
}
catch (CloudflareApiException ex)
{
    // Other API errors
    foreach (var error in ex.Errors)
    {
        Console.WriteLine($"[{error.Code}] {error.Message}");
    }
}

Summary

The D1 HTTP API isn't for real-time queries - use native Worker bindings for that. But for DevOps workflows, the Cloudflare.NET SDK provides a clean way to manage D1 from C#:

Scenario	What You Get
Test Data Seeding	Reset and populate D1 from xUnit setup
Reference Data Sync	Push authoritative data from your backend to the edge
Automated Backups	Export D1 to R2 without Node.js
CI/CD Migrations	Run schema changes from .NET pipelines

The key benefit: no Node.js or Wrangler required. If your team is .NET-first, you can manage D1 using your existing toolchain.

Get started:

dotnet add package Cloudflare.NET.Api

Learn more:

GitHub Repository
API Documentation
D1 API Coverage
Cloudflare R2 in .NET Without the AWS SDK Headaches - Companion article on R2 object storage

Cloudflare.NET is an open-source, community-maintained SDK. Contributions are welcome!

Cloudflare R2 in .NET Without the AWS SDK Headaches

Alexis — Sat, 20 Dec 2025 05:56:53 +0000

TL;DR: The Cloudflare.NET SDK provides IR2Client for R2 object storage with strongly-typed APIs, native dependency injection, automatic multipart uploads, and built-in operation metrics.

R2 is Cloudflare's object storage with zero egress fees. Unlike AWS S3 or Azure Blob Storage, you don't pay to download your own data.

While R2 offers S3 API compatibility and .NET developers can use the AWS SDK, the Cloudflare.NET SDK provides a streamlined .NET experience with IntelliSense, dependency injection, and automatic handling of R2-specific behaviors.

What the SDK Handles for You

When working with R2's S3-compatible API directly, there are a few things you need to know. The SDK handles these automatically:

Payload Signing Configuration

R2 requires specific S3 client settings. The official Cloudflare documentation specifies that payload signing must be disabled:

var request = new PutObjectRequest
{
    BucketName = bucketName,
    Key = objectKey,
    InputStream = stream,
    DisablePayloadSigning = true,
    DisableDefaultChecksumValidation = true
};

The SDK configures this automatically, so you never need to remember these flags.

Multipart Upload Rules

R2 has specific rules for multipart uploads:

Constraint	Value
Minimum part size	5 MiB (except the last part)
Maximum part size	5 GiB
Maximum total size	5 TiB
Maximum parts	10,000

The key rules to be aware of:

All parts except the last must be at least 5 MiB.
All parts except the last must be the same size. R2 requires uniform part sizes.
Only the last part can be smaller than 5 MiB.
The last part cannot be larger than the other parts.

The SDK validates these constraints automatically and calculates optimal part sizes for you.

Endpoint and Region Configuration

R2 uses a specific endpoint format and the region value "auto":

var config = new AmazonS3Config
{
    ServiceURL = $"https://{accountId}.r2.cloudflarestorage.com",
    ForcePathStyle = true,
    AuthenticationRegion = "auto"
};

The SDK constructs this from your configuration automatically.

Operation Metrics

R2 has a specific pricing model based on operation classes:

Class A operations (writes, lists): $4.50 per million
Class B operations (reads): $0.36 per million
Delete operations: Free

The SDK tracks these automatically. Every operation returns an R2Result with operation counts and bytes transferred.

Key Features

Here's what the SDK provides:

Strongly-Typed APIs

Full IntelliSense with XML documentation. Enums and typed models guide you through the API:

var result = await r2.UploadAsync(
    bucketName: "my-bucket",
    objectKey: "path/to/file",
    filePath: "/local/file.pdf",
    partSize: 50 * 1024 * 1024);

Simplified Configuration

Native dependency injection with appsettings.json:

builder.Services.AddCloudflareR2Client(builder.Configuration);

Production-Ready Resilience

The core API client includes automatic retries with exponential backoff, circuit breaker, and rate limiting via Polly:

builder.Services.AddCloudflareApiClient(builder.Configuration);

Operation Metrics

Every operation returns Class A/B counts and bytes transferred for cost monitoring:

var result = await r2.UploadAsync(bucket, key, filePath);

Console.WriteLine($"Class A ops: {result.ClassAOperations}");
Console.WriteLine($"Ingress: {result.IngressBytes} bytes");

Additional Features

Smart upload selection: Auto-chooses single-part vs. multipart based on file size
Multipart validation: Enforces R2's part size rules before API calls
Typed exceptions: Clear error information with partial metrics
Presigned URLs: Generate secure URLs for direct browser uploads

Installation

dotnet add package Cloudflare.NET.Api
dotnet add package Cloudflare.NET.R2

Configuration

appsettings.json

{
  "Cloudflare": {
    "AccountId": "your-cloudflare-account-id"
  },
  "R2": {
    "AccessKeyId": "your-r2-access-key-id",
    "SecretAccessKey": "your-r2-secret-access-key"
  }
}

⚠️ Security Note: Never commit secrets to source control. Use User Secrets for development and environment variables or Azure Key Vault for production.

Dependency Injection Setup

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCloudflareApiClient(builder.Configuration);
builder.Services.AddCloudflareR2Client(builder.Configuration);

var app = builder.Build();

Basic Operations

Uploading Files

public class StorageService(IR2Client r2)
{
    public async Task<R2Result> UploadAsync(string bucket, string key, string filePath)
    {
        return await r2.UploadAsync(bucket, key, filePath);
    }
}

Upload from a stream:

await using var stream = File.OpenRead(filePath);
await r2.UploadAsync(bucket, key, stream);

Downloading Files

// To file
await r2.DownloadFileAsync(bucket, key, destinationPath);

// To stream
await r2.DownloadFileAsync(bucket, key, outputStream);

Deleting Objects

// Single delete (free)
await r2.DeleteObjectAsync(bucket, "documents/old-file.pdf");

// Batch delete (up to 1,000)
await r2.DeleteObjectsAsync(bucket, new[] { "temp/file1.txt", "temp/file2.txt" });

// Clear bucket
await r2.ClearBucketAsync(bucket);

Multipart Uploads

The SDK automatically handles multipart uploads based on file size. You don't need to think about part sizing, R2's uniform-size requirement, or cleanup on failure.

// Upload a 2 GB file. Multipart happens automatically.
var result = await r2.UploadAsync(bucket, "backups/large-database.bak", filePath);

Custom Part Size

Force multipart and specify part size (clamped to 5 MiB - 5 GiB):

await r2.UploadMultipartAsync(bucket, key, filePath, partSize: 100 * 1024 * 1024);

Automatic Abort on Failure

If a multipart upload fails, the SDK automatically aborts to clean up orphaned parts:

try
{
    await r2.UploadMultipartAsync(bucket, key, filePath);
}
catch (CloudflareR2OperationException ex)
{
    Console.WriteLine($"Upload failed: {ex.Message}");
    Console.WriteLine($"Partial metrics: {ex.PartialMetrics}");
}

Presigned URLs

Generate presigned URLs for direct client uploads:

var url = r2.CreatePresignedPutUrl(bucket, new PresignedPutRequest(
    Key: "uploads/document.pdf",
    ExpiresAfter: TimeSpan.FromMinutes(15),
    ContentLength: 10 * 1024 * 1024,
    ContentType: "application/pdf"
));

Multipart Presigned URLs

For large client-side uploads, generate URLs for each part:

// Initiate multipart upload
var initResult = await r2.InitiateMultipartUploadAsync(bucket, key);
var uploadId = initResult.Data;

// Generate URLs for all parts
var urls = r2.CreatePresignedUploadPartsUrls(bucket, new PresignedUploadPartsRequest(
    Key: key,
    UploadId: uploadId,
    PartNumbers: Enumerable.Range(1, partCount).ToArray(),
    ExpiresAfter: TimeSpan.FromHours(1),
    ContentLength: partSize,
    ContentType: "application/octet-stream"
));

The SDK validates part sizes before generating URLs, catching R2's uniform-size requirement early rather than after clients attempt uploads.

Error Handling

The SDK provides typed exceptions with partial metrics:

try
{
    await r2.UploadAsync(bucket, key, filePath);
}
catch (CloudflareR2OperationException ex)
{
    Console.WriteLine($"Failed: {ex.Message}");
    Console.WriteLine($"Partial metrics: {ex.PartialMetrics}");
}
catch (CloudflareR2BatchException<string> ex)
{
    Console.WriteLine($"Failed keys: {string.Join(", ", ex.FailedItems)}");
}

Listing Objects

var result = await r2.ListObjectsAsync(bucket, prefix: "documents/");

foreach (var obj in result.Data)
{
    Console.WriteLine($"{obj.Key}: {obj.Size} bytes");
}

The SDK handles continuation tokens automatically.

Complete Example: File Upload API

A minimal file upload API using ASP.NET Core:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCloudflareApiClient(builder.Configuration);
builder.Services.AddCloudflareR2Client(builder.Configuration);

var app = builder.Build();

app.MapPost("/upload/{bucket}/{*key}", async (
    string bucket, string key, IFormFile file, IR2Client r2) =>
{
    await using var stream = file.OpenReadStream();
    var result = await r2.UploadAsync(bucket, key, stream);
    return Results.Ok(new { key, result.IngressBytes, result.ClassAOperations });
});

app.MapGet("/download/{bucket}/{*key}", async (
    string bucket, string key, IR2Client r2, HttpResponse response) =>
{
    response.ContentType = "application/octet-stream";
    await r2.DownloadFileAsync(bucket, key, response.Body);
});

app.MapDelete("/{bucket}/{*key}", async (
    string bucket, string key, IR2Client r2) =>
{
    await r2.DeleteObjectAsync(bucket, key);
    return Results.NoContent();
});

app.Run();

Multi-Account Support

builder.Services.AddCloudflareR2Client("production", options =>
{
    options.AccessKeyId = "prod-access-key";
    options.SecretAccessKey = "prod-secret-key";
});

builder.Services.AddCloudflareR2Client("staging", options =>
{
    options.AccessKeyId = "staging-access-key";
    options.SecretAccessKey = "staging-secret-key";
});

Use via factory or keyed services (.NET 8+):

// Factory pattern
public class MigrationService(IR2ClientFactory factory)
{
    public async Task MigrateAsync(string bucket, string key)
    {
        var staging = factory.CreateClient("staging");
        var production = factory.CreateClient("production");

        using var stream = new MemoryStream();
        await staging.DownloadFileAsync(bucket, key, stream);
        stream.Position = 0;
        await production.UploadAsync(bucket, key, stream);
    }
}

// Keyed services
public class ProductionService([FromKeyedServices("production")] IR2Client r2)
{
    public async Task UploadAsync(string bucket, string key, Stream data)
        => await r2.UploadAsync(bucket, key, data);
}

Bucket Management

The Cloudflare.NET.Api package provides bucket operations via the REST API for end-to-end workflows:

// Create a bucket with location hint
var bucket = await cf.Accounts.Buckets.CreateAsync("my-bucket", R2LocationHint.WestEurope);

// Get bucket details
var info = await cf.Accounts.Buckets.GetAsync("my-bucket");

// List all buckets
await foreach (var b in cf.Accounts.Buckets.ListAllAsync())
{
    Console.WriteLine($"{b.Name} - {b.Location}");
}

// Delete bucket (must be empty)
await r2.ClearBucketAsync("my-bucket");
await cf.Accounts.Buckets.DeleteAsync("my-bucket");

This enables complete infrastructure-as-code scenarios where you provision buckets, manage objects, and tear down resources programmatically.

Summary

The Cloudflare.NET SDK provides a streamlined R2 experience for .NET developers:

Feature	What You Get
Strongly-Typed APIs	Full IntelliSense with XML documentation
Simplified Configuration	One-line DI registration from `appsettings.json`
Production-Ready Resilience	Automatic retries, circuit breaker, and rate limiting
Operation Metrics	Class A/B counts and bytes transferred
Automatic Multipart	Part sizing, validation, and orchestration
Bucket Management	Create, list, and delete buckets via REST API

Get started:

dotnet add package Cloudflare.NET.Api
dotnet add package Cloudflare.NET.R2

Learn more:

Cloudflare.NET is an open-source, community-maintained SDK. Contributions are welcome!

Preparing for the IETF RateLimit Header Standard in .NET

Alexis — Sat, 20 Dec 2025 05:22:42 +0000

Running an integration test or a production job when everything starts failing with 429 Too Many Requests is frustrating. The typical response is to add some Task.Delay calls, maybe exponential backoff, and hope for the best.

But what if APIs told you exactly when to slow down, before you hit the limit?

A new standard for rate limit headers

There's an IETF draft standard that defines how APIs should communicate rate limits via HTTP headers. It's still early days, but adoption is starting: Cloudflare added support in September 2025, and more providers are likely to follow as the standard matures.

The headers look like this:

RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=15;t=23

This tells you: "You get 100 requests per 60-second window. You have 15 remaining. The window resets in 23 seconds."

That's useful information. But .NET doesn't have built-in support for parsing these headers or acting on them. Most code just waits until it hits a 429, then reacts.

Proactive instead of reactive

RateLimitHeaders is a .NET library that parses these IETF-standard headers and can automatically back off when quota gets low, before hitting a 429.

The idea is simple: if the API tells you that you have 5% of your quota left and the window resets in 30 seconds, don't fire off 50 more requests. Slow down. Spread them out.

Getting started

Install the package:

dotnet add package RateLimitHeaders

The easiest way to use it is with IHttpClientFactory:

builder.Services.AddHttpClient("GitHubApi", client =>
{
    client.BaseAddress = new Uri("https://api.github.com");
})
.AddRateLimitAwareHandler(options =>
{
    options.EnableProactiveThrottling = true;
    options.QuotaLowThreshold = 0.1; // Start slowing down at 10% remaining
});

Your HTTP client will now:

Parse rate limit headers from every response
Track your remaining quota
Automatically introduce small delays when quota gets low
Prevent 429s in the first place

Reading rate limit info directly

Sometimes you want to make decisions based on the rate limit info yourself:

var response = await httpClient.GetAsync("/api/resource");

if (response.TryGetRateLimitInfo(out var info))
{
    Console.WriteLine($"Remaining: {info.Remaining}/{info.Quota}");
    Console.WriteLine($"Resets in: {info.ResetSeconds}s");

    if (info.IsQuotaLow(0.1))
    {
        // Maybe queue this work for later instead
    }
}

Polly integration

If you're using Polly for resilience, there's a separate integration package:

dotnet add package RateLimitHeaders.Polly

It adds an AddRateLimitHeaders() extension to the resilience pipeline builder:

var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
    .AddRateLimitHeaders(options =>
    {
        options.EnableProactiveThrottling = true;
        options.OnQuotaLow = args =>
        {
            logger.LogWarning("Quota low: {Remaining}%", args.RemainingPercentage * 100);
            return ValueTask.CompletedTask;
        };
    })
    .AddRetry(new RetryStrategyOptions<HttpResponseMessage>())
    .Build();

Rate limit awareness sits alongside your retry and circuit breaker strategies. Proactive throttling prevents 429s; Polly handles recovery when things still go wrong.

Why bother?

If you already have retry logic, why add this?

Retries cost time. Every 429 means waiting for a retry delay. Proactive throttling spreads that delay out so you never stop completely.
Some APIs penalize repeat offenders. Hit rate limits too often and some APIs will temporarily ban you or reduce your quota.
Better observability. The callbacks give you visibility into your rate limit consumption before it becomes a problem.
The standard is coming. As more APIs adopt the IETF headers, your code is already prepared.