DEV Community: Xiantao Cai

My quote feed returns two premium numbers. I only show one when they agree.

Xiantao Cai — Wed, 07 Oct 2026 18:20:26 +0000

Over a week-long holiday I built a small dashboard for a narrow problem: investors in mainland China who want US index exposure.

The context: many onshore Nasdaq-100 funds now cap purchases at ¥5–100 a day, or have paused them entirely. Demand moved to exchange-traded ETFs, and on Sep 30 the 12 Nasdaq-100 ETFs listed in China were trading 10.3–15.4% above their indicative NAV (IOPV). Put ¥10,000 in and you pay roughly ¥935–1,335 more than the underlying assets are worth.

The page itself is simple: a list of ETFs sorted by that premium. The hard part is that every number comes from free public endpoints that lag, rate-limit and change shape without notice. A wrong number on a page like this costs readers real money, so a surprising amount of the code exists to decide when not to show a number.

Three pieces of it.

1. Two numbers from the same response must agree

The quote endpoint returns one ~-separated string per ticker. Field 3 is the last price, field 78 is the IOPV, and field 77 is the source's own premium. I compute the premium myself and only accept the IOPV when my number matches theirs:

const iopv = Number(fields[78]);
const reported =
  fields[77] !== "" && fields[77] !== undefined ? Number(fields[77]) : NaN;
const calculated = positive(iopv) ? (price / iopv - 1) * 100 : null;
// Cross-check both fields before accepting the reference value.
const validReference =
  calculated !== null &&
  Number.isFinite(reported) &&
  Math.abs(calculated - reported) <= 0.05;

return {
  // ...price, bid/ask, turnover, quote time...
  iopv: validReference ? iopv : null,
  premiumPercent: validReference ? calculated : null,
};

Price and IOPV come out of the same response, so at least they describe the same moment. If the two premiums disagree by more than 0.05 percentage points, something upstream is off (a stale field, a shifted column), and the card says "IOPV unavailable" instead of showing a confident-looking number.

The same rule carries into the ranking. Without a usable IOPV, a card falls back to the last published NAV, labelled as such, and is sorted in a separate group. A day-old NAV next to a live price makes the premium look bigger or smaller than it really is, so the two never share one list. There's a test with exactly that name:

test("ETF premium preserves unknowns and does not mix IOPV with lagged NAV in rankings", () => {
  // ...
});

2. A failed fetch must not look like fresh data

Every API route is the same small wrapper around a loader (lightly trimmed):

export function createFeedHandler(loader, ttlSeconds, mergePayload = (prev, next) => next) {
  let lastGood = null;
  let pending = null;
  let expires = 0;

  async function retrieve() {
    if (lastGood && Date.now() < expires) return lastGood;
    if (pending) return pending;
    pending = (async () => {
      try {
        const value = await loader();
        lastGood = mergePayload(lastGood, {
          ...value,
          checkedAt: new Date().toISOString(),
          stale: false,
        });
        expires = Date.now() + (value.errors?.length ? 60 : ttlSeconds) * 1000;
        return lastGood;
      } catch (error) {
        if (!lastGood) throw error;
        return {
          ...lastGood,
          stale: true,
          lastAttemptAt: new Date().toISOString(),
          error: error.message,
        };
      } finally {
        pending = null;
      }
    })();
    return pending;
  }
  // ...fetch(request) calls retrieve() and sets the headers below
}

Three things in there are deliberate:

On failure it returns the last good payload, marked stale: true, with the time of the failed attempt and the error. The data keeps its original timestamp. The UI shows that date and a stale badge; it never re-stamps old numbers with "now".
pending makes the upstream call single-flight. Concurrent requests share one fetch, which matters when the sources rate-limit.
A partial failure expires in 60 seconds instead of the full TTL (300 s for ETF quotes, 900 s for fund purchase status, a day for holdings), so a hiccup heals quickly instead of being cached for an hour.

Then the CDN headers:

// CDN expiry is explicit. No stale-while-revalidate that could hide an outage.
const headers = {
  "Cache-Control": "public, max-age=0, must-revalidate",
  "Vercel-CDN-Cache-Control": `public, s-maxage=${duration}`,
};

stale-while-revalidate is usually a fine default. Here it would let the CDN keep serving an old payload without the stale flag while revalidation fails in the background: precisely the "looks fresh, isn't" case the handler above exists to prevent.

3. Nothing is fetched while nobody is looking

There is no cron job. The server only loads data when a request arrives, and the client only polls while the tab is visible:

const check = () => {
  if (
    !document.hidden &&
    Date.now() - lastAttempt.current >= retryInterval.current
  )
    refresh();
};
const timer = setInterval(check, Math.min(config.interval, 60000));
document.addEventListener("visibilitychange", check);
window.addEventListener("online", check);
window.addEventListener("focus", check);

A background tab costs zero requests; coming back to it triggers a check immediately. Together with the shared server cache, ten readers cost the upstream about as much as one. Since the whole thing runs on public sources with no paid keys, being a polite client is part of keeping it alive.

What the page says out loud

Every card shows when its quote was taken and where it came from, with a link back to the source. Research notes are dated to the filing they cite, and refreshing prices never rewrites them.

None of this is clever. It's the lesson from my notes export post again: a pipeline that fails quietly is worse than one that fails loudly. On a page about money, "I don't know" is a valid output.

The site is live at https://nasdaq-observer.vercel.app (Chinese UI). Not investment advice, just the receipts.

Edit (Oct 10): corrected the premium range in the intro. I had originally quoted only the first few ETFs on the page.

I exported 11 years of notes through a CLI. Three of its failures looked like success.

Xiantao Cai — Wed, 23 Sep 2026 14:30:48 +0000

I wanted eleven years of my own notes as plain Markdown files, so I could grep them. Two sources: a phone notes app going back to 2015, and Youdao Note, a Chinese note service with an official command-line client.

The plan was one script: walk the folder tree, read every note, write it to disk with a little YAML frontmatter. The first run finished without an error. It was also wrong in three different ways, and none of them raised anything.

1. A flaky error that looked like "no more pages"

The CLI lists a folder 50 entries at a time; you pass the last id as a cursor to get the next page.

The server also drops the socket fairly often. My first version treated a failed list call as "this folder doesn't paginate" and moved on with what it had. Every folder with more than 50 notes was silently cut at 50. The walk finished, the totals looked plausible, nothing complained.

The fix is boring: retry the transient failure, and only stop paginating when a page comes back short.

for attempt in range(RETRIES):
    code, text = run(["list", "-f", folder_id, *cursor_args])
    if code == 0:
        break
    time.sleep(1.5 * (attempt + 1))

# ...parse entries into `page`...

if len(page) < PAGE:   # a short page is the only real "end"
    break

The rule I wrote into the docstring: a transient error and a terminal condition must never share a code path.

2. Exit code 0, body = the error message

Reading a note is youdaonote read <id>. For some notes the server answers with {"text": "获取笔记内容失败", "isError": true} ("failed to get note content"). The CLI ignores isError, prints the text to stdout, and exits 0.

So the script wrote files whose entire body was an error string. By exit code, by file count, by "did it write something": all success.

The guard has to look at the content:

ERRORS = ("获取笔记内容失败", "SSE error", "socket connection was closed")

ok = (code == 0 and text.strip()
      and not (len(text.strip()) < 400
               and any(e in text for e in ERRORS)))

The length cap is there so a real note that happens to quote one of those strings isn't thrown away.

Same place, second trap: empty notes. For a note with no body, the CLI throws an SSE connection error instead of returning an empty string. I checked each of those through a second client; they really were empty. So "failed" had to be split into empty, unreadable, and actual failures. Otherwise --only-failed keeps retrying notes that will never have content.

3. The API was never going to work for most of them

With both guards in place, the numbers were finally honest, and bad:

status	notes
readable through the API	504
server returns `isError`	1,292
empty	78
duplicates of the phone-app notes	80

The 1,292 weren't random. They were the older notes in the service's legacy .note format; everything from before 2021 came back this way. Retrying doesn't help. The server's text extraction just doesn't handle them.

What worked was the unclever path: the app's own "export everything" button. It renders legacy notes to PDF, and the text inside those PDFs is intact. So the second importer reads the export folder instead of the API:

def extract(path):
    name = path.name.lower()
    if name.endswith(".pdf"):
        import pymupdf
        with pymupdf.open(path) as doc:
            return "\n".join(pg.get_text() for pg in doc).strip(), "pdf"
    if name.endswith(".mindmap"):
        return mindmap_to_outline(path.read_text("utf-8")), "mindmap"
    return path.read_text("utf-8").strip(), path.suffix.lstrip(".")

Mind maps are JSON node trees; mindmap_to_outline walks from the root and emits an indented bullet list, which greps fine.

Where it can match on (folder, title), the importer reuses the note id from the API pass, so both passes line up; otherwise it derives a stable id from a hash of the path.

Final count from the export: 1,853 notes with a body. 1,652 from PDF, 103 mind maps, 94 Markdown. Plus 234 from the phone app: 2,087 notes, about 3.5 million characters, all greppable.

One more: trust the disk, not the manifest

The exporter runs 12 workers and takes a while, so it has to resume. The manifest of finished notes is only written at the end of a run. Hit Ctrl-C and the manifest says nothing is done, while the disk holds hundreds of files. So the resume check asks the disk:

def already(item):
    if done.get(item["id"], {}).get("status") == "ok":
        return True
    p = note_path(item)
    return p.exists() and p.stat().st_size > 0

What I'd do first next time

Pick one note you know is broken and one you know is empty. Look at exactly what the tool returns for each before writing the loop.
Count by content, not by exit code or file count.
Check the official export before the API. It was the less clever path and the only complete one.

Once everything was on disk, the payoff was immediate. The first thing I counted was punctuation: about half of my short notes don't contain a single period. That part is a different story, written up here: https://medium.com/@cxtao203/i-exported-eleven-years-of-my-own-notes-and-found-the-same-sentence-every-time-64b04dbdfc60

A container restarted 39,352 times. Every exit code was 0.

Xiantao Cai — Sat, 19 Sep 2026 07:05:01 +0000

A container on one of my servers had restarted 39,352 times. Every single exit code was 0.

That number is why nobody noticed. Monitoring watches for crashes, and this was not a crash. The process started, found nothing to do, exited successfully — and restart: unless-stopped dutifully brought it back. About 39,000 times.

This turned into one of those debugging sessions where every layer is behaving "correctly" and the system as a whole is broken. Here's the walk-through, and the one metric I now trust more than exit codes.

The successful infinite loop

The service was an MCP server running in stdio mode. In stdio mode the process talks over standard input/output — it reads requests from stdin and writes responses to stdout.

Here's the compose block, simplified:

services:
  mcp:
    image: my/mcp-server
    restart: unless-stopped
    # note what's NOT here:
    # stdin_open: true
    # tty: true

Without stdin_open (the compose equivalent of docker run -i), the container gets no open standard input. So the MCP server boots, reads from stdin, and immediately hits EOF. There's nothing to read and never will be. It does the correct thing on EOF: it shuts down cleanly and exits 0.

restart: unless-stopped sees a stopped container and restarts it. The new process boots, reads stdin, hits EOF, exits 0. Restart. Boot. EOF. Exit 0. Restart.

Every individual decision in that loop is right. The process should exit when its input stream closes. The restart policy should revive a service that stopped without being told to. Compose it together and you get a clean, successful, infinite loop that a crash-based alert will never fire on.

The fix is one line — give it a stdin to hold open:

    stdin_open: true
    tty: true

But the fix isn't the interesting part. The interesting part is why it stayed invisible for 39,352 iterations.

The health signal was inverted in both directions

While I was in there, I looked at the other containers on the same box. Two of them had been marked unhealthy for four weeks. Both were completely fine the whole time.

Health check #1 probed a port that nothing in the container listens on. The service was up; the check was pointed at the wrong door.
Health check #2 connected to localhost from a Node 18 process. Since Node 17, Node no longer reorders DNS results, so localhost resolves to IPv6 ::1 first. The service bound IPv4 only. Result: ECONNREFUSED, forever — against a service that was answering fine on 127.0.0.1.

// Node 18+: this can resolve to ::1 and miss an IPv4-only server
const res = await fetch("http://localhost:3000/health");

// Force IPv4 if that's what your service binds:
const res = await fetch("http://127.0.0.1:3000/health");

So on one machine, at the same time:

Two containers screaming unhealthy that were serving traffic perfectly.
One container reporting exit 0 that was broken and had been for tens of thousands of restarts.

The health signal wasn't just wrong. It was inverted in both directions at once. If I'd trusted it, I'd have "fixed" the two healthy ones and never looked at the broken one.

What I actually changed

stdin_open: true + tty: true for the stdio service.
Health check #1 repointed at a port the service actually listens on.
Health check #2 switched to 127.0.0.1 (and I now treat "works in docker run, fails in a health check" as an IPv4/IPv6 smell).
An alert on restart count velocity — restarts per hour — independent of exit code.

That last one is the takeaway.

Exit code 0 is not a success signal

Exit 0 only tells you the process agreed to leave. It does not tell you it should have.

Restart count, by contrast, is honest. A number that climbs into the thousands means something is wrong regardless of how politely each instance exited. It's a better smoke alarm than exit code, and a far better one than a health check that can be pointed at the wrong port or the wrong IP stack.

Cheap checks worth stealing:

Alert on restart count / restart velocity, not just non-zero exits.
A health check that has never once reported unhealthy is probably not testing anything.
When something works under docker run but a health check says it's down, suspect localhost → IPv6 before you suspect your code.
A stdio service with no stdin_open will exit cleanly on boot. "Clean" is not the same as "correct."

What's the longest a silent restart loop has run in your infrastructure before anyone noticed?

Four versions of one translate() function

Xiantao Cai — Sun, 06 Sep 2026 14:47:54 +0000

I build Connexa, a chat product for cross-language teams: you write Chinese, your teammate reads English.

I assumed translation was one function. The file now holds four versions of it, and each one exists because the previous one dropped something.

v1: ten lines

async translate(text: string, targetLang: string): Promise<string> {
  const slice = text.length > 12000 ? `${text.slice(0, 12000)}…` : text;
  return this.chat([{
    role: 'user',
    parts: [{ text: `Translate the following text into ${targetLang}. Return only the translation, no explanations:\n\n${slice}` }],
  }]);
}

The output was correct. The problem is that it translates sentences, not conversations.

Example: 这个我看一下 → I'll take a look at this. Literally accurate. In Chinese that line is sometimes a polite refusal. The words arrived, the intent stayed behind.

v2: make tone a field, not a hope

The tempting fix is to ask for a "more natural" translation. That isn't controllable and isn't testable.

Instead I made tone a schema-constrained field:

generationConfig: {
  temperature: 0.3,
  topP: 0.9,
  maxOutputTokens: 2048,
  responseMimeType: 'application/json',
  responseSchema: {
    type: 'OBJECT',
    properties: {
      translated: { type: 'STRING' },
      tone: { type: 'STRING' },
    },
    required: ['translated'],
  },
}

with a system instruction pinning the vocabulary:

Tone should be a short lowercase label such as casual, formal, urgent, direct, friendly, sarcastic, frustrated, or neutral.

Note required: ['translated'] — tone is optional on purpose. That matters in v5 below.

Tone went from something I hoped the model conveyed into something I can render in the UI, store, and reason about.

v3: context, and the bug it introduced

A single message can't be translated without what came before it, so I appended the last 10 lines:

const ctx = (contextLines || []).filter(Boolean).slice(-10).join('\n');

const parts = [
  `Translate the following message into ${targetLang}.`,
  glossaryText ? `Team glossary (use these terms):\n${glossaryText}` : '',
  ctx ? `Conversation context (tone/reference only):\n${ctx}` : '',
  `Message to translate:\n${slice}`,
  'Return ONLY the translation.',
].filter(Boolean).join('\n\n');

The bug: the model helpfully translates the context too. You ask for one translated line and get a translated transcript.

(tone/reference only) is not a comment for human readers. It is the constraint. Remove that parenthetical and the return shape changes.

v4: glossary, and the verb you use to introduce it

If the same term renders as A in one message and B in the next, the conversation quietly desyncs. So: a per-team glossary, flattened line by line.

const glossaryText = glossary && Object.keys(glossary).length
  ? Object.entries(glossary).map(([k, v]) => `${k} → ${v}`).join('\n')
  : '';

The part worth noting is the wording change between versions:

- `Team glossary (use these terms):\n${glossaryText}`
+ `Team glossary (must follow):\n${glossaryText}`

I did not A/B this. I am not claiming a measured lift. I changed it because "use these terms" phrases a constraint as a suggestion, and I had no reason to keep it phrased that way.

v5 is the fallback, and its direction matters

Structured output fails sometimes. The question is what you drop when it does.

try {
  const parsed = JSON.parse(this.extractText(await this.generateRaw(body)));
  return {
    translated: parsed?.translated?.trim() || fallbackText,
    tone: parsed?.tone?.trim() || null,
  };
} catch (e) {
  this.logger.warn(`translateWithTone fallback: ${(e as Error).message}`);
  return {
    translated: await this.chat([{
      role: 'user',
      parts: [{ text: prompt + '\n\nReturn only the translated text.' }],
    }]),
    tone: null,
  };
}

Drop to a plain-text request, return tone: null. In a chat product, translation is the primary path and tone is an enhancement. Degrade the enhancement, never the path. That is why tone was optional in the schema.

What I'd keep

Translation is not converting language A into B. It is reconstructing A's intent in B.

The literal layer is the easiest part to move, which is why it gets finished first — and exactly why it is easy to believe you are done. Tone, prior context, and term consistency do not show up in the output on their own. Each one has to be added back deliberately, and each one costs you a prompt section and a failure mode.

What is the last output you shipped that was correct and still wrong?

Shorter versions of this appeared on LinkedIn and on my Chinese-language channels.

Eastern Philosophy for Developers: Using Wang Yangming to Combat Burnout

Xiantao Cai — Sun, 19 Jul 2026 04:53:44 +0000

As developers, we are constantly bombarded with noise. There is always a new framework to learn (Rust, Go, Next.js), a new architectural pattern to master (Microservices, K8s), and endless workplace politics to navigate.

The result is often "mental friction" (精神内耗) or severe burnout. We get stuck in our own heads, analyzing every problem until we are paralyzed by anxiety.

When I faced this, I didn't turn to typical Silicon Valley productivity hacks. Instead, I found my solution in the 16th-century Eastern philosophy of Wang Yangming (王阳明心学). Here is how I compiled his ancient philosophy into a modern developer's anti-burnout script.

1. "Nothing Outside the Mind" (心外无物): Your Mental Firewall

Wang Yangming taught that all perceptions and emotions are generated internally. If something doesn't directly relate to your core goals, it effectively doesn't exist for you.

In a workplace context, this is the ultimate firewall. When you are worried about an upcoming performance review, or what a toxic coworker thinks of you, remember: you are generating that anxiety, not them.

The Patch: Stop trying to change how others view you. Prejudices in the minds of others are like mountains—you cannot move them. You are only working for yourself. Configure your mental firewall to block out any external "noise" that doesn't align with your personal roadmap. If a situation doesn't serve your goals, drop the packet.

2. "Unity of Knowledge and Action" (知行合一): The Ultimate Anti-Loop Mechanism

Many developers get stuck in a "while(true)" loop of overthinking. We analyze architecture, debate trade-offs, and worry about edge cases without writing a single line of code.

Wang Yangming argued that true knowledge only comes from action and direct perception (the five senses), not from cognitive habits or endless theory.

The Patch: When you feel your brain entering a state of contradiction or mental friction, execute an immediate physical interrupt (Ctrl+C). Stop thinking. Shift your awareness entirely to your five senses. Focus on your breathing. Look at the screen from a third-person perspective. By anchoring yourself to physical reality and taking immediate, small actions, you break the infinite loop of overthinking.

3. Master Your Own Source Code

Philosophy isn't just about reading quotes; it's a utility tool. Just like you choose the right tech stack for a specific project, you must choose the right mental framework for a specific problem.

The core utility of Wang Yangming's philosophy is its ability to reduce noise and increase focus. It teaches you to identify your true desires, overcome your biases (bugs in your cognitive habits), and establish a new, objective understanding of the world through direct action.

The next time you feel overwhelmed by the tech world, try running this ancient algorithm. Turn off the external noise, trust your five senses, and hit compile.