ULUKAYA.DEV

Notes

Short engineering notes and code snippets from building production AI systems on Firebase and Google Cloud. Each one is a gotcha I hit and the fix that held. 7 notes, newest first.

DateNoteTag
A Stale File in public/ Silently Shadows Its Dynamic Astro Route

Astro serves public/ before src/pages/, and a same-named static file wins with no warning at build time. My generated robots.txt and podcast feed had never once been served.

verifyNoShadowedRoutes.mjs
import { readdirSync, existsSync } from "node:fs";

// A route is shadowed when public/<name> and a src/pages/<name>.{js,ts,astro}
// generator both exist. public/ wins, so the generator is dead code.
export function findShadowedRoutes(publicDir = "public", pagesDir = "src/pages") {
  const shadowed = [];
  for (const entry of readdirSync(publicDir, { withFileTypes: true })) {
    if (entry.isDirectory()) continue;
    const generator = [".js", ".ts", ".astro"]
      .map((ext) => `${pagesDir}/${entry.name}${ext}`)
      .find((candidate) => existsSync(candidate));
    if (generator) shadowed.push({ served: `${publicDir}/${entry.name}`, dead: generator });
  }
  return shadowed;
}

const hits = findShadowedRoutes();
if (hits.length > 0) {
  for (const hit of hits) {
    console.error(`${hit.served} shadows ${hit.dead}. The generator never runs.`);
  }
  process.exit(1);
}
Astro, Static Assets, SEO
A Naive Quoted-String Regex Truncates at the First Escaped Quote

My subtitle parser used [^"]+ and stopped dead at the first escaped inner quote. One social card shipped for weeks with a two-character subtitle reading "From \".

parseQuoted.mjs
// Wrong: [^"]+ halts at the backslash-escaped quote inside the value.
const NAIVE = /subtitle:\s*"([^"]+)"/;

// Right: consume either a non-quote non-backslash character, or any
// backslash-escaped pair, so escaped quotes stay inside the capture.
const ESCAPE_AWARE = /subtitle:\s*"((?:[^"\\]|\\.)*)"/;

export const unescape = (value) =>
  value.replace(/\\(["\\nt])/g, (_, ch) =>
    ({ n: "\n", t: "\t" })[ch] ?? ch);

export function parseSubtitle(source) {
  const match = source.match(ESCAPE_AWARE);
  return match ? unescape(match[1]) : null;
}
Regex, Build Tooling, Node.js
Atomic Idempotency Key Enforcement for Multi-Turn Agent Tool Calling

When autonomous agents execute external tool calls (such as payment triggers or cloud resource provisioning), network blips or TCP disconnects frequently cause the agent client to retry the request.

idempotencyMutex.ts
// Atomic Idempotency Check in Cloud Firestore
export async function withIdempotency(db, key, executeTool) {
  const ref = db.collection("idempotency_keys").doc(key);
  return db.runTransaction(async (tx) => {
    const doc = await tx.get(ref);
    if (doc.exists && doc.data().status === "completed") {
      return doc.data().cachedResult;
    }
    tx.set(ref, { status: "in_flight", startedAt: Date.now() }, { merge: true });
    const result = await executeTool();
    tx.set(ref, { status: "completed", cachedResult: result, completedAt: Date.now() }, { merge: true });
    return result;
  });
}
Firestore, AI Agents
TCP Chunk Tearing and Multi-Byte UTF-8 Reassembly in LLM Streams

LLM streaming endpoints emit UTF-8 text chunks over HTTP/2 or Server-Sent Events (SSE). Because TCP packet boundaries operate independently of UTF-8 character encoding, multi-byte sequences can tear cleanly across chunk boundaries.

streamDecoder.js
import { StringDecoder } from "node:string_decoder";

export async function* decodeSafeStream(rawByteStream) {
  const decoder = new StringDecoder("utf8");
  for await (const chunk of rawByteStream) {
    // StringDecoder preserves trailing partial UTF-8 bytes across iterations
    const safeText = decoder.write(chunk);
    if (safeText) yield safeText;
  }
  const finalChunk = decoder.end();
  if (finalChunk) yield finalChunk;
}
Streaming, Node.js
Enforcing Firebase App Check on Cloud Run Endpoints Without SDK Wrappers

When deploying standalone containers on Cloud Run, you can verify incoming Firebase App Check JWTs at the Envoy ingress layer or inside Express/Fastify middleware by verifying the token against Google's public JWKS.

appCheckMiddleware.ts
import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://firebaseappcheck.googleapis.com/v1/jwks"));

export async function verifyAppCheck(req, reply) {
  const token = req.headers["x-firebase-appcheck"];
  if (!token) {
    return reply.status(401).send({ error: "Missing App Check token." });
  }
  try {
    await jwtVerify(token, JWKS, {
      issuer: "https://firebaseappcheck.googleapis.com/v1",
      audience: `projects/${process.env.GCP_PROJECT_NUMBER}`,
    });
  } catch (err) {
    return reply.status(401).send({ error: "Invalid App Check verification." });
  }
}
Cloud Run, App Check
Atomic Firestore Token Bucket Increments Under Concurrency

To prevent client retry loops from overwhelming per-UID token allowances, do not use read-then-write transactions. Instead, use FieldValue.increment(consumedTokens) within a Firestore document update.

tokenCounter.ts
import { FieldValue } from "firebase-admin/firestore";

export async function recordTokenUsage(db, userId, promptTokens, completionTokens) {
  const ref = db.collection("token_usage").doc(userId);
  await ref.set(
    {
      promptTokens: FieldValue.increment(promptTokens),
      completionTokens: FieldValue.increment(completionTokens),
      totalInvocations: FieldValue.increment(1),
      lastUpdated: FieldValue.serverTimestamp(),
    },
    { merge: true }
  );
}
Firestore, Tokenomics
Preventing Prompt Loop Quota Exhaustion with 402 HTTP Circuit Breakers

When a Google Cloud Spend Cap fuses, new API calls return a quota error. If your agent does not catch this explicitly, it can crash mid-execution and leave database state partially mutated.

circuitBreaker.ts
export async function callWithSpendCapGuard(apiCall) {
  try {
    return await apiCall();
  } catch (err) {
    if (err.status === 429 || err.code === "RESOURCE_EXHAUSTED") {
      const error = new Error("Spend cap reached or quota exhausted. Safe checkpoint created.");
      error.statusCode = 402;
      error.isFatalQuota = true;
      throw error;
    }
    throw err;
  }
}
Cloud Billing, Gemini API, Tokenomics