Brails / Supabase example code and offline checks

Download the Brails / Supabase examples ZIP. Extract the archive before following the commands below.

brails-check.mjs is the original helper preserved without changes. Import it into a Deno-based, operator-only diagnostic path to check a selected QuotaGuard route before an authorized Brails sandbox read.

Files

There is no package install step or third-party runtime dependency in the helper. The mock suites use Node’s built-in test and assertion modules. The actual HTTP client is Deno-specific.

Signature

checkBrailsSandbox(mode = "echo")

Only echo and wallets are accepted. Omitting the argument selects the echo. No argument can select a different destination, method, token source or arbitrary URL.

Configuration contract

QUOTAGUARD_PROXY_URL must be a complete HTTP or HTTPS proxy URL. The helper requires credentials, a standard QuotaGuard subdomain and no path/query/fragment beyond the root slash. It passes the URL origin separately from the decoded basic-auth credentials.

QUOTAGUARD_EXPECTED_IPS must contain exactly two distinct syntactically valid IPv4 addresses. This format validation does not prove ownership, allocation, routability or provider approval; the operator supplies the actual subscription pair.

BRAILS_SANDBOX_API_KEY is required only for wallets. It is read before the echo in that mode, so missing token configuration produces no fetch. The token is attached only to the fixed Brails request.

Result contract

// echo
{ echoEgressIp: "192.0.2.10" }

// wallets, illustrative HTTP success
{
  echoEgressIp: "192.0.2.10",
  brailsStatus: 200,
  brailsHttpOk: true
}

The documentation address and status here illustrate shape only. echoEgressIp deliberately names the echo observation rather than claiming the Brails connection used that exact address.

brailsHttpOk follows the response’s HTTP success flag. A non-2xx status returns false; it does not itself cause the helper to throw. Since the body is canceled, no Brails business-state field is inspected.

Failures and resource lifecycle

The helper sanitizes caught errors to one of three stages: configuration, IP echo or Brails sandbox. It does not expose the caught exception’s message. The surrounding operator workflow should catch thrown failures and separately inspect brailsHttpOk on returned wallet results.

Each call creates a client and closes it in finally. Echo JSON is consumed on success; a non-success echo body is canceled. Every received wallet body is canceled before return, whether the HTTP status is success or failure. The code does not fetch a direct URL as a fallback after proxy failure.

Both requests reject redirects and retain default certificate validation. Timeout signals are set to 10,000 milliseconds per request. The mock tests assert the signal is supplied; they do not simulate a real network clock or TLS handshake.

Install and invoke

Copy the preserved module into supabase/functions/_shared/brails-check.mjs. From an existing operator function in the adjacent directory:

import { checkBrailsSandbox } from "../_shared/brails-check.mjs";

// Invoke only after the existing operator authorization has succeeded.
const routing = await checkBrailsSandbox("echo");

The comment marks an application requirement, not an implemented authentication mechanism. Do not paste this into an unauthenticated handler. No new handler is supplied because the existing application’s authorization boundary should remain authoritative.

When the operator is separately authorized to read the sandbox account, the same import supports await checkBrailsSandbox("wallets"). Neither mode creates a payout.

Run the offline suites

From the downloaded examples root:

node --check code/brails-check.mjs
node --test code/brails-check.offline.test.mjs
node --test code/brails-check.supplementary.test.mjs

The tests replace global Deno and fetch; all addresses, users and tokens in the tests are fixtures. No API account is needed. Do not replace those fixture values with real credentials.

Keep the boundary when adapting

If your application needs production API calls, a custom proxy hostname, additional destinations, pooling or a separate SDK adapter, implement and review that work outside this preserved helper. Keep destination allowlists, credential separation, authorization, timeout behavior, response cleanup and explicit routing visible in the review. Do not turn the diagnostic into a general-purpose fetch endpoint or use it to forward a caller-supplied URL.

See the technical guide and troubleshooting reference for the deployment workflow.