From 9686cbc1c2a1de1d9080df182f0a563d016d723c Mon Sep 17 00:00:00 2001 From: Dami Date: Fri, 4 Sep 2026 15:09:15 -0600 Subject: [PATCH 1/3] scripts: margin projections separate socket messages from requests and label unmodeled host costs --- scripts/ops/margin.mjs | 27 ++++++++++++++++----------- test/unit/margin.test.ts | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 11 deletions(-) create mode 100644 test/unit/margin.test.ts diff --git a/scripts/ops/margin.mjs b/scripts/ops/margin.mjs index a4691f5..9f39e6f 100644 --- a/scripts/ops/margin.mjs +++ b/scripts/ops/margin.mjs @@ -12,10 +12,10 @@ import { readFileSync } from "node:fs"; const args = Object.fromEntries(process.argv.slice(2).map((a, i, all) => (a.startsWith("--") ? [a.slice(2), all[i + 1] && !all[i + 1].startsWith("--") ? all[i + 1] : "true"] : [])).filter((x) => x.length)); -const TARGET = Number(args.target ?? 0.33); // margin on revenue: 0.33 is a 1.5x markup +const TARGET = Number(args.target ?? 0.33); // gross margin on revenue; price is cost / (1 - target) const FLOOR = Number(args.floor ?? 0.2); // below this, reprice now -// Cloudflare list prices, Workers Paid, USD. Checked 2026-09-03 against +// Cloudflare list prices, Workers Paid, USD. Checked 2026-09-04 against // developers.cloudflare.com/{durable-objects/platform,r2,workers/platform}/pricing. const CF = { base: 5, // per month, the plan itself @@ -79,7 +79,7 @@ for (const l of lines) { let out = []; out.push(`# Fuel margins at $${n(btc)} per bitcoin`, ""); -out.push(`Target margin ${pct(TARGET)} of revenue (a ${(1 / (1 - TARGET)).toFixed(2)}x markup). Reprice when a line falls under ${pct(FLOOR)}.`, ""); +out.push(`Target gross margin ${pct(TARGET)} of revenue (price is cost / ${(1 - TARGET).toFixed(2)}; ${pct(1 / (1 - TARGET) - 1)} markup on cost). Reprice when a line falls under ${pct(FLOOR)}.`, ""); out.push("| Line | Cloudflare cost | Cost in sats | Our price | Margin | Target holds while BTC is above | Price for target today |"); out.push("|---|---|---|---|---|---|---|"); for (const l of lines) { @@ -101,10 +101,11 @@ out.push(`The plan includes ${n(coveredHours)} awake hours, ${n(CF.rowsWrittenIn // Lines nobody pays for: requests, reads, R2 operations, KV. Absorbed by margin. out.push("## What is not priced", ""); -out.push("Traffic is free to relays, but Cloudflare bills these. They come out of the margin on the four lines above.", ""); +out.push("Traffic has no fuel price, but Cloudflare bills these. They consume margin on the four lines above. This is a partial, pro-rata projection, not an invoice: DO compute and R2 billing-unit rounding are omitted. Worker CPU, logs, traces, Analytics Engine, KV usage, custom hostnames, payment fees, support and additional retry or maintenance work also need separate budgets.", ""); out.push("| Line | Cloudflare cost | Included per month |"); out.push("|---|---|---|"); -out.push(`| Durable Object requests (every websocket message, HTTP request and alarm) | $${CF.doRequestsPerM} per million | ${n(CF.doRequestsIncluded)} |`); +out.push(`| Durable Object requests (HTTP, RPC and alarms) | $${CF.doRequestsPerM} per million | ${n(CF.doRequestsIncluded)} |`); +out.push(`| Durable Object inbound WebSocket messages (20:1 request ratio) | $${CF.doRequestsPerM} per million billable requests | included with DO requests |`); out.push(`| Worker requests | $${CF.workerRequestsPerM} per million | ${n(CF.workerRequestsIncluded)} |`); out.push(`| rows read | $${CF.rowsReadPerM} per million | ${n(CF.rowsReadIncluded / 1e9)} billion |`); out.push(`| R2 writes (class A) | $${CF.r2ClassAPerM} per million | ${n(CF.r2ClassAIncluded)} |`); @@ -115,18 +116,22 @@ out.push(`| the plan | $${CF.base} | |`, ""); // A deployment projection: what N relays cost at a typical shape, and what the paid ones bring in. const relays = Number(args.relays ?? 1000); // Websocket messages count as object requests but never reach the Worker, so Worker requests are the HTTP door and page loads only. -const typical = { eventsGB: 0.02, mediaGB: 0.1, hours: 8, rowsM: 0.1, doReqM: 0.3, workerReqM: 0.01, rowsReadM: 5, r2AM: 0.002, r2BM: 0.02 }; -const heavy = { eventsGB: 0.5, mediaGB: 3, hours: 200, rowsM: 3, doReqM: 5, workerReqM: 0.2, rowsReadM: 100, r2AM: 0.05, r2BM: 0.5 }; +// Illustrative raw traffic mixes total 0.3M and 5M messages/requests. The +// split is an assumption, not measured traffic. Incoming socket messages +// use the 20:1 ratio; HTTP/RPC/alarms count individually. +const typical = { eventsGB: 0.02, mediaGB: 0.1, hours: 8, rowsM: 0.1, doHttpRpcAlarmM: 0.01, wsMessagesM: 0.29, workerReqM: 0.01, rowsReadM: 5, r2AM: 0.002, r2BM: 0.02 }; +const heavy = { eventsGB: 0.5, mediaGB: 3, hours: 200, rowsM: 3, doHttpRpcAlarmM: 0.2, wsMessagesM: 4.8, workerReqM: 0.2, rowsReadM: 100, r2AM: 0.05, r2BM: 0.5 }; function bill(count, heavyShare) { const h = Math.round(count * heavyShare), t = count - h; const sum = (k) => t * typical[k] + h * heavy[k]; + const doBillableRequestsM = sum("doHttpRpcAlarmM") + sum("wsMessagesM") / 20; const over = (x, inc) => Math.max(0, x - inc); const items = { "SQLite storage": over(sum("eventsGB"), CF.sqlIncludedGB) * CF.sqlGBMonth, "R2 storage": over(sum("mediaGB"), CF.r2IncludedGB) * CF.r2GBMonth, "DO duration": (over(sum("hours") * GBS_PER_HOUR, CF.doDurationIncluded) / 1e6) * CF.doDurationPerMGBs, "rows written": (over(sum("rowsM") * 1e6, CF.rowsWrittenIncluded) / 1e6) * CF.rowsWrittenPerM, - "DO requests": (over(sum("doReqM") * 1e6, CF.doRequestsIncluded) / 1e6) * CF.doRequestsPerM, + "DO requests": (over(doBillableRequestsM * 1e6, CF.doRequestsIncluded) / 1e6) * CF.doRequestsPerM, "Worker requests": (over(sum("workerReqM") * 1e6, CF.workerRequestsIncluded) / 1e6) * CF.workerRequestsPerM, "rows read": (over(sum("rowsReadM") * 1e6, CF.rowsReadIncluded) / 1e6) * CF.rowsReadPerM, "R2 operations": (over(sum("r2AM") * 1e6, CF.r2ClassAIncluded) / 1e6) * CF.r2ClassAPerM + (over(sum("r2BM") * 1e6, CF.r2ClassBIncluded) / 1e6) * CF.r2ClassBPerM, @@ -138,15 +143,15 @@ function bill(count, heavyShare) { return { items, total: Object.values(items).reduce((a, b) => a + b, 0), revenue, heavy: h }; } out.push(`## The deployment at ${n(relays)} relays`, ""); -out.push(`A typical relay: ${Math.round(typical.eventsGB * 1024)} MB of events, ${Math.round(typical.mediaGB * 1024)} MB of files, ${typical.hours} hours awake, ${typical.rowsM * 1e6 / 1000}k rows written, ${typical.doReqM}M object requests a month. A heavy one: ${heavy.eventsGB * 1024} MB, ${heavy.mediaGB} GB, ${heavy.hours} hours, ${heavy.rowsM}M rows, ${heavy.doReqM}M requests. Heavy relays pass their allowances and pay fuel; typical ones ride free.`, ""); -out.push("| Heavy share | Cloudflare bill | Fuel revenue | Net | Per relay |"); +out.push(`A typical relay: ${Math.round(typical.eventsGB * 1024)} MB of events, ${Math.round(typical.mediaGB * 1024)} MB of files, ${typical.hours} hours awake, ${typical.rowsM * 1e6 / 1000}k rows written, ${typical.doHttpRpcAlarmM}M raw DO HTTP/RPC/alarm requests plus ${typical.wsMessagesM}M inbound WebSocket messages (illustrative ${(typical.doHttpRpcAlarmM + typical.wsMessagesM / 20).toFixed(4)}M billable DO requests) a month. A heavy one: ${heavy.eventsGB * 1024} MB, ${heavy.mediaGB} GB, ${heavy.hours} hours, ${heavy.rowsM}M rows, ${heavy.doHttpRpcAlarmM}M raw DO requests plus ${heavy.wsMessagesM}M inbound WebSocket messages (illustrative ${(heavy.doHttpRpcAlarmM + heavy.wsMessagesM / 20).toFixed(4)}M billable DO requests). WebSocket messages do not count as Worker requests. Heavy relays pass their allowances and pay fuel; typical ones ride free.`, ""); +out.push("| Heavy share | Modeled provider cost | Fuel revenue | Net before omitted costs | Cost per relay |"); out.push("|---|---|---|---|---|"); for (const share of [0, 0.02, 0.05, 0.1]) { const b = bill(relays, share); out.push(`| ${pct(share)} (${n(b.heavy)} relays) | ${money(b.total)} | ${money(b.revenue)} | ${money(b.revenue - b.total)} | ${money(b.total / relays)} |`); } const b5 = bill(relays, 0.05); -out.push("", `Where the bill goes at 5% heavy: ` + Object.entries(b5.items).filter(([, x]) => x > 0.005).sort((a, b) => b[1] - a[1]).map(([k, x]) => `${k} ${money(x)}`).join(", ") + ".", ""); +out.push("", `Modeled costs at 5% heavy: ` + Object.entries(b5.items).filter(([, x]) => x > 0.005).sort((a, b) => b[1] - a[1]).map(([k, x]) => `${k} ${money(x)}`).join(", ") + ".", ""); // Repricing guidance. out.push("## Weekly check", ""); diff --git a/test/unit/margin.test.ts b/test/unit/margin.test.ts new file mode 100644 index 0000000..371aa20 --- /dev/null +++ b/test/unit/margin.test.ts @@ -0,0 +1,32 @@ +import { spawnSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const script = fileURLToPath(new URL("../../scripts/ops/margin.mjs", import.meta.url).href); +const forecast = (...args: string[]) => spawnSync(process.execPath, [script, ...args], { encoding: "utf8" }); + +describe("margin", () => { + it("uses gross margin for target prices and keeps the default target unchanged", () => { + const result = forecast("--btc", "80000", "--target", "0.4"); + expect(result.status).toBe(1); + expect(result.stdout).toContain("price is cost / 0.60; 67% markup on cost"); + expect(result.stdout).toContain("$83,333 | 417 sats"); + expect(result.stdout).toContain("$83,333 | 32 sats"); + expect(result.stdout).toContain("$87,273 | 13 sats"); + expect(result.stdout).toContain("$83,333 | 2,084 sats"); + const normal = forecast("--btc", "80000"); + expect(normal.status).toBe(0); + expect(normal.stdout).toContain("Target gross margin 33%"); + }); + + it("discounts incoming socket messages once and pools the account request allowance once", () => { + const result = forecast("--btc", "100000", "--relays", "1000"); + expect(result.status).toBe(0); + // 950 * (10k + 290k/20) + 50 * (200k + 4.8M/20) = 45.275M. + // Less one pooled 1M allowance, at $0.15/M, gives $6.64125. + expect(result.stdout).toContain("DO requests $6.64"); + // 950 * 10k + 50 * 200k = 19.5M Worker requests; frames stay in the DO. + expect(result.stdout).toContain("Worker requests $2.85"); + expect(result.stdout).toContain("not an invoice"); + }); +}); From 055f3d63d88f431ccde76948b840271d4d278960 Mon Sep 17 00:00:00 2001 From: Dami Date: Fri, 4 Sep 2026 15:09:15 -0600 Subject: [PATCH 2/3] docs: fuel accounting gaps and a proposed maintenance budget contract accompany the 40% margin scenarios --- README.md | 2 +- docs/02-understanding-fuel.md | 11 ++- docs/15-costs-and-margins.md | 152 +++++++++++++++++++++++++++++++++- src/fuel.ts | 11 +-- src/relay.ts | 9 +- 5 files changed, 164 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 3f6fc36..67c44da 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Site hosting and mirroring are on by default; Marmot and GRASP are off until ena - [Hosting bind.ws](docs/11-hosting-bindws.md): run your own on your own domain, and watch it through logs, traces and metrics. - [Hosting without Cloudflare](docs/16-hosting-without-cloudflare.md): the same Worker on celld, with your own bucket and proxy, and what "supported" promises. - [Develop and extend](docs/12-develop-extend.md): layout, tests, adding methods and NIPs, the console, the templates. -- [Costs and margins](docs/15-costs-and-margins.md): what a relay costs the host, what fuel charges, the weekly check against the bitcoin price. +- [Costs and margins](docs/15-costs-and-margins.md): tenant meters, host accounting gaps, margin scenarios and the proposed maintenance budget contract. ### Draft NIPs diff --git a/docs/02-understanding-fuel.md b/docs/02-understanding-fuel.md index bc2c742..09b2e95 100644 --- a/docs/02-understanding-fuel.md +++ b/docs/02-understanding-fuel.md @@ -26,12 +26,11 @@ charge attached to moving or storing those bytes. **Time awake** estimates how long the relay is in memory from its entrypoints. It can sleep between messages, while alarms and scheduled jobs wake it even -when no client is connected. A relay with a client connected all day is awake only while messages -pass, plus a few seconds after each. Jobs on the Sync tab, pulls, backfills and -rebroadcasts wake the relay on their own and spend this line while they run; a -standing job spends it on every run. Git requests and site work also wake the -relay, although the exact provider duration can differ from the relay's -entrypoint meter. +when no client is connected. The meter adds ten seconds after a wake, then +the gap between entrypoints capped at ten seconds. It does not time a whole +long-running job. Jobs on the Sync tab, pulls, backfills, rebroadcasts, Git +requests and site work all wake the relay. The host's actual duration cost +can be higher or lower than this estimate. Dumps, the JSONL files the Data tab can write on a schedule, live next to uploaded files and count as files stored. What each job and dump does is in [Data and names](04-data-and-names.md). diff --git a/docs/15-costs-and-margins.md b/docs/15-costs-and-margins.md index 8962864..c67f599 100644 --- a/docs/15-costs-and-margins.md +++ b/docs/15-costs-and-margins.md @@ -40,7 +40,7 @@ operation is not measured as an exact request duration. Those costs belong in the host's deployment review and margin target; they do not silently change the four meters shown to a relay owner. -For a line with cost `c` dollars per unit and price `p` sats per unit at `B` dollars per bitcoin, revenue per unit is `p / 1e8 * B` and margin is `1 - c / revenue`. The margin target is 33% of revenue, which is a 1.5x markup on cost. The floor is 20%. Under the target the weekly run flags it; under the floor, reprice. +For a line with cost `c` dollars per unit and price `p` sats per unit at `B` dollars per bitcoin, revenue per unit is `p / 1e8 * B` and margin is `1 - c / revenue`. The script defaults to a 33% margin on revenue, which prices a line at about 1.493x cost. The floor is 20%. Under the target the weekly run flags it; under the floor, review pricing. Because prices are in sats and costs in dollars, margins move with the exchange rate on their own. A rising bitcoin widens them. A falling one narrows them, and the script prints, for each line, the bitcoin price under which the target no longer holds and the price under which the floor breaks. @@ -59,7 +59,7 @@ Time awake is an hour of a Durable Object held in memory at 128 MB, which Cloudf ## The free tier -At the dated rates above, a relay that spends its whole allowance costs the host about $0.87 a month. Time awake is most of it. Storage is nearly free at these sizes. The rows allowance was a million until Sept. 2026, which made it $1.00 of a $1.61 tier; it came down to 250,000, about 15 times what a personal relay writes, because rows are the one line Cloudflare charges real money per unit. +At the dated rates above, a relay that spends its whole allowance costs the host about $0.86 a month. Time awake is most of it. Storage is nearly free at these sizes. The rows allowance was a million until Sept. 2026, which made it $1.00 of a $1.61 tier; it came down to 250,000, about 15 times what a personal relay writes, because rows are the one line Cloudflare charges real money per unit. | Allowance | Amount | Cost | |---|---|---| @@ -72,9 +72,9 @@ Few relays get near the allowance. At the dated rates above, a typical personal ## The deployment -The script projects a fleet from two shapes, a typical relay and a heavy one that passes its allowances and pays fuel, at a chosen share of heavy relays. In the dated 1,000-relay example with 5% heavy, the Cloudflare bill is about $420 a month, fuel brings in about $280, and the gap is the free tier. Rows written are the largest modeled line on the bill, then duration. The fleet projection includes platform requests, rows read and R2 operations as host costs even though these have no separate tenant price. It lists KV read pricing, but does not project site-index KV usage or custom-hostname fees. +The script projects a fleet from two illustrative shapes, a typical relay and a heavy one that passes its allowances and pays fuel, at a chosen share of heavy relays. These are assumptions, not measured customer workloads or a validated provider bill. The fleet projection includes platform requests, rows read and R2 operations as host costs even though these have no separate tenant price. Worker CPU, logs, traces, Analytics Engine, site-index KV operations, custom-hostname fees, payment fees and support still need deployment measurements or separate budgets. -Two things follow. The free tier is a cost the paid relays and the host share, and its size is the lever: `FREE_ROWS_WRITTEN` is the expensive allowance. And the unpriced provider lines, especially request operations, are real; the 33% target exists to absorb them, which is why the target is not lower. +The free tier is a cost the paid relays and the host share. Unpriced operations consume part of the margin on paid usage. A target on four priced lines alone does not establish a fleet margin after free users and shared costs. The bounded GRASP implementation adds a relay-wide ceiling of 320 MiB for retained Git objects, with 4 MiB packs, 16 MiB packed history and bounded @@ -100,3 +100,147 @@ The workflow is `.github/workflows/margin.yml`. Read the summary. When a line is 3. Deploy. Fuel meters are unchanged; only the price of what is over the allowance moves, from the next charge. Prices go up when bitcoin falls. When it rises, do nothing until a line has sat above twice the target for a month, then bring it down. Relay owners see prices on the front page and on their Fuel section, so every change is visible the moment it deploys. The table above was checked on Sept. 3, 2026; rerun `npm run margin` and verify current provider pricing before using it for a new forecast. + +## Accounting coverage, checked Sept. 4, 2026 + +The following inventory describes the host with ntig 0.1.1. Observing an +expense does not authorize a new customer charge. `/fuel` and the Health tab +expose aggregate tenant meters, not every operation the host pays for. + +| Dimension | Existing source and persistence | Coverage limit | +|---|---|---| +| Usage and credits | [Fuel](../src/fuel.ts), monthly SQLite usage and unique receipt IDs | Counters become durable only after a flush; receipts prevent duplicate credit | +| SQLite storage | `Relay.eventBytes`, the database's allocated size | Includes tables beyond events; daily charging uses the current size, not a continuous storage integral | +| R2 storage | `Relay.mediaBytes`, blobs + dumps + imports + `grasp_objects` | Shared allowance; retained history and conservative reservations can outlive visible refs | +| Awake time | `Relay.touch`, in-memory ten-second entrypoint gaps | No handler completion timing; long async work, idle gaps and restart estimates differ from provider duration | +| SQL rows | [Store](../src/store.ts), cursors from `Store.x`, then `Relay.tally` | Direct SQL in settings, GRASP, sites, media and other modules bypasses the meter; DO key-value and alarm work is not covered | +| Traffic | `Relay.meterBytes` and socket counters, then monthly usage | No fuel price; socket string lengths and attempted/produced HTTP bytes are not exact delivered wire bytes | +| Requests | [Worker routing](../src/index.ts), HTTP, RPC, sockets and alarms | No durable per-tenant request ledger; application REQ counters are not platform request counts | +| R2 operations | [Git object wrapper](../src/grasp.ts), [Blossom](../src/blossom.ts), [site mirrors](../src/site-mirror.ts) and dumps | No durable per-tenant Class A/B ledger; observer callbacks are best-effort evidence | +| Jobs and alarms | [Jobs](../src/jobs.ts) and `Relay.alarm` | Required cleanup, mirrors and retries consume host work; no optional maintenance budget exists | +| KV and external services | [Host routing](../src/edge.ts), [site index](../src/sites.ts), notifications and provider fetches | No tenant operation meter for reads, writes, misses, retries or external fees | +| Observability | `Relay.flushUsage`, console deltas and optional Analytics Engine | Logs, traces and analytics are expense and diagnosis sources, not the durable fuel ledger | + +[Relay](../src/relay.ts) batches usage in memory. A restart can lose an +unflushed batch. `flushUsage` resets counters before `Fuel.record`; a failed +record can therefore lose that batch too. Its final `Store.drain` discards +pending cursors, so a direct flush without `tally` can omit rows. Usage is +assigned to the month of the flush rather than split across the work's month +boundary. These are accounting gaps, not grounds for reconstructing charges +against old tenant balances. + +Git reserves the larger retained object size in SQLite before PUT. Success +reconciles the size; a definite CAS loss uses HEAD to reconcile it. An +exception leaves the reservation because the write may have succeeded. No +automatic reconciliation queue or orphan collector exists. Counting PUT +bytes again as stored bytes would double-charge existing media accounting. +Future temporary packs also need reservations while both copies exist. + +`graspBusy`, `graspControls` and the job round's `working` flag fence work +within a live instance. Async handlers can interleave across awaits. Those +flags are admission controls, not persisted crash recovery or authority to +delete data. Repository CAS and persisted authority remain necessary. + +Provider request accounting separates HTTP/RPC/alarm invocations from +incoming WebSocket messages, which have a 20:1 billing ratio. Socket frames +do not become Worker requests. DO duration counts overlapping work once per +object; idle objects eligible for hibernation have no duration charge. +DO key-value operations and alarm writes also consume SQLite rows. Included +allocations and billing-unit rounding apply at account level. +See [Durable Object pricing](https://developers.cloudflare.com/durable-objects/platform/pricing/). + +R2 Standard includes pooled storage and operation allowances. Beyond them, +storage is $0.015/GB-month, Class A operations $4.50/million and Class B +$0.36/million, with billing-unit rounding. Free egress does not remove those +operation costs. See [R2 pricing](https://developers.cloudflare.com/r2/pricing/). +[Workers pricing](https://developers.cloudflare.com/workers/platform/pricing/), +[KV pricing](https://developers.cloudflare.com/kv/platform/pricing/) and +[Cloudflare for SaaS plans](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/plans/) +cover other host expenses. These sources were checked on Sept. 4, 2026. + +## A 40% margin scenario + +This is a planning target; the deployed rates, allowances and weekly default +remain unchanged. A 40% gross margin means `price = cost / 0.60`, or about +1.667x cost. Multiplying cost by 1.40 produces only a 28.57% margin. + +``` +npm run margin -- --btc 60000 --target 0.40 +npm run margin -- --btc 80000 --target 0.40 +npm run margin -- --btc 100000 --target 0.40 +``` + +These are Sept. 4 planning scenarios, not bitcoin spot quotes. At the +current sats rates, before free users and other expenses: + +| BTC scenario | Events, files and rows margin | Awake margin | +|---|---|---| +| $60,000 | 16.67% | 12.73% | +| $80,000 | 37.50% | 34.55% | +| $100,000 | 50.00% | 47.64% | + +The 40% threshold is about $83,333/BTC for events, files and rows, and +$87,273/BTC for awake time at $0.00576 per provider hour. The script already +uses gross margin; its existing 33% default was never a 40% markup formula. + +For a whole deployment, the planning condition is +`revenue >= (provider bill + shared operating costs + subsidy) / 0.60`. +The subsidy is only free-user cost not already included in the provider bill; +counting it twice overstates expense. Provider allocations are pooled once, +including other services on the account, rather than granted anew per relay. + +An illustrative personal relay consumes about $0.152 of the four resource +lines at marginal list rates: 20 MB events, 100 MB files, eight provider hours +and 100,000 written rows. A relay consuming all current allowances reaches +about $0.861 before other costs and account rounding. Actual duration and row +usage must come from provider evidence because the tenant meters are partial. + +Storage-light workloads can still be expensive. One million Class A and ten +million Class B operations beyond the pooled allocation cost $8.10 even if +they repeatedly access only a few kilobytes. Across 100 such relays that is +$810 before duration, requests or rows; storage revenue alone cannot cover it. +A fleet forecast therefore needs active tenant share, utilization, operation +mix, cache misses, retries and concentration in its busiest tenants, alongside +FX and payment-fee sensitivity. The script's two shapes do not establish this +distribution. + +## What can be bundled + +These are proposed operating boundaries, not new allowances or charges. + +| Work | Proposed treatment | +|---|---| +| Bounded metadata and health reads during ordinary use | Bundled with request and abuse caps; no separate tiny surcharge | +| Service-caused retries and ambiguous-write reconciliation | Host operating budget; record attempts and expense without charging a second logical operation | +| Existing retained data | Existing storage meter, including reserved and temporary bytes; no second Git storage charge | +| Free tenants | Explicit monthly fleet subsidy budget with utilization and heavy-tail review | +| High-volume scans, repeated cold clones and uncached site fetches | Bounded work and request quotas; operation-heavy use cannot be treated as unlimited because bytes are unpriced | +| Optional optimization | Tenant-visible budget and deferral; extra wake-ups require opt-in | + +## Proposed maintenance contract + +ntig 0.1.1 has no resumable optimization runner. No maintenance job, budget +setting, wake schedule, format migration or garbage collection is enabled by +this contract. Existing ref cleanup, retention and alarms keep their current +roles. An eventual integration has these boundaries: + +| Stage | Host and backend contract | +|---|---| +| Eligibility | Cheap stored statistics identify pack/read amplification, reclaimable bytes or a limit approaching; no daily full scan or unconditional repack | +| Admission | Optional work starts only while the tenant is already active by default; foreground requests take priority before each bounded step | +| Reservation | A durable job ID and UTC budget month reserve bounded work, operation counts and temporary retained bytes before execution | +| Execution | A resumable cursor, bounded I/O and a cooperative deadline limit each step; a timer alone cannot preempt arbitrary work safely | +| Completion | Persist outcome and actual expense once per step; stable attempt IDs separate retries from completed logical work | +| Recovery | A crash or ambiguous write keeps its reservation until reconciliation; CAS and persisted authority protect state across restarts | +| Scheduling | Extra wakes require opt-in, a monthly budget and an allowed window; later window, manual run and pause are separate choices | +| Exhaustion | Optional work defers; a write that cannot safely fit a hard limit fails clearly without discarding protected data | +| Retention | Optimization never authorizes deleting retained history; reachability, readers and retention rules need a separate proof | + +Host expense accounting stays separate from tenant charge calculation. A +future duration observer measures the union of registered work intervals, +including long steps, without claiming it is the provider's entire active +lifetime. Its validation covers overlap, mid-step flush, month boundaries, +crash before and after persistence, retries, reservation exhaustion and +foreground arrival. The host contract also needs tests for ambiguous PUT, +temporary copies, authority changes and paused scheduling before it runs +against customer data. diff --git a/src/fuel.ts b/src/fuel.ts index f79066e..a90eb43 100644 --- a/src/fuel.ts +++ b/src/fuel.ts @@ -1,7 +1,8 @@ // Fuel: quotas on what a relay costs to run, topped up by zaps. Four things -// are metered and priced, each mirroring a line on the Cloudflare bill: -// events stored (SQLite), media stored (R2), time awake (Durable Object -// duration) and rows written. Traffic is metered but free, as it is for us. +// are metered and priced using related Cloudflare resource rates: +// events stored (SQLite), media stored (R2), estimated time awake and +// metered rows written. Traffic has no fuel price; provider operations +// attached to traffic remain host costs. These meters are not an invoice. // Every relay gets a free monthly allowance of each; beyond it, usage burns // sats credited by NIP-57 zap receipts that arrive at the relay itself as // ordinary events. Receipts are @@ -21,8 +22,8 @@ export interface FuelConfig { servicePubkey: string; // recipient pubkey zap requests must name // Free per relay per month. freeEventsMB: number; // SQLite: events, tags, search index - freeMediaMB: number; // R2: Blossom blobs - freeActiveHours: number; // wall-clock time the object is awake + freeMediaMB: number; // R2: blobs, dumps, imports and retained Git objects + freeActiveHours: number; // the relay's entrypoint-based awake estimate freeRowsWritten: number; // SQLite rows written // Beyond the allowances. Each tracks what Cloudflare bills for the same // thing, so the prices in wrangler.jsonc are set from those rates. diff --git a/src/relay.ts b/src/relay.ts index 9c99c5b..d44be07 100644 --- a/src/relay.ts +++ b/src/relay.ts @@ -100,7 +100,7 @@ export const IP_LIMIT_MULTIPLE = 4; function clientIP(req: Request): string { return req.headers.get("x-relay-ip") || "unknown"; } -// How long Cloudflare keeps an idle object awake before hibernating it. +// The legacy fuel estimate caps entrypoint gaps at this window. const IDLE_GRACE_MS = 10_000; export class Relay extends DurableObject { @@ -201,10 +201,9 @@ export class Relay extends DurableObject { this.meter.bytesOut += bytesOut; } - // touch accounts for the object being awake. Cloudflare bills wall-clock - // time from a wake until the object has been idle for about ten seconds - // and hibernates, so each piece of work is charged the gap since the last - // one, capped at that idle window, and a wake is charged the window once. + // touch estimates awake time from entrypoint gaps, with one window on wake. + // It does not measure long handlers or Cloudflare's billable duration: + // idle objects eligible for hibernation incur no provider duration charge. private touch() { const t = Date.now(); this.meter.activeMs += this.lastActive === 0 ? IDLE_GRACE_MS : Math.min(t - this.lastActive, IDLE_GRACE_MS); From 119725b6a80b4c435763e485b6ea9a1e3a4b931a Mon Sep 17 00:00:00 2001 From: Dami Date: Fri, 4 Sep 2026 15:24:28 -0600 Subject: [PATCH 3/3] test: all PR ref operations wait through temporary Git alarm contention --- test/object/grasp.test.ts | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/test/object/grasp.test.ts b/test/object/grasp.test.ts index 47a1312..53f5250 100644 --- a/test/object/grasp.test.ts +++ b/test/object/grasp.test.ts @@ -34,10 +34,12 @@ const receivePack = (path: string, host: string, old: string | null, next: strin headers: { "content-type": "application/x-git-receive-pack-request" }, body: concat(packet(`${old ?? "0".repeat(40)} ${next ?? "0".repeat(40)} ${ref}\0report-status\n`), flush(), ...(pack ? [pack] : [])), }); +// receiveSettled waits for transient alarm contention before testing the Git response. const receiveSettled = async (path: string, host: string, old: string | null, next: string | null, ref: string, pack?: Uint8Array) => { for (let attempt = 0; attempt < 20; attempt++) { const response = await receivePack(path, host, old, next, ref, pack); if (response.status !== 429) return response; + await response.arrayBuffer(); await new Promise((resolve) => setTimeout(resolve, 10)); } throw new Error("Git transaction did not become available"); @@ -214,10 +216,10 @@ describe("GRASP", () => { expect((await c.ok(state)).ok).toBe(true); c.ws.close(); const path = gitRepositoryPath(npubEncode(pk(owner)), "pr-refs"); - expect((await receivePack(path, host, null, pack.commitID, "refs/heads/main", pack.pack)).status).toBe(200); + expect((await receiveSettled(path, host, null, pack.commitID, "refs/heads/main", pack.pack)).status).toBe(200); const realPR = ev(owner, KIND_GIT_PR, "", [["a", `30617:${pk(owner)}:pr-refs`], ["c", pack.commitID]]); const unknownRef = `refs/nostr/${realPR.id}`; - expect((await receivePack(path, host, null, pack.commitID, unknownRef, pack.pack)).status).toBe(200); + expect((await receiveSettled(path, host, null, pack.commitID, unknownRef, pack.pack)).status).toBe(200); expect(await (await SELF.fetch(`http://${host}${path}/info/refs?service=git-upload-pack`)).text()).toContain(`${pack.commitID} ${unknownRef}`); const deletion = await receiveSettled(path, host, pack.commitID, null, unknownRef); expect(deletion.status).toBe(200); @@ -225,20 +227,20 @@ describe("GRASP", () => { const late = await WS.connect(host); expect((await late.ok(realPR)).ok).toBe(true); - expect((await receivePack(path, host, pack.commitID, pack.commitID, "refs/heads/main")).status).toBe(200); + expect((await receiveSettled(path, host, pack.commitID, pack.commitID, "refs/heads/main")).status).toBe(200); expect((await late.req({ ids: [realPR.id] })).map((e) => e.id)).toEqual([realPR.id]); const listed = await SELF.fetch(`http://${host}${path}/info/refs?service=git-upload-pack`); expect(await listed.text()).toContain(`refs/nostr/${realPR.id}`); const wrongPR = ev(owner, KIND_GIT_PR, "", [["a", `30617:${pk(owner)}:pr-refs`], ["c", "b".repeat(40)]]); const wrongEvent = await WS.connect(host); expect((await wrongEvent.ok(wrongPR)).ok).toBe(true); - const mismatch = await receivePack(path, host, null, pack.commitID, `refs/nostr/${wrongPR.id}`); + const mismatch = await receiveSettled(path, host, null, pack.commitID, `refs/nostr/${wrongPR.id}`); expect(await mismatch.text()).toContain(`ng refs/nostr/${wrongPR.id}`); wrongEvent.ws.close(); const expiringID = "c".repeat(64); const expiringRef = `refs/nostr/${expiringID}`; - expect(await (await receivePack(path, host, null, pack.commitID, expiringRef, pack.pack)).text()).toContain(`ok ${expiringRef}`); + expect(await (await receiveSettled(path, host, null, pack.commitID, expiringRef, pack.pack)).text()).toContain(`ok ${expiringRef}`); await runInDurableObject(env.RELAY.getByName(host.split(".")[0]), (relay) => { relay.sql.exec("UPDATE grasp_pr_refs SET until=0 WHERE repo=? AND ref=?", `30617:${pk(owner)}:pr-refs`, expiringRef); });